markdown/tools/ges-launch.md

   1 ---
   2 short-description: The GStreamer Editing Services prototyping tool
   3 ...
   4
   5 # ges-launch-1.0
   6
   7 **ges-launch-1.0** creates a multimedia [timeline](https://phabricator.freedesktop.org/w/gstreamer/gst-editing-services/ges-timeline/) and plays it back, or renders it to the specified format.
   8
   9 It can load a timeline from an existing project, or create one from the specified commands.
  10
  11 Updating an existing project can be done through thanks to the [GstValidate](http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-validate/html/) [scenarios](http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-validate/html/scenarios.html) using the `--set-scenario` argument, if ges-launch-1.0 has been compiled with GstValidate.
  12
  13 You can inspect action types with:
  14
  15     ges-launch-1.0 --inspect-action-type
  16
  17 By default, ges-launch-1.0 is in "playback-mode".
  18
  19 ## Synopsis
  20
  21   ges-launch-1.0'  [-l <path>|--load=<path>] [-s <path>|--save=<path>]
  22       [-p <path>|--sample-path=<path>] [-r <path>|--sample-path-recurse=<path>]
  23       [-o <uri>|--outputuri=<uri>] [-f <profile>|--format=<profile>]
  24       [-e <profile-name>|--encoding-profile=<profile-name>]
  25       [-t <track-types>|--track-types=<track-types>]
  26       [-v <videosink>|--videosink=<videosink>]
  27       [-a <audiosink>---audiosink=<audiosink>]
  28       [-m|--mute] [--inspect-action-type[=<action-type>]]
  29       [--list-transitions] [--disable-mixing]
  30       [-r <times>|--repeat=<times>] [--set-scenario=<scenario-name]
  31
  32 ## Define a timeline through the command line
  33
  34 The ges-launch-1.0 tool allows you to simply build a timeline through a dedicated set of commands:
  35
  36 ### +clip
  37
  38 Adds a clip to the timeline.
  39
  40 See documentation for the --track-types option to ges-launch-1.0, as it
  41 will affect the result of this command.
  42
  43 #### Examples:
  44
  45     ges-launch-1.0 +clip /path/to/media
  46
  47 This will simply play the sample from its beginning to its end.
  48
  49     ges-launch-1.0 +clip /path/to/media inpoint=4.0
  50
  51 Assuming "media" is a 10 second long media sample, this will play the sample from the 4th second to the 10th, resulting in a 6-seconds long playback.
  52
  53     ges-launch-1.0 +clip /path/to/media inpoint=4.0 duration=2.0 start=4.0
  54
  55 Assuming "media" is an audio video sample longer than 6 seconds, this will play a black frame and silence for 4 seconds, then the sample from its 4th second to its sixth second, resulting in a 6-seconds long playback.
  56
  57     ges-launch-1.0 --track-types=audio +clip /path/to/media
  58
  59 Assuming "media" is an audio video sample, this will only play the audio of the sample in its entirety.
  60
  61     ges-launch-1.0 +clip /path/to/media1 layer=1 set-alpha 0.9 +clip /path/to/media2 layer=0
  62
  63 Assume media1 and media2 both contain audio and video and last for 10 seconds.
  64
  65 This will first add media1 in a new layer of "priority" 1, thus implicitly creating a layer of "priority" 0, the start of the clip will be 0 as no clip had been added in that layer before.
  66
  67 It will then add media2 in the layer of "priority" 0 which was created previously, the start of this new clip will also be 0 as no clip has been added in this layer before.
  68
  69 Both clips will thus overlap on two layers for 10 seconds.
  70
  71 The "alpha" property of the second clip will finally be set to a value of 0.9.
  72
  73 All this will result in a 10 seconds playback, where media2 is barely visible through media1, which is nearly opaque. If alpha was set to 0.5, both clips would be equally visible, and if it was set to 0.0, media1 would be invisible and media2 completely opaque.
  74
  75 #### Mandatory arguments
  76
  77 __path|uri:__
  78 ```
  79 Specifies the location of the sample to make a clip from.
  80 ```
  81
  82 #### Options
  83
  84 __inpoint[i]=<inpoint>:__
  85 ```
  86 Sets the inpoint of the clip, that is the
  87 position in the original sample at which the clip will start outputting
  88 data.
  89
  90 It is an error to have an inpoint superior to the actual duration of the original sample.
  91
  92 0 by default.
  93 ```
  94
  95 __duration[i]=<duration>:__
  96 ```
  97 Sets the duration of the clip, that is the
  98 duration of the media the clip will output.
  99
 100 It is an error to have inpoint + duration be superior to the duration of the
 101 original sample.
 102
 103 The default is the duration of the original sample - the inpoint of the clip.
 104 ```
 105
 106 __start[s]=<start>:__
 107
 108 ```
 109 Sets the start of the clip, that is its position in
 110 the timeline.
 111
 112 If not specified, it will be set to the duration of the layer the clip is added on,
 113 as the expected default behaviour is to queue clips one after another.
 114 ```
 115
 116 __layer[l]=<layer>:__
 117 ```
 118 Sets the layer of the clip. The video stream in
 119 overlapping clips on different layers will be blended together according
 120 to their alpha property, starting with the clip on the last layer. An
 121 example is shown in the EXAMPLES section.
 122
 123 If not specified, it will be set to the last layer a clip has been added on, or
 124 a first layer if no clip has been added yet.
 125 ```
 126
 127 #### Properties
 128
 129 ##### Video properties
 130
 131 These have no effects if there is no video stream in the sample.
 132
 133 __alpha:__
 134 ```
 135 This is the amount of transparency of the clip, ranging from 0.0
 136 to 1.0 Clips overlapping on different layers will be composited
 137 together, unless --disable-mixing has been specified, in the order of
 138 the layers.
 139 ```
 140
 141 __posx:__
 142 ```
 143 This is the x position (offset) of the clip in pixels, relatively
 144 to the output frame of the timeline.
 145 ```
 146
 147 __posy:__
 148 ```
 149 This is the y position (offset) of the clip in pixels, relatively
 150 to the output frame of the timeline.
 151 ```
 152
 153 __width:__
 154 ```
 155 This is the width in pixels that the clip will occupy in the
 156 final output frame.
 157 ```
 158
 159 __height:__
 160 ```
 161 This is the height in pixels that the clip will occupy in the final output frame.
 162 ```
 163
 164 ##### Audio properties
 165
 166 __volume:__
 167 ```
 168 This is the volume that will be set on the audio part of the
 169 clip, ranging from 0.0 to 10.0, with 1.0 being the default.
 170 ```
 171
 172 __mute:__
 173 ```
 174 Set to true to mute the audio of the clip. Default is false.
 175 ```
 176
 177 ### +effect
 178
 179 #### Mandatory arguments
 180
 181 __bin-description:__
 182
 183 ```
 184 Specifies the description of a GStreamer a bin, in the gst-launch format.
 185 ```
 186
 187 #### Options
 188
 189 Properties can be set on the effect either directly in the bin-description, or separately through the set-<property-name> command, which will lookup any readable property in any of the children of the bin, and set the provided value on it.
 190
 191 #### Examples
 192
 193     ges-launch-1.0 +clip /path/to/media +effect "agingtv"
 194
 195 This will apply the agingtv effect to "media" and play it back.
 196
 197 ### set-<property-name>
 198
 199 Sets the property of an object (for example a clip or an effect). Trying to set a property than can't be looked up is considered an error.
 200
 201 By default, set-<property-name> will lookup the property on the last added object.
 202
 203 #### Examples
 204
 205     ges-launch-1.0 +clip /path/to/media set-alpha 0.3
 206
 207 This will set the alpha property on "media" then play it back, assuming "media"
 208 contains a video stream.
 209
 210     ges-launch-1.0 +clip /path/to/media +effect "agingtv" set-dusts false
 211
 212 This will set the "dusts" property of the agingtv to false and play the
 213 timeline back.
 214
 215 ## Options
 216
 217 ### Project-related options
 218
 219 __--load[-l]=<path>:__
 220 ```
 221 Load project from file. The project be saved again with the --save option.
 222 ```
 223
 224 __-s --save=<path>:__
 225 ```
 226 Save project to file before rendering. It can then be loaded with the --load option
 227 ```
 228
 229 __-p --sample-path:__
 230 ```
 231 If some assets are missing when loading a project file, ges-launch-1.0 will try to
 232 locate them in this path. It is especially useful when sharing a project.
 233 ```
 234
 235 __-r --sample-path-recurse:__
 236 ```
 237 Identical to --sample-path, but ges-launch-1.0 will also recurse in the subfolders
 238 to look for assets.
 239 ```
 240
 241 ### Rendering options
 242
 243 __-o --outputuri=<uri>:__
 244 ```
 245 If set, ges-launch-1.0 will render the specified timeline instead
 246 of playing it back. The default rendering format is ogv, containing
 247 theora and vorbis.
 248 ```
 249
 250 __-f --format=<profile>:__
 251 ```
 252 Set an encoding profile on the command line. See ges-launch-1.0 help profile
 253 for more information.
 254 This will have no effect if no outputuri has been specified.
 255 ```
 256
 257 __-e --encoding-profile=<profile-name>:__
 258 ```
 259 Set an encoding profile from a preset file. See ges-launch-1.0 help profile
 260 for more information.
 261 This will have no effect if no outputuri has been specified.
 262 ```
 263
 264 __-t --track-types=<track-types>:__
 265 ```
 266 Specify the track types to be created. When loading a project, only relevant
 267 tracks will be added to the timeline.
 268 ```
 269
 270 ### Playback options
 271
 272 __-v --videosink=<videosink>:__
 273 ```
 274 Set the videosink used for playback.
 275 ```
 276
 277 __-a --audiosink=<audiosink>:__
 278 ```
 279 Set the audiosink used for playback.
 280 ```
 281
 282 _       _-m --mute:__
 283 ```
 284 Mute playback output. This has no effect when rendering.
 285 ```
 286
 287 ### Helpful options
 288
 289 __--inspect-action-type=<action-type>:__
 290 ```
 291 Inspect the available action types that can be defined in a scenario set with --set-scenario.
 292 Will list all action-types if action-type is empty.
 293 ```
 294
 295 __--list-transitions:__
 296 ```
 297 List all valid transition types and exit. See ges-launch-1.0 help transition
 298 for more information.
 299 ```
 300
 301 ### Generic options
 302
 303 __--disable-mixing:__
 304 ```
 305 Do not use mixing elements to mix layers together.
 306 ```
 307
 308 __-r --repeat=<times>:__
 309 ```
 310 Set the number of times to repeat the timeline.
 311 ```
 312
 313 __--set-scenario:__
 314 ```
 315 ges-launch-1.0 exposes gst-validate functionalities, such as scenarios.
 316 Scenarios describe actions to execute, such as seeks or setting of properties.
 317 GES implements editing-specific actions such as adding or removal of clips.
 318 ```