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    

Examples of API usage

Controlling mimoLive with php

We have a good documented sample php script on github:
https://github.com/boinx/mimoLive-HTTP-Demo

Controlling mimoLive with CURL

To control mimoLive via HTTP you can use the bash command "curl". For the curl commands to work you need to find the ID of your document you want to manipulate:

Prerequisites

  • Open the document you want to manipulate in mimoLive.
  • Enable the HTTP-Server in mimoLive Remote Control Preferences. Check the "Allow Remote Control Access" option:

Get the Document ID

  • Launch the "Terminal" app by Apple. You should get a new window with a terminal prompt.
  • Copy&Paste the following command into the Terminal's window. This will output a JSON data file describing the current state of your document.
curl http://localhost:8989/api/v1/documents/

The API Responds is always in unformatted compact JSON format

Because a JSON file can be very long and usually isn't read by humans but your program the output of the mimoLive HTTP API is in an unformatted compact form. You may use an online JSON formatter to get it in shape.

In the result please find the document ID in the first "data" container. In this sample data its 1259565357:

{
	"links": {
		"self": "\/api\/v1\/documents"
	},
	"data": [{
		"id": "1259565357",
		"relationships": {
			"sources": {
				"links": {
					"related": "\/api\/v1\/documents\/1259565357\/sources"
				},
				"data": [{
					"type": "sources",
					"id": "1259565357-com.boinx.BoinxTV.Camera.1"
<snip>

With this document ID you are able to dig deeper into the document structure and data.

Get a Layer ID

  • Use the following curl command to get all layers of your document.

Please make sure to replace the xxxxxxxxx with your document ID you found in the previous steps.

curl http://localhost:8989/api/v1/documents/xxxxxxxxx/layers/

The JSON respond should look something like this:

{
	"links": {
		"self": "\/api\/v1\/documents\/1259565357\/layers"
	},
	"data": [{
		"id": "F92A067C-AF78-421A-ADFD-E44E14D94782",
		"relationships": {
			"document": {
				"links": {
					"related": "\/api\/v1\/documents\/1259565357\/"
				},
				"data": {
					"type": "documents",
					"id": "1259565357"
				}
			},
			"live-variant": {
				"data": null
			},
			"variants": {
				"links": {
					"related": "\/api\/v1\/documents\/1259565357\/layers\/F92A067C-AF78-421A-ADFD-E44E14D94782\/variants"
				},
				"data": [{
					"type": "variants",
					"id": "9C1E07E4-B6E7-4ABD-8B43-4BEC040E99AF"
				}]
			},
<snip>
  • From this result extract the layer ID you want to manipulate. In this example its F92A067C-AF78-421A-ADFD-E44E14D94782

Switching ON and OFF a Layer

  • With the retrieved document ID and layer ID you can toggle on and off this particular layer with the following terminal commands.

Please make sure to replace xxxxxxxxx with your document ID and yyyyyyyyy with your layer ID from the previous steps.

curl http://localhost:8989/api/v1/documents/xxxxxxxxx/layers/yyyyyyyyy/setLive

curl http://localhost:8989/api/v1/documents/xxxxxxxxx/layers/yyyyyyyyy/setOff

curl http://localhost:8989/api/v1/documents/xxxxxxxxx/layers/yyyyyyyyy/toggleLive

Setting a Value of a Layer

  • All the parameter of a layer can be set via the HTTP API. You need to find the correct key in order to set a new value. In our example we will set the Title of a Lower Third Layer] with the key tvGroup_Content__Title. Because we need to send the new value in a JSON file to the HTTP server with a PUT request the curl command gets a bit crowded.

Please make sure to replace xxxxxxxxx with your document ID and yyyyyyyyy with your layer ID from the previous steps.

curl -d '{"input-values":{"tvGroup_Content__Title":"My new title"}}' -H "Content-Type: application/json" -X PUT "http://localhost:8989/api/v1/documents/xxxxxxxxx/layers/yyyyyyyyy/"

Controlling mimoLive with Apple Script

Currently mimoLive doesn't natively support Apple Script. However you can use a workaround to reach out to mimoLive: There is a "do shell script" command in apple script that let you perform bash commands like "curl". The previous section explains how to create a curl command to manipulate a certain layer or layer value.

Once you are satisfied with your curl command you need to wrap it in a "do shell script" command in Apple Script:

Pitfalls in Apple Script

In Apple Script there are two pitfalls when bringing a terminal command like "curl" over to the do shell script command:

  1. All " needs to be prefixed with a \ in oder to let the Apple-Script parser to know that those are not the end markers for the do shell script command. The \ is an escape character to tell the parser to ignore the following character.

  2. If you concatenate multiple text parts with & then this is a "list of text" to Apple Script rather than a single text. The do shell command won't work with "list of text" and therefore your need to convert it back to a single text with the "as text" at the end of your curl command text.

Please make sure to replace xxxxxxxxx with your document ID and yyyyyyyyy with your layer ID from the previous steps.

set documentID to "xxxxxxxxx"
set layerID to "yyyyyyyyy"
set lowerThirdTitle to "Hello World!"

do shell script "curl -d '{\"input-values\":{\"tvGroup_Content__Title\":\"" & lowerThirdTitle & "\"}}' -H \"Content-Type: application/json\" -X PUT \"http://localhost:8989/api/v1/documents/" & documentID & "/layers/" & layerID & "\"" as text

Examples of API usage


Suggested Edits are limited on API Reference Pages

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