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 type, url, container (technical metadata) and metadata (user defined metadata).

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.

{
  "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.

{
  "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.

{
  "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	Tooltip to show when hovering over a marker
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.

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

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.