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.
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:
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
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
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
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
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:
-
Press the Windows key and R (for run)
-
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.
-
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:
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
flag when installing the server as a service.-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.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
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.websrv
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
command option followed by the number of workers to be spawned.-workers
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
and on the specified address
. The worker will try to register with a manager node having the address specified by the port
parameter.nodeaddress
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
Access | Details |
---|---|
URL |
/compositions |
Query Params |
To be added |
Method |
GET |
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:
Access | Details |
---|---|
URL |
/compositions |
Method |
POST |
1.2.1. Request
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.
{
"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:
Access | Details |
---|---|
URL |
/compositions/{composition UUID} |
METHOD |
DELETE |
1.3.1. Request
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.
{
"status" : "ok",
}
The following table shows the possible status codes that this function can return
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:
Access | Details |
---|---|
URL |
/control/status |
Method |
GET |
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:
Access | Details |
---|---|
URL |
/control/shutdown |
Method |
POST |
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:
Access | Details |
---|---|
URL |
/jobs |
METHOD |
GET |
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:
Access | Details |
---|---|
URL |
/jobs |
Method |
POST |
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 |
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 |
string |
Optional parameter. The path of the xml file containing the parameter definition. It cannot be used together with the |
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:
Access | Details |
---|---|
URL |
/jobs/{job UUID} |
METHOD |
DELETE |
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
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:
Access | Details |
---|---|
URL |
/jobs/<jobs_UUID> |
Method |
POST |
3.6. Obtaining a job’s log
The following example shows you how to obtain a job’s log of a specific node:
Access | Details |
---|---|
URL |
/jobs/<jobs_UUID>/log |
Method |
GET |
3.7. Obtaining logs for all jobs
The following example shows you how to obtain the list of events for all jobs:
Access | Details |
---|---|
URL |
/jobs/logs |
Method |
GET |
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:
Access | Details |
---|---|
URL |
/processinggraphs |
Method |
GET |
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:
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.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:
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
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:
Access | Details |
---|---|
URL |
/processinggraphs/<UUID>/log |
Method |
GET |
4.5. Obtaining logs for all processing-graphs
The following example shows you how to obtain the list of events for all jobs:
Access | Details |
---|---|
URL |
/processinggraphs/logs |
Method |
GET |
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:
Access | Details |
---|---|
URL |
/outputpresets |
Method |
GET |
5.2. Add a new Output Preset
The following example shows you how to add a new output preset to the list:
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.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:
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
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:
Access | Details |
---|---|
URL |
/outputpresets/<UUID>/log |
Method |
GET |
5.5. Obtaining logs for all output presets
The following example shows you how to obtain the list of events for all output presets:
Access | Details |
---|---|
URL |
/outputpresets/logs |
Method |
GET |
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:
Access | Details |
---|---|
URL |
/watchfolders |
Method |
GET |
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:
Access | Details |
---|---|
URL |
/watchfolders |
Method |
POST |
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 |
string |
Mandatory parameter. Mutually exclusive with |
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 |
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.3. Delete a watchfolder
The following example shows you how to delete a watchfolder from the list of monitored watchfolders on a specific node:
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
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:
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”
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:
Access | Details |
---|---|
URL |
/workers |
METHOD |
GET |
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. |
Access | Details |
---|---|
URL |
/workers |
Method |
POST |
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. |
{
"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. |
Access | Details |
---|---|
URL |
/workers/{worker UUID} |
METHOD |
DELETE |
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:
Access | Details |
---|---|
URL |
/workers/<worker_UUID>/log |
Method |
GET |
7.5. Obtaining logs for all workers
The following example shows you how to obtain the list of events for all workers:
Access | Details |
---|---|
URL |
/workers/logs |
Method |
GET |
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.2. AssetDescriptorType
8.2.1. Elements
Element Name | Type | Description |
---|---|---|
AssetKind |
a tag uniquely identifying the type of the asset |
|
SourceDescriptor |
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.
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.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
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.7. CompositionDescriptorType
8.7.1. 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 |
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 |
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.12. DataRateDescriptorType
8.12.1. 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
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
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 |
main essence language |
|
EncodingDescriptor |
A complex type describing the codec parameters used to encode the essence |
|
DataRateDescriptor |
An optional complex type describing the essence data rate |
8.14.2. 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
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
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.18. MasteringDisplayDescriptorType
8.18.1. 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 |
the CIExy coordinates of the red chromaticity of the reference display |
|
CIEGreenPrimary |
the CIExy coordinates of the green chromaticity of the reference display |
|
CIEBluePrimary |
the CIExy coordinates of the bluechromaticity of the reference display |
|
CIEWhitePoint |
the CIExy coordinates of the white point of the reference display |
8.19. SourceDescriptorType
8.19.1. 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
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 |
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.22. TimecodeDescriptorType
8.22.1. 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.24. TrackDescriptorType
8.24.1. 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 |
A complex type describing the essence properties used by the track |
8.25. VideoDescriptorType
8.25.1. 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 |
If present, a complex type contaioing the SMPTE ST2086 HDR Static Metadata |
|
ContentLightLevelsDescriptor |
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.
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.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 |
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
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
<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 |
FrameHeightList |
FrameHeightListType |
Complex type containing a list of |
FrameRateList |
FrameRateListType |
Complex type containing a list of |
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.4. Codec
The
element is a complex type using various sub-type elements that describe the video and audio track’s encoding properties.Codec
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
and Shim
the values defining the ShimVersion
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 Codec
then the definition is further refined by the Id
then Profile
and so on. Furthermore, not all elements are applicable to all Level
definitions.Codec
9.5. Colorimetry
The
element defines the color-space and the black to white range. The values are signaled by metadata embedding.Colorimetry
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.6. Audio
The
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
<Audio>
<Codec>
..
</Codec>
<SoundfieldList>
...
</SoundfieldList>
</Audio>
9.7. SoundfieldList
The
element is a complex type containing a list of SoundfieldList
elements.Soundfield
9.8. Soundfield
The
element is a complex type using various sub-type elements that describe the properties of a soundfield.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 |
9.10. Channel
The
element is an unsigned 32-bit integer specifying the source channel to be used. In addition a number of attributes can be specified:Channel
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
value will determine the number of Configuration
elements in a Channel
.ChannelMap
For example, in the case where
has the value ST, representing a stereo audio configuration, the Configuration
shall contain and define 2 ChannelMap
elements.Channel
9.11. ExtendedProperties
The
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
<ExtendedProperties>
<PropertyList>
...
</PropertyList>
</ExtendedProperties>
9.12. PropertyList
The
element is a complex type containing a list of PropertyList
elements.Property
9.13. Property
The
element is a complex type defining a metadata or additional master delivery property entry as a name/value pair.Property
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 |