Exempel på användning av API

Styrning av mimoLive med php

Vi har ett väldokumenterat exempel på PHP-skript på GitHub:
https://github.com/boinx/mimoLive-HTTP-Demo

Kontroll av mimoLive med CURL

För att styra mimoLive via HTTP kan du använda bash-kommandot "curl". För att curl-kommandona ska fungera måste du hitta ID:t för det mimoLive-dokument som du vill manipulera.

Styrning av mimoLive med automatiseringslager

The Automatiseringsskikt kan utföra några enkla kommandon för att utlösa åtgärder i mimLive av deras API Slutpunkter. Den har också ett httpRequest()-kommando för att utföra alla typer av GET begäran om åtgärder HTTP API är kapabel till.

Förkunskapskrav

- Öppna det dokument du vill manipulera i mimoLive.
- Se till att dokumentet är i ett färdigt tillstånd så att API-slutpunkterna som lager inte ändras längre. Tänk på att om du tar bort ett lager och lägger till det igen kommer lagret att ha ett annat lager-ID när du pratar med det via API:et. Om du ordnar om lager eller lägger till lagervarianter ändras dock inte lager-ID:t.
- Aktivera HTTP-Server i mimoLive Inställningar för fjärrkontroll. Markera alternativet "Tillåt åtkomst för fjärrkontroll":

Vänligen notera IP-nummer eller IP-adress med portnummer för mimoLive för vidare användning när du arbetar med HTTP API.

Att få en API Slutpunkt

Innan mimoLive 5.5 var det svårt att få fram dokument-ID och t.ex. ett lager-ID med terminalkommandon som letade igenom långa JSON data. Sedan mimoLive 5.5 är det mycket enklare:

Först av allt, kopiera mimoLive HTTP serverbas URL från avsnittet Fjärrkontroll i mimoLives preferensfönster (se skärmdump ovan). Öppna en textredigerare (t.ex. TextEdit från Apple) och klistra in urklippets innehåll i ett nyskapat textdokument. Se till att det finns nej backslash i slutet av kommandot URL! Resultatet bör se ut så här:

http://172.28.30.202:8989

I mimoLives dokumentfönster kan du med musen högerklicka (eller kontrollklicka, eller tvåfingerklicka) på det objekt du är intresserad av (t.ex. ett lager, en källa, en knapp i en lagerkontroll) för att få fram en snabbmeny. Det finns ett menyalternativ som låter dig kopiera API Slutpunkt till macOS Urklipp för att använda det i din mimoLive API projekt.

Ibland är det viktigt att adressera en specifik lagervariant snarare än lagret i allmänhet. Om du högerklickar på ett lagers parameter ser du att det finns olika API slutpunkter för antingen det aktuella live-lagret eller den specifika lagervarianten:

Gå tillbaka till din textredigerare och klistra in det just kopierade API Slutpunkt efter HTTP Serverbas URL. Nu är URL i din webbläsare bör se ut så här

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

Detta är den slutliga API Slutpunkt för att adressera ett lager i ditt dokument. I detta exempel 458706932 är dokumentets ID och BA868701-8131-49CB-8EDD-8C7E6E7CD60B är det specifika skikt-ID:t för ett visst skikt i detta dokument.

Tillkoppling och OFF ett lager

Med den hämtade API Slutpunkt för ett visst lager kan du slå på och av med följande terminalkommandon.

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

Ändra ett värde för ett lager

- Alla parametrar för ett lager kan ställas in via HTTP API. Du måste hitta rätt nyckel för att kunna ange ett nytt värde. I vårt exempel kommer vi att ange titeln på en Lower Third Skikt med nyckeln tvGroup_Content__Title. Eftersom vi behöver skicka det nya värdet i en JSON fil till HTTP server med en PUT begära att curl-kommandot blir lite trångt.

*Var noga med att ersätta xxxxxxxxx med ditt specifika lager API Slutpunkt!

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

Samling av användbara API Kommandon för dig att utforska

Inställning av RTMP URL och streamingnyckel för en destination för direktuppspelning:

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

Ange filnamn och sökväg för en filskrivares utdatadestination

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

Ställa in videokällan för ett placeringslager

yyyyyyyyyyyyyyy kommer att vara UUID av videokällan. (e.g CCAF4418-367A-415F-AD25-6536C3EF3512)

xxxxxxxxxxxxx kommer att vara API slutpunkt för en viss lagervariant. (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"

Ställa in volymen för ett lager som har en ljudvolymratt

Med detta curl-kommando kan du ändra ljudvolymen för ett lager som har en ljudjusteringsratt (som Placerskikt). Värdet "volym" kan anta värden från 0,0 till 1,0.

xxxxxxxxxxxxx kommer att vara API Skiktets slutpunkt (t.ex. 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"

Ställa in färg för ett bakgrundslager

xxxxxxxxxxxxx kommer att vara API slutpunkt för en viss lagervariant. (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"

Rensa filvägen för en videokälla för Sista inspelningen

I din Källförvaring, kan du ha en Senaste inspelningskälla vilket ger tillgång till den senaste inspelningen som varje File Recording Output Destination kommer att tillkännage. I en kioskapplikation kommer det att vara nödvändigt att rensa sökvägen för den senaste inspelningen så att nästa användare av stationen inte kan granska den föregående användarens inspelning. Med följande Kommando för automatiseringslager kan du rensa bort denna information från den senaste inspelningskällan:

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)

Lagring JSON Data i mimoLive-dokumentet

Med ändpunkten "datastores" kan du lagra alla typer av data i mimoLive-dokumentet för att bevara dem över en dokumentomladdning. Du måste använda en "PUT" begäran om att spara data och en "GET" för att läsa tillbaka den. Du kan lagra alla typer av data, men i det här exemplet lagrar vi JSON Data eftersom detta verkar vara ett mycket vanligt användningsfall. Om du vill lagra andra data måste du justera -H-parametern i enlighet med detta.

Curl-kommando för att lagra data:
bc. curl -data '{"myData1": 1.5, "myData2":"Någon text"}' -H "Innehållstyp: applikation/json" -X PUT http://127.0.0.1:8989/api/v1/documents/1643911183/datastores/myDataStore1

Curl-kommando för att läsa tillbaka data:
bc. curl -X GET http://127.0.0.1:8989/api/v1/documents/1643911183/datastores/myDataStore1

Uppdatera sökvägen till källfilen för en mediefil

Du kanske vill byta ut filmen som spelas eller ersätta en annons som visas av en Källa för mediefiler. Detta kan göras med ett uppdateringskommando som utförs på källan API slutpunkt.

Kontrollera att filreferensläget för mediekällan är inställt på "Absolut Path". Hämta den API slutpunkt för denna källa genom att högerklicka på den i den vänstra kolumnen och välja "Kopiera källans API Endpoint to Clipboard" i snabbmenyn. Skapa en URL av följande form:

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

Se till att koda JSON uppgifter i URL för att få en giltig URL som kan användas i ett curl-kommando på följande sätt:

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

*Observera att du kan använda "~" i början av filsökvägen för att referera till hemkatalogen för den aktuella användaren.

Styrning av mimoLive med Apple Script

För närvarande har mimoLive inget inbyggt stöd för Apple Script. Du kan dock använda en lösning för att nå ut till mimoLive: Det finns ett "do shell script"-kommando i Apple Script som låter dig utföra bash-kommandon som "curl". I föregående avsnitt förklaras hur man skapar ett curl-kommando för att manipulera ett visst lager eller lagervärde.

När du är nöjd med ditt curl-kommando måste du linda in det i ett "do shell script"-kommando i Apple Script:

*Fallgropar i Apple-skript
I Apple Script finns det två fallgropar när man för över ett terminalkommando som "curl" till kommandot do shell script:
1. Alla " måste föregås av ett \ för att Apple-Script-parsern ska veta att de inte är slutmarkörer för kommandot do shell script. \ är ett escape-tecken som talar om för parsern att den ska ignorera följande tecken.
2. Om du konkatenerar flera textdelar med & så är detta en "lista över text" för Apple Script snarare än en enda text. Do shell-kommandot fungerar inte med "list of text" och därför måste du konvertera den tillbaka till en enda text med "as text" i slutet av curl-kommandotexten.

Detta exempel visar hur du anger titeln på en lägre tredjedel:

*Var noga med att ersätta xxxxxxxxx med ditt specifika lager API Slutpunkt!

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

Följande exempel på Apple-skript visar hur man slår på ett lager varje halvtimme på timmen: Detta kan vara användbart för kommersiella överlagringar. Se till att använda ett lager som stänger av sig självt efter en viss tid (t.ex. ett Placer Layer med en filmkälla som inte loopar kommer att göra det).

*Var noga med att ersätta xxxxxxxxx med ditt specifika lager API Slutpunkt!

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

Konvertering av en CURL kommando med JSON Data till en HTTP URL för enkel HTTP Förfrågningar

Ibland är det bara möjligt att skicka en enkel HTTP förfrågan till mimoLive istället för att använda ett curl-kommando, t.ex. när det gäller automatiseringsappar från tredje part eller automatiseringslagret mimoLive självt. Detta kräver att curl-kommandots datablock konverteras till att vara en del av URL. Du kan göra på följande sätt:

Låt oss anta att vi har följande curl-kommando:

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

Du skulle ta HTTP del första:

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

Lägg till ?uppdatering= till den:

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

Hämta alla -data sträng och ta bort alla onödiga mellanslag:

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

Koda detta till dess URL form av escaping av icke-URL-konforma tecken (t.ex. med hjälp av 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

Slutligen, lägg allt detta efter ?uppdateringen= så här:

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 kan du använda detta URL i en enkel HTTP begäran.