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
Scripting transcode presets
Transcode preset elements
Image transcode settings

Transcode presets ¶

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

Use one of the built in preset templates.
Use one of the presets defined in this documentation.
Define your own preset. See Transcode preset elements for more information.

Preset templates¶

New in version 4.0.3.

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));

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¶

New in version 4.0.

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¶

New in version 4.0.

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

Setting a maximum duration of a chunk in QuickTime files¶

New in version 4.1.

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¶

New in version 4.0.

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="0.5"/>
      <input channel="1" stream="1" gain="1.0"/>
      <input channel="3" stream="1" gain="1.0"/>
      <input channel="5" stream="1" gain="1.0"/>
    </mix>
    <mix>
      <input channel="1" stream="1" gain="1.5"/>
      <input channel="2" stream="1" gain="1.0"/>
      <input channel="4" stream="1" gain="1.0"/>
      <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¶

New in version 4.1.

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¶

New in version 4.1.1.

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:

A WAV file containing 1 audio stream with 2 channels.
A MOV file containing 2 audio streams, each stream has one channel.
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>

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.

Example: overlaying a logo¶

<TranscodePresetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  ...
  <overlay>
    <uri>http://example.com/logo.png</uri>
    <x>10</x>
    <y>30</y>
  </overlay>
</TranscodePresetDocument>

Image transcode settings ¶

Image-to-image transcoding uses the same resolution settings etc. as video jobs. There are some custom settings that can be added in presets for certain image control. They are added using setting element inside the video element.

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.

profile¶

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

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.

Shape tags and presets¶

Transcode presets¶

Preset templates¶

Scripting transcode presets¶

Examples¶

A preset that only produces two audio channels in the output¶

Scaling the output depending on the input¶

Transcode preset elements¶

Setting a preferred source tag¶

Burning in the timecode in the video¶

Setting a maximum duration of a chunk in QuickTime files¶

Example: setting the maximum chunk duration to 2 seconds¶

Mixing audio channels¶

Example: mixing 5.1 audio into stereo¶

Example: adding two silent audio channels in output¶

Splitting audio channels to mono files¶

Example: split specific channels¶

Example: split all channels¶

Splitting audio channels to different output files¶

Example¶

Image overlays¶

Example: overlaying a logo¶

Image transcode settings¶

colorspace¶

profile¶

strip¶

density¶

Transcode presets ¶

Scripting transcode presets ¶

Transcode preset elements ¶

Image transcode settings ¶