Closing the movie editor object does not result in an export. Since there is no way to undo adding tracks, adding segments, adding compositing instructions and that all the work of compositing happens at export time having export happen coincidentally with closing the object is expensive for possibly unintended behaviour. This is different behaviour of the video frames writer object where much of the work of saving the file happens as frames are added and the finalise command is relatively low cost.

You can also create a movie editor using make_createmovieeditor method of a SmigCommands object. With default arguments a name for the object will be automatically generated and a close command for the object is automatically added to the list of cleanup commands.

Adding segments to tracks

It is probably best to add segments in time order. It keeps things simplest that way. If you insert a segment prior to the end of another segment in the same track it is not always clear what will happen. If you insert a segment with the same start time as another segment on the same track the other segment will be pushed to start after the inserted segments end time. It is possible to get information about inserted segments using the 'getproperty' command. In ruby test file test018 (see links above), test02 obtains the track segment mappings before and after the insertion of an empty segment that moves another segment.

You can also add an image map of the current state of the video composition showing tracks, segments and composition instructions to the image collection. See section below for how to do this.

Video tracks in the movie editor do not have to have segments with content through their full range. Content in a time range in a track is needed where a layer instruction refers to that track and time range.

Adding a segment with content

Ruby for inserting a track segment from a movie importer object into a track of the movie editor. To add sound content to an audio track you need to make sure the source is an audio track and vice versa for video content.

Adding composition instructions

Composition instructions define how 1 or more video tracks are combined to compose the final output video. Each composition instruction is created from a list of layer instructions. Each layer instruction refers to one track. If you don't add the composition instructions in temporal order the output video will fail to be composed. Each layer instruction applies only within the time period of the composition instruction but the time specification is not defined by the time range of the composition instruction but of the time frame of the video.

The order of the layer instructions is important. The first layer instruction in the list of layer instructions is at the front, and the last layer instruction is at the back.

If the first layer instruction was a pass thru layer instruction and the video track applied was the same size as the output video composition then it would cover over all other instructions. If you just want one a specific video track as output for a time range of the output video then you would create composition instruction with a single layer instruction. That single layer instruction would be a passthru instruction.

The different layer instructions

All the layer instructions have a start and duration times. For the non ramp layer instructions then the instruction applies unchanging for the duration of the layer instruction. For the ramp layer instructions the instruction varies continuously from the start ramp value at the beginning to the end ramp value at the end of the duration.

Passthru - Where the track is passed unmodified for compositing

Opacity - Where an opacity between 0 and 1 is applied to a track

Crop - Where the track is cropped before being composited.

Transform - Where a track has a transform applied before being composited.

Opacity ramp - Where you apply a start and end opacity value to a track.

Transform ramp - Where you apply a start and end transform to a track.

Crop ramp - Where you apply a start and an end crop to the track.

Currently not implemented is the ability to have more than one type of instruction in a single layer instruction, so for example you can not have a transform with opacity ramp applied in one layer instruction.

The example I use here is to have the first couple of seconds have track 0 be the source for the output, then followed by a dissolve ramp that lasts for two seconds which slowly dissolves out track 0 and replaces it with track 1 and then 2 seconds where the output is just track 1. Each subsection below implements one instruction with one or more layer instructions.

Adding an opacity ramp layer instruction

Actually two layer instructions will be applied. An opacity ramp layer instruction and a pass thru layer instruction. The order of the instructions is relevant.

Notice that the pass thru instruction which is applied to track 1 is the second layer instruction and the first layer instruction is the opacity instruction and is applied to track 0. The opacity instruction is the front instruction and as the opacity value reduces to 0 the pass thru layer below appears.

At the end of this section I'm combining all the parts into one single script and JSON output. Here I'll be leaving out the bits where I am just doing further passthru only instructions as the only things that change are the track and the time range.

Adding a transform ramp layer instruction

Once again two layer instructions will be applied. The transform ramp instruction and a pass thru instruction. Since we are now transferring from track 1 to track 0 rather than the other way round with the opacity ramp instruction the transform ramp instruction is the first layer instruction and is applied to track 1.

The script also generates a video composition diagram image file. If for some reason your video composition doesn't render and save then looking at the video composition diagram can sometimes be helpful when working out why it doesn't work.

Adding Audio mix instructions

Since you can create sound tracks, and add audio content to those tracks, it is necessary to be able to mix the audio content of the different tracks. This is done using audio mix instructions which allows you to specify the track volume from a particular time, or set a volume ramp, where the volume level is gradually changed to the new desired level.

By default each audio track starts with the maximum volume level of 1.0. The following example sets the start volume of the second audio track to 0.0. At 1 second in, two volume ramps that last for 2 seconds are setup, the first audio track has the volume ramped down 1.0 to 0.0, whilst the second has volume ramped up from 0.0 to 1.0

Add composition diagram to the image collection

The composition diagram is an image that describes the state of the video composition when it is generated. It will show you the created tracks, the inserted segments, and the applied instructions. It can be really helpful in debugging your video compositions.