Launch template format

The launch template consists of three main parts

data - session data
endpoints - endpoints for outgoing communication
settings - settings to use

Here is an example of a launch template.

launch-template.json
{
  "data": {
    "assets": [
      {
        "id": "123",
        "creationDate": "1977-05-04T13:37:00.000Z",
        "updateDate": "1977-05-25T13:37:00.000Z",
        "metadata": [
          {
            "key": "title",
            "value": "Example asset"
          }
        ],
        "files": [
          {
            "id": "234",
            "type": "VIDEO",
            "url": "https://example.com/video.mp4",
            "container": {
              "videoStreams": [
                {
                  "frameRateNumerator": 30,
                  "frameRateDenominator": 1
                }
              ],
              "audioStreams": [
                {
                  "channels": 2
                }
              ]
            },
            "metadata": [
              {
                "key": "language",
                "value": "en"
              }
            ]
          },
          {
            "url": "https://example.com/audio.mp4",
            "type": "AUDIO",
            "container": {
              "audioStreams": [
                {
                  "channels": 2
                }
              ]
            }
          },
          {
            "type": "SUBTITLE",
            "url": "https://example.com/subtitle.vtt",
            "container": {
              "format": "vtt"
            }
          },
          {
            "type": "SUBTITLE",
            "url": "https://example.com/subtitle.stl",
            "container": {
              "format": "stl",
              "startTime": {
                "frame": 3600,
                "numerator": 1,
                "denominator": 1
              }
            }
          },
          {
            "type": "STILL_FRAME",
            "url": "https://example.com/thumbnail.001.jpg",
            "metadata": [
              {
                "key": "still_frame:timestamp",
                "value": "27361@24:1"
              }
            ]
          },
          {
            "type": "SPRITE_MAP",
            "url": "https://example.com/spritemap.jpg",
            "manifest": {
              "width": 240,
              "height": 135,
              "sprites": [
                {
                  "x": 0,
                  "y": 0,
                  "t": 13152384000
                }
              ]
            }
          },
          {
            "type": "WAVEFORM",
            "url": "https://example.com/waveform.dat",
            "metadata": [
              {
                "key": "waveform:source_file_id",
                "value": "234"
              },
              {
                "key": "waveform:track",
                "value": "0"
              }
            ]
          }
        ],
        "markerGroups": [
          {
            "title": "Group title",
            "readOnly": false,
            "markerStyle": {
              "backgroundColor": "var(--AP-SUCCESS)"
            },
            "markerTracks": [
              {
                "title": "Track title",
                "markers": [
                  {
                    "metadata": [
                      {
                        "key": "name",
                        "value": "Marker name"
                      },
                      {
                        "key": "description",
                        "value": "Marker description"
                      }
                    ],
                    "start": {
                      "frame": 100,
                      "numerator": 24,
                      "denominator": 1
                    },
                    "end": {
                      "frame": 9000,
                      "numerator": 24,
                      "denominator": 1
                    }
                  }
                ]
              }
            ]
          }
        ]
      }
    ],
    "project": {
      "metadata": [
        {
          "key": "av_frame_rate_numerator",
          "value": "24"
        },
        {
          "key": "av_frame_rate_denominator",
          "value": "1"
        },
        {
          "key": "av_drop_frame",
          "value": "false"
        },
        {
          "key": "av_aspect_ratio_width",
          "value": "256"
        },
        {
          "key": "av_aspect_ratio_height",
          "value": "109"
        }
      ],
      "segments": [
        {
          "start": {
            "frame": 0,
            "numerator": 24,
            "denominator": 1
          },
          "end": {
            "frame": 121,
            "numerator": 24,
            "denominator": 1
          },
          "metadata": [
            {
              "key": "z-index",
              "value": "0"
            },
            {
              "key": "source-in",
              "value": "0"
            },
            {
              "key": "source-out",
              "value": "3557400000"
            },
            {
              "key": "track-type",
              "value": "V"
            },
            {
              "key": "track",
              "value": "V0"
            },
            {
              "key": "source-track",
              "value": "0"
            },
            {
              "key": "source-channel",
              "value": "0"
            },
            {
              "key": "target-track",
              "value": "0"
            },
            {
              "key": "source-rate-drop-frame",
              "value": "false"
            },
            {
              "key": "source-asset-id",
              "value": "123"
            },
            {
              "key": "source-file-id",
              "value": "234"
            }
          ]
        }
      ]
    }
  },
  "endpoints": {
    "publish": {
      "download": false,
      "http": {
        "url": "https://example.com/export",
        "method": "POST",
        "headers": {
          "Authorization": "Bearer ..."
        }
      }
    }
  },
  "settings": {
    "features": {
      "videoContextMenu": false
    }
  }
}

Data

Contains all session data. Information about the assets that are to be opened. It is possible to define multiple assets although in most cases a single asset is sufficient.

Asset Files

An asset can hold multiple files. Typically, files consist of a id, type, url, container (technical metadata) and metadata (user defined metadata).

id is optional but helps with identifying the file when you publish your changes. An autogenerated id is used if it is not set explicitly.

Video

MP4 video files are analyzed on the fly to extract container information like frame rate and channel count. HLS/DASH streams are not analyzed, and format, frame rate and audio channel counts needs to be added manually.

{
  "id": "234",
  "type": "VIDEO",
  "url": "https://example.com/dash_video.mpd",
  "container": {
    "format": "dash",
    "videoStreams": [
      {
        "frameRateNumerator": 24,
        "frameRateDenominator": 1
      }
    ],
    "audioStreams": [
      {
        "channels": 2
      }
    ]
  },
  "metadata": [
    {
      "key": "language",
      "value": "en"
    }
  ]
}

Container

The frontend application will try to figure out some of these properties by analyzing the file. Information provided in the launch template will however always take precedence over the file analysis.

Container property	Required	Description
`format`	No	The video file format. Needs to be set to `dash` for MPEG Dash manifests (.mpd) and `hls` for HLS manifests (.m3u8). It does not need to be set for simple video proxies, played with progressive download.
`startTime`	No	The start time offset for the video. Specified as a time code object. This example uses a start time offset of 1 hour (`01:00:00:00`): `{ "frame": 3600, "numerator": 1, "denominator": 1}`
`videoStreams`	No	Array of videoStream objects
`audioStreams`	No	Array of audioStream objects
`subtitleStreams`	No	Array of subtitleStream objects

Video stream object

Video stream property	Required	Type	Description
`timeBaseNumerator`	No	`number`	Time base numerator
`timeBaseDenominator`	No	`number`	Time base denominator
`duration`	No	`number`	Duration of the video stream in the provided time base
`frameRateNumerator`	No	`number`	Video frame rate numerator
`frameRateDenominator`	No	`number`	Video frame rate denominator
`resolutionWidth`	No	`number`	Video resolution width
`resolutionHeight`	No	`number`	Video resolution height
`aspectRatioWidth`	No	`number`	Video aspect ratio width
`aspectRatioHeight`	No	`number`	Video aspect ratio height
`metadata`	No	`array`	Array of key/value pairs. ex: `[{ "key": "the key", "value": "the value" }]`
`bitrate`	No	`number`	bitrate information, used for display purposes only
`codec`	No	`string`	codec information, used for display purposes only

Audio stream object

Audio stream property	Required	Type	Description
`timeBaseNumerator`	No	`number`	Time base numerator
`timeBaseDenominator`	No	`number`	Time base denominator
`duration`	No	`number`	Duration of the video stream in the provided time base
`sampleRate`	No	`number`	The sample rate
`channels`	No	`number`	The number of channels in the stream
`metadata`	No	`array`	Array of key/value pairs. ex: `[{ "key": "the key", "value": "the value" }]`
`bitrate`	No	`number`	bitrate information, used for display purposes only
`codec`	No	`string`	codec information, used for display purposes only

Subtitle stream object

Subtitle stream property	Required	Type	Description
`metadata`	No	`array`	Array of key/value pairs. ex: `[{ "key": "the key", "value": "the value" }]`

Audio

Audio files are not analyzed. They require channel count information to be provided.

{
  "id": "456",
  "type": "AUDIO",
  "url": "https://example.com/audio.mp4",
  "container": {
    "audioStreams": [
      {
        "channels": 2
      }
    ]
  }
}

Container

Container property	Required	Description
`audioStreams`	No	Array of audioStream objects

Subtitle

Subtitle files are not analyzed. They require container format to be defined.

{
  "id": "789",
  "type": "SUBTITLE",
  "url": "https://example.com/subtitle.vtt",
  "container": {
    "format": "vtt",
    "startTime": {
      "frame": 3600,
      "numerator": 1,
      "denominator": 1
    }
  }
}

Container

Container property	Required	Description
`format`	Yes	The subtitle/caption format. One of: `srt`, `vtt`, `scc`, `pac`, `imsc`, `.cap`, `.ìtt` or `stl`
`startTime`	No	The start time offset for the time codes in the file. Specified as a time code object. This example uses a start time offset of 1 hour (`01:00:00:00`): `{ "frame": 3600, "numerator": 1, "denominator": 1}`

Thumbnails - Still Frame

Thumbnails as still frames, one thumbnail per image file.

{
  "type": "STILL_FRAME",
  "url": "https://example.com/thumbnail.001.jpg",
  "metadata": [
    {
      "key": "still_frame:timestamp",
      "value": "27361@24:1"
    }
  ]
}

Metadata Key	Required	Description
`still_frame:timestamp`	Yes	Timestamp of still frame. Format `timestamp@timebase_numerator:timebase_denominator`. Example: Frame `123` on a video with `29.97` fps would be described as `123@30000:1001`

Thumbnails - Sprite Map

Thumbnails as sprite map, multiple thumbnails per image file.

{
  "type": "SPRITE_MAP",
  "url": "https://example.com/spritemap.jpg",
  "manifest": {
    "width": 240,
    "height": 135,
    "sprites": [
      {
        "x": 0,
        "y": 0,
        "t": 13152384000
      },
      ...
    ]
  }
}

Sprite Map Manifest

{
  "width": 240,
  "height": 135,
  "sprites": [
    {
      "x": 0,
      "y": 0,
      "t": 13152384000
    }
  ]
}

Key	Required	Type	Description
`width`	Yes	`number`	Width of thumbnails.
`height`	Yes	`number`	Height of thumbnails.
`sprites`	Yes	`array`	Array of sprites, describing the coordinate and the timestamp of a single thumbnail

Sprites

Key	Required	Type	Description
`x`	Yes	`number`	x coordinate (horizontal) in pixels from the upper left corner of the image. 0 is the left edge of the image.
`y`	Yes	`number`	y coordinate (vertical) in pixels from the upper left corner of the image. 0 is the top edge of the image.
`t`	Yes	`number`	Timestamp of thumbnail in Flicks

Waveforms

Waveform files requires source file information to match an audio or video file. We currently support the formats generated by audiowaveform.

{
  "type": "WAVEFORM",
  "url": "https://example.com/waveform.dat",
  "metadata": [
    {
      "key": "waveform:source_file_id",
      "value": "VIDEO-1"
    },
    {
      "key": "waveform:track",
      "value": "0"
    }
  ]
}

Metadata Key	Required	Description
`waveform:source_file_id`	Yes	The source file id, this should match the `id` of the video or audio file this waveform was generated from
`waveform:track`	Yes	The source track index

Asset Markers

Asset markers are defined through the markerGroups property.

{
  "markerGroups": [
    {
      "title": "Group title",
      "readOnly": false,
      "markerStyle": {
        "backgroundColor": "var(--AP-SUCCESS)"
      },
      "markerTracks": [
        {
          "title": "Track title",
          "isDefaultTrackForMarkerCreation": true,
          "markers": [
            {
              "metadata": [
                {
                  "key": "name",
                  "value": "Marker name"
                },
                {
                  "key": "description",
                  "value": "Marker description"
                }
              ],
              "start": {
                "frame": 100,
                "numerator": 24,
                "denominator": 1
              },
              "end": {
                "frame": 9000,
                "numerator": 24,
                "denominator": 1
              },
              "markerStyle": {
                "backgroundColor": "var(--AP-SUCCESS)"
              }
            }
          ]
        }
      ]
    }
  ]
}

Marker group

Property	Required	Type	Description
`title`	Yes	`string`	Title to show in timeline
`markerTracks`	Yes	`array`	Array of tracks included in the marker group, see Marker track
`id`	No	`string`	Identifier for the group
`markerStyle`	No	`string`	Style for all markers within this group, see Marker style
`readOnly`	No	`boolean`	When set to `true` it prevents the user from adding markers to the group
`allowCreateTrack`	No	`boolean`	When set to `true` it allows user to manually create tracks in the UI for the group

Marker track

Property	Required	Type	Description
`title`	Yes	`string`	Title to show in timeline
`id`	No	`string`	Identifier for the track
`markers`	No	`array`	Array of markers included in the track, see Marker
`markerStyle`	No	`string`	Style for all markers within this track, see Marker style
`readOnly`	No	`boolean`	When set to `true` it prevents the user from adding markers to the track
`form`	No	`string`	Specifies what form to be used for the track. If no form is specified the form with key "defaultMarker" will be used. If set to `null`, no form will be used.
`tooltip`	No	`string`	A template string configuring the tooltip display value when hovering a marker, default is `%name`. See Tooltip
`isDefaultTrackForMarkerCreation`	No	`boolean`	When set to `true`, this track is the default track selected when creating markers. Can only be set to true on *one* marker track. If not set on any track, the first writeable track is selected.

The tooltip when hovering a marker can be configured on the marker track.

The format of the configuration variable is a template string where the keys in the marker metadata are available for use.

 {
  "metadata": [
    {
      "key": "name",
      "value": "Marker name"
    },
    {
      "key": "description",
      "value": "Marker description"
    }
  ]
}

Given the marker metadata keys above, an example of the tooltip configuration field could look like this:

"tooltip": "The name of the marker is %name and the description is %description"

which would render the following result:

The name of the marker is Marker name and the description is Marker description

Marker

Property	Required	Type	Description
`start`	Yes	`object`	A timecode object containing information about the start time of the marker
`end`	Yes	`object`	A timecode object containing information about the end time of the marker
`metadata`	No	`array`	Array of Metadata

Metadata

Property	Required	Type	Description
`key`	Yes	`string`	The metadata key
`value`	Yes	`string`	The value

Timecode

Property	Required	Type	Description
`frame`	Yes	`number`	The frame representing the time
`numerator`	Yes	`number`	Used for calculating the framerate
`denominator`	Yes	`number`	Used for calculating the framerate

Marker style

  {
    "markerStyle": {
      "hover": {
        "backgroundColor": "red",
        "opacity": "1",
        "borderWidth": 1,
        "borderColor": "white",
        "borderRadius": "10"
      },
      "selected": {
        "backgroundColor": "red",
        "opacity": "1",
        "borderWidth": 1,
        "borderColor": "white",
        "borderRadius": "10"
      },
      "disabled": {
        "backgroundColor": "red",
        "opacity": "1",
        "borderWidth": 1,
        "borderColor": "white",
        "borderRadius": "10"
      }
    }
  }

The markerStyle property can be set on either group level, track level or marker level. Setting markerStyle on group level will add the marker style on all markers in that group, setting markerStyle on track level will add the marker style to all markers in that track and setting it on marker level will add that marker style to the individual marker.

Precedence

Marker level > Track level > Group level

Endpoints

The endpoints object literal describes outgoing communication for the session, how data is published, for example.

  "endpoints": {
    "publish": {
      "download": true,
      "http": {
        "url": "https://example.com/publish",
        "method": "POST",
        "headers": {
          "Authorization": "Bearer ..."
        }
      }
    }
  },

publish

Key	Required	Type	Description
`download`	No	`boolean`	Download data as a .json file. This is useful when debugging.
`http`	No	`object`	Pass data through `http`. See http.
`includePreviewImageData`	No	`boolean`	Set to `true` to include preview image data when publishing posters in Poster.

http

Key	Required	Type	Alternatives	Default	Description
`url`	Yes	`string`			Url to the target endpoint.
`method`	No	`string`	`POST`, `PUT`, `PATCH`	`POST`	HTTP method to use.
`headers`	No	`object`			Headers to use in request.

Authentication

Note that if authentication is enabled, the Authorization header will be used in the http call unless overridden in http.headers.Authorization

Settings

The settings property allows you to configure the settings described here.

{
  "data": [
    ...
  ],
  "settings": {
    "features": {
      "videoContextMenu": false
    }
  }
}

Settings can also be provided as a list of settings objects, in that case they are merged in the order they appear. This is useful if you want to use $ref references.

Remote JSON References

The launch template format allows the use of JSON Schema $ref references. This is useful if you want to split the launch template up in different parts. You could for example keep settings that seldom change in a separate file hosted somewhere else.

{
  "data": [
    ...
  ],
  "settings": [
    {
      "$ref": "https://example.com/remote/settings.json"
    },
    {
      "retention": "P2W"
    }
  ]
}

Remote references ($ref) will be resolved before the launch template is opened. Let's say https://example.com/remote/settings.json contains:

{
  "safeAreas": [
    {
      "name": "16:9",
      "url": "https://example.com/safeareas/16-9.png",
      "aspectRatio": "16:9"
    },
    {
      "name": "4:3",
      "url": "https://example.com/safeareas/4-3.png",
      "aspectRatio": "4:3"
    }
  ]
}

This would result in the following settings object after de-referencing and merging:

{
  "safeAreas": [
    {
      "name": "16:9",
      "url": "https://example.com/safeareas/16-9.png",
      "aspectRatio": "16:9"
    },
    {
      "name": "4:3",
      "url": "https://example.com/safeareas/4-3.png",
      "aspectRatio": "4:3"
    }
  ],
  "retention": "P2W"
}

info

JSON references ($ref) works in all parts of the launch template, not just the settings block that is exemplified here. There is one exception and that is the settings.forms key. Custom forms are dereferenced when they are used instead of when the launch template is read.

Data​

Asset Files​

Video​

Container​

Video stream object​

Audio stream object​

Subtitle stream object​

Audio​

Container​

Subtitle​

Container​

Thumbnails - Still Frame​

Thumbnails - Sprite Map​

Sprite Map Manifest​

Sprites​

Waveforms​

Asset Markers​

Marker group​

Marker track​

Tooltip​

Marker​

Metadata​

Timecode​

Marker style​

Precedence​

Endpoints​

publish​

http​

Settings​

Remote JSON References​

Data

Asset Files

Video

Container

Video stream object

Audio stream object

Subtitle stream object

Audio

Container

Subtitle

Container

Thumbnails - Still Frame

Thumbnails - Sprite Map

Sprite Map Manifest

Sprites

Waveforms

Asset Markers

Marker group

Marker track

Tooltip

Marker

Metadata

Timecode

Marker style

Precedence

Endpoints

publish

http

Settings

Remote JSON References