Shape tags and presets

Shapes can be tagged in order to retrieve their file contents easily using Retrieving item information. The system adds certain tags to shapes automatically during certain operations, such as an import job. Predefined tags can be seen in the table below.

Tag Description
original The first shape that was created for the item.

While shape tags serve as a “name tag” for shapes, they also contain the recipe for how new shape instances with the shape tag should be constructed, or transcoded, from other shapes. This is defined using a transcode preset that defines the format, codec, bitrate etc of the shapes.

Transcode presets

The transcode preset specifies the output format, codec and encoding settings that should be used when transcoding. You can either

Preset templates

Vidispine comes with some preset templates built in. These can be added to the system by making a PUT request to APIinit/preset-templates. These template tags have names that begin with double underscore and cannot be overwritten (Also, shape tags with names starting with double underscore cannot be added to the system).

Scripting transcode presets

Transcode presets can be made dynamic by assigning a JavaScript to them. Made available to the script will be the shape that is going to be transcoded as well as the unmodified preset. The shape can be used as input to determine for example the original resolution of the media. For output the preset can be modified before it is sent to the transcoder. An overview is given in the table below.

Mode Identifier XML Type Java Type
input jobMetadata - java.util.Map<String, String>
input metadata MetadataType com.vidispine.generated.MetadataType
input shape ShapeType com.vidispine.generated.ShapeType
output preset TranscodePresetType com.vidispine.generated.TranscodePresetType

The given data types are generated from the XML schema and belong to the package com.vidispine.generated. They follow JavaBean standard, i.e. getters and setters for their attributes.

Caution

Lists of integer

When adding integers of a list, simply using integer literals will not work. Instead java.lang.Integer must be used, for example: list.add(new java.lang.Integer(5));

Tip

When writing the script, or after you have written one, write tests that verifies it for a range of shapes using the script test resource.

Examples

A preset that only produces two audio channels in the output

First we create a preset with only the formats and codecs set.

PUT /shape-tag/h264
Content-Type: application/xml

<TranscodePresetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <format>mp4</format>
  <audio>
    <codec>aac</codec>
  </audio>
  <video>
    <codec>h264</codec>
  </video>
</TranscodePresetDocument>
200 OK

Then we add the script

PUT /shape-tag/h264/script
Content-Type: application/javascript

// Retrieve the channel count: <ShapeDocument><audioComponent><channelCount>
var channelCount = shape.getAudioComponent().get(0).getChannelCount();

// If we have more than two channels, limit it to the first two:
if (channelCount > 2) {
    // Adding elements to <TranscodePresetDocument><audio><channel>
    preset.getAudio().getChannel().add(new java.lang.Integer(0));
    preset.getAudio().getChannel().add(new java.lang.Integer(1));
}
200 OK

The result preset will then look like this if the input shape has more than two audio channels:

<TranscodePresetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <format>mp4</format>
  <audio>
    <codec>aac</codec>
    <channel>0</channel>
    <channel>1</channel>
  </audio>
  <video>
    <codec>h264</codec>
  </video>
</TranscodePresetDocument>

Scaling the output depending on the input

Using the same shape-tag as in the example above we can use the following script.

// Retrieve the width and height of the input
var width = shape.getVideoComponent().get(0).getResolution().getWidth();
var height = shape.getVideoComponent().get(0).getResolution().getHeight();

if (width == 720 && height == 608) {
    // Create the scaling element
    var scaling = new com.vidispine.generated.ScalingType();
    preset.getVideo().setScaling(scaling);

    // Crop 32 pixels from the top
    scaling.setTop(32);

    // Set the desired display aspect ratio
    var targetDar = new com.vidispine.generated.AspectRatioType();
    targetDar.setHorizontal(4);
    targetDar.setVertical(3);
    scaling.setTargetDAR(targetDar);

    // Set the desired resolution
    scaling.setWidth(480);
    scaling.setHeight(360);
} else if (height > 700) {
    // Create the scaling element
    var scaling = new com.vidispine.generated.ScalingType();
    preset.getVideo().setScaling(scaling);

    // Set the desired display aspect ratio
    var targetDar = new com.vidispine.generated.AspectRatioType();
    targetDar.setHorizontal(16);
    targetDar.setVertical(9);
    scaling.setTargetDAR(targetDar);

    // Set the desired resolution
    scaling.setWidth(640);
    scaling.setHeight(360);
} else {
    // Create the scaling element
    var scaling = new com.vidispine.generated.ScalingType();
    preset.getVideo().setScaling(scaling);

    // Set the desired display aspect ratio
    var targetDar = new com.vidispine.generated.AspectRatioType();
    targetDar.setHorizontal(4);
    targetDar.setVertical(3);
    scaling.setTargetDAR(targetDar);

    // Set the desired resolution
    scaling.setWidth(320);
    scaling.setHeight(240);
}

Transcode preset elements

This section highlights some of the settings and possibilities that are often useful when authoring a transcode preset.

Setting a preferred source tag

It is possible to specify that another file than the original should be used as the source file when transcoding. This is done using the preferredSourceTag element.

Burning in the timecode in the video

Vidispine can burn the timecode into the output video. To enable this, set the burnTimecode element to true within the video element.

Customizing the timecode

The following settings can be added as key-value pairs in the transcode preset:

  • bitc_font. Font to use.

    monospace

    fixed-width font (default)

    sans

    sans-serif font

    serif

    font with serifs

  • bitc_size. Height of font in pixels. Defaults to 15th of the video height.

  • bitc_sizeRel. Height of font relative to full video frame.

  • bitc_xRel. Position relative to width of video. Default is 0.5 (middle).

  • bitc_yRel. Position relative to height of video. Default is 0.9 (bottom).

  • bitc_horizontalbase. Horizontal position of base point relative to text bounding box.

    0.0 (or left)

    base point is left border of bounding box.

    0.5 (or center)

    base point is center of bounding box.

    1.0 (or right)

    base point is right border of of bounding box.

  • bitc_verticalbase. Vertical position of base point relative to text bounding box.

    0.0 (or top)

    base point is top border of of bounding box.

    0.5 (or middle)

    base point is middle of bounding box.

    1.0 (or bottom)

    base point is bottom border of bounding box.

  • bitc_r, bitc_g, bitc_b, bitc_a. RGB+alpha of text. Defaults to opaque white.

  • bitc_outlineR, bitc_outlineG, bitc_outlineB, bitc_outlineR. RGB+alpha of surrounding block. Defaults to opaque black.

  • bitc_outline. Type of outline. Default is bar.

  • bitc_outlinesize. Size (margin) of outline.

Setting a maximum duration of a chunk in QuickTime files

It is possible to specify a maximum duration for chunks in QuickTime files (MOV/MP4/3GPP). To set the duration add the maxChunkDuration element to the TranscodePresetType.

Example: setting the maximum chunk duration to 2 seconds

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TranscodePresetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <format>mp4</format>
  <maxChunkDuration>
    <samples>50</samples>
    <timeBase>
        <numerator>1</numerator>
        <denominator>25</denominator>
    </timeBase>
  </maxChunkDuration>
  <audio>
    <codec>aac</codec>
    <bitrate>320000</bitrate>
  </audio>
  <video>
    <codec>h264</codec>
    <bitrate>500000</bitrate>
    <framerate>
      <numerator>1</numerator>
      <denominator>25</denominator>
    </framerate>
    <resolution>
      <width>512</width>
      <height>288</height>
    </resolution>
  </video>
</TranscodePresetDocument>

Mixing audio channels

It is possible to define advanced mappings between input and output audio channels. This is done using the mix element.

Example: mixing 5.1 audio into stereo

<TranscodePresetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <format>mp4</format>
  <audio>
    <codec>aac</codec>
    <bitrate>128000</bitrate>
    <mix>
        <input channel="0" stream="1" gain="1.0"/>
        <input channel="2" stream="1" gain="0.5"/>
        <input channel="4" stream="1" gain="1.0"/>
    </mix>
    <mix>
        <input channel="1" stream="1" gain="1.0"/>
        <input channel="2" stream="1" gain="0.5"/>
        <input channel="5" stream="1" gain="1.0"/>
    </mix>
  </audio>
  <video>
    <scaling>
      <width>512</width>
      <height>288</height>
    </scaling>
    <codec>h264</codec>
    <bitrate>256000</bitrate>
    <framerate>
      <numerator>1</numerator>
      <denominator>25</denominator>
    </framerate>
  </video>
</TranscodePresetDocument>

The value of the stream attribute can be deduced from the input shape. The gain attribute is expressed linearly, i.e. a value of 1.0 means a gain of 0 dB. Also, since the number of input channels will probably vary with different inputs, this functionality is best utilized in conjunction with the JavaScript functionality described below.

The mix element can also be used to insert silent audio channels in the output.

Example: adding two silent audio channels in output

<TranscodePresetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <format>mp4</format>
  <audio>
    <codec>aac</codec>
    <bitrate>128000</bitrate>
    <mix silence="true"/>
    <mix silence="true"/>
  </audio>
  <video>
    <scaling>
      <width>512</width>
      <height>288</height>
    </scaling>
    <codec>h264</codec>
    <bitrate>256000</bitrate>
    <framerate>
      <numerator>1</numerator>
      <denominator>25</denominator>
    </framerate>
  </video>
</TranscodePresetDocument>

Splitting audio channels to mono files

It is possible to split audio channels into separate mono audio files. And they can be renamed according to their channel ids .

Example: split specific channels

<TranscodePresetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <format>wav</format>
  <audio>
    <codec>pcm_s16le</codec>
    <channel>0</channel>
    <channel>3</channel>
    <channel>5</channel>
    <monoFile>true</monoFile>
  </audio>
  <video>
    <noVideo>true</noVideo>
  </video>
</TranscodePresetDocument>

Example: split all channels

<TranscodePresetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <format>wav</format>
  <audio>
    <codec>pcm_s16le</codec>
    <monoFile>true</monoFile>
    <allChannel>true</allChannel>
  </audio>
  <video>
    <noVideo>true</noVideo>
  </video>
</TranscodePresetDocument>

Splitting audio channels to different output files

It is possible to split audio channels into files that contain more than one channels. And they can be renamed according to their channel ids.

Example

This preset below will produce three files:

  1. A WAV file containing 1 audio stream with 2 channels.
  2. A MOV file containing 2 audio streams, each stream has one channel.
  3. A MP4 file containing only the video.
<TranscodePresetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <format>mp4</format>
  <audio>
    <output>
      <format>wav</format>
      <codec>pcm_s24le</codec>
      <channel>0</channel>
      <channel>1</channel>
    </output>
    <output>
      <format>mov</format>
      <codec>aac</codec>
      <bitrate>320000</bitrate>
      <channel>2</channel>
      <channel>3</channel>
      <stream>1</stream>
      <stream>1</stream>
    </output>
  </audio>
  <video>
    <codec>h264</codec>
    <bitrate>1000000</bitrate>
    <framerate>
      <numerator>1</numerator>
      <denominator>25</denominator>
    </framerate>
    <resolution>
      <width>512</width>
      <height>288</height>
    </resolution>
  </video>
</TranscodePresetDocument>

Specifying multiple audio tracks with different audio codecs in output

It is possible to output multiple audio tracks, with different audio codecs, using the audioTrack element in the preset. The AudioTrackTranscodePresetType has the channel and mix elements from the AudioTranscodePresetType. However, there is no stream element, since adding multiple AudioTrackTranscodePresetType gives the same behaviour.

If you add a script to your preset you can access the audioTrack list with: preset.getAudioTrack(). This is useful for doing advanced channel mappings and mixdown depending on the input(s).

Example: two audio tracks, one with AC-3 and one with AAC

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TranscodePresetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <format>mov</format>
    <audioTrack>
        <codec>ac3</codec>
        <bitrate>384000</bitrate>
    </audioTrack>
    <audioTrack>
        <codec>aac</codec>
        <bitrate>96000</bitrate>
    </audioTrack>
</TranscodePresetDocument>

Example: two audio tracks, one with AC-3 and one with a mixdown to stereo AAC

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TranscodePresetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <format>mov</format>
    <audioTrack>
        <codec>ac3</codec>
        <bitrate>384000</bitrate>
    </audioTrack>
    <audioTrack>
        <codec>aac</codec>
        <bitrate>96000</bitrate>
        <mix>
            <input channel="0" gain="1.0"/>
            <input channel="2" gain="0.5"/>
            <input channel="4" gain="1.0"/>
        </mix>
        <mix>
            <input channel="1" gain="1.0"/>
            <input channel="2" gain="0.5"/>
            <input channel="5" gain="1.0"/>
        </mix>
    </audioTrack>
</TranscodePresetDocument>

Example: two audio tracks, one with AC-3 and one with AAC, picking some channels

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TranscodePresetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <format>mov</format>
    <audioTrack>
        <codec>ac3</codec>
        <bitrate>384000</bitrate>
        <channel>0</channel>
        <channel>1</channel>
    </audioTrack>
    <audioTrack>
        <codec>aac</codec>
        <bitrate>96000</bitrate>
        <channel>2</channel>
        <channel>3</channel>
    </audioTrack>
</TranscodePresetDocument>

Specifying audio channel layout

New in version 5.6.

It is possible to specify the channel layout by adding a <channelLayoutName> or <channelLayout>

Note

Currently not supported by the nablet_aac codec

<channelLayout> is a binary representation of the channel layout.

<channelLayoutName> accepts an layout name.

The name can be:

  • an usual channel layout (mono, stereo, 4.0, quad, 5.0, 5.0(side), 5.1, 5.1(side), 7.1, 7.1(wide), downmix)
  • the name of a single channel (FL, FR, FC, LFE, BL, BR, FLC, FRC, BC, SL, SR, TC, TFL, TFC, TFR, TBL, TBC, TBR, DL, DR)
  • a multiple of the above separated with ‘+’ or ‘|’, for example: “stereo+FC” or “FL+FR+FC”

Example: 5.1

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TranscodePresetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    ...
    <audio>
      ...
      <channelLayout>63</channelLayout>
    </audio>
</TranscodePresetDocument>

or

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TranscodePresetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    ...
    <audio>
      ...
      <channelLayoutName>"5.1"</channelLayoutName>
    </audio>
</TranscodePresetDocument>

Image overlays

One can overlay images on the output at specific positions and intervals by using the overlay element. Note that the image is overlaid as is and will not be scaled in any way, meaning that you may want to overlay different images depending on the output resolution. Specifying an overlay interval in an image preset is not supported. Only PNG overlays are supported.

Multiple overlays are supported.

Text overlays

In addition to image overlays, test overlays can also be added. The XML syntax is somewhat different from the image overlay syntax, see TextOverlayType in XML Schema for details.

Example: overlaying text

<TranscodePresetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  ...
  <textOverlay>
    <text xRel="0.1" yRel="0.9" horizontalBase="left" align="left" verticalBase="bottom" sizeRel="0.05">
      <line>Happy</line>
      <line>birthday!</line>
     </text>
   </textOverlay>
   <textOverlay>
     <text xRel="0.9" yRel="0.9" horizontalBase="right" align="right"
           verticalBase="bottom" sizeRel="0.02" r="0" g="0" b="0" language="ar">
        <line>&#1571;&#1580;&#1605;&#1604; &#1575;&#1604;&#1571;&#1605;&#1606;&#1610;&#1575;&#1578;&#1616; &#1576;&#1575;&#1604;&#1605;&#1586;&#1610;&#1583; &#1605;&#1606; &#1575;&#1604;&#1587;&#1593;&#1575;&#1583;&#1577; &#1608;&#1575;&#1604;&#1607;&#1606;&#1575;&#1569;!</line>
     </text>
  </textOverlay>
</TranscodePresetDocument>

Thumbnails at specific interval

By adding the element <thumbnailPeriod> to the preset, the interval of the the thumbnails can be customized. The default interval is 10 seconds. Example, for one thumbnail per second:

<TranscodePresetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    ...
    <thumbnailPeriod>
        <samples>1</samples>
        <timeBase>
            <numerator>1</numerator>
            <denominator>1</denominator>
        </timeBase>
    </thumbnailPeriod>
    ...
</TranscodePresetDocument>

Thumbnails at scene changes

By adding the element <thumbnailPlugin>scenechange</thumbnailPlugin> to the preset, the fixed thumbnail interval is replaced by an algorithm that extracts thumbnail at scene changes in the version.

Since 4.14, you can combine this element with <thumbnailPeriod> to specify the maximum interval between thumbnails. The example below will create a thumbnail at every scene change, but never more than 20 seconds apart:

<TranscodePresetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    ...
    <thumbnailPeriod>
        <samples>1</samples>
        <timeBase>
            <numerator>1</numerator>
            <denominator>1</denominator>
        </timeBase>
    </thumbnailPeriod>
    <thumbnailPlugin>scenechange</thumbnailPlugin>
    ...
</TranscodePresetDocument>

MPEG-DASH representation presets

New in version 5.4.

When creating presets for MPEG-DASH representations, the format should be set as mpd-representation.

Video representations should have noAudio and audio representations should have noVideo.

Example

<TranscodePresetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <name>__dash_1080p</name>
    <format>mpd-representation</format>
    <audio>
        <noAudio>true</noAudio>
    </audio>
    <video>
        ...
    </video>
    <metadata/>
</TranscodePresetDocument>

Deinterlacing video

By adding the setting deinterlacer, the video will be deinterlaced.

Supported values:

  • advanced - deinterlace the video using yadif.
  • nablet - deinterlace the video using nablet. (New in 22.4.)
  • effects - deinterlace sequences that are affected by scaling and rotation video effects by using the value effects, should be combined by a matching interlacer with value effects. This is not recommended for pixel formats where the chroma planes have a lower vertical resolution (eg. YUV420). (New in 22.4.)
  • nablet_effects - same as effects but using nablet instead of yadif. (New in 22.4.)

Additional settings available when using the deinterlacer:

  • deinterlacer_mode controls the function of the deinterlacer and takes the following values:

    • 0 - Output one frame for each frame (ex. 25i -> 25p).
    • 1 - Output one frame for each field (ex. 25i -> 50p).
    • 2 - Similar as 0, but it skips the spatial interlacing check.
    • 3 - Similar to 1, but it skips the spatial interlacing check.

    As default the mode is selected automatic to avoid frame duplication / drops. If the output framerate is less than 50% higher than the input framerate mode 0 is used, if higher 1 is used.

  • deinterlacer_parity The picture field parity assumed for the input interlaced video. It accepts one of the following values:

    • 0 - Assume the top field is first (tff).
    • 1 - Assume the bottom field is first (bff).
    • -1 - Enable automatic detection of field parity.

    The default value is -1 (Automatic detection). If the interlacing is unknown or the decoder does not export this information, top field first will be assumed.

  • deint Specify which frames to deinterlace. Accepts one of the following values:

    • 0 - Deinterlace all frames.
    • 1 - Only deinterlace frames marked as interlaced.

    The default value is 0 (Deinterlace all frames).

Example

<TranscodePresetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
...
    <video>
...
      <setting>
        <key>deinterlacer</key>
        <value>advanced</value>
      </setting>
      <setting>
        <key>deinterlacer_parity</key>
        <value>1</value>
      </setting>
      <setting>
        <key>deinterlacer_mode</key>
        <value>1</value>
      </setting>
    </video>
    <metadata/>
</TranscodePresetDocument>

Interlacing video

New in version 22.4.

By adding the setting interlacer, the video will be interlaced.

Supported values:

  • advanced - Interlace the video.
  • effects - Interlace sequences that are affected by scaling and rotation video effects by using the value effects. This should be combined by a matching deinterlacer with value effects. This value not recommended for pixel formats where the chroma planes have a lower vertical resolution (eg. YUV420).

Additional settings available when using the interlacer:

  • interlacer_parity The picture field parity assumed for the interlaced input video. It accepts one of the following values:

    • 0 - Assume the top field is first (tff).
    • 1 - Assume the bottom field is first (bff).

    The default value is 0 (Top field first).

Example

<TranscodePresetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
...
    <video>
...
      <setting>
        <key>interlacer</key>
        <value>advanced</value>
      </setting>
      <setting>
        <key>interlacer_parity</key>
        <value>1</value>
      </setting>
    </video>
    <metadata/>
</TranscodePresetDocument>

Color Conversion

New in version 23.4.

By adding a nablet_hdr_preset setting, it is possible to do color conversion, for example HDR to SDR.

The following target presets are supported:

  • CIP_BT601 - BT.601 PAL/SECAM.
  • CIP_BT601_NTSC - BT.601 NTSC.
  • CIP_BT709 - BT.709.
  • CIP_BT2020 - BT.2020.
  • CIP_sRGB - sRGB.
  • CIP_HDR_PQ - BT.2020 BT.2100-PQ.
  • CIP_HDR_HLG - BT.2020 BT.2100-HLG.
  • CIP_HDR_SLog2 - SONY S-Gamma, S-Log2.
  • CIP_HDR_SLog3 - SONY S-Gamma, S-Log3.
  • CIP_HDR_VLog - Panasonic VARICAM, V-Gamut.
  • CIP_HDR_LogC2 - ALEXA LogC V2, ALEXA Wide Gamut RGB.
  • CIP_HDR_LogC3 - ALEXA LogC V3, ALEXA Wide Gamut RGB.
  • custom - Uses values from colorSpace, colorPrimaries and colorTransferFunction (for supported values, see Sequence render color settings).

As default the color range from the source file is used, it can be overridden by adding a colorRange setting. If the color range of the source file is not detected correctly, it can be overridden by setting nablet_hdr_source colorRange.

Supported values:

  • limited, tv or 1 - Narrow or limited range, standard for most video material (for 8-bit formats, usually 16-235/240)
  • full, pc or 2 - Full range (for 8-bit formats, usually 0-255).

If the color settings are not identified correctly for the source file it is possible to override it using either a preset from the above list by adding a nablet_hdr_source_preset. When using custom, then the values from nablet_hdr_source_colorSpace, nablet_hdr_source_colorPrimaries and/or nablet_hdr_source_colorTransferFunction (for supported values, see Sequence render color settings) are used.

It is also possible to make additional adjustments with settings for:

  • nablet_hdr_r_gain, nablet_hdr_g_gain and nablet_hdr_b_gain, float value, 1.0 -> 100%, when using any of these settings, all 3 should be set, or a default value of 0 is used.
  • nablet_hdr_art_gamma - Artistic gamma correction, 0 - no correction; Y=Kr*R + Kg*G + Kb*B; {R,G,B} = pow(Y/Lwhite, art_gamma)*{R, G, B}.

scaling / cropping / rotating video

Used to set cropping and scaling parameters to the transcoder.

By default, the transcoder will attempt to maintain the display aspect ratio (DAR) of the cropped input. Use targetDAR to specify a different DAR to maintain.

The transcoder will typically try to adjust the pixel aspect ratio (PAR) so that the cropped picture ends up with the correct DAR. This minimizes the amount of processing required. Use pixelAspectRatio to set the PAR explicitly, in which case either width or height will be adjusted to maintain DAR. Use width and height to scale in those dimensions. If only one of them is set and PAR is set, the other one will be adjusted so the result matches the target DAR. If both are set and PAR is set, the transcoder will take them as is.

Setting neither width nor height while PAR is set results in undefined behavior.

The transcoder will always double-check the resulting dimensions and PAR against the desired DAR. If there’s a mismatch, the job will fail. If you want to force the transcoder to accept your settings, set targetDAR manually to the resulting DAR.

  • top, bottom, left, right is used to specify cropping of the image, negative values will pad the picture with padColor.
  • rotate - specifies how the image should be rotated, supported values are:
    • right - rotate the image -90 degrees
    • left - rotate the image 90 degrees
    • upsidedown - rotate the image 180 degrees
    • autorotate - rotate the image based on video metadata

Example

<TranscodePresetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
...
    <video>
...
      <scaling>
        <width>1000</width>
        <height>2000</height>
        <top>-40</top>
        <bottom>-50</bottom>
        <left>-60</left>
        <right>-70</right>
        <padColor>#c0c0c0</padColor>
        <rotate>right</rotate>
        <targetDAR>
          <horizontal>1000</horizontal>
          <vertical>2000</vertical>
        </targetDAR>
      </scaling>
    </video>
    <metadata/>
</TranscodePresetDocument>

Custom settings

Some codecs support fine-grained custom settings. These settings are specified by adding setting element inside the video or audio element, or by adding a muxerSetting.

Common settings for video and image

thumbnailformat

By default, video thumbnails are JPEG and image thumbnails and PNG.

This can be changed with thumbnailformat. Valid values are jpeg and png.

Video-only settings

sceneChangeThreshold

Can be used to control GOP structure based on scene changes for mpeg2video. By default, GOPs are adjusted according to detected scene changes. Set to a very high number (1000000000) to disable scene change detection in order to get equal-sized GOPs.

noTimeCodeTrack

If true, do not write time code track. Primarily used for MP4 and MOV containers.

Image-only settings

colorspace

Sets the color space to specified value. Valid values are CIELab, CMY, CMYK, Gray, HCL, HCLp, HSB, HSI, HSL, HSV, HWB, Lab, LCH, LCHab, LCHuv, LMS, Log, Luv, OHTA, Rec601Luma, Rec601YCbCr, Rec709Luma, Rec709YCbCr, RGB, scRGB, sRGB, Transparent, XYZ, YCbCr, YDbDr, YCC, YIQ, YPbPr, YUV.

In addition, colorspace can be set as demuxerSetting as well. This works for PDF and PS files, and will cause PDF/PS parsing to generate result in the correct color space already when reading the file.

profile

Sets a profile. Profiles must be installed on transcoder node ( /usr/share/color/icc).

The transcoder now comes preinstalled with the most common profiles.

A special profile is added, detect-xmp. The profile will read the profile from XMP metadata and use that profile. An example, that will read the XMP profile and then set sRGB:

<TranscodePresetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  ...
  <setting>
    <key>profile</key>
    <value>detect-xmp</value>
  </setting>
  <setting>
    <key>profile</key>
    <value>sRGB</value>
  </setting>
</TranscodePresetDocument>

scaling algorithm

New in version 21.3.

It is possible to select which scaling algoritm that should be used when scaling the video.

Accepted values:

  • SWS_FAST_BILINEAR - Bilinear scaling with some short cuts to give higher performance.
  • SWS_BILINEAR - Bilinear scaling, uses a 2x2 environment of a pixel and then takes the average of these pixels to interpolate the new value.
  • SWS_BICUBIC - Bicubic scaling, uses a 4x4 environment of a pixel, weighing the innermost pixels higher, and then takes the average to interpolate the new value.
  • SWS_X - FFmpeg experimental algorithm.
  • SWS_POINT - Fastest, uses closest point, gives a pixelated result when upscaling, might give ok result for down scaling
  • SWS_AREA - Uses a mapping of source and destination pixels, averaging the source pixels with regards to the fraction of destination pixels that are covered.
  • SWS_BICUBLIN - Uses bicubic scaling for luma values, and bilinear for croma values.
  • SWS_GAUSS - Gaussian scaling, usually used for computer vision, not very useful for video.
  • SWS_SINC - Uses higher-order polynomials and are therefore harder to compute than bicubic interpolation.
  • SWS_LANCZOS - Resampling involves a sinc filter as well. It is more computationally expensive.
  • SWS_SPLICE - Use higher-order polynomials and are therefore harder to compute than bicubic interpolation.

Changed in version 21.3.

The default value is SWS_BICUBIC, in older version SWS_FAST_BILINEAR was used.

<TranscodePresetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  ...
  <setting>
    <key>scaling_mode</key>
    <value>SWS_BICUBIC</value>
  </setting>
</TranscodePresetDocument>

strip

If true, strip profile info. If false, do not strip profile.

density

Set the density (resolution) of the image. The format is xRes[ "x" yRes] WHITESPACE ( "dpi" | "dpcm" ). If only one value is set, the same resolution is used for x and y. By specifying dpi or dpcm, resolution can explicitly be set to mean pixels per inch or pixels per centimeter, respectively.

sharpen

If true, sharpens the image. May produce better results after scaling.

alpha extraction

New in version 5.0.

Accepted values:

  • keep_alpha - The alpha value is kept and the color and luminance information is discarded.
  • discard_alpha - The alpha information is discarded and the color and luminance information is kept.

Normally, if you have a source video with an alpha layer and transcode it to a format that doesn’t support alpha, the alpha information is taken into account when calculating the color and luminance of the output video. By using one of the above values, you can filter out the alpha or color and luminance components of the pixels.

Muxer settings

streamOrder

Controls in which order streams are numbered in the output. Comma separated list of audio, video, subtitle.

Demuxer settings

extract closed captions

It is possible to extract EIA-608(also known as “line 21 captions”) from source file and store it in item metadata by specifying extract_closed_captions = true in demuxerSetting.

From version 5.7, it is possible to extract all caption tracks, both EIA-608 and CEA-708, by specifying extract_closed_captions = mcc in demuxerSetting. The caption metadata vill contain a new field stl_service that shows what service it belongs to, CC1 or CC3 for EIA-608 and S1 to S64 for CEA-708.

Example: preset with extract_closed_captions=true

PUT /shape-tag/extract_CC
Content-Type: application/xml

<TranscodePresetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <format>mp4</format>
  <audio>
    <codec>aac</codec>
  </audio>
  <video>
    <codec>h264</codec>
  </video>
  <demuxerSetting>
    <key>extract_closed_captions</key>
    <value>true</value>
  </demuxerSetting>
</TranscodePresetDocument>
200 OK

Example: transcode using previously defined preset

PUT item/VX-82/transcode?tag=extract_CC
200 OK

When the job is finished item metadata will contain extracted closed caption Subtitles if the extraction was successful.

Sequence render color settings

New in version 5.4.

A normal transcode operations only operates in YUV color space, and does not change the YUV values. However, a sequence rendering operation takes place in RGB color space, and gives the user more options with regards to output color space. There are four settings, added as video setting key-values pairs.

Note

Default values are unknown/unspecified. If you are unsure, use bt709.

Color matrix

Key: colorMatrix

Available values:

  • gbr
  • bt709
  • unknown
  • reserved
  • fcc
  • bt470bg
  • smpte170m
  • smpte240m
  • ycgco
  • bt2020nc
  • bt2020c
  • smpte2085
  • chroma-derived-nc
  • chroma-derived-c
  • ictcp

Color transfer function

Key: colorTransferFunction

Available values:

  • reserved
  • bt709
  • unknown
  • reserved
  • bt470m
  • bt470bg
  • smpte170m
  • smpte240m
  • linear
  • log100
  • log316
  • iec61966-2-4
  • bt1361e
  • iec61966-2-1
  • bt2020-10
  • bt2020-12
  • smpte2084
  • smpte428
  • arib-std-b67

Color primaries

Key: colorPrimaries

Available values:

  • reserved
  • bt709
  • unknown
  • reserved
  • bt470m
  • bt470bg
  • smpte170m
  • smpte240m
  • film
  • bt2020
  • smpte428
  • smpte431
  • smpte432
  • ebu3213

RGB sample bit resolution

While the conversion between YUV and RGB is lossless and reversible in theory, round-off errors may occur. By setting the internal RGB sample width to 16, these errors are eliminated.

Key: renderQuality

Available values:

  • 8 (default)
  • 16