Effects commands

To add an effect to a clip use the command:

-add_effect CLIP_IDENTIFIER /full/path/to/effect.xml

The first argument to this command identifies the clip(s) you wish to apply the effect to. The second argument is the path to an XML file which describes the effect to apply. This XML file maybe rather simple, for example when adding a dirt correction effect which uses default settings; rather complex, for example when adding a sharpen effect with time-animated curves and in/out points; or anywhere in between.

As mentioned earlier, to document the XML files to describe every possible parameter in every possible effect would be a whole document in itself. In this chapter we simply describe some of the more commonly used effects and parameters. If this does not cover the effect/parameter you need then you can (1) contact support for advice (once we know which effect/parameter you are interested in documenting it is straight forward... its just there are an awful lot of them!), and/or (2) create the effect you wish to use in the GUI and then look at the XML description of the clip in the project directory structure - the XML required by the command line processing and that generated by the GUI are one and the same.

Auto Dirt

In its simplest form a dirt effect can be added using the XML file:

<meta type="Effect">
  <effect type="AutoDirtFix">
  </effect>
</meta>

The default settings for this effect are the same as when creating the effect using the GUI. A more complex example changing dirt type, minimum contrast, frame lookahead and fix mode:

<meta type="Effect">
  <effect type="AutoDirtFix">
    <dirtParams>
      <type>0</type>
      <contrast>0.05</contrast>
      <lookahead>2</lookahead>
      <fix>1</fix>
    </dirtParams>
  </effect>
</meta>

Note that contrast is specified as an absolute, whereas in the GUI it is a percentage; the dirt type is an integer where dark only=0, light only=1 and dark and light=2; and the fix mode is an integer with temporal=0 and spatial=1.

If you need to specify colour channels use channels where the value is the the sum of red=1, green=2 and blue=4. Sizes, such as minimumSize and maximumSize, are normalised to the clip width. For example if a clip is 2k resolution then a size of 0.00244141 is 5 pixels (0.002441412048=5). To have no bound on minimum or maximum size sets its value to -1.

Scratch

A basic scratch effect can be added using the XML file:

<meta type="Effect">
  <effect type="Scratch2013">
  </effect>
</meta>

The default settings for this effect are the same as when creating the effect using the GUI. A fuller example:

<meta type="Effect">
  <effect type="Scratch2013">
    <scratchParams>
      <scratchType>3</scratchType>
      <motion>1</motion>
      <contrast>0.1</contrast>
      <length>0.5</length>
      <angle>2</angle>
      <width>0.00292969</width>
    </scratchParams>
  </effect>
</meta>

scratchType, while doing the same job as type for the dirt effect has a different name and values - dark only=1, light only=2, dark and light=3; motion is spatial=0 and temporal=1; length, like contrast, is an absolute number; and width is normalised to 1.

Degrain

To create a degrain effect use an XML file:

<meta type="Effect">
  <effect type="Degrain">
    [grain parameters]
  </effect>
</meta>

where "[grain parameters]" is an XML block which describes the grain parameters. By far the easiest way of obtaining this is to save out a grain preset from the GUI. This will write the required grain parameters XML block into the presets/grain directory.

Generating a set of grain parameters is best achieved using the GUI tools to sample relevant areas of the footage. A library of grain parameters for different film stocks can then be built up and used across projects. However, there is nothing stopping a user manually generating a set of grain parameters by using a GUI generated set as a template and enter values for the grain strength and standard deviations.

Effects with keyframed parameters

Effects such as sharpen, blur and median filter are not as straight forward as they first may appear. Even though you may wish to create a simple blur effect with a single constant blur value, the blur effect, in its most general form, is actually defined by 6 parameters

- red, green and blue horizontal and vertical values - each of which is keyframed curve. And it is these keyframed curves that you need to define in an XML file in order to create the effect.

Blur

Below is an example of a blur effect:

<meta type="Effect">
 <effect type="Blur">

   <bezierAnimParam name="sizeX" type="bezierAnimParam">
    <curve componentColour="255 0 0" componentName="Red" type="bezier1d">
     <point>0.000000 2.100000</point>
    </curve>

    <curve componentColour="0 255 0" componentName="Green" type="bezier1d">
     <point>0.000000 2.100000</point>
    </curve>

    <curve componentColour="0 0 255" componentName="Blue" type="bezier1d">
     <point>0.000000 2.100000</point>
     <point>0.500000 1.000000</point>
    </curve>
   </bezierAnimParam>

   <bezierAnimParam name="sizeY" type="bezierAnimParam">
    <curve componentColour="255 0 0" componentName="Red" type="bezier1d">
     <point>0.000000 2.100000</point>
    </curve>

    <curve componentColour="0 255 0" componentName="Green" type="bezier1d">
     <point>0.000000 2.100000</point>
    </curve>

    <curve componentColour="0 0 255" componentName="Blue" type="bezier1d">
     <point>0.000000 2.100000</point>
     <point>0.500000 1.000000</point>
    </curve>
   </bezierAnimParam>

 </effect>
</meta>

The single point comprising the sizeX Red curve - 0.0, 2.1 - means at time 0 use a value of 2.1 (and since no other points are defined that value is used at all other times, ie. its clamped). The two points for the sizeX Blue curve - 0.0, 2.1 and 0.5, 1.0 - means use a value of 2.1 at time 0 decreasing to a value of 1.0 at time 0.5. The time value is normalised to the clip frame range so time=0 maps to the start frame and time=1 is the end frame.

The blur effect is said to have 2 curve groups - sizeX and sizeY - each consisting of 3 curves Red, Green and Blue.

Sharpen

The sharpen effect () has 3 curve groups - sizeX, sizeY and amount - each consisting of Red, Green and Blue curves.

Median filter

The media filter effect () has 4 curve groups - windowSizeX, windowSizeY, blend and percentile - each consisting of Red, Green and Blue curves.

Stabilize

A basic stabilisation effect can be added to a clip with:

<meta type="Effect">
  <effect type="Stabilize">
    <mode>3</mode>
  </effect>
</meta>

where mode is none=0, horizontal=1, vertical=2, translation=3, affine=4 and perspective=5. If you do not specify a mode then it will default to 0 and that is probably not what you want!

An example with other parameters specified:

<meta type="Effect">
  <effect type="Stabilize">
    <mode>3</mode>
    <range>10</range>
    <threshold>30</threshold>
    <border>0.2</border>
    <lock>1</lock>
  </effect>
</meta>

Note that threshold is specified as a percentage but border is an absolute even though both are presented in the GUI as a percentage. lock is an integer where false=0 and true=1.

Edge framing

The edge framing effect can be added to a clip with:

<meta type="Effect">
  <effect type="AutoFill">
    <mode>1</mode>
  </effect>
</meta>

where mode is none=0, translation=1, affine=2 and perspective=3. Like the stabilize effect, make sure you specify a mode otherwise it defaults to 0 (none) which is probably not what you want.

Deflicker

A basic deflicker effect can be added to a clip with:

<meta type="Effect">
  <effect type="Deflicker">
  </effect>
</meta>

An example with other parameters specified:

<meta type="Effect">
  <effect type="Deflicker">
    <channels>0</channels>
    <filter>1</filter>
    <rgbChannels>7</rgbChannels>
    <range>5</range>
    <sensitivity>0.25</sensitivity>
    <adjust>1</adjust>
    <temporal>1</temporal>
  </effect>
</meta>

where channels is RGB=0 and luminance=1; filter is median=0, Gaussian=1 and lock=2; rgbChannels are the colour channels as documented elsewhere; adjust is brightness=1, contrast=2 and both=3; and temporal is false=0 and true=1.

Lens undistort

The XML for creating a lens undistort effect is:

<meta type="Effect">
  <effect type="Lens Undistort">
    <mode>0</mode>
    <centre>0.5 0.5</centre>
    <bezierAnimParam name="lowRadial" type="bezierAnimParam">
     <curve componentColour="255 255 255" componentName="Value" type="bezier1d">
      <point>0.0 0.1</point>
     </curve>
    </bezierAnimParam>
 </effect>
</meta>

where mode is low=0, low+high=1, low+offset=2 and low+high+offset=3; centre is the distortion centre normalised to 1. The effect has 3 curve groups: lowRadial consisting of a single curve Value; highRadial consisting of a single curve Value; and offset consisting of 2 curves X and Y.

In/out points and region of interest

In and out points for an effect can be set using the in and out attributes of the XML description of the effect, e.g.:

<meta type="Effect" in="25000" out="75000">
 <effect type="Sharpen">
  ...
 </effect>
</meta>

in and out values are represented at integers where 0 is the start frame and 100000 is the end frame. So, in the above example the in point is 25% of the way into the clip and the out point is 75%. A region of interest can be set using the roiXMin, roiYMin, roiXMax and roiYMax attributes of the XML description of the effect, e.g.:

<meta type="Effect" roiXMin="2500" roiYMin="2500" roiXMax="75000" roiYMax="75000">
 <effect type="Sharpen">
  ...
 </effect>
</meta>

Again the values are normalised in the range 0-100000 for the width and height.

The above sets the in/out points and region of interest for a specific effect. It is also possible to set these for the clip as a whole (such that they acts on all effects unless overridden) by adding a ClipInfo effect to the clip:

<meta type="ClipInfo" in="10000" out="90000">
</meta>

The ClipInfo data does not directly represent an effect, but its contents can influence other effects.

← MEDIA COMMANDS

EXPORT COMMANDS →