Voorbeelden van API-gebruik

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.

Manieren om mimoLive op afstand te bedienen

Bediening van mimoLive met afstandsbedieningsoppervlakken

De meest effectieve manier is om een aangepast Remote Control Surface voor uw mimoLive-document te maken, dat op een iPad, iPhone of een ander apparaat met een internetbrowser kan draaien.

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.

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.

❗

Valkuilen in Apple Script

In Apple Script zijn er twee valkuilen bij het overbrengen van een terminalopdracht zoals "curl" naar de opdracht do shell script: 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-teken om de parser te vertellen het volgende teken te negeren. 2. Als u meerdere tekstdelen aan elkaar rijgt met &, dan is dit voor Apple Script een "lijst met tekst" in plaats van een enkele tekst. Het do shell commando werkt niet met een "lijst met tekst" en daarom moet u het terug converteren naar een enkele tekst met de "as text" aan het einde van uw curl commando tekst.

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

*

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

Gebruikersinterface-elementen in mimoLive besturen

Een API Eindpunt

API endpoints zijn essentieel voor het adresseren van specifieke elementen in uw mimoLive document. Voor een lijst van beschikbare API-eindpunten, zie API Eindpunten.

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.

Rechtsklikken op bepaalde gebruikersinterface-elementen om een contextmenu weer te geven voor het verkrijgen van het specifieke API-eindpunt werkt voor het volgende:

• Bronnen
• Lagen
• Laagvarianten
• Laag Parameter
• Uitvoer Bestemmingen
• Laag sets

Voorbeeld: AAN en UIT schakelen UIT a Laag

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

*

Zorg ervoor dat u xxxxxxxxx vervangt door het API Endpoint uit de vorige stap!

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

*

De URL's werken ook in een internetbrowser

Deze URL's (zonder het "curl" commando) kunnen ook in de adresbalk van een internetbrowser geplaatst worden. Zodra je op return drukt zal de browser de mimoLive HTTP server aanroepen en de opdracht uitvoeren die je hebt opgegeven. Als je JSON data hebt die je naar het API endpoint moet sturen kun je dit ook toevoegen aan de URL, zie "Converteren van een CURL commando met JSON data naar een HTTP URL voor eenvoudige HTTP verzoeken" hieronder.

Een eenvoudige manier om de volledige HTTP URL te verkrijgen om de live-status van een laag in of uit te schakelen, is door met de rechtermuisknop op de Live-knop van de laag te klikken om een contextmenu te openen en 'Copy URL To Set Layer Live' (URL kopiëren om laag live in te stellen) te selecteren. Hiermee wordt de URL naar het klembord gekopieerd voor gebruik. In de schermafbeelding ziet u het contextmenu voor de Live-knop van een Lower Third laag.

Voorbeeld: 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"

Een snelle manier om een volledige HTTP URL te verkrijgen om de update van een laageigenschap te triggeren, is door met de rechtermuisknop op de naam van de eigenschap te klikken, waardoor een contextmenu verschijnt, en "Copy URL To Change '.....'" te selecteren. "Deze menuopdracht kopieert een HTTP URL naar het klembord, die bij het oproepen (bijv. in een internetbrowser) de eigenschap op de huidige waarde instelt. Door de URL te bekijken, kunt u bepalen welk deel ervan gewijzigd moet worden om uw eigen gegevens naar deze eigenschap te sturen. In de schermafbeelding ziet u het contextmenu voor het kopiëren van de URL om de ondertitel van een Lower Third laag te wijzigen.

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

❗

De nieuwe waarde in de URL moet URL-gecodeerd zijn!

In dit voorbeeld wordt de spatie tussen "mimoLive" en "User" gecodeerd als

Beste Praktijken

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

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

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 kunt u het geluidsvolume wijzigen van een laag die een audio-instelknop heeft (zoals de Placer 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 Bronnenarchief kunt u een Laatste opnamebron hebben die toegang geeft tot de laatste opname die een 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 de volgende Automation Layer opdracht kunt u deze informatie uit de Laatste opnamebron wissen:

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:

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 commando om gegevens terug te lezen:

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.

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 er ?update= aan toe:

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

Haal alle -datastrings op 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 tenslotte achter 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.