mimoLive User Manual

The mimoLive™ User Manual Developer Hub

Welcome to the mimoLive™ User Manual developer hub. You'll find comprehensive guides and documentation to help you start working with mimoLive™ User Manual as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

.Endpoints & Methods

Learn which endpoints can be used to query and modify mimoLive's data.

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:

Parameter

Default

Description

format

png

The format in which the preview is returned. Allowed values: png, jpeg, mjpeg, mpng

fps

10

The 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"
    }
}

Note: 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

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.

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

Supported methods: GET
Available since: mimoLive 4.2
Returns the output destination specified by (OutputDestinationID).
For information on the objects returned see the output-destinations data type.

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 for more information)

Update description must be given in JSON:API update format. Example:

{
  "data": {
    "type": "output-destinations",
    "id": "4FF003EA-D071-43FD-845F-DCD4A25DFA00",
    "attributes": {
      "title": "Our Recording",
      "starts-with-show": true,
      "settings": {
        "location": "~/Movies"
      }
    }
  }
}
# Update the output destination title and the recording's filename
curl -X "PATCH" "http://localhost:8989/api/v1/documents/78834821/output-destinations/4FF003EA-D071-43FD-845F-DCD4A25DFA00" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "data": {
    "type": "output-destinations",
    "id": "4FF003EA-D071-43FD-845F-DCD4A25DFA00",
    "attributes": {
      "title": "New Output Destination Name",
      "settings": {
        "filename": "Recording 1234.mov"
      }
    }
  }
}'

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

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.

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

Supported methods: GET
Available since: mimoLive 5.0
Returns the layer set specified by (LayerSetID).
For information on the objects returned see the layer-sets data type.

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.

Updated 7 days ago


What's Next

Learn more about the data returned by these methods.

Data Types

.Endpoints & Methods


Learn which endpoints can be used to query and modify mimoLive's data.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.