Voorbeelden van API-gebruik

MimoLive besturen met php

We hebben een goed gedocumenteerd voorbeeld PHP script op GitHub:
https://github.com/boinx/mimoLive-HTTP-Demo

MimoLive besturen met CURL

Om mimoLive te bedienen via HTTP kun je het bash commando "curl" gebruiken. Om de curl-commando's te laten werken, moet je de ID vinden van het mimoLive-document dat je wilt manipuleren.

MimoLive besturen met Automatiseringslaag

De Automatiseringslaag kunnen enkele eenvoudige commando's uitvoeren om acties in mimLive te activeren door hun API Eindpunten. Het heeft ook een httpRequest() commando om elk soort GET verzoekacties de HTTP API in staat is.

Vereisten

- Open het document dat u wilt bewerken in mimoLive.
- Zorg ervoor dat het document in een voltooide staat is, zodat de API-eindpunten zoals Lagen niet meer veranderen. Houd er rekening mee dat als je een laag verwijdert en weer toevoegt, deze laag een andere laag-ID krijgt als je er via de API mee praat. Het opnieuw ordenen van lagen of het toevoegen van laagvarianten zal de laag-ID echter niet veranderen.
- Schakel de HTTP-server in de voorkeuren voor afstandsbediening van mimoLive. Vink de optie "Toegang op afstand toestaan" aan:

Noteer het IP-nummer of IP-adres met het poortnummer van mimoLive voor verder gebruik bij het werken met de HTTP API.

Een API Eindpunt

Vóór mimoLive 5.5 was het moeilijk om het document-ID en bijvoorbeeld een laag-ID te krijgen met Terminal-opdrachten die door lange JSON gegevens. Sinds mimoLive 5.5 is het veel eenvoudiger:

Kopieer eerst de mimoLive HTTP serverbasis URL in de sectie Afstandsbediening van het voorkeurenvenster van mimoLive (zie bovenstaande schermafbeelding). Open een teksteditor (bijv. TextEdit van Apple) en plak de inhoud van het klembord in een nieuw aangemaakt tekstdocument. Zorg ervoor dat er geen backslash aan het einde van de URL! Het resultaat zou er zo uit moeten zien:

http://172.28.30.202:8989

In het mimoLive-documentvenster kun je met de rechtermuisknop (of control-klik, of twee-vinger-klik) op het object van interesse klikken (bijv. een Layer, een Bron, een knop van een Layer-besturingselement) om een contextmenu te krijgen. Er is een menu-item waarmee je de API Eindpunt naar het macOS Klembord voor gebruik in je mimoLive API project.

Soms is het belangrijk om een specifieke laagvariant aan te pakken in plaats van de laag in het algemeen. Als je met de rechtermuisknop klikt op de parameter van een laag, zie je dat er verschillende API eindpunten voor de huidige live laag of de specifieke laagvariant:

Ga terug naar je tekstverwerker en plak het zojuist gekopieerde API Eindpunt na de HTTP Serverbasis URL. Nu de URL in je tekstbrowser er zo uit zou moeten zien:

http://172.28.30.202:8989/api/v1/documents/458706932/layers/BA868701-8131-49CB-8EDD-8C7E6E7CD60B

Dit is de laatste API Endpoint om een laag in je document aan te spreken. In dit voorbeeld 458706932 is de document-ID en BA868701-8131-49CB-8EDD-8C7E6E7CD60B is de specifieke laag-ID van een bepaalde laag in dit document.

Inschakelen van ON en UIT a Laag

Met de opgehaalde API Eindpunt voor een bepaalde laag kun je aan- en uitzetten met de volgende terminalopdrachten.

curl xxxxxxxxx/setLive
curl xxxxxxxxx/setOff
curl xxxxxxxxx/toggleLive
# our example will look like this:
curl http://172.28.30.202:8989/api/v1/documents/458706932/layers/BA868701-8131-49CB-8EDD-8C7E6E7CD60B/setLive

Een waarde van een laag wijzigen

- Alle parameters van een laag kunnen worden ingesteld via de HTTP API. Je moet de juiste sleutel vinden om een nieuwe waarde in te stellen. In ons voorbeeld stellen we de titel van een Lower Third Laag met de sleutel tvGroup_Content__Title. Omdat we de nieuwe waarde in een JSON bestand naar de HTTP server met een PUT het curl commando aanvragen wordt een beetje druk.

*Zorg ervoor dat u xxxxxxxxx vervangt door uw specifieke laag API Eindpunt!

curl -d '{"input-values":{"tvGroup_Content__Title":"My new title"}}' -H "Content-Type: application/json" -X PUT "xxxxxxxxx"

Verzameling van nuttige API Commando's om te verkennen

De RTMP URL en Streaming Key van een Live Streaming uitvoerbestemming:

curl --data '{"data": { "attributes": {"settings": {"rtmpurl":"rtmp://mystreaminghost.com", "streamingkey":"MYTOTALLYSECRETSTREAMKEY"} } } }' --request PATCH http://192.168.0.100:8989/api/v1/documents/458706932/output-destinations/4D072496-1CE3-418E-B73E-59A2927A2110

De bestandsnaam en het pad van een uitvoerbestemming van de bestandsschrijver instellen

curl --data '{"data": { "attributes": {"settings": { "location": "~/Destktop/Recordings", "filename": "MyGreatShow %year-%month-%day-%hour-%minute.%extension" } } } }' --request PATCH http://192.168.0.100:8989/api/v1/documents/458706932/output-destinations/4D072496-1CE3-418E-B73E-59EDA388BB

De videobron van een plaatsingslaag instellen

yyyyyyyyyyy zal de UUID van de videobron. (e.g CCAF4418-367A-415F-AD25-6536C3EF3512)

xxxxxxxxxxxxxxxxxxxxx zal de API eindpunt van de bepaalde laagvariant. (e.g. http://172.28.30.202:8989/api/v1/documents/2014814935/layers/BA868701-8131-49CB-8EDD-8C7E6E7CD60B/variants/AA868701-8131-49CB-8EDD-8C7E6E7CD60A)

curl -d '{"input-values":{"tvIn_VideoSourceAImage":"yyyyyyyyyyyyy"}}' -H "Content-Type: application/json" -X PUT "xxxxxxxxxxxxxxxx"

Het volume instellen van een laag met een audiovolumeknop

Met dit curl commando kun je het geluidsvolume wijzigen van een laag die een audio-instelknop heeft (zoals de Minerale laag). De waarde "volume" kan waarden aannemen van 0,0 tot 1,0.

xxxxxxxxxxxxxxxxxxxxx zal de API eindpunt van de laag (bijv. http://10.101.2.2:8989/api/v1/documents/13195157/layers/BA868701-8131-49CB-8EDD-8C7E6E7CD60B)

curl -d '{"volume": 0.5}' -H "Content-Type: application/json" -X PUT "xxxxxxxxxxxxxxxx"

De kleur van een achtergrondlaag instellen

xxxxxxxxxxxxxxxxxxxxx zal de API eindpunt van de bepaalde laagvariant. (e.g. http://172.28.30.202:8989/api/v1/documents/2014814935/layers/BA868701-8131-49CB-8EDD-8C7E6E7CD60B/variants/AA868701-8131-49CB-8EDD-8C7E6E7CD60A)

curl -d '{"input-values":{"tvGroup_Appearance__Color_1":{"red": 1.0, "blue": 0.5, "green": 0, "alpha": 0.5}}}' -H "Content-Type: application/json" -X PUT "xxxxxxxxxxxxxxxx"

Het bestandspad van een videobron van de laatste opname wissen

In uw Bronnenarchiefkun je een Laatste opnamebron die toegang geeft tot de laatste opname die elke Bestand Opname Uitvoer Bestemming zal aankondigen. In een kiosktoepassing zal het nodig zijn om het laatste opnamepad te wissen zodat de volgende gebruiker van het station niet in staat is om de opname van de vorige gebruiker te bekijken. Met het volgende Opdracht Automatiseringslaag kunt u deze informatie wissen uit de Laatste opnamebron:

httpRequest(http://127.0.0.1:8989/api/v1/documents/2014814935/sources/2014814935-413AC0A3-AC43-4A7D-A228-6D0181BF1476?update=%7B%22filepath%22%3A%22%22%7D)

Opslaan JSON Gegevens in het mimoLive-document

Met het "datastores" eindpunt kun je elk soort data in het mimoLive document opslaan om het te behouden na een documentherlading. Je moet een "PUT" verzoek om de gegevens op te slaan en een "GET" om het terug te lezen. Je kunt alle soorten gegevens opslaan, maar in dit voorbeeld slaan we op JSON Gegevens omdat dit een veelvoorkomend gebruik lijkt te zijn. Als je andere gegevens wilt opslaan, moet je de -H parameter overeenkomstig aanpassen.

Curl commando om gegevens op te slaan:
bc. curl -data '{"myData1": 1.5, "myData2":"Sommige tekst"}' -H "Inhoudstype: toepassing/json" -X PUT http://127.0.0.1:8989/api/v1/documents/1643911183/datastores/myDataStore1

Curl commando om gegevens terug te lezen:
bc. curl -X GET http://127.0.0.1:8989/api/v1/documents/1643911183/datastores/myDataStore1

Het bronbestandspad van een mediabron bijwerken

Misschien wil je de film die wordt afgespeeld vervangen of een advertentie die wordt getoond door een Bron mediabestand. Dit kan worden gedaan met een updateopdracht die wordt uitgevoerd op de bron API eindpunt.

Zorg ervoor dat de bestandsreferentiemodus van de mediabron is ingesteld op "Absolut Path". Verkrijg de API eindpunt voor deze bron door er met de rechtermuisknop op te klikken in de linkerkolom en "Kopieer bron API Endpoint to Clipboard" in het contextmenu. Maak een URL van de volgende vorm:

http://127.0.0.1:8989/api/v1/documents/<YOUR DOCUMENT ID>/sources/<SOURCE API ENDPOINT>?update={"filepath":"<LOCAL FILE PATH>"}

Zorg ervoor dat je de JSON gegevens in de URL om een geldige URL die als volgt in een curl-opdracht kan worden gebruikt:

curl -X GET http://127.0.0.1:8989/api/v1/documents/1748069974/sources/1748069974-334DA2E4-DFF3-4225-8F4A-D09D40A6BD5D?update=%7B%22filepath%22:%22~/Desktop/Screen%20Recording%202022-07-27%20at%2012.18.23.mov%22%7D

*Merk op dat je gebruik kunt maken van de "~" aan het begin van het bestandspad om te verwijzen naar de thuismap van de huidige gebruiker.

MimoLive besturen met Apple Script

Momenteel ondersteunt mimoLive geen Apple Script. Je kunt echter een workaround gebruiken om mimoLive te bereiken: Er is een "do shell script" commando in apple script waarmee je bash commando's zoals "curl" kunt uitvoeren. De vorige sectie legt uit hoe je een curl commando maakt om een bepaalde laag of laagwaarde te manipuleren.

Als je tevreden bent met je curl commando moet je het in een "do shell script" commando verpakken in Apple Script:

*Valkuilen in Apple Script
In Apple Script zijn er twee valkuilen bij het overbrengen van een terminal commando zoals "curl" naar het do shell script commando:
1. Alle " moeten voorafgegaan worden door een om de Apple-Script parser te laten weten dat dit niet de eindmarkeringen zijn voor het do shell script commando. De is een escape karakter om de parser te vertellen het volgende karakter te negeren.
2. Als je meerdere tekstdelen aan elkaar rijgt met & dan is dit een "lijst met tekst" voor Apple Script in plaats van een enkele tekst. Het do shell commando werkt niet met een "lijst met tekst" en daarom moet je het terug converteren naar een enkele tekst met de "as text" aan het einde van je curl commando tekst.

Dit voorbeeld toont hoe je de titel van een lager derde deel instelt:

*Zorg ervoor dat u xxxxxxxxx vervangt door uw specifieke laag API Eindpunt!

set layerAPIEndpoint to "xxxxxxxxx" -- in our example this would be "http://172.28.30.202:8989/api/v1/documents/458706932/layers/BA868701-8131-49CB-8EDD-8C7E6E7CD60B"
set lowerThirdTitle to "Hello World!"
do shell script "curl -d '{\"input-values\":{\"tvGroup_Content__Title\":\"" & lowerThirdTitle & "\"}}' -H \"Content-Type: application/json\" -X PUT \"" & layerAPIEndpoint & "\"" as text

Het volgende voorbeeldscript van Apple laat zien hoe je elk half uur op het hele uur een laag kunt inschakelen: Dit kan handig zijn voor commerciële overlays. Zorg ervoor dat je een laag gebruikt die zichzelf na een bepaalde tijd uitschakelt (bijvoorbeeld een plaatslaag met een niet-lopende filmbron doet dat).

*Zorg ervoor dat u xxxxxxxxx vervangt door uw specifieke laag API Eindpunt!

-- configure your Layer API Endpoint:
set layerAPIEndpoint to "xxxxxxxxx" -- in our example this would be "http://172.28.30.202:8989/api/v1/documents/458706932/layers/BA868701-8131-49CB-8EDD-8C7E6E7CD60B"
-- repeat endlessly:
repeat
	-- get the seconds last in this hour
	set currentDate to current date
	set secondsToNextHour to 3600 - ((minutes of currentDate) * 60 + (seconds of currentDate))
	-- --------------------------------------------
	-- The following code snippet is useful only if you want to
	-- switch the layer live on half hours also.
	-- if you don't want this behaviour you can delete this part.
	-- --------------------------------------------
	-- check if we are currently in the first half of the hour
	if secondsToNextHour > 1800 then
		-- yes, we are in the first half of the hour, so only wait half the time
		set secondsToNextHour to secondsToNextHour - 1800
	end if
	-- --------------------------------------------
	-- wait until the time to trigger the layer
	delay secondsToNextHour
	-- set the specified layer to live:
	do shell script "curl \"" & layerAPIEndpoint & "/setLive\"" as text
	-- wait a couple of seconds to make sure we don't glitch in time
	delay 5
end repeat

Een CURL commando met JSON Gegevens naar een HTTP URL voor eenvoudige HTTP Verzoeken

Soms is het alleen mogelijk om een eenvoudige HTTP verzoek naar mimoLive in plaats van een curl commando, bijvoorbeeld in het geval van 3rd party automation apps of de Automation Layer mimoLive zelf. Hiervoor moet het gegevensblok van het curl-commando worden geconverteerd zodat het deel uitmaakt van de URL. U kunt dit als volgt doen:

Laten we aannemen dat we het volgende curl commando hebben:

curl --data '{"data": { "attributes": {"settings": {"rtmpurl":"rtmp://mystreaminghost.com", "streamingkey":"MYTOTALLYSECRETSTREAMKEY"} } } }' --request PATCH http://192.168.0.100:8989/api/v1/documents/458706932/output-destinations/4D072496-1CE3-418E-B73E-59A2927A2110

Je zou de HTTP deel eerst:

http://192.168.0.100:8989/api/v1/documents/458706932/output-destinations/4D072496-1CE3-418E-B73E-59A2927A2110

Voeg toe update= aan:

http://192.168.0.100:8989/api/v1/documents/458706932/output-destinations/4D072496-1CE3-418E-B73E-59A2927A2110?update=

Krijg alle -gegevens string en verwijder alle overbodige spaties:

{"data":{"attributes":{"settings":{"rtmpurl":"rtmp://mystreaminghost.com","streamingkey":"MYTOTALLYSECRETSTREAMKEY"}}}}

Codeer dit naar zijn URL vorm door escapen van de niet-URL-conforme tekens (bijv. met https://www.urlencoder.org/)

%7B%22data%22%3A%7B%22attributes%22%3A%7B%22settings%22%3A%7B%22rtmpurl%22%3A%22rtmp%3A%2F%2Fmystreaminghost.com%22%2C%22streamingkey%22%3A%22MYTOTALLYSECRETSTREAMKEY%22%7D%7D%7D%7D

Zet dit alles ten slotte na de ?update= op deze manier:

http://192.168.0.100:8989/api/v1/documents/458706932/output-destinations/4D072496-1CE3-418E-B73E-59A2927A2110?update=%7B%22data%22%3A%7B%22attributes%22%3A%7B%22settings%22%3A%7B%22rtmpurl%22%3A%22rtmp%3A%2F%2Fmystreaminghost.com%22%2C%22streamingkey%22%3A%22MYTOTALLYSECRETSTREAMKEY%22%7D%7D%7D%7D

Nu kun je dit gebruiken URL in een eenvoudige HTTP verzoek.