Reducing the API responds with Sparse Filtering
If the API responds is too much data, you can narrow down which data you what to get back by Sparse Filtering. For sparse Filtering you have two fields that will help you with this:
– “include=,” will describe which categories of the JSON responds should be included. You can specify multiple paths separated by commas.
– “field[]=,” will describe which values should be included of that specific category. You can have multiple field definitions to specify different values for each category.
Example: You want to read out if a certain File Recording Output Destination is currently recording or not. In this case we are interested in the “live-state” value of the “attributes” category in the root category “data”. This means we need to specify the include category path as “data.attributes”. The “attributes” category contains multiple values but we just want to see the “live-state” in the responds thats why we narrow it down by the “fields[attributes]=live-state”
This makes up the following curl command: (Please make sure to replace the and with your own values!)
curl "http://192.168.0.107:8989/api/v1/documents//output-destinations/?include=data.attributes&fields[attributes]=live-state"
The responds will look like this:
{"data":{"attributes":{"live-state":"preview"}}}
Documents
The “documents” type corresponds to the document object that mimoLive writes to disk as “.tvshow” files.
{
// Unique Identifier of the document
"id": String,
// Always "documents" (see the JSON-API documentation for more information on this field)
"type": "documents",
// See the JSON:API specification for more information on this field
"relationships": {
// The layer contained in the document
"layers": Relationship,
// The sources used by the document
"sources": Relationship,
// The output destinations used by this document
"output-destinations": Relationship
},
// The link to the resource itself (see the JSON:API specification for more information on this field)
"links": Object,
// This is probably the data you are after
"attributes": {
// The name of the document
"name": String,
// Metatdata of the document
"metadata": {
// Comments as entered in the show metadata panel in mimoLive
"comments": String,
// The height of the document in pixels
"height": Integer,
// The width of the document in pixels
"width": Integer,
// The author of the document as entered in the show metadata panel in mimoLive
"author": String,
// The title of the show as entered in the show metadata panel in mimoLive
"title": String,
// The proposed show length (timer) as entered in the show metadata panel inmimoLive (in seconds)
"duration": Integer,
// The framerate of the document in frames per second
"framerate": Float,
// The generic show name as entered in the show metadata panel in mimoLive
"show": String,
// The audio samplerate of the document in hz
"samplerate": Integer
},
// The live state of the document/show (see LiveState for possible values and their meaning)
"live-state": LiveState,
// If the show is currently live, the current length of the show in seconds
"duration": Integer,
// If the show is currently live, timestamp when the show went live (can be used together with "metadata.duration" and "duration" to compute a countdown)
"show-start": Integer
}
}
Layers
The “layers” type represents the layers that are used in the rendering pipeline to generate the video output of mimoLive.
{
// Unique identifier of the layer
"id": String,
// Always "layers" (see the JSON-API documentation for more information on this field)
"type": "layers",
// See the JSON:API specification for more information on this field
"relationships": {
// The document this layer is part of
"document": Relationship,
// All the layer variants for this layer
"variants": Relationship,
// The variant that is currently live (null otherwise)
"live-variant": Relationship,
// The variant that is active/selected for that layer
"active-variant": Relationship
},
// The link to the resource itself (see the JSON:API specification for more information on this field)
"links": Object,
// Attributes of the layer (this is probably the data you are after)
"attributes": {
// The composition identifier for the layer, this can be used to differentiate the various layer types
"composition-id": String,
// The live state of the layer (see LiveState for possible values and their meaning)
"live-state": LiveState,
// The name of the layer as displayed in the mimoLive layer stack
"name": String,
// The user-controlled volume of the layer, as seen in the layer stack
// where 0.0 means silence and 1.0 is full volume.
// If the layer has no volume control, the value is null.
"volume": Float | null,
// The inputs used for the layer (composition). The keys come directly from the underlying QuartzComposition. Check out the custom layer protocol for more information on the key names and their meaning. The layer reports the "input-values" from either "live-variant" or the "active-variant" if the layer is not live.
"input-values": Object,
// Description object for each of the keys returned in "input-values"
"input-descriptions": {
(String): {
// Whether the input is currently hidden in the mimoLive user interface
"hidden": Bool,
// The type of the input ("string", "number", "index", "bool", "color", "image", "structure")
"type": String,
// If applicable: The minimum value the input accepts
"value-min": Float,
// If applicable: The maximum value the input accepts
"value-max": Float,
// For dropdowns a list of names for the individual values
"value-list": Array,
// By which ammount a value should be increased or decreased
"value-step": Float,
// String that declares in which unit the value is (eg. "°C")
"value-unit": String,
// Label that is shown next to the input
"label": String,
// The index of the input (for sorting)
"index": Integer
}
},
// Outputs from the last render cycle that were returned from QuartzComposer, including the original keys
"output-values": Object,
// The index of the layer in the layer stack (zero relates to the top of the stack)
"index": Integer
}
}
*The “volume” attribute has been added in mimoLive 5.2.
Variants
The “variants” type models one instance of a layer configuration. Most layers will only ever have one variant, but for some layers (e.g. Lower Thirds), it is common to have multiple variants featuring different text contents.
Variants share a lot of information with the “layers” type. In fact, a layer mostly acts as a proxy to its currently active variant.
{
// Unique identifier of the variant
"id": String,
// Always "variants" (see the JSON-API documentation for more information on this field)
"type": "variants",
// See the JSON:API specification for more information on this field
"relationships": {
// The layer this variant belongs to
"layer": Relationship
},
// The link to the resource itself (see the JSON:API specification for more information on this field)
"links": Object,
// Attributes of the variant (this is probably the data you are after)
"attributes": {
// The live state of the variant (see LiveState for possible values and their meaning). If the layer is not live, the value will always be "off".
"live-state": LiveState,
// The name of the variant as displayed in the mimoLive layer stack
"name": String,
// The inputs used for the variant (composition). The keys come directly from the underlying QuartzComposition. Check out the custom layer protocol for more information on the key names and their meaning. The layer reports the "input-values" from either "live-variant" or the "active-variant" if the layer is not live.
"input-values": Object,
// Description object for each of the keys returned in "input-values"
"input-descriptions": {
(String): {
// Whether the input is currently hidden in the mimoLive user interface
"hidden": Bool,
// The type of the input ("string", "number", "index", "bool", "color", "image", "structure")
"type": String,
// If applicable: The minimum value the input accepts
"value-min": Float,
// If applicable: The maximum value the input accepts
"value-max": Float,
// For dropdowns a list of names for the individual values
"value-list": Array,
// By which ammount a value should be increased or decreased
"value-step": Float,
// String that declares in which unit the value is (eg. "°C")
"value-unit": String,
// Label that is shown next to the input
"label": String,
// The index of the input (for sorting)
"index": Integer
}
},
// Outputs from the last render cycle that were returned from QuartzComposer, including the original keys
"output-values": Object
}
}
Sources
The “sources” type models sources that are used in layers, filters, and other sources, providing audio and video inputs to mimoLive.
{
// Unique identifier of the source
"id": String,
// Always "sources" (see the JSON-API documentation for more information
// on this field).
"type": "sources",
// See the JSON:API specification for more information on this field
"relationships": {
// The document this source is part of
"document": Relationship,
// The filters that process this source's video
"filters": Relationship
},
// The link to the resource itself (see the JSON:API specification for
// more information on this field).
"links": Object,
// Attributes of the variant (this is probably the data you are after)
"attributes": {
// The tally state of the source (see tally-state for possible values
// and their meaning)
"tally-state": TallyState,
// The name of the source as displayed in mimoLive
"name": String,
// Whether the source supplies video
"video": Bool,
// [optionally] If the associated video hardware is currently connected
// (Available since 5.5)
"video-device-connected": Bool,
// Whether the source supplies audio
"audio": Bool,
// [optionally] If the associated audio hardware is currently connected
// (Available since 5.5)
"audio-device-connected": Bool,
// Summary text of the source as displayed in mimoLive
"summary": String,
// The identifier of the composition if the source is based on a QuartzComposition
"composition-id": String,
// The gain that is applied to audio comming from this source, as
// controlled in the source settings view where 0.0 means silence,
// 1.0 is the default and 2.0 means doubled volume.
// Null if a source has no audio.
"gain": Float | null,
// The inputs used for the underlying composition (if it is a composition
// source). Check out the custom layer protocol for more information on
// the key names and their meaning.
"input-values": Object,
// Description object for each of the keys returned in "input-values"
"input-descriptions": {
(String): {
// Whether the input is currently hidden in the mimoLive window
"hidden": Bool,
// The type of the input ("string", "number", "index", "bool",
// "color", "image", "structure")
"type": String,
// If applicable: The minimum value the input accepts
"value-min": Float,
// If applicable: The maximum value the input accepts
"value-max": Float,
// For dropdowns a list of names for the individual values
"value-list": Array,
// By which ammount a value should be increased or decreased
"value-step": Float,
// String that declares in which unit the value is (eg. "°C")
"value-unit": String,
// Label that is shown next to the input
"label": String,
// The index of the input (for sorting)
"index": Integer
}
},
// Outputs from the last render cycle that were returned from
// QuartzComposer, including the original keys
"output-values": Object
}
}
*The “gain” attribute has been added in mimoLive 5.2.
Filters
The “filters” type represents the filters that can be assigned to video sources to process the video before being used in layers.
{
// Unique identifier of the filter
"id": String,
// Always "filters" (see the JSON-API documentation for more information on this field)
"type": "filters",
// See the JSON:API specification for more information on this field.
"relationships": {
// The source that this filter belongs to
"source": Relationship
},
// The link to the resource itself (see the JSON:API specification for more information on this field)
"links": Object,
// Attributes of the variant (this is probably the data you are after)
"attributes": {
// The name of the filter as displayed in mimoLive
"name": String,
// The identifier of the filter's QuartzComposition
"composition-id": String,
// The inputs used for the underlying composition (if it is a composition source). Check out the custom layer protocol for more information on the key names and their meaning.
"input-values": Object,
// Description object for each of the keys returned in "input-values"
"input-descriptions": {
(String): {
// Whether the input is currently hidden in the mimoLive user interface
"hidden": Bool,
// The type of the input ("string", "number", "index", "bool", "color", "image", "structure")
"type": String,
// If applicable: The minimum value the input accepts
"value-min": Float,
// If applicable: The maximum value the input accepts
"value-max": Float,
// For dropdowns a list of names for the individual values
"value-list": Array,
// By which ammount a value should be increased or decreased
"value-step": Float,
// String that declares in which unit the value is (eg. "°C")
"value-unit": String,
// Label that is shown next to the input
"label": String,
// The index of the input (for sorting)
"index": Integer
}
},
// Outputs from the last render cycle that were returned from QuartzComposer, including the original keys
"output-values": Object
}
}
Output Destinations
Available since: mimoLive 4.2
The “output-destinations” type models the different output destinations a mimoLive show can have, including recording, streaming and more.
{
// Unique identifier of the output destination
"id": String,
// Always "output-destinations" (see the JSON-API documentation for more information on this field)
"type": "output-destinations",
// See the JSON:API specification for more information on this field
"relationships": {
// The document that this output destination belongs to
"document": Relationship
},
// The link to the resource itself (see the JSON:API specification for more information on this field)
"links": Object,
// Attributes of the variant (this is probably the data you are after)
"attributes": {
// The name of the output destination as displayed in mimoLive
"title": String,
/*
The concrete type of output destination:
- "File Recording"
- "Audio Aux"
- "Live Streaming"
- "Virtual Camera"
- "Fullscreen"
- "Blackmagic Design"
- "NDI®" (including the "®")
*/
"type": String,
// A summary containing the most important settings
"summary": String,
// Whether the output destination is properly configured
"ready-to-go-live": Bool,
// Whether the output destination is set to start when the mimoLive show starts
"starts-with-show": Bool,
// Whether the output destination is set to stop when the mimoLive show ends
"stops-with-show": Bool,
// Individual settings depending on the "type" of output destination (see below for reference)
"settings": Object,
// The current live state of the output destination (see below for how to interpret the values)
"live-state": LiveState
}
}
Individual Settings
Different output destination types have different settings.
Below are the different types of “settings” object. For output destinations types that are not listed, the dictionary will be empty.
{
// Path to the folder that will contain the recording. Can be set to "null" to reset to initial value ("~/Movies').
"location": String,
// Filename that will be given to the recording. See below for placeholder values. Can be set to "null" to reset to initial value ("%document %year-%month-%day %hour-%minute-%second.%extension").
"filename": String
}
{
// Available since: mimoLive 5.5:
// Ofuscated URL of the streaming endpoint.
"rtmpurl": String,
// Ofuscated steaming key.
"streamingkey": String,
// Public broadcast URL.
"publicurl": String
}
Even that the “rtmpurl” and “streamingkey” values are obfuscated you still can set those values by a PATCH request.
Placeholder values for File Recording’s “filename” attribute
Placeholder | Explanation |
---|---|
%document | name of the document including the .tvshow extension (depending on user system settings) |
%show | name of the show |
%extension | mov, without the . prefix |
%year | 4 digit year, e.g. 2018 |
%month | 2 digit month, e.g. 01 for January |
%day | 2 digit day, e.g. 31 |
%hour | 2 digit hour (24h clock), e.g. 15 |
%minute | 2 digit minutes, e.g. 45 |
%second | 2 digit seconds, e.g. 50 |
Layer Sets
Available since: mimoLive 4.8
The “layer-sets” type models layer sets the user can create and manage in mimoLive.
{
// Unique identifier of the layer set
"id": String,
// Always "layer-sets" (see the JSON-API documentation for more information on this field)
"type": "layer-sets",
// See the JSON:API specification for more information on this field
"relationships": {
// The document that this layer set belongs to
"document": Relationship
},
// The link to the resource itself (see the JSON:API specification for more information on this field)
"links": Object,
"attributes": {
// The name of the layer set as displayed in mimoLive
"name": String,
// Wheter the layer stack currently matches the configuration represented by the layer set
"active": Bool
}
}
Live State
The “LiveState” type represents the state a document, layer or variant can be in. Possible values are:
Value | Explanation |
---|---|
off | Layer: The layer is off and will not be rendered. |
Document: The show is not running. | |
Output Destination: The output destination is not able to go live because it is not properly configured. | |
live | Layer: The layer is live and will be rendered, on a variant this means that the layer is live and the variant is live. |
Document: The show is currently running. | |
Output Destination: The output destination is active and transmitting/recording data. | |
preview | Layer: The layer is displayed in the preview column and may be switched live soon. |
Output Destination: The output destination is ready to go live and waiting for commands. | |
shutdown | Layer: The layer is currently live but is in the process of shutting down (e. g. an outgoing transition). |
startup | Output Destination: The output destination is in the process of starting (e.g. connecting to an external service). |
TallyState
A “TallyState” represents the state a source can be in. The degree of activity is ordered and only the highest use will be reported. Possible values (from low to high) are:
Value | Explanation |
---|---|
off | The source is currently not in use by mimoLive |
in-use | The source is currently being used somewhere inside mimoLive |
effect | The source is currently used for being rendered in an filter preview |
preview | The source is currently used inside the preview output |
program | The source is currently used inside the program output |