Exempel på användning av API

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.

Sätt att fjärrstyra mimoLive

Styrning av mimoLive med fjärrkontrollytor

Det mest effektiva sättet är att skapa en anpassad Remote Control Surface för ditt mimoLive-dokument, som kan köras på en iPad, iPhone eller någon annan enhet med en webbläsare.

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.

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.

❗

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 dessa inte är slutmarkörerna för do shell script-kommandot. \ är ett escape-tecken som talar om för parsern att den ska ignorera följande tecken. 2. Om du sammanfogar flera textdelar med & så är detta en "lista med text" för Apple Script snarare än en enda text. Shellkommandot do fungerar inte med "list of text" och därför måste du konvertera tillbaka den till en enda text med "as text" i slutet av ditt curl-kommando text

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:

*

Se till att ersätta xxxxxxxxx med ditt specifika lags 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"

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

*

Se till att ersätta xxxxxxxxx med ditt specifika lags API Endpoint!

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

Styrning av användargränssnittselement i mimoLive

Att få en API Slutpunkt

API-slutpunkter är viktiga för att adressera specifika element i ditt mimoLive-dokument. För en lista över tillgängliga API-slutpunkter, vänligen se API-slutpunkter.

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.

Att högerklicka på vissa användargränssnittselement för att visa en snabbmeny för att hämta den specifika API-slutpunkten fungerar för följande:

• Källor
• Skikt
• Varianter av lager
• Lager Parameter
• Utgångsdestinationer
• Lageruppsättningar

Exempel: Koppling av ON 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.

*

Se till att ersätta xxxxxxxxx med API-ändpunkten från föregående steg!

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

*

URL-adresserna fungerar även i en webbläsare

Dessa URL:er (utan "curl"-kommandot) kan också skrivas in i adressfältet i en webbläsare. När du trycker på retur kommer webbläsaren att anropa mimoLives HTTP-server och utföra det kommando du angav. Om du har JSON-data som du behöver skicka till API-slutpunkten kan du också lägga till detta i URL:en, se "Konvertera ett CURL-kommando med JSON-data till en HTTP-URL för enkla HTTP-förfrågningar" nedan.

Ett enkelt sätt att få den fullständiga HTTP-URL:en för att aktivera eller inaktivera ett lagers live-tillstånd är att högerklicka på lagrets Live-knapp för att visa en snabbmeny och välja "Copy URL To Set Layer Live". Detta kommer att kopiera webbadressen till urklippet för din användning. I skärmdumpen kan du se snabbmenyn för Live-knappen i ett Lower Third-lager.

Exempel: Ä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"

Ett snabbt sätt att få en komplett HTTP-URL för att utlösa uppdateringen av en lageregenskap är att högerklicka på egenskapens namn, visa en snabbmeny och välja "Copy URL To Change '.....' " Detta menykommando kopierar en HTTP-URL till urklippet, som när den anropas (t.ex. i en webbläsare) kommer att ställa in egenskapen till dess aktuella värde. Genom att undersöka URL:en kan du avgöra vilken del av den som behöver ändras för att skicka dina egna data till den här egenskapen. I skärmdumpen kan du se snabbmenyn för att kopiera URL:en för att ändra undertexten i ett Lower Third-lager.

http://127.0.0.1:8989/api/v1/documents/xxxxxxxxxxxx/layers/yyyyyyyyyyyy/variants/zzzzzzzzzzzz?include=data.attributes.input-values&fields[input-values]=tvGroup_Content__Subtitle&update=%7B%22input-values%22:%7B%22tvGroup_Content__Subtitle%22:%22mimoLive%20User%22%7D%7D

❗

Det nya värdet i URL:en måste vara URL-kodat!

I det här exemplet kodas mellanslaget mellan "mimoLive" och "User" som

Bästa praxis

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/xxxxxxxxx/output-destinations/yyyyyyyyyyyyy

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/xxxxxxxxxxxx/output-destinations/yyyyyyyyyyyy

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 det här curl-kommandot kan du ändra ljudvolymen för ett lager som har en ljudjusteringsknapp (som Placer-lagret). Värdet "volym" kan ta 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 Source Repository kan du ha en Last Recording Source som ger tillgång till den senaste inspelningen som någon File Recording Output Destination kommer att meddela. I en kioskapplikation kommer det att vara nödvändigt att rensa den sista inspelningsvägen så att nästa användare av stationen inte kan granska inspelningen av den tidigare användaren. Med följande Automation Layer-kommando kan du rensa bort denna information från Last Recording Source:

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:

curl —data '{"myData1": 1.5, "myData2":"Some text"}' -H "Content-Type: application/json" -X PUT http://127.0.0.1:8989/api/v1/documents/1643911183/datastores/myDataStore1

Curl-kommando för att läsa tillbaka data:

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.

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 ?update= till den:

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

Hämta alla -datasträngar 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ägger du allt detta efter ?update= 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.