On one hand, mimoLive publishes a Remote Control UI which you can use to create custom user interfaces that you can use on a tablet or similar device to remote control mimoLive.
Additionally, mimoLive provides access to the bare HTTP API so you can create custom scripts (via bash and curl, AppleScript, build-in Automation Layer or something similar that can talk to an HTTP server) that control various aspects of mimoLive – the possibilities are nearly endless. (See Examples of API usage)
In this topic, we will focus on the bare HTTP API. As the API is based on the json:api specification be sure to familiarize yourself with it before working with the mimoLive API.
*In addition to the documentation you can also have a look at our PHP demo scripts on github
Also, there is an example for Shell and Apple Script available.
API Access
The mimoLive API is accessible on the same machine mimoLive is running on (via “localhost”) and on the local network (via “.local”).
If enabled mimoLive serves an HTTP server on “port 8989”.
All the API calls are prefixed with a path of “/api/v1/” so for example if you want to get a list of opened documents you would call “http://localhost:8989/api/v1/documents”.
All IDs (for documents, layers, sources, output destinations etc.) are stored and persisted to disk, so hard-coding these values is safe as long as the same document is used inside mimoLive.
Please refer to API Endpoints to learn more about all the endpoints provided.
Authentication
Starting with mimoLive 3.1, if the user enabled authentication in the mimoLive preferences, you need to provide the user password for every request to the API which can be done in two ways:
- Setting the custom HTTP header “X-MimoLive-Password-SHA256: xxxxxxx”
- Appending the query parameter “?pwSHA256=xxxxxxx”
In both cases, xxxxxxx has to be replaced by the original password (in UTF-8 encoding) hashed using SHA-256 and encoded as a string of hexadecimal digits.
To ease the development of custom scripts and applications, mimoLive shows this API key and allows copying to the clipboard in the Remote Controls preference pane:
Deprecated Authentication Method
Prior to mimoLive version 3.1, requests against the API would be authenticated using the special HTTP header “X-MimoLive-Password: “ or the query parameter “?pw=” on every request.
Unfortunately, this method sends the password in the clear over a potentially insecure network connection which may expose sensitive data if the HTTP API password is being reused elsewhere.
While it continues to work, this authentication method is therefore discouraged and may be removed in the future.
Errors
If an error occurs during a request, mimoLive will stop processing that request and return an HTTP response with its status code indicating the error. The response also contains a JSON payload array of error objects containing additional information about each error that occurred:
{
"errors": [
{
"status": "404",
"title": "Not Found",
"description": "The requested object could not be found"
}
]
}Remote Access via the Internet
As the HTTP API is enabled by a webserver built into mimoLive, remote access to the HTTP API from anywhere on the Internet could be enabled by giving the mimoLive computer a public IP number. Since the HTTP API isn’t very well protected, this is a bad idea. A better way to enable remote access to the HTTP API via a public network is to establish a secure tunnel to your mimoLive host computer using ngrok.
