mimoLive® - User Manual

Generic selectors
Exact matches only
Search in title
Search in content
Post Type Selectors

Manual – Table of Content

Endpoints

Table of Contents

General

The API, when enabled, is available at “http://localhost:8989/api/v1”. This is the base URL that must be prepended to every method URL listed below.

If a resource was introduced after the initial launch of the HTTP API, the method is marked with an Available since information.

/

Supported methods: “GET
Redirects to the list of open documents at “/documents”.

Documents

Querying Documents

/documents

Supported methods: “GET
Results in a list of open documents. See the documents data type on what information the returned objects contain.

/documents/(DocumentID)

Supported methods: “GET
Returns a single document specified by the “(DocumentID)”. In the included section of the response all “layer” objects used by this document and all “source” objects contained in this document will be returned as well (sideloading). See the documents data type for more information on the data returned.

/documents/(DocumentID)/programOut

Supported methods: “GET
The program output that is currently produced by the document specified by the “(DocumentID)”.
Takes the same parameters as source previews.

Document Actions

/documents/(DocumentID)/setLive

Supported methods: “GET” “POST
Starts a show/document and triggers all asociated events. Calling this on an already running document will not result in an error. The updated document object will be returned.

/documents/(DocumentID)/setOff

Supported methods: “GET” “POST
Stops a show/document. Calling this on an already stopped show will not result in an error. The updated document object will be returned.

*Because a document can decide to keep running after you call this method the returned layer object might be in state “shutdown” instead of “off”.

/documents/(DocumentID)/toggleLive

Supported methods: “GET” “POST
Toggles a show/document between live and off.

Layers

Querying Layers

/documents/(DocumentID)/layers

Supported methods: “GET
Returns a list of layers for the document specified by “(DocumentID)”. For information on the objects returned see the layers data type.

/documents/(DocumentID)/layers/(LayerID)

Supported methods: “GET”, “PUT
Returns a single layer specified by the “(LayerID)” in the document specified by “(DocumentID)”. In the “included” section of the response all “variant” objects related to this layer will be returned as well (sideloading). See the layers data type for more information on the data returned. Please keep in mind that the “input-values” from the layer endpoint reflect the “input-values” of the associated “liveVariant” variant.

Modifying a Layer

Supported methods: “GET”, “PUT
To set the name of the layer, audio volume or input values perform a “PUT” request with a JSON encoded object to the layer endpoint. Alternatively you can use a “GET” request by adding the JSON data to the URL with the key “?update=”. In this case the JSON data must be URL encoded.

Values you don’t want to change should be simply excluded from the JSON data. Example:

{
    "name": "New name of the Layer",
    "volume": 0.5,
    "input-values": { 
        "tvGroup_Content__Subtitle": "This is a Test"
    }
}

After updating the values mimoLive will respond with an updated layer object. Keep in mind that not all values can be applied instantly or might only have an effect after another render cycle.

Note: The “volume” attribute has been added in mimoLive 5.6 and is ignored in earlier versions or if the layer has no volume control. Value will be clipped to (0, 1), where 0 is silent and 1 is full volume.

Layer Actions

/documents/(DocumentID)/layers/(LayerID)/setLive

Supported methods: “GET” “POST
Activates a layer, when this is called directly on the layer, the last selected layer variant will be used. Calling this on an already active layer will not result in an error. The updated layer object will be returned.

/documents/(DocumentID)/layers/(LayerID)/setOff

Supported methods: “GET” “POST
Deactivates a layer. Calling this on an already deactivated layer will not result in an error. The updated layer object will be returned.

*Because a layer can decide to do some animations after you call this method the returned layer object might be in state “shutdown” instead of “off”.

/documents/(DocumentID)/layers/(LayerID)/toggleLive

Supported methods: “GET” “POST
Toggles a layer between “live” and “off”.

/documents/(DocumentID)/layers/(LayerID)/signals/(SignalID)

Supported methods: “GET” “POST
Triggers the signal specified by “(SignalID)” in the current “live-variant” or if the layer is not live in the “active-variant”. You can get the “(SignalID)” from the “input-values” field of the layer (identified by the key suffix “_TypeSignal”).

/documents/(DocumentID)/layers/(LayerID)/cycleThroughVariants

Supported methods: “GET” “POST
Available since: mimoLive 5.6
Selects the next variant after the currently active variant of layer “(LayerID)” to be the layer’s new active variant. This can be used to select the variant (e.g. of a Lower Third Layer) that should go live next.
Calling this endpoint does not disturb your show if the layer is currently live. The effect only shows when the layer is set live afterwards.

Variants

Querying Variats

/documents/(DocumentID)/layers/(LayerID)/variants

Supported methods: “GET
Returns a list of variants for the layer specified by “(LayerID)” and the document specified by “(DocumentID)”. For information on the objects returned see the “variants” data type.

/documents/(DocumentID)/layers/(LayerID)/variants/(VariantID)

Supported methods: “GET”, “PUT
Returns a single variant specified by the “(VariantID)” and the “(LayerID)” in the document specified by “(DocumentID)”. See the “variants” data type for more information on the data returned.

Modifying a Variant

To set the name of the variant or input values perform a “PUT” request with a JSON encoded object to the variant endpoint. Values you don’t want to change should be simply excluded from the JSON you “PUT”. Example:

{
    "name": "New name of the Variant",
    "input-values": { 
        "tvGroup_Content__Subtitle": "This is a Test"
    }
}

After updating the values mimoLive will respond with an updated variant object. Keep in mind that not all values can be applied instantly or might only have an effect after another render cycle.

Variant Actions

/documents/(DocumentID)/layers/(LayerID)/variants/(VariantID)/setLive

Supported methods: “GET” “POST
Activates a variant, if the owning layer is not live it will be switched to live too. Calling this on an already active variant will not result in an error. The updated variant object will be returned.

/documents/(DocumentID)/layers/(LayerID)/variants/(VariantID)/setOff

Supported methods: “GET” “POST
Deactivates a variant. This will also cause the owning layer to be turned off.

/documents/(DocumentID)/layers/(LayerID)/variants/(VariantID)/toggleLive

Supported methods: “GET” “POST
Toggles a variant between live and off.

/documents/(DocumentID)/layers/(LayerID)/variants/(VariantID)/signals/(SignalID)

Supported methods: “GET” “POST
Triggers the signal specified by “(SignalID)” on the variant. You can get the “(SignalID)” from the “input-values” field of the layer (identified by the key suffix “_TypeSignal”).

Sources

Querying Sources

/documents/(DocumentID)/sources

Supported methods: “GET
Returns a list of sources for the document specified by “(DocumentID)”. For information on the objects returned see the “sources layer” data type.

/documents/(DocumentID)/sources/(SourceID)

Supported methods: “GET”, “PUT
Returns a single source specified by the “(SourceID)” in the document specified by “(DocumentID)”. In the included section of the response all “filter” objects related to this source will be returned as well (sideloading). See the “sources” data type for more information on the data returned.

/documents/(DocumentID)/sources/(SourceID)/preview

Supported methods: “GET
Returns a graphical preview of the source specified by the “(SourceID)” in the document specified by “(DocumentID)”. The endpoint supports the following parameters:

ParameterDefaultDescription
formatpngThe format in which the preview is returned. Allowed values: png, jpeg, mjpeg, mpng
fps10The framerate for motion image previews. Only applicable to mjpeg and mpng formats. Please note that 1 fps roughly equals to 1% of CPU utilization.
width(document width)The maximum width of the preview. The image will be scaled down to fit into the given width.
height(document width)The maximum height of the preview. The image will be scaled down to fit into the given height.

Modifying a Source

To set the name of the source or input values (only if the source has any, e. g. it is a Composition Source) perform a “PUT” request with a JSON encoded object to the source endpoint. Values you don’t want to change should be simply excluded from the JSON you “PUT”. Example:

{
    "name": "New name of the Source",
    "gain": 1.25,
    "input-values": { 
        "tvGroup_Content__Subtitle": "This is a Test"
    }
}

*The “gain” attribute has been added in mimoLive 5.6 and is ignored in earlier versions or if the source has no gain control. Value will be clipped to (0, 2), where 0 is silent, 1 is default and 2 approximately doubles the volume.

Source Actions

/documents/(DocumentID)/sources/(SourceID)/signals/(SignalID)

Supported methods: “GET” “POST
Triggers the signal specified by “(SignalID)” on the source (only if the source has “input-values”, e. g. it is a Composition Source). You can get the “(SignalID)” from the “input-values” field of the source (identified by the key suffix “_TypeSignal”).

Filters

Querying Filters

/documents/(DocumentID)/sources/(SourceID)/filters

Supported methods: “GET
Returns a list of filters for the source specified by “(SourceID)” and the document specified by “(DocumentID)”. For information on the objects returned see the “filters” data type.

/documents/(DocumentID)/sources/(SourceID)/filters/(FilterID)

Supported methods: “GET”, “PUT
Returns a single filter specified by the “(FilterID)” and the “(SourceID)” in the document specified by “(DocumentID)”. See the “filters” data type for more information on the data returned.

Modifying a Filter

To set the input values perform a “PUT” request with a JSON encoded object to the filter endpoint. Values you don’t want to change should be simply excluded from the JSON you “PUT”. Example:

{
    "input-values": { 
        "tvGroup_Content__Subtitle": "This is a Test"
    }
}

/documents/(DocumentID)/sources/(SourceID)/filters/(FilterID)/signals/(SignalID)

Supported methods: “GET” “POST
Triggers the signal specified by “(SignalID)” on the filter. You can get the “(SignalID)” from the “input-values” field of the filter (identified by the key suffix “_TypeSignal”).

Output Destinations

Querying Output Destinations

/documents/(DocumentID)/output-destinations

textileRef:9996801466400ba8908856:linkStartMarker:“Supported methods: “GET
Available since: mimoLive 4.2
Lists all output destinations for the specified document.
For information on the objects returned see the ““output-destinations” data type”:{TOPIC-LINK+data-typesh1(}. section-output-destinations).

/documents/(DocumentID)/output-destinations/(OutputDestinationID)

Supported methods: “GETtextileRef:9996801466400ba8908856:linkStartMarker:”
Available since: mimoLive 4.2
Returns the output destination specified by “(OutputDestinationID)”.
For information on the objects returned see the ““output-destinations” data type”:{TOPIC-LINK+data-typesh1(}. section-output-destinations).

Modifying an Output Destination

/documents/(DocumentID)/output-destinations/(OutputDestinationID)

Supported methods: “PATCH
Available since: mimoLive 4.2
Update selected properties of the output destination specified by “(OutputDestinationID)”.
Returns the updated output destination.

The following properties are modifiable:

  • “title”
  • “starts-with-show”
  • “stops-with-show”
  • Contents of the “settings” object (see the settings description. section-individual-settings) for more information)

Update description must be given in JSON:API update format . crud-updating). Example:

{
  "data": {
    "type": "output-destinations",
    "id": "4FF003EA-D071-43FD-845F-DCD4A25DFA00",
    "attributes": {
      "title": "Our Recording",
      "starts-with-show": true,
      "settings": {
        "location": "~/Movies"
      }
    }
  }
}

Output Destination Actions

/documents/(DocumentID)/output-destinations/(OutputDestinationID)/setLive

Supported methods: “GET” “POST
Available since: mimoLive 4.2
Causes the output destination specified by “(OutputDestinationID)” to go live, if it is properly configured and the allowed to go live (e.g. based on the mimoLive licensing state).
If the output destination is able to go live, the output destination with its new “live-state” is returned, otherwise a “409 Conflict” error is returned.

*Because an output destination may need to perform some work before being live (e.g. contacting an external service to create a live stream), the returned output destination object may be in state “startup” instead of “live”.

/documents/(DocumentID)/output-destinations/(OutputDestinationID)/setOff

Supported methods: “GET” “POST
Available since: mimoLive 4.2
Causes the output destination specified by “(OutputDestinationID)” to stop.
If the output destination is allowed to stop, the output destination is returned, otherwise a “409 Conflict” error is returned.

*Because an output destination may need to perform some work before stopping operations, the returned output destination may be in state “shutdown” instead of “preview” (which would be the default for a well-configured output destination).

Layer Sets

Layer sets were introduced in mimoLive 5.0 and allow setting the live state of multiple layers at once, enabling the creation of lightweight scenes for different situations in a show. They can only be created and manged in mimoLive. API access is restricted to obtaining and recalling (activating) layer sets.

Querying Layer Sets

/documents/(DocumentID)/layer-sets

textileRef:9996801466400ba8908856:linkStartMarker:“Supported methods: “GET
Available since: mimoLive 5.0
Lists all layer sets for the specified document.
For information on the objects returned see the ““layer-sets” data type”:{TOPIC-LINK+data-typesh1(}. section-layer-sets).

/documents/(DocumentID)/layer-sets/(LayerSetID)

Supported methods: “GETtextileRef:9996801466400ba8908856:linkStartMarker:”
Available since: mimoLive 5.0
Returns the layer set specified by “(LayerSetID)”.
For information on the objects returned see the ““layer-sets” data type”:{TOPIC-LINK+data-typesh1(}. section-layer-sets).

Layer Set Actions

/documents/(DocumentID)/layer-sets/(LayerSetID)/recall

Supported methods: “GET” “POST
Available since: mimoLive 5.0
Recalls (activates) the layer set specified by “(LayerSetID)”, causing all layers to assume the live state recorded in the layer set.
Returns the layer set after recalling, i.e. with “active == true”.

Data Stores

/documents/(DocumentID)/datastores/(StoreID)

Supported methods: “GET”, “PUT”, “DELETE
mimoLive offers the ability to store data you provide inside the document file, for example to restore a state at a later time. You are free to choose a “StoreID” yourself, but be aware that there is no way to list all data stores associated with a document (however, you may create some kind of index store that keeps track of your other, dynamically named stores).

Create/Update a data store

To create or update a data store send a “PUT” request to a “StoreID” of your choice with the associated data in the body of your request. If the operation was successfull mimoLive will respond with a “200 OK” status.

Read contents of a data store

To read a previously stored data store simple request it via “GET”. The data will be returned exactly as you provided it in the “PUT” request to store it. If no data store with that ID was found for this document mimoLive will return a “404 Not Found” error.

Delete an existing data store

To delete a data store when you no longer need it simply issue an “DELETE” request for the “StoreID” you want to delete. In the event that the data store was not there in the first place mimoLive will respond with a “404 Not Found” error.

Your Feedback

How would you rate your experience with this feature of mimoLive®?

Email Newsletter

English

Join the 24/7 Live Zoom® Demo

*required