1. INTRODUCTION

MIST Studio offers the ability to be controlled by a third-party system using Marquise Technologies' STORM API

There is 2 ways of communication with the application:

  • A Command Line Interface

  • A REST Interface

This document describes the STORM API.

1.1. Legal Information

1.1.1. Copyright Notice

All rights reserved. No part of this document may be reproduced, copied or transmitted in any form by any means electronic, mechanical or otherwise without the permission of Marquise Technologies sàrl. If you are interested in receiving permissions for reproduction or excerpts, please contact us at contact@marquise-tech.com

1.1.2. Trademarks

Marquise Technologies, the logo and MIST are trademarks of Marquise Technologies sàrl.

All other trademarks mentioned here within are the property of their respective owners.

1.1.3. Notice of Liability

The information in this document is distributed and provided “as is“ without warranty.

While care has been taken during the writing of this document to make the information as accurate as possible, neither the author or Marquise Technologies sàrl shall not be held responsible for losses or damages to any person or entity as a result of using instructions as given in this document.

1.1.4. Disclaimer of Warranty

*THIS SOFTWARE AND THE ACCOMPANYING FILES ARE PROVIDED "AS IS" AND WITHOUT WARRANTIES AS TO PERFORMANCE OR MERCHANTABILITY OR ANY OTHER WARRANTIES WHETHER EXPRESSED OR IMPLIED.

NO WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE IS OFFERED.*

STORM API

Version 2021

Application Programming Interface

1. About STORM API

Storm is the name of the engine powering all the software applications of Marquise Technologies. It’s API is described in the following sections:

  • Operational Contexts

  • Command Line Interface

  • REST API

  • STORM API References

2. Operational contexts

Each job supported by STORM will require an operational context as the main parameter. The context defines the kind of task that must be performed.

When using the command line interface, the context is the first parameter that is mandated. It also defines the following accepted parameters and options. Below is an example for the usage of the context for the command line interface:

2.1. Command Line Interface example

stormserver mediainfo -i "E:/SOURCE/testFile.mxf" -format pdf -o "E:/RESULT/testFileInfo.pdf"

The exact syntax for the command line interface is explained in the following sections.

2.2. REST API example

When adding a job, the JSON parameters must contain the context definition, otherwise the job will not be added to the queue. Here is an example of how a job context is identified in the JSON parameters:

{
  "context" : "mediainfo",
  "input"   : "E:/SOURCE/testFile.mxf",
  "output"  : "E:/RESULT/testFileInfo.pdf",
  "format"  : "pdf",
  ...
}

2.3. Operational Contexts

The values for the context are described in the table below:

Table 1. Operational Contexts
Context Details

analayze

Creates a content analysis report

enum

Enumerates the various entities supported by the API such a mastering formats, codecs, etc

help

Displays the command line interface usage instructions

masterinfo

Create a mastering information report in various file formats

mediainfo

Create a media information report in various file formats

validate

Creates a QC report for a master in various file formats

xcode

Transcode a file, a composition or a package into various file formats

websrv

Start the STORM API server as a webservice

webwrk

Start the STORM API server as a webworker

For each of the above operatinal contexts, a set of parameters are defined.

2.3.1. xcode Operational Context parameters

Table 2. xcode context parameters
Parameter Name Required/Optional Details

input

Required

Absolute file name of the source file in one of the remote mounted volumes (e.g. "F:/MEDIA/test.mxf").

output

Required

Absolute file name of the destination file in one of the remote mounted volumes (e.g. "G:/RENDERS/result.mov").

format

Optional

Defines the container format (e.g. "quicktime").

preset

Optional

Absolute file name of the XML preset to be used for the output file. It is mutually exclusive with the format parameter.

2.3.2. websrv Operational Context parameters

Table 3. websrv context parameters
Parameter Name Required/Optional Details

workers

Optional

Used to specify the number of worker nodes to be launched as local sub-processes by this node.

service

Optional

If specified than the node can be installed as a system service.

2.3.3. webwrk Operational Context parameters

Table 4. webwrk context parameters
Parameter Name Required/Optional Details

address

Required

Specifies this node’s URL e.g. "http://127.0.0.1"

port

Required

Specifies this node’s communication port.

nodeaddress

Required

Specifies the manager’s node URL with which the worker node should register e.g. "http://127.0.0.1:8080"

2.3.4. Enumerable entities

Table 5. Enumerables
Option Name Details

masters

Displays a list of available master format names

formats

Displays a list of available output file format names

specifications

Displays a list of available specifications

shims

Displays a list of available shims

shimversions

Displays a list of available shium-versions

3. Command Line Interface API

Storm can be used via the command line interface (CLI) just like any other operating system command. This interface is simple and practical for integration into scripts for batch processing and is supported by most of the interpreted languages (e.g. PHP, etc).

The syntax of the command line interface follows a structure based on contexts, actions, objects and options. The general syntax can be described like this:

stormserver [context] [action] [object 1] .. [object n] [option 1] .. [option n]

Example 1:

stormserver enum -masters

The example above enumerates the possible mastering formats.

Example 2:

stormserver mediainfo –i “E:/video.mov” –format “xml” –o “E:/metadata.xml”

The example above extracts the metadata from the file “E:/video.mov” into the file “e:/metadata.xml”.

Please note that the double quotes around options are only necessary when options contain white spaces or characters that would be forbidden in the direct syntax of a regular command line on the operating system. In most cases they can be omitted, however it is always safe to use them.

3.1. Using the CLI on Microsoft Windows systems

To use the command line interface on Microsoft Windows systems, the following steps must be folloed:

  1. Press the Windows key and R (for run)

  2. When the prompt window appears (next to the Windows Start button), type cmd (for command) and press Enter. The console/command line tool should be displayed.

  3. Go to the installation directory using the cd command (change directory):

E:\>cd "Marquise Technologies\x64"

Note that if the installation drive is different than the current drive, the current drive (volume) must be changed by typing the drive/volume letter followed by the column character:

Change current drive

C:\Users\marquise>e:

Change current directory

E:\>cd "Marquise Technologies\x64"

The last step is to type the STORM Server command as illustrated above, followed by the operational context and the list of parameters for the context. After this sequence, STORM Server would start in the specified operational context and will continue with the requested processing.

4. REST Interface

The STORM API can be accessed via the REST (REpresentational State Transfer) interface which allows a scalable, service-oriented use. This interface is simple and practical for integration into scripts for batch processing and is supported by most of the interpreted languages (e.g. PHP, etc).

The STORM API REST interface is implemented via the HTTP protocol. Commands are sent as JSON structured requests.

In the following documentation, cURL is used as a tool to demonstrate the HTTP requests to the STORM API server. cURL is multi-platform free tool and can be obtained here:

http://curl.haxx.se/

4.1. Starting the server

In order to start STORM Server as a REST web service, you must use the following command:

stormserver websrv

The command above will start the STORM server as a web service listening for HTTP requests on port 8080 by default. This will result in the following:

STORM v2021.1.5.0
(C) 2009-2021 Marquise Technologies
Release Date Jan 5 2021
start threadpool
starting up server... done!
listening on port 8080
waiting requests...

At this point the server will keep running until the /control/shutdown request is received or the command line process is killed.

If you wish to change the communication port, the following command must be used:

stormserver websrv –port 1234

STORM Server can also be installed and started as a system service. In order to do so you must specify the -service flag when installing the server as a service.

The following example uses the Windows sc.exe service manager to install then start STORM Server as a service:

sc create "STORMSERVER" binPath="stormserver websrv -service"
sc start "STORMSERVER"

4.2. How jobs are managed

Storm processes media via a list of queued jobs. These jobs can be created directly via the API, or can be spawned automatically by a watchfolder that is actively monitored by a specific node.

Regardless of the manner in which the job has been created, once the job has been added to the queue of jobs, it can be further manipulated like any other regular job.

4.3. Processing graphs

Processing graphs are complex XML descriptions of various image processing, audio processing and transcoding functions that Storm can apply to the media that needs to be processed.

The processing graph can describe one or more outputs, each of the output being the result of a list of daisy-chained processing nodes.

The following example shows a processing graph document basics (incomplete):

<?xml version="1.0" encoding="UTF-8" ?>
<mtprocessinggraph>
  <nodelist>
    <node uuid="12d42cf7-76ea-42ba-bc39-40e684176b08" type="source">
    ...
    </node>
  </nodelist>
  <linklist>
    <link target="13015df7-a165-47a5-9061-50ce646dcfed" input="0" source="12d42cf7-76ea-42ba-bc39-40e684176b08" output="0"/>
    ...
  </linklist>
</mtprocessinggraph>

Each node has a unique id, a type and a list of type-specific parameters

4.3.1. Node linking

The processing order of the nodes is dictated by a list of links that connect the various nodes involved in the processing of an output. This mechanism allows a node to be used in multiple processing combinations within the same graph.

Each link has a target node id (i.e. the next node in the processing chain), as well as an input number. The number of inputs depends on the target, however most nodes have only one input and therefore the input number is usually 0.

In addition to the target description, each link has a source node id (i.e. the previous node in the processing chain), as well as an output number. The number of outputs depends on the source, however most nodes have only one output and therefore the output number is usually 0.

4.3.2. Processable nodes

Only output nodes are actually processed by Storm. Nodes that are not connected to an output are ignored and do not generate any processing.

4.3.3. Processing Graph example

The following example describes a full processing graph with two processing nodes and one ouput node. Also, please note the top node of the type "source", which describes the input media.

<?xml version="1.0" encoding="UTF-8" ?>
<mtprocessinggraph>
  <nodelist>
    <node uuid="12d42cf7-76ea-42ba-bc39-40e684176b08" type="source"/>
    <node uuid="13015df7-a165-47a5-9061-50ce646dcfed" type="lut">
      <annotation>Untitled Output</annotation>
      <filename>E:\Marquise Technologies\x64\luts/HDR 1000 nits to Gamma 2.4.cube</filename>
    </node>
    <node uuid="97ce96df-08f4-4e9e-8fb9-9e4222c687d2" type="imageResize">
      <annotation>Untitled Output</annotation>
      <width>1920</width>
      <height>1080</height>
      <aspectratio>0</aspectratio>
      <fit>3</fit>
      <flip>false</flip>
      <flop>false</flop>
      <expandmethod>0</expandmethod>
      <compressmethod>0</compressmethod>
    </node>
    <node uuid="29b7adb8-24b8-4d30-9420-b436eb6b44fa" type="output">
      <annotation>Untitled Output</annotation>
      <directory>$ProjectName$/$CompositionName$</directory>
      <filename>$ClipName$</filename>
      <container>mxfop1a</container>
      <video>
        <channel>0</channel>
        <codec>dnxhd</codec>
        <quality>hqx</quality>
        <bitdepth>10</bitdepth>
        <colorprimaries>CIEXYZ</colorprimaries>
        <transfercharacteristic>SMPTE.ST2084</transfercharacteristic>
        <codingequations>ITU-R.BT.2020</codingequations>
        <coderange>full</coderange>
        <ST2086Metadata enabled="false">
          <MaximumLuminance>0</MaximumLuminance>
          <MinimumLuminance>0</MinimumLuminance>
          <WhitePointChromaticity>
            <x>0.333333</x>
            <y>0.333333</y>
          </WhitePointChromaticity>
          <Primaries>
            <ColorPrimaryRed>
              <x>0.333333</x>
              <y>0.333333</y>
            </ColorPrimaryRed>
            <ColorPrimaryGreen>
              <x>0.333333</x>
              <y>0.333333</y>
            </ColorPrimaryGreen>
            <ColorPrimaryBlue>
              <x>0.333333</x>
              <y>0.333333</y>
            </ColorPrimaryBlue>
          </Primaries>
        </ST2086Metadata>
      </video>
      <audio>
        <byteorder>little</byteorder>
        <soundfieldlist>
          <soundfield config="51" downmix="no">
            <name>surround mix</name>
            <language>ja</language>
            <mapping/>
          </soundfield>
          <soundfield config="ST" downmix="no">
            <name>stereo downmix</name>
            <language>ja</language>
            <mapping/>
          </soundfield>
        </soundfieldlist>
      </audio>
      <timecode>
        <tcorigin>0</tcorigin>
        <tcstart>00:00:00:00</tcstart>
      </timecode>
    </node>
  </nodelist>
  <linklist>
    <link target="13015df7-a165-47a5-9061-50ce646dcfed" input="0" source="12d42cf7-76ea-42ba-bc39-40e684176b08" output="0"/>
    <link target="97ce96df-08f4-4e9e-8fb9-9e4222c687d2" input="0" source="13015df7-a165-47a5-9061-50ce646dcfed" output="0"/>
    <link target="29b7adb8-24b8-4d30-9420-b436eb6b44fa" input="0" source="97ce96df-08f4-4e9e-8fb9-9e4222c687d2" output="0"/>
  </linklist>
</mtprocessinggraph>

4.4. Working with watchfolders

Storm can handle a list of watchfolders that are actively monitored.

Every new entry (i.e. new file or new directory) into one of the monitored watch folders is checked by Storm against a list of filters attached to a watchfolder.

If the entry matches one of the filters, then a new job is automatically added to the queue of job. The job is described by a processing graph, associated with the watchfolder.

4.4.1. How watchfolders spawn jobs

As described previously, watchfolders monitor specific file system locations for incoming media. Once a media has been accepted by one of the filters associated with the watchfolder, a job is automatically spawned.

The job will process the media using a processing graph or a preset, associated with the watchfolder, when the watchfolder is created.

Once the job is spawned, it is automatically queued to the list of jobs and therefore can be managed as any regular job.

4.4.2. Input and output folders of watchfolder jobs

Each watchfolder descriptor has a definition for an input and an output folder. The input folder is the folder being monitored, the output folder is the location where the results are generated.

4.5. Compositions

Compositions are XML timeline descriptions of various audio, video, subtitles and data elements synchronized together. Storm can process complex compositions and apply various processing operators onto them and generate multiple outputs.

4.5.1. Composition example

The following example shows a simple composition document (incomplete):

<?xml version="1.0" encoding="UTF-8"?>
<axf>
  <project>
    <name>Simple</name>
    <format>
      <width>3840</width>
      <height>2160</height>
      <aspectratio>1:1</aspectratio>
      <framerate>24:1</framerate>
      <cms>
      ...
      </cms>
    </format>
    <composition>
      <name>simple</name>
        <type>2</type>
        <in>0</in>
        <out>750</out>
        <format>
          <width>1920</width>
          <height>1080</height>
          <aspectratio>1:1</aspectratio>
          <framerate>25:1</framerate>
          <cms>
          ...
          </cms>
        </format>
        <soundfieldlist>
          <soundfield>
            <audioconfig>LtRt</audioconfig>
            <mapping>
            ...
            </mapping>
          </soundfield>
        </soundfieldlist>
        <uid>0c85ed19-fb97-405d-ac6b-8c7057cee84a</uid>
        <media>
          <video>
            <layer>
              <name>V1</name>
              <v1>
                <segment type="clip">
                  <name>Clearcast 30sec AD FINAL_1080p_full</name>
                  <uid>46c307d6-e5b5-47b0-ac7a-b7d2f0307861</uid>
                  <in>0</in>
                  <out>750</out>
                  <source>
                    <refname>/Clearcast 30sec AD FINAL_1080p_full.mov</refname>
                    <url>F:\Adstream\Clearcast 30sec AD FINAL_1080p_full.mov</url>
                    <in>0</in>
                    <out>750</out>
                  </source>
                </segment>
              </v1>
            </layer>
          </video>
          <audio>
            <layer>
              <name>Lt</name>
              <routing>
                <channel>0</channel>
              </routing>
              <audiotrack>
                <segment type="clip">
                  <name>Clearcast 30sec AD FINAL_1080p_full</name>
                  <uid>43564d4b-2ddc-4938-b52e-755867df3bc1</uid>
                  <in>0</in>
                  <out>750</out>
                  <groupid>0</groupid>
                  <source>
                    <refname>/Clearcast 30sec AD FINAL_1080p_full.mov</refname>
                    <url>F:\Adstream\Clearcast 30sec AD FINAL_1080p_full.mov</url>
                    <in>0</in>
                    <out>750</out>
                    <routing>
                      <channel>0</channel>
                    </routing>
                  </source>
                </segment>
              </audiotrack>
            </layer>
            <layer>
            ...
            </layer>
          <subtitles>
          ...
          </subtitles>
          <auxdata>
          ...
          </auxdata>
        </media>
      </composition>
    </project>
</axf>

Compositions can have multiple tracks, multiple layers and can deal with complex editing information, just like any NLE timeline.

4.6. Output presets

Output presets are XML descriptions that define the output format for the input media passed to Storm server. They are templates that can be reused when transcoding.

The following example shows a output preset that describes an MP4 container with a h264 encoded video with a 720p resolution:

<?xml version="1.0" encoding="UTF-8" ?>
<MasterDeliverySpecification>
  <Name>720p_H264_MP4_noTCStart</Name>
  <Type>MPEG4</Type>
  <Specification>custom</Specification>
  <Shim>isobmff.mp4</Shim>
  <ShimVersion>default</ShimVersion>
  <Presentation>monoscopic</Presentation>
  <Video>
    <FrameWidthList>
      <FrameWidth>1280</FrameWidth>
    </FrameWidthList>
    <FrameHeightList>
      <FrameHeight>720</FrameHeight>
    </FrameHeightList>
    <FrameRateList>
      <FrameRate>24:1</FrameRate>
    </FrameRateList>
    <Codec>
      <Id>h264</Id>
      <ColorEncoding>YCbCr.4:2:2</ColorEncoding>
      <Profile>baseline</Profile>
    </Codec>
    <Colorimetry>
      <ColorSpace>custom</ColorSpace>
      <CodeRange>head</CodeRange>
    </Colorimetry>
  </Video>
  <Audio>
    <Codec>
      <Id>aac</Id>
    </Codec>
    <SoundfieldList/>
  </Audio>
</MasterDeliverySpecification>

For a detailed description of the Output Preset file format see: MT-TN-20 Output Preset File Format Specification

5. About STORM node architecture

5.1. Manager and Worker nodes

When starting STORM Server in webserver mode, via the websrv operational context, it will automatically accept and handle jobs via an internally managed job queue. This means that the process will handle REST request and jobs on the same node. In this case the job queue is treated sequentially on job at a time.

STORM Server can also be used as a manager node. In this case it has a registered list of worker nodes that handle the received jobs while the manager node is used to distribute jobs and control the worker pool.

5.2. Creating Worker nodes

A STORM Server worker node can be started as a subprocess of a manager node or as a standalone webserver.

A subprocess worker node can only be created by a manager node and it can only run locally on the same machine as the manager.

A standalone worker node can only be created by an external process and it can run locally or remotely.

In both cases a worker always needs to register with a manager node when started.

5.2.1. Starting Worker nodes as subprocesses

In order to start workers as subprocesses, a manager node must be first started, via the CLI, with the -workers command option followed by the number of workers to be spawned.

Example starting a manager node with 4 workers as subprocesses:

stormserver websrv -workers 4

5.2.2. Starting Worker nodes manually

A worker node can be started manually or via an automated script used by an external application. In this case prior knowledge of existing manager nodes and their addresses is required as a worker can be started only if it can register with a manager node.

Example starting a worker node with a given manager:

stormserver webwrk -address "http://192.168.1.10" -port 6060 -nodeaddress "http://192.168.10.1:8080"

The above command will start a worker on a machine with the given address and on the specified port. The worker will try to register with a manager node having the address specified by the nodeaddress parameter.

5.3. Managing workers

In a standard configuration, STORM Server processes media via a list of queued jobs managed on a single, local node. These jobs are handled sequentially, one at a time.

There are cases when multiple nodes are required to handle jobs. In that case some of those nodes will be workers.

Workers can be managed by using the dedicated workers REST API available on the manager node on which they are registered.

STORM API Reference

1. Compositions

1.1. Obtain the list of compositions

Storm maintains a list of compositions that can be obtained at any time. The following example shows you how to obtain the list of compositions registered on a given node:

URL: /compositions METHOD: GET

Table 6. Request structure
Access Details

URL

/compositions

Query Params

To be added

Method

GET

1.1.1. Request

Request example (curl)

curl "http://127.0.0.1:8080/compositions"

1.1.2. Response

Response structure:
{
	"status" : "ok",
	"compositions" :
	[
		{
			"uuid" : "0326122f-3273-4700-af80-4c4e5d34fcdb",
			"name" : "single clip edit"
		},
		{
			"uuid" : "ab737d47-ce37-401b-8886-f483a9b9904b",
			"name" : "main program with color bars inserted",
		}
	]
}

1.2. Add a new composition

The following example shows you how to add a new composition to the list managed by a specific node:

Table 7. Request structure:
Access Details

URL

/compositions

Method

POST

1.2.1. Request

Request example:
curl -X POST -H "Content-Type: text/xml" -T E:/simple_composition.xml “http://127.0.0.1:8080/compositions”

1.2.2. Parameters

The command sends an XML composition to be added to the list of managed compositions. No other parameters are associated with this command.

1.2.3. Response

The response contains the status of the operation as well as the different timestamps associated with the request.

A UUID is assigned to the new composition and included in the response. This unique ID can be used for retrieval and further managing the composition after it’s creation.

Response example:
{
    "uuid": "ae81f492-04f5-43d1-b766-64dcbb97dc3b",
    "status": "ok",
    "name": "Simple",
    "filename": "<user-home>/TORNADO/users/<username>/session/compositions/ae81f492-04f5-43d1-b766-64dcbb97dc3b.axf"
}

1.3. Delete a composition

The following example shows you how to delete a composition from the list of compositions managed by a specific node:

Table 8. Request Structure:
Access Details

URL

/compositions/{composition UUID}

METHOD

DELETE

1.3.1. Request

Request example:
curl -X DELETE "http://127.0.0.1:8080/compositions/13ff097c-d4c9-43c0-a272-fb69a7a062e0"

1.3.2. Response

The response is the status of the operation.

Response example:
{
  "status" : "ok",
}

The following table shows the possible status codes that this function can return

Table 9. Status codes
Status Details

ok

The composition was successfully deleted.

error

The composition cannot be found in the list of managed processing graphs by this node.

busy

The composition is currently in use and cannot be deleted.

2. Nodes Control

2.1. Controlling nodes via the REST API

STORM Server nodes can be controlled via the dedicated REST API. The API can be used to put in place automated polling mechanisms that check the status, shuts down or restarts nodes.

2.2. Check the status of a node

The following example shows you how to check the status of a node:

Table 10. Request structure:
Access Details

URL

/control/status

Method

GET

2.2.1. Request

curl -X GET “http://127.0.0.1:8080/control/status”

2.2.2. Response

The response is the status of the operation:

{
    "status": "ok"
}

If an error occurs in the communication the node will not respond.

2.3. Shutting down a node

Shutting down a node will terminate the process and all managed workers registered with this node.

This operation will block until all registered nodes will be shutdown. This should be taken into account when implementing timeouts for this call.

The following example shows you how to shutdown a node:

Table 11. Request structure:
Access Details

URL

/control/shutdown

Method

POST

2.3.1. Request

curl -X POST “http://127.0.0.1:8080/control/shutdown”

2.3.2. Response

The response is the status of the operation:

{
    "status": "ok"
}

If an error occurs in the communication the node will not respond.

3. Jobs

3.1. Obtain the list of jobs

Storm maintains a list of jobs that can be obtained at any time. This is the easiest method to get the status of all the running or pending jobs. The following example shows you how to obtain the list of jobs currently running or pending on a given node:

Table 12. Request structure
Access Details

URL

/jobs

METHOD

GET

3.1.1. Request

curl "http://127.0.0.1:8080/jobs"

3.1.2. Response

{
	"status" : "ok",
	"jobs" :
	[
		{
			"uuid" : "977a2c65-b4d4-4848-9464-8aefd52538e7",
			"status" : "queued",
			"progress" : "0"
		},
		{
			"uuid" : "887b12ee-30f1-4059-afff-db3e89a4e270",
			"status" : "queued",
			"progress" : "0"
		}
	]
}

3.2. Get job description

URL: /job/<uuid> METHOD: GET

3.2.1. Request

curl "http://host:8080/joblist/12345/description"

3.2.2. Response

{
	"uuid" : "12345"
	"name" : "hello"
	"context" : "xcodeimf"
}

3.3. Add a new job

The following example shows you how to add a new job to the list of jobs of a specific node:

Table 13. Request structure:
Access Details

URL

/jobs

Method

POST

3.3.1. Request

curl -X POST -T "e:/job_parameters.json" “http://127.0.0.1:8080/jobs”

3.3.2. Parameters

Parameter Name Value Description

context

string

Mandatory parameter. Defines the operational context of the job. See Operational Contexts for more information.

input

string

Mandatory parameter. The path of the input file or folder for the job.

output

string

Mandatory parameter. The path of the output file or folder for the job.

master

string

Optional parameter. A fixed text string value defined in a controlled vocabulary. It cannot be used together with the preset parameter

format

string

Optional parameter. A fixed text string value defined in a controlled vocabulary that defines the container format (e.g. "quicktime"). It cannot be used together with the preset parameter.

preset

string

Optional parameter. The path of the xml file containing the parameter definition. It cannot be used together with the master or format parameters. See MT-TN-20 Output Preset File Format Specification for more information on the document structure.
Request example:

The following request exports the file metadata in XML. See MT-TN-10 Report XML File Format Specification for more information on the document structure.

{
	"context" : "mediainfo",
	"input" : "F:/ALEXA_Mini_LF_MXFARRIRAW/F004C003_190925_MN99.mxf",
	"output" : "F:/ALEXA_Mini_LF_MXFARRIRAW/F004C003_190925_MN99_metadata.mxf",
	"format" : "xml"
}

3.3.3. Response

The response is the status of the operation as well as the UUID assigned to the new job. This unique ID can be used for further job manipulation requests:

{
    "uuid": "b9206f48-42a3-4557-a80e-1912160b776e",
    "priority": 0,
    "status": "queued",
    "requesttimestamp": "2021-02-17T21:44:49+00:00",
    "input": "F:/ALEXA_Mini_LF_MXFARRIRAW/F004C003_190925_MN99.mxf",
    "output": "F:/ALEXA_Mini_LF_MXFARRIRAW/F004C003_190925_MN99_metadata.xml",
    "format": "xml",
    "context": "mediainfo"
}

3.4. Delete a running job

The following example shows you how to delete a new job from the list of jobs of a specific node:

Table 14. Request structure
Access Details

URL

/jobs/{job UUID}

METHOD

DELETE

3.4.1. Request

curl -X DELETE "http://127.0.0.1:8080/jobs/887b12ee-30f1-4059-afff-db3e89a4e270"

3.4.2. Response

The response is the status of the operation.

{
  "status" : "ok",
}

The following table shows the possible status codes that this function can return

Table 15. Status codes
Status Details

ok

The job was successfully deleted.

error

The job cannot be found in the list of jobs on this node.

3.5. Abort a running job

The following example shows you how to abort a running job to of a specific node:

Table 16. Request structure:
Access Details

URL

/jobs/<jobs_UUID>

Method

POST

3.5.1. Request

curl -X POST “http://127.0.0.1:8080/jobs/887b12ee-30f1-4059-afff-db3e89a4e270”

3.5.2. Response

{
	"status" : "ok"
}
Table 17. Status codes
Status Details

ok

The job was successfully aborted.

error

The job cannot be found in the list of jobs on this node.

3.6. Obtaining a job’s log

The following example shows you how to obtain a job’s log of a specific node:

Table 18. Request structure:
Access Details

URL

/jobs/<jobs_UUID>/log

Method

GET

3.6.1. Request

curl “http://127.0.0.1:8080/jobs/887b12ee-30f1-4059-afff-db3e89a4e270/log”

3.6.2. Response

{
    "events": [
        {
            "message": "Master type not supported",
            "severity": "error",
            "code": 2
        }
    ]
}

An empty "events" array may be returned in the case when there’s nothing to be reported.

{
    "events": []
}

3.7. Obtaining logs for all jobs

The following example shows you how to obtain the list of events for all jobs:

Table 19. Request structure:
Access Details

URL

/jobs/logs

Method

GET

3.7.1. Request

curl “http://127.0.0.1:8080/jobs/logs”

3.7.2. Response

{
    "events": [
        {
            "message": "Master type not supported",
            "severity": "error",
            "code": 2
        },
        {
            "message": "Master type not supported",
            "severity": "error",
            "code": 2
        },
        {
            "message": "Master type not supported",
            "severity": "error",
            "code": 2
        }
    ]
}

An empty "events" array may be returned in the case when there’s nothing to be reported.

{
    "events": []
}

4. Processing Graphs

4.1. Obtain the list of processing graphs

Storm maintains a list of processing graphs that can be obtained at any time.

The following example shows you how to obtain the list of processing graphs currently registered on a given node:

Table 20. Request structure:
Access Details

URL

/processinggraphs

Method

GET

4.1.1. Request

curl -X GET "http://127.0.0.1:8080/processinggraphs"

4.1.2. Response

{
	"status" : "ok",
	"processinggraphs" :
	[
		{
			"uuid" : "8e8d789d-5f03-4deb-9d0a-ebe9ef9923a8",
			"name" : "Convert to MXF Op1a DNxHD"
		},
		{
			"uuid" : "31c082ce-a38c-473a-b0c3-1e1708b9fb53",
			"name" : "multiple HD1080 ouputs",
		}
	]
}

4.2. Add a new processing graph

The following example shows you how to add a new processing graph to the list of managed by a specific node:

Table 21. Request structure:
Access Details

URL

/processinggraphs

Method

POST

4.2.1. Request

curl -X POST -H "Content-Type: text/xml" -T E:/processing_graph_example.xml “http://127.0.0.1:8080/processinggraphs”

4.2.2. Parameters

The command sends an XML processing graph to be added to the list of managed processing graphs. No other paramters are associated with this command.

4.2.3. Response

The response is the status of the operation as well as the UUID assigned to the new processing graph. This unique ID can be used for further managing the processing graph

{
	"status" : "ok",
	"uuid" : "a51f1483-217d-4ddb-a926-4d13d6ffc309",
}

4.3. Delete a processing graph

The following example shows you how to delete a processing graph from the list of processing graphs managed by a specific node:

Table 22. Request structure:
Access Details

URL

/processinggraphs/<processinggraph_UUID>

METHOD

DELETE

4.3.1. Request

curl -X DELETE "http://127.0.0.1:8080/processinggraphs/13ff097c-d4c9-43c0-a272-fb69a7a062e0"

4.3.2. Response

The response is the status of the operation.

{
  "status" : "ok",
}

The following table shows the possible status codes that this function can return

Table 23. Status codes
Status Details

ok

The processing graph was successfully deleted.

error

The processing graph cannot be found in the list of managed processing graphs by this node.

busy

The processing graph is currently in use and cannot be deleted.

4.4. Obtaining a processing-graph’s log

The following example shows you how to obtain a processing graph’s log of a specific node:

Table 24. Request structure:
Access Details

URL

/processinggraphs/<UUID>/log

Method

GET

4.4.1. Request

curl “http://127.0.0.1:8080/processinggraphs/887b12ee-30f1-4059-afff-db3e89a4e270/log”

4.4.2. Response

{
    "events": [
        {
            "message": "Invalid request ContentType",
            "severity": "error",
            "code": 2
        }
    ]
}

An empty "events" array may be returned in the case when there’s nothing to be reported.

{
    "events": []
}

4.5. Obtaining logs for all processing-graphs

The following example shows you how to obtain the list of events for all jobs:

Table 25. Request structure:
Access Details

URL

/processinggraphs/logs

Method

GET

4.5.1. Request

curl “http://127.0.0.1:8080/processinggraphs/logs”

4.5.2. Response

{
    "events": [
        {
            "message": "Invalid request ContentType",
            "severity": "error",
            "code": 2
        },
        {
            "message": "Cannot write Processing Graph file",
            "severity": "error",
            "code": 2
        }
    ]
}

An empty "events" array may be returned in the case when there’s nothing to be reported.

{
    "events": []
}

5. Output Presets

5.1. Obtain the list of Output Presets

Storm maintains a list of output presets that can be obtained at any time.

The following example shows you how to obtain the list of output presets currently registered on a given node:

Table 26. Request structure:
Access Details

URL

/outputpresets

Method

GET

5.1.1. Request

curl -X GET "http://127.0.0.1:8080/outputpresets"

5.1.2. Response

{
	"status" : "ok",
	"outputpresets" :
	[
		{
			"uuid" : "8e8d789d-5f03-4deb-9d0a-ebe9ef9923a8",
			"name" : "720p_H264_MP4"
		},
		{
			"uuid" : "31c082ce-a38c-473a-b0c3-1e1708b9fb53",
			"name" : "1080p_DNxHD_LB_MXFOp1A",
		}
	]
}

5.2. Add a new Output Preset

The following example shows you how to add a new output preset to the list:

Table 27. Request structure:
Access Details

URL

/outputpresets

Method

POST

5.2.1. Request

curl -X POST -H "Content-Type: text/xml" -T E:/output_preset_example.xml “http://127.0.0.1:8080/outputpresets”

5.2.2. Parameters

The command sends an XML output preset to be added to the list of managed presets. No other parameters are associated with this command.

5.2.3. Response

The response is the status of the operation as well as the UUID assigned to the new output preset. This unique ID can be used for further managing the preset.

{
	"status" : "ok",
	"uuid" : "a51f1483-217d-4ddb-a926-4d13d6ffc309",
}

5.3. Delete a Output Preset

The following example shows you how to delete a output preset from the list of output presets managed by a specific node:

Table 28. Request structure:
Access Details

URL

/outputpresets/<outputpreset_UUID>

METHOD

DELETE

5.3.1. Request

curl -X DELETE "http://127.0.0.1:8080/outputpresets/13ff097c-d4c9-43c0-a272-fb69a7a062e0"

5.3.2. Response

The response is the status of the operation.

{
  "status" : "ok",
}

The following table shows the possible status codes that this function can return

Table 29. Status codes
Status Details

ok

The output preset was successfully deleted.

error

The output preset cannot be found in the list of managed output presets by this node.

5.4. Obtaining an output preset’s log

The following example shows you how to obtain a output preset’s log of a specific node:

Table 30. Request structure:
Access Details

URL

/outputpresets/<UUID>/log

Method

GET

5.4.1. Request

curl -X GET “http://127.0.0.1:8080/outputpresets/887b12ee-30f1-4059-afff-db3e89a4e270/log”

5.4.2. Response

{
    "events": [
        {
            "message": "Invalid request ContentType",
            "severity": "error",
            "code": 2
        }
    ]
}

An empty "events" array may be returned in the case when there’s nothing to be reported.

{
    "events": []
}

5.5. Obtaining logs for all output presets

The following example shows you how to obtain the list of events for all output presets:

Table 31. Request structure:
Access Details

URL

/outputpresets/logs

Method

GET

5.5.1. Request

curl -X GET “http://127.0.0.1:8080/outputpresets/logs”

5.5.2. Response

{
    "events": [
        {
            "message": "Invalid request ContentType",
            "severity": "error",
            "code": 2
        },
        {
            "message": "Cannot write Processing Graph file",
            "severity": "error",
            "code": 2
        }
    ]
}

An empty "events" array may be returned in the case when there’s nothing to be reported.

{
    "events": []
}

6. Watchfolders

6.1. Obtain the list of watchfolders

Storm maintains a list of watchfolders that can be obtained at any time. This is the easiest method to get the status of all the watchfolders that are monitored along with their status.

The following example shows you how to obtain the list of watchfolders currently registered on a given node:

Table 32. Request structure:
Access Details

URL

/watchfolders

Method

GET

6.1.1. Request

curl "http://127.0.0.1:8080/watchfolders"

6.1.2. Response

{
	"status" : "ok",
	"watchfolders" :
	[
		{
			"uuid" : "4e64937f-b254-4e52-af73-48f8a4674feb",
			"status" : "active",
			"processgraphid" : "509f9f3a-4c4d-43a7-a2ac-a85c764f63c3",
			"input" : "E:/MEDIA_SOURCE",
			"output" : "E:/MEDIA_DESTINATION"
		},
		{
			"uuid" : "e0e5c68d-18bf-49b3-aa11-cc0ce838c8fc",
			"status" : "paused",
			"processgraphid" : "fadd6541-f81c-4be4-add6-f5b265b69411",
			"input" : "E:/RECEIVED_FILES",
			"output" : "E:/PROCESSED_FILES"
		}
	]
}

6.2. Add a new watchfolder

The following example shows you how to add a new watchfolder to the list of watchfolders monitored by a specific node:

Table 33. Request structure:
Access Details

URL

/watchfolders

Method

POST

6.2.1. Request

curl -X POST -T E:/watchfolder_parameters.json “http://127.0.0.1:8080/watchfolders”

6.2.2. Parameters

Parameter Name Value Description

name

string

Mandatory parameter. Custom defined name of the watchfolder.

processgraphid

string

Mandatory parameter. Mutually exclusive with presetid. The UUID of the processing-graph that should be applied to the current watchfolder.

presetid

string

Mandatory parameter. Mutually exclusive with processgraphid The UUID of the preset that should be applied to the current watchfolder.

input

string

Mandatory parameter. The path to the folder that should be used as input.

output

string

Mandatory parameter. The path to the folder that should be used as output.

filters

array

Optional parameter. List of extension filter objects to be applied to the input folder.

fileextension

string

Mandatory parameter in a filter object. A fixed text string value defined in a controlled vocabulary that defines the file format.
Request example:

The following example creates a watchfolder named "MOV_MXF_folder" that uses a previously defined processing-graph that get’s applied only to .mov and .mxf files.

{
    "name" : "MOV_MXF_folder",
	"processgraphid" : "c8494095-37da-4e04-93d4-5bc88102e701",
	"input" : "E:/RECEIVED_FILES",
	"output" : "E:/PROCESSED_FILES",
	"filters" :
	[
		{
			"fileextension" : "mxf",
		},
		{
			"fileextension" : "mov",
		}
	]
}

6.2.3. Response

The response is the status of the operation as well as the UUID assigned to the new watchfolder. This unique ID can be used for further managing the watchfolder

{
	"status" : "ok",
	"uuid" : "a51f1483-217d-4ddb-a926-4d13d6ffc309",
}

6.3. Delete a watchfolder

The following example shows you how to delete a watchfolder from the list of monitored watchfolders on a specific node:

Table 34. Request structure
Access Details

URL

/watchfolders/{watchfolder UUID}

METHOD

DELETE

6.3.1. Request

curl -X DELETE "http://127.0.0.1:8080/watchfolders/13ff097c-d4c9-43c0-a272-fb69a7a062e0"

6.3.2. Response

The response is the status of the operation.

{
  "status" : "ok",
}

The following table shows the possible status codes that this function can return

Table 35. Status codes
Status Details

ok

The watchfolder was successfully deleted.

error

The watchfolder cannot be found in the list of monitored watchfolders by this node.

6.4. Changing the status of a watchfolder

The following example shows you how to change the status of a watchfoldermonitored for a specific node:

Table 36. Request structure:
Access Details

URL

/watchfolders/<watchfolder_uuid>

Method

PUT

6.4.1. Request

curl -X PUT -H "Content-Type: application/json" -d '{"status":"paused"}'  “http://127.0.0.1:8080/watchfolders/887b12ee-30f1-4059-afff-db3e89a4e270”

6.4.2. Parameters

Parameter Name Value Description

status

string

Mandatory parameter. A fixed text string value defined in a controlled vocabulary that defines possible states of a watchfolder. Possible values active, paused.

6.4.3. Response

{
	"status" : "ok"
}

7. Workers

7.1. Obtaining the list of workers

STORM Server maintains a list of managed workers that can be obtained at any time. The following example shows you how to obtain the list of workers being managed by the current node:

Table 37. Request structure
Access Details

URL

/workers

METHOD

GET

7.1.1. Request

curl "http://127.0.0.1:8080/workers"

7.1.2. Response

The response is an array containing the workers descriptors as well as the status of the operation:

{
	"status" : "ok",
	"workers": [
        {
            "uuid": "8c80d6d9-f8a6-445f-828d-6f0bc8edcc5b",
            "address": "http://localhost",
            "port": 65535
        },
        {
            "uuid": "77038177-5fa4-471b-a5ec-e18d1f3cb9e9",
            "address": "http://localhost",
            "port": 65534
        },
        {
            "uuid": "556e68b6-b185-4980-91ac-b57bdefe4152",
            "address": "http://192.168.1.250",
            "port": 9090
        },
        {
            "uuid": "a016a364-5a86-4f4d-98f4-abe53e0a8275",
            "address": "http://192.168.1.150",
            "port": 9090
        }
    ]
}

7.2. Add a new worker

The following example describes the API for adding a new worker to the manager’s worker list.

This API is automatically called when a worker is either spawned locally or created remotely (see Manager and Worker nodes). It should not be used by an external application, safe for testing purposes.
Table 38. Request structure:
Access Details

URL

/workers

Method

POST

7.2.1. Request

curl -X POST -T "e:/worker_parameters.json" “http://127.0.0.1:8080/workers”

7.2.2. Parameters

Parameter Name Value Description

address

string

Mandatory parameter. Defines the address of the worker node.

port

number

Mandatory parameter. The port on which the worker node will communicate.

pid

number

Mandatory parameter. The Process ID of the worker node assigned by the Operating System.
Request example:
{
	"address": "http://localhost",
	"port": 6060,
	"pid": 10252
}

7.2.3. Response

The response is the status of the operation as well as the UUID assigned to the new worker. This unique ID can be used for further worker manipulation requests. In case there was an error in the process then the response will only contain the status of the operation set to "error":

{
    "uuid": "b9206f48-42a3-4557-a80e-1912160b776e",
    "status": "ok"
}

7.3. Delete a running worker

The following example shows you how to delete a specific worker from the manager’s node list.

Using this API will also call the control shutdown API (see Shutting down a node) with the worker’s parameters. As such, the status code of this operation will be the logical conjunction of the delete and shutdown operations.
Table 39. Request structure
Access Details

URL

/workers/{worker UUID}

METHOD

DELETE

7.3.1. Request

curl -X DELETE "http://127.0.0.1:8080/workers/887b12ee-30f1-4059-afff-db3e89a4e270"

7.3.2. Response

The response is the status of the operation.

{
  "status" : "ok",
}

The following table shows the possible status codes that this function can return:

Table 40. Status codes
Status Details

ok

The worker was successfully deleted.

error

The worker cannot be found in this node’s list.

7.4. Obtaining a worker’s log

The following example shows you how to obtain a list of logged events for a specific worker node:

Table 41. Request structure:
Access Details

URL

/workers/<worker_UUID>/log

Method

GET

7.4.1. Request

curl “http://127.0.0.1:8080/workers/887b12ee-30f1-4059-afff-db3e89a4e270/log”

7.4.2. Response

{
    "events": [
        {
            "message": "Invalid UUID.",
            "severity": "error",
            "code": 2
        },
        {
            "message": "Cannot shutdown Worker (worker unreachable)",
            "severity": "error",
            "code": 7
        }
    ]
}

An empty "events" array may be returned in the case when there’s nothing to be reported.

{
    "events": []
}

7.5. Obtaining logs for all workers

The following example shows you how to obtain the list of events for all workers:

Table 42. Request structure:
Access Details

URL

/workers/logs

Method

GET

7.5.1. Request

curl “http://127.0.0.1:8080/jobs/logs”

7.5.2. Response

{
    "events": [
        {
            "message": "Cannot find Worker",
            "severity": "error",
            "code": 2
        },
        {
            "message": "Cannot register Worker (not enough memory)",
            "severity": "error",
            "code": 1
        },
        {
            "message": "Invalid UUID.",
            "severity": "error",
            "code": 2
        },
        {
            "message": "Cannot shutdown Worker (worker unreachable)",
            "severity": "error",
            "code": 7
        }
    ]
}

An empty "events" array may be returned in the case when there’s nothing to be reported.

{
    "events": []
}

8. MT-TN-10 Report XML File Format Specification

8.1. Introduction

8.1.1. Overview

This document describes the Marquise Technologies Report XML file format used for various reporting purposes among the Marquise Technology product line. Among these purposes, the report is generated when validating various file formats, or simply to obtain detailed information on those.

The file format is based on the eXtensible Markup Language (XML) and uses its conventions and structures.

8.1.2. Scope

This specification is intended to give a reference to developers and implementers of this file format. As the format evolves to include new features, this specification is subject to frequent updates.

8.1.3. Document Organization

The specification is divided in various sections with a strong focus on implementation.

The last section of the document provides a detailed description of the various types used by the file format. These types are either simple types or complex types. Complex types contain a description of the sub-elements they contain.

The types are listed in alphabetic order.

8.1.4. Document Notation and Conventions

8.1.5. Language code conventions

This specification makes an extensive use of language codes for different purposes. All codes are assumed to use the ISO 639-1 or 639-2 notation.

8.1.6. XML Conventions

The document always uses the UTF-8 encoding.

Currently this specification does not follow the rules of an XML schema (XSD), however this may change in the future.

8.2. AssetDescriptorType

8.2.1. Elements

Table 43. AssetDescriptorType elements
Element Name Type Description

AssetKind

AssetKindEnum

a tag uniquely identifying the type of the asset

SourceDescriptor

SourceDescriptorType

a source descriptor that describes the location and storage properties of the asset

8.2.2. AssetKindEnum

The AssetKindEnum is an enumeration of fixed UTF-8 values that indicate the kind of the asset. Typically the kind of the asset must be compatible with the type of the essence referenced in a composition playlist track, otherwise it’s considered as an error.

Table 44. AssetKindEnum elements
Value Description

unknown

any asset for which the kind cannot be determined has this value

picture

the asset contains a single video track.

picture.s3d

the asset contains a single stereoscopic video track.

sound

the asset contains a single audio track.

timedtext

the asset contains a single timed text track.

immersiveaudio

the asset contains a single immersive audio track.

data

the asset contains a single data track.

combined

the asset contains multiple tracks with various essences.

pkl

the asset is a packing list.

cpl

the asset is a composition playlist.

opl

the asset is an output profile list.

scm

the asset is a sidecar composition map.

8.3. AcquisitionMetadataType

8.3.1. Elements

8.4. AssetDescriptorListType

The AssetDescriptorList element is defined by the AssetDescriptorListType and contains an ordered list of AssetDescriptor elements. Each AssetDescriptor element is defined by the AssetDescriptorType.

Below is an example of a AssetDescriptorList:

...
<AssetDescriptorList>
  <AssetDescriptor>
  ...
  </AssetDescriptor>
  ...
  <AssetDescriptor>
  ...
  </AssetDescriptor>
</AssetDescriptorList>
...

8.5. AudioDescriptorType

8.5.1. Elements

Table 45. AudioDescriptorType elements
Element Name Type Description

ChannelCount

UInt32

a value representing the number of audio channels in the essence referenced by the parent track.

SoundfieldConfiguration

UTF-8 string

a tag representing the configuration formed by the audio channels in the track. The tag is based on the SMPTE ST377-4 Multichannel Audio framework MCATagSymbol, using the "sg" prefix.

Annotation

UTF-8 string

An optional user-defined annotation text string

Title

UTF-8 string

An optional text string as specified in SMPTE ST377-41

TitleVersion

UTF-8 string

An optional text string as specified in SMPTE ST377-41

TitleSubVersion

UTF-8 string

An optional text string as specified in SMPTE ST377-41

Episode

UTF-8 string

An optional text string as specified in SMPTE ST377-41

ContentKind

UTF-8 string

A tag representing the content kind as specified in SMPTE ST377-41

ElementKind

UTF-8 string

A tag representing the element kind as specified in SMPTE ST377-41

PartitionKind

UTF-8 string

A tag representing the partition kind as specified in SMPTE ST377-41

PartitionNumber

UTF-8 string

A text string representing the partition number as specified in SMPTE ST377-41

ContentType

UTF-8 string

A tag representing the content type as specified in SMPTE ST377-41

ContentSubType

UTF-8 string

A tag representing the content subtype as specified in SMPTE ST377-41

ContentDifferentiator

UTF-8 string

An optional user-defined text string representing the content differentiator as specified in SMPTE ST377-41

UseClass

UTF-8 string

A tag representing the use class as specified in SMPTE ST377-41

SpokenLanguageAttribute

UTF-8 string

A tag representing the attribute of the main spoken language as specified in SMPTE ST377-41

8.6. CIExyType

8.6.1. Elements

Table 46. CIExyType elements
Element Name Type Description

x

Float32

a floating point value representing the x coordinated of a CIExy chromaticity vector

y

Float32

a floating point value representing the y coordinated of a CIExy chromaticity vector

8.7. CompositionDescriptorType

8.7.1. Elements

Table 47. CompositionDescriptorType elements
Element Name Type Description

Name

UTF-8 string

a human readable text string containing the name of the composition as stored in the subject

Annotation

UTF-8 string

A human readable text containing comments associated with the composition

Issuer

UTF-8 string

A human readable text that identifies the entity that produced the composition

IssueDate

xs:dateTime

creation date and time of the composition

Creator

UTF-8 string

a human readable text string containing the name of the tool used to create the composition

Language

ISO639LanguageType

main composition language

Duration

UInt64

A 64-bit unsigned interger containing the number of edit units in the composition

EditRate

Rational

A rational containing the edit rate of the composition (e.g. frame rate)

TimecodeDescriptor

TimecodeDescriptorType

A timecode descriptor defining the start timecode of the composition

8.8. ComplianceTestPlanListType

The ComplianceTestPlanList element is defined by the ComplianceTestListType and contains an ordered list of ComplianceTestPlan elements. Each ComplienceTestPlan element is defined by the ComplianceTestPlanType.

Below is an example of a ComplianceTestPlanList:

...
<ComplianceTestPlanList>
  <ComplianceTestPlan>
  ...
  </ComplianceTestPlan>
  ...
  <ComplianceTestPlan>
  ...
  </ComplianceTestPlan>
</ComplianceTestPlanList>
...

8.9. ComplianceTestPlanType

The ComplienceTestPlan is defined by the ComplianceTestPlanType and contains an ordered list of TestSequence elements. Each TestSequence element is defined by the TestSequenceType.

Below is an example of a ComplianceTestPlan:

...
<ComplianceTestPlan type=<type> version=<version>>
  <TestSequence type=<type>>
  ...
  </TestSequence>
  ...
  <TestSequence type=<type>>
  ...
  </TestSequence>
</ComplianceTestPlan>
...

8.9.1. Attributes

Table 48. ComplianceTestPlanListType attributes
Attribute Name Type Description

type

UTF-8 string

A fixed text string value defined in a controlled vocabulary

version

UTF-8 string

A fixed text string value defined in a controlled vocabulary

8.10. ContentLightLevelsType

8.10.1. Elements

Table 49. ContentLightLevelsType elements
Element Name Type Description

MaxCLL

Float32

Maximum Content Light Level as defined in CEA-861.3 2015, Annex A

MaxFALL

Float32

Maximum Frame Average Light Level as defined in CEA-861.3 2015, Annex A

8.11. CryptographicDescriptorType

8.11.1. Elements

Table 50. CryptographicDescriptorType elements
Element Name Type Description

UsesHMAC

Boolean

A flag indicating the usage of Hash-based message authentication code

KeyDescriptor

KeyDescriptorType

A complex type describing the encryption key properties

8.12. DataRateDescriptorType

8.12.1. Elements

Table 51. DataRateType elements
Element Name Type Description

AverageBytesPerSecond

UInt32

A 32-bit non-null unsigned integer containing the average bytes per second

AverageSampleSize

UInt32

A 32-bit non-null unsigned integer containing the average sample size in bytes

MaximumBytesPerSecond

UInt32

A 32-bit non-null unsigned integer containing the maximum bytes per second

MaximumSampleSize

UInt32

A 32-bit non-null unsigned integer containing the maximum sample size in bytes

MinimumSampleSize

UInt32

A 32-bit non-null unsigned integer containing the minimum sample size in bytes

8.13. EncodingDescriptorType

8.13.1. Elements

Table 52. EncodingDescriptorType elements
Element Name Type Description

Codec

UTF-8 string

a tag uniquely identifying the codec used by the parent essence descriptor

Profile

UTF-8 string

a tag uniquely identifying the codec profile used by the parent essence descriptor

Level

UTF-8 string

a tag uniquely identifying the codec profile level used by the parent essence descriptor

8.14. EssenceDescriptorType

8.14.1. Elements

Table 53. EssenceDescriptorType elements
Element Name Type Description

Duration

UInt64

A 64-bit unsigned interger containing the number of edit units in the underlying essence.

SampleRate

Rational

A rational containing the sample rate of the underlying essence.

Language

ISO639LanguageType

main essence language

EncodingDescriptor

EncodingDescriptorType

A complex type describing the codec parameters used to encode the essence

DataRateDescriptor

DataRateDescriptorType

An optional complex type describing the essence data rate

8.14.2. Attributes

Table 54. EssenceDescriptorType attributes
Attribute Name Type Description

type

UTF-8 string

a tag uniquely identifying the type of essence described

8.14.3. About SampleRate

For video essence descriptors, the sample rate is equal to the edit rate of the track that the essence descriptor belongs to. However, if the essence is stereoscopic, the sample rate is the double of the track’s edit rate. For instance, a stereoscopic video track that has an edit rate of 24 frames per second, will have it’s essence sample rate set to 48, indicating that 2 samples (i.e. 2 frames) are played for every edit unit in the track.

For audio essence descriptors, the sample rate is representing the audio sample rate (typically 48kHz).

Unless specified otherwise, other tracks have their sample rate specified in video frame units.

8.15. ImmersiveAudioDescriptorType

8.15.1. Elements

Table 55. ImmersiveAudioDescriptorType elements
Element Name Type Description

SoundfieldConfiguration

UTF-8 string

a tag representing the immersive audio configuration in the track. The tag is based on the SMPTE ST377-4 Multichannel Audio framework MCATagSymbol (typically IAB).

Annotation

UTF-8 string

An optional user-defined annotation text string

Title

UTF-8 string

An optional text string as specified in SMPTE ST377-41

TitleVersion

UTF-8 string

An optional text string as specified in SMPTE ST377-41

TitleSubVersion

UTF-8 string

An optional text string as specified in SMPTE ST377-41

Episode

UTF-8 string

An optional text string as specified in SMPTE ST377-41

ContentKind

UTF-8 string

A tag representing the content kind as specified in SMPTE ST377-41

ElementKind

UTF-8 string

A tag representing the element kind as specified in SMPTE ST377-41

PartitionKind

UTF-8 string

A tag representing the partition kind as specified in SMPTE ST377-41

PartitionNumber

UTF-8 string

A text string representing the partition number as specified in SMPTE ST377-41

ContentType

UTF-8 string

A tag representing the content type as specified in SMPTE ST377-41

ContentSubType

UTF-8 string

A tag representing the content subtype as specified in SMPTE ST377-41

ContentDifferentiator

UTF-8 string

An optional user-defined text string representing the content differentiator as specified in SMPTE ST377-41

UseClass

UTF-8 string

A tag representing the use class as specified in SMPTE ST377-41

SpokenLanguageAttribute

UTF-8 string

A tag representing the attribute of the main spoken language as specified in SMPTE ST377-41

8.16. JobDescriptorType

The JobDescriptor element is a complex element containing various sub-elements that describe the nature of the job that produced the XML report.

8.16.1. Elements

Table 56. JobDescriptorType elements
Element Name Type Description

Type

UTF-8 string

a tag uniquely identifying the type of the job that has produced the report

Status

UTF-8 string

a tag that represents the status of the job that has produced the report

Creator

UTF-8 string

A human readable text that identifies the device that has produced the report

8.17. ISO639LanguageType

A UTF-8 text string containing the ISO 639-1 or ISO 639-2 language code

8.18. MasteringDisplayDescriptorType

8.18.1. Elements

Table 57. MasteringDisplayDescriptorType elements
Element Name Type Description

MaximumLuminance

Float32

a value representing the maximum luminance of the reference display in cd/m2

MinimumLuminance

Float32

a value representing the minimum luminance of the reference display in cd/m2

CIERedPrimary

CIExyType

the CIExy coordinates of the red chromaticity of the reference display

CIEGreenPrimary

CIExyType

the CIExy coordinates of the green chromaticity of the reference display

CIEBluePrimary

CIExyType

the CIExy coordinates of the bluechromaticity of the reference display

CIEWhitePoint

CIExyType

the CIExy coordinates of the white point of the reference display

8.19. SourceDescriptorType

8.19.1. Elements

Table 58. SourceDescriptorType elements
Element Name Type Description

Path

UTF-8 string

a string defining the file system location of the object (i.e. file name or directory name)

Length

UInt64

The number of bytes occupied by the object on the file system

CreationDate

xs:dateTime

creation date and time of the object on the file system

LastAccessDate

xs:dateTime

last access date and time of the object on the file system

LastModifiedDate

xs:dateTime

last modification date and time of the object on the file system

8.20. SubjectDescriptorType

The SubjectDescriptor element is a complex element containing various sub-elements that contain information on the subject that the XML report was produced for.

The values for the various sub-elements are extracted or deduced from the subject’s metadata.

8.20.1. Elements

Table 59. SubjectDescriptorType elements
Element Name Type Description

Type

UTF-8 string

a tag uniquely identifying the type of the subject (i.e. file format or package format)

Name

UTF-8 string

A human readable text containing the subject name as stored in the underlying subject format

Annotation

UTF-8 string

A human readable text containing comments associated with the subject’s file or package

Issuer

UTF-8 string

A human readable text that identifies the entity that produced the file or package

Specification

UTF-8 string

a tag uniquely identifying the type of the job that has produced the report

SourceDescriptor

SourceDescriptorType

a source descriptor that describes the location and storage properties of the subject

8.21. TestSequenceType

The TestSequenceType contains an ordered list of Test elements. Each Test element is defined by the TestType.

Below is an example of a TestSequence:

...
<TestSequence type="ID_AssetMap">
  ...
  <Test id="ID_AssetMap_Existence">
    ...
  </Test>
  <Test id="ID_AssetMap_XMLSchema">
    ...
  </Test>
  ...
</TestSequence>
...

8.21.1. Attributes

Table 60. TestSequenceType attributes
Attribute Name Type Description

type

UTF-8 string

a tag uniquely identifying the type of test sequence

8.22. TimecodeDescriptorType

8.22.1. Elements

Table 61. TimecodeDescriptorType elements
Element Name Type Description

StartTimecode

UInt64

a value representing the start frame that the timecode corresponds to

RoundedTimecodeBase

UInt32

a value representing the rounded timecode frame rate base.

DropFrame

Boolean

a boolean value that indicates whether the timecode skips frames at certain frame number. This value is typically set to TRUE for NTSC-like frame rates.

8.22.2. About RoundedTimecodeBase

For integer frame rate, this value is the actual frame rate.

For non-integer frame rates (e.g. NTSC-like frame rates), this value represents the frame rate rounded to the smaller integer that is larger than the frame rate. For instance, for a 29.97 frame rate, the RoundedTimecodeBase will be equal to 30.

8.23. TimedTextDescriptorType

8.23.1. Elements

Table 62. TimedTextDescriptorType elements
Element Name Type Description

Usage

UTF-8 string

a tag uniquely identifying the usage or role of the timed text (closed captions, force narrative, etc)

8.24. TrackDescriptorType

8.24.1. Elements

Table 63. TrackDescriptorType elements
Element Name Type Description

Name

UTF-8 string

A human readable text containing the track name as stored in the underlying subject format

Language

UTF-8 string

a ISO 639-1 or ISO 639-2 language code

Duration

UInt64

A 64-bit unsigned interger containing the number of edit units in the track

EditRate

Rational

A rational containing the edit rate of the track (e.g. frame rate for video tracks)

EssenceDescriptor

EssenceDescriptorType

A complex type describing the essence properties used by the track

8.25. VideoDescriptorType

8.25.1. Elements

Table 64. VideoDescriptorType elements
Element Name Type Description

Width

UInt32

A non-null 32-bit unsigned interger containing the frame width in pixels

Height

UInt32

A non-null 32-bit unsigned interger containing the frame height in pixels

ChannelCount

UInt32

If present, a non-null 32-bit unsigned interger representing the number of video channels in the essence referenced by the parent track. A value of one is used for monoscopic content and a value of 2 is used for stereoscopic content. If the element is absent, then the content is considered monoscopic

FrameLayout

UTF-8 string

a tag uniquely identifying the frame layout as progressive or interlaced

Orientation

UTF-8 string

a tag uniquely identifying the frame stored orientation

PixelAspectRatio

Rational

A rational containing the pixel aspect ratio

ColorSpace

UTF-8 string

a tag uniquely identifying the signaled color space

ColorPrimaries

UTF-8 string

a tag uniquely identifying the signaled color primaries

TransferCharacteristic

UTF-8 string

a tag uniquely identifying the signaled EOTF

CodingEquations

UTF-8 string

a tag uniquely identifying the coding equations required for RGB to YCbCr and YCbCr to RGB cpmversions

ColorRange

UTF-8 string

a tag uniquely identifying the range of values used by the content pixels

DynamicToneMapping

UTF-8 string

a tag uniquely identifying the dynamic tone mapping technology required for content interpretation

ACESInputDeviceTransform

UTF-8 string

a tag uniquely identifying the ACES Input Device Transform associated with the content

MasteringDisplayDescriptor

MasteringDisplayDescriptorType

If present, a complex type contaioing the SMPTE ST2086 HDR Static Metadata

ContentLightLevelsDescriptor

ContentLightLevelsType

If present, a complex type contaioing the CEA 861.3-2015 HDR Contgent Light Levels

9. MT-TN-20 Output Preset File Format Specification

9.1. Introduction

9.1.1. Overview

This document describes the Marquise Technologies' Preset XML file format used for specifying and reusing various parameters for delivery jobs.

The file format is based on the eXtensible Markup Language (XML) and uses its conventions and structures.

Scope

This specification is intended to give a reference to developers and implementers of this file format. As the format evolves to include new features, this specification is subject to frequent updates.

9.1.2. Document Organization

The specification is divided in various sections with a strong focus on implementation.

The last section of the document provides a detailed description of the various types used by the file format. These types are either simple types or complex types. Complex types contain a description of the sub-elements they contain.

The types are listed in the order they appear in the XML document.

9.1.3. Document Notation and Conventions

9.1.4. Language code conventions

This specification makes an extensive use of language codes for different purposes. All codes are assumed to use the ISO 639-1 or 639-2 notation.

9.1.5. XML Conventions

The document always uses the UTF-8 encoding.

Currently this specification does not follow the rules of an XML schema (XSD), however this may change in the future.

9.2. MasterDeliverySpecification

The MasterDeliverySpecification is the preset’s root element.

9.2.1. Elements

Element Name Type Description

Name

UTF-8 string

a human readable text string containing the name of the composition.

Type

UTF-8 string

A fixed text string value defined in a controlled vocabulary.

Specification

UTF-8 string

A fixed text string value, defined in a controlled vocabulary, that defines a collection of predefined values for all the elements found in a MasterDeliverySpecification.

Shim

UTF-8 string

A fixed text string value, defined in a controlled vocabulary, that defines a collection of predefined values, that are applicable for a given Specification.

ShimVersion

UTF-8 string

A fixed text string value, defined in a controlled vocabulary, that defines a collection of predefined values, that are applicable for a given Shim.

Container

UTF-8 string

A fixed text string value, defined in a controlled vocabulary, that defines a collection of predefined values, that are applicable for a given Specification, Shim and ShimVersion.

TimecodeStart

UTF-8 string

A timecode descriptor defining the start timecode of the composition.

Presentation

UTF-8 string

An image descriptor defining the presentation type of the picture. Can have the values monoscopic or stereoscopic.

Video

VideoType

Complex element describing the properties of the video track.

Audio

AudioType

Complex element describing the properties of the audio track.

TimedText

TimedTexxtType

Complex element describing the properties of the timed-text track.

ExtendedProperties

ExtendedPropertiesType

Complex type containing a list of extended properties.

9.2.2. About Specification, Shim and ShimVersion

The Specification element, also known as a delivery specification, defines a set of constrains for the output file.

The Shim adds an additional layer of constrains and are applicable for a given Specification.

The ShimValue identifies which version of the Shim is to be used.

For example, a broadcaster like BBC, has a delivery specification: BBC AS-11 UK DPP HD 1.1.

This delivery specification will contain file naming conventions, containers, codecs and other mandatory parametrs necessary for the delivery.

Then this Specification is further refined by the Shim: AS-11 UK DPP HD because there is another variant for SD.

Lastly the ShimVersion is 1.1 because there is another, deprecated variant, 1.0.

9.2.3. About TimecodeStart

When the TimecodeStart element is present and a value is specified then that value is used as the start timecode for the output file using the preset.

If the element is not present then the start timecode of the composition is used as the start timecode of the output file.

9.3. Video

The Video element is a complex type using various sub-type elements that describe the video track’s properties. Below is the basic structure of a Video element:

<Video>
  <FrameWidthList>
    ...
  </FrameWidthList>
  <FrameHeightList>
    ...
  </FrameHeightList>
  <FrameRateList>
    ...
  </FrameRateList>
  <Codec>
    ...
  </Codec>
  <Colorimetry>
    ..
  </Colorimetry>
</Video>

9.3.1. Elements

Element Name Type Description

FrameWidthList

FrameWidthListType

Complex type containing a list of FrameWidth elements

FrameHeightList

FrameHeightListType

Complex type containing a list of FrameHeight elements

FrameRateList

FrameRateListType

Complex type containing a list of FrameRate elements

Codec

CodecType

Complex type containing a list of elements describing the codec properties

Colorimetry

ColorimetryType

Complex type containing a list of elements describing colorimetric properties

9.3.2. About FrameWidthList and FrameHeightList

The FrameWidthList and FrameHeightList are comprised of FreameWidth and FrameHeight elements. Each FrameWidth and FrameHeight elements are coupled, based on their positions in their respective lists, to describe the image frame resolution.

9.4. Codec

The Codec element is a complex type using various sub-type elements that describe the video and audio track’s encoding properties.

9.4.1. Elements

Element Name Type Description

Id

UTF-8 string

A fixed text string value, defined in a controlled vocabulary, that defines a collection of predefined values

ColorEncoding

UTF-8 string

A fixed text string value, defined in a controlled vocabulary, that defines a collection of predefined values

Quality

UTF-8 string

A fixed text string value, defined in a controlled vocabulary, that defines a collection of predefined values

Profile

UTF-8 string

A fixed text string value, defined in a controlled vocabulary, that defines a collection of predefined values

Level

UTF-8 string

A fixed text string value, defined in a controlled vocabulary, that defines a collection of predefined values

BitRate

UInt32

An unsigned 32bit integer representing the codec’s bit-rate

9.4.2. About Codec

Much like the Specification, Shim and ShimVersion the values defining the Codec define a set of constraints where one or more values depend on the ones chosen previously. In the context of a Codec the first level of constraint is defined by the Id then the definition is further refined by the Profile then Level and so on. Furthermore, not all elements are applicable to all Codec definitions.

9.5. Colorimetry

The Colorimetry element defines the color-space and the black to white range. The values are signaled by metadata embedding.

9.5.1. Elements

Element Name Type Description

ColorSpace

UTF-8 string

A fixed text string value, defined in a controlled vocabulary, that defines a collection of predefined values

CodeRange

UTF-8 string

A fixed text string value, defined in a controlled vocabulary, that defines a collection of predefined values

9.5.2. About Colorimetry

The values defined by the Colorimetry element do not trigger colorimetric transformations upon the rendered result. Instead it writes the data in the resulted file, if the chosen container and codec allow it.

9.6. Audio

The Audio element is a complex type using various sub-type elements that describe the audio track’s properties. Below is the basic structure of a Audio element:

<Audio>
  <Codec>
    ..
  </Codec>
  <SoundfieldList>
    ...
  </SoundfieldList>
</Audio>

9.6.1. Elements

Element Name Type Description

Codec

CodecType

Complex type containing a list of elements describing the codec properties

SoundfieldList

SoundfieldListType

Complex type containing a list of Soundfield elements

9.7. SoundfieldList

The SoundfieldList element is a complex type containing a list of Soundfield elements.

9.7.1. Elements

Element Name Type Description

Soundfield

SoundfieldType

Complex type containing a list of elements describing the properties of a soundfield

9.8. Soundfield

The Soundfield element is a complex type using various sub-type elements that describe the properties of a soundfield.

9.8.1. Elements

Element Name Type Description

Title

UTF-8 string

User defined value setting the Title metadata element when applicable

TitleVersion

UTF-8 string

User defined value setting the TitleVersion metadata element when applicable

TitleSubVersion

UTF-8 string

User defined value setting the TitleSubVersion metadata element when applicable

Episode

UTF-8 string

User defined value setting the Episode metadata element when applicable

ContentKind

UTF-8 string

User defined value setting the ContentKind metadata element when applicable

ElementKind

UTF-8 string

User defined value setting the ElementKind metadata element when applicable

Language

UTF-8 string

A fixed text string value, defined in a controlled vocabulary

Annotation

UTF-8 string

User defined value setting the Annotation metadata element when applicable

Configuration

UInt32

A fixed unsigned 32bit integer value, defined in a controlled vocabulary

ChannelMap

ChannelMapType

Complex type containing a list of Channel elements describing the mapping between tracks and channels

9.9. ChannelMap

The ChannelMap element is a complex type containing a list of Channel elements.

9.9.1. Elements

Element Name Type Description

Channel

UInt32

Unsigned 32bit integer value designating the position index of a channel relative to it’s track

9.10. Channel

The Channel element is an unsigned 32-bit integer specifying the source channel to be used. In addition a number of attributes can be specified:

9.10.1. Attributes

Attribute Name Type Description

trackType

UTF-8 string

A fixed text string value, defined in a controlled vocabulary

trackIndex

UInt32

A zero-based index value, defining the track index in the source.

symbol

UTF-8 string

A text string value, defined in a controlled vocabulary

9.10.2. About Configuration and ChannelMap

The Soundfield Configuration value will determine the number of Channel elements in a ChannelMap.

For example, in the case where Configuration has the value ST, representing a stereo audio configuration, the ChannelMap shall contain and define 2 Channel elements.

9.11. ExtendedProperties

The ExtendedProperties element is a complex type using various sub-type elements that describe the additional metadata that should be written into the delivery. Below is the basic structure of a ExtendedProperties element:

<ExtendedProperties>
  <PropertyList>
    ...
  </PropertyList>
</ExtendedProperties>

9.11.1. Elements

Element Name Type Description

PropertyList

PropertyListType

Complex type containing a list of Property elements

9.12. PropertyList

The PropertyList element is a complex type containing a list of Property elements.

9.12.1. Elements

Element Name Type Description

Property

PropertyType

Complex type in the form of a name/value pair

9.13. Property

The Property element is a complex type defining a metadata or additional master delivery property entry as a name/value pair.

9.13.1. Elements

Element Name Type Description

Name

UTF-8 string

A text string value, defined in a controlled vocabulary, that determines the field value for a metadata or master delivery property entry

Value

UTF-8 string

User defined, text string value, corresponding to the value for the metadata or property entry