Exemplos de utilização de API

Controlar o mimoLive com php

Temos uma amostra bem documentada de um script PHP no GitHub:
https://github.com/boinx/mimoLive-HTTP-Demo

Controlar o mimoLive com CURL

Para controlar o mimoLive através de HTTP pode usar o comando bash "curl". Para que os comandos curl funcionem, é necessário encontrar o ID do documento mimoLive que pretende manipular.

Controlar o mimoLive com a camada de automatização

O Camada de automatização pode executar alguns comandos fáceis para desencadear acções no mimLive através das suas API Endpoints. Tem também um comando httpRequest() para efetuar qualquer tipo de OBTER acções de pedido o HTTP API é capaz de o fazer.

Pré-requisitos

- Abra o documento que pretende manipular no mimoLive.
- Certifique-se de que o documento está num estado finalizado para que os pontos de extremidade da API, como Camadas, não sejam alterados. Tenha em atenção que, se remover uma camada e a adicionar novamente, esta camada terá um ID de camada diferente quando falar com ela através da API. No entanto, reordenar camadas ou adicionar variantes de camadas não altera o ID da camada.
- Ativar o HTTP-Servidor nas Preferências de Controlo Remoto do mimoLive. Marque a opção "Permitir acesso ao controlo remoto":

Anote o número de IP ou o endereço de IP com o número da porta do mimoLive para utilização posterior quando trabalhar com o HTTP API.

Obter um API Ponto final

Antes do mimoLive 5.5 era difícil obter a ID do documento e, por exemplo, uma ID de camada com comandos de terminal que procuravam através de longos JSON dados. Desde o mimoLive 5.5 é muito mais fácil:

Em primeiro lugar, copie o ficheiro mimoLive HTTP base do servidor URL na secção Controlo Remoto da janela de Preferências do mimoLive (ver imagem acima). Abra um editor de texto (por exemplo, TextEdit da Apple) e cole o conteúdo da Área de Transferência num documento de texto recém-criado. Certifique-se de que existe não barra invertida no final do URL! O resultado deve ser o seguinte:

http://172.28.30.202:8989

Na janela do documento mimoLive com o seu rato, pode clicar com o botão direito do rato (ou com o botão de controlo, ou com dois dedos) no objeto de interesse (por exemplo, uma Camada, uma Fonte, um botão de um controlo de Camada) para obter um menu de contexto. Existe um item de menu que lhe permite copiar o API Ponto final para a área de transferência do macOS para a utilizar no seu mimoLive API projeto.

Por vezes, é importante abordar uma variante de camada específica em vez da camada em geral. Se clicar com o botão direito do rato no parâmetro de uma camada, verá que existem diferentes API para a camada ativa atual ou para a variante de camada específica:

Volte ao seu editor de texto e cole o ficheiro que acabou de copiar API Ponto final após o HTTP Base do servidor URL. Agora o URL no seu navegador de texto deve ter o seguinte aspeto:

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

Esta é a última API Endpoint para endereçar uma camada no seu documento. Neste exemplo 458706932 é o ID do documento e BA868701-8131-49CB-8EDD-8C7E6E7CD60B é o ID de camada específico de uma determinada camada deste documento.

Ligar e desligar DESLIGADO a Camada

Com os dados recuperados API Endpoint para uma determinada camada, pode activá-lo e desactivá-lo com os seguintes comandos de terminal.

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

Alterar um valor de uma camada

- Todos os parâmetros de uma camada podem ser definidos através da função HTTP API. É necessário encontrar a chave correcta para definir um novo valor. No nosso exemplo, vamos definir o título de um Camada Lower Third com a chave tvGroup_Content__Title. Porque precisamos de enviar o novo valor numa JSON para o ficheiro HTTP servidor com um PUT o comando curl fica um pouco cheio.

*Certifique-se de que substitui xxxxxxxxx pela sua camada específica API Ponto final!

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

Coleção de Úteis API Comandos para explorar

Definir o RTMP URL e Chave de transmissão de um destino de saída de transmissão em direto:

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

Definir o nome do ficheiro e o caminho de um destino de saída do File Writer

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

Definir a origem de vídeo de uma camada de estratificação

yyyyyyyyyyyyy será o UUID da fonte de vídeo. (e.g CCAF4418-367A-415F-AD25-6536C3EF3512)

xxxxxxxxxxxxxxx será o API ponto de extremidade de uma determinada variante de camada. (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"

Definir o volume de uma camada que tenha um botão de volume de áudio

Com este comando curl, é possível alterar o volume de áudio de uma camada que tenha um botão de ajuste de áudio (como o botão Camada de plaqueamento). O valor "volume" pode assumir valores de 0,0 a 1,0.

xxxxxxxxxxxxxxx será o API ponto final da camada (por exemplo, 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"

Definir a cor de uma camada de fundo

xxxxxxxxxxxxxxx será o API ponto de extremidade de uma determinada variante de camada. (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"

Limpar o caminho do ficheiro de uma fonte de vídeo da Última Gravação

No seu Repositório de Fontes, pode ter um Última fonte de registo que dará acesso à última gravação que qualquer Destino de Saída de Gravação de Ficheiros anunciará. Numa aplicação de quiosque, será necessário limpar o caminho da última gravação para que o utilizador seguinte da estação não possa rever a gravação do utilizador anterior. Com o seguinte Comando da camada de automatização pode apagar esta informação da Última fonte de gravação:

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)

Armazenamento JSON Dados no documento mimoLive

Com o ponto de extremidade "datastores" pode armazenar qualquer tipo de dados no documento mimoLive para os manter durante um recarregamento do documento. É necessário utilizar um "PUT" para guardar os dados e um pedido "OBTER" para o ler de volta. Pode armazenar qualquer tipo de dados, mas neste exemplo estamos a armazenar JSON Dados porque este parece ser um caso de utilização muito comum. Se pretender armazenar dados diferentes, tem de ajustar o parâmetro -H em conformidade.

Comando Curl para armazenar dados:
bc. curl -data '{"meusDados1": 1.5, "myData2": "Algum texto"}' -H "Content-Type: application/json" -X PUT http://127.0.0.1:8989/api/v1/documents/1643911183/datastores/myDataStore1

Comando Curl para ler os dados de volta:
bc. curl -X OBTER http://127.0.0.1:8989/api/v1/documents/1643911183/datastores/myDataStore1

Atualizar o caminho do ficheiro de origem de uma fonte de ficheiro multimédia

Pode querer trocar o filme que é reproduzido ou substituir um anúncio apresentado por um Fonte do ficheiro multimédia. Isto pode ser feito com um comando de atualização executado na fonte API ponto final.

Certifique-se de que o modo de referência do ficheiro da Fonte de Média está definido para "Caminho absoluto". Obtenha o API para esta fonte, clicando com o botão direito do rato na coluna da esquerda e seleccionando "Copiar ponto de extremidade da fonte API Ponto final para a área de transferência" no menu de contexto. Criar um URL da seguinte forma:

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

Certifique-se de que codifica o JSON dados no URL para obter um URL que pode ser usado em um comando curl como este:

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

*Tenha em atenção que pode utilizar o "~" no início do caminho do ficheiro para fazer referência ao diretório pessoal do utilizador atual.

Controlar o mimoLive com o Apple Script

Atualmente, o mimoLive não suporta nativamente o Apple Script. No entanto, pode usar uma solução alternativa para contactar o mimoLive: Existe um comando "do shell script" no apple script que lhe permite executar comandos bash como "curl". A secção anterior explica como criar um comando curl para manipular uma determinada camada ou valor de camada.

Quando estiveres satisfeito com o teu comando curl, tens de o envolver num comando "do shell script" no Apple Script:

*Armadilhas no Apple Script
No Apple Script há duas armadilhas quando se traz um comando de terminal como "curl" para o comando do shell script:
1. Todos os " têm de ser prefixados com um \ para que o analisador Apple-Script saiba que não são os marcadores de fim do comando do shell script. O \ é um carácter de escape para dizer ao analisador para ignorar o carácter seguinte.
2. Se concatenar várias partes de texto com &, então, para o Apple Script, isto é uma "lista de texto" em vez de um único texto. O comando do shell não funciona com "lista de texto" e, por isso, é necessário convertê-lo de novo num único texto com "as text" no final do texto do comando curl.

Este exemplo mostra como definir o título de um terço inferior:

*Certifique-se de que substitui xxxxxxxxx pela sua camada específica API Ponto final!

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

O seguinte exemplo de script da Apple mostra como ativar uma camada de meia em meia hora, à hora: Isto pode ser útil para sobreposições comerciais. Certifique-se de que utiliza uma camada que se desliga após um determinado período de tempo (por exemplo, uma camada Placer com uma fonte de filme sem looping).

*Certifique-se de que substitui xxxxxxxxx pela sua camada específica API Ponto final!

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

Conversão de um CURL comando com JSON Dados para um HTTP URL para simples HTTP Pedidos

Por vezes, só é possível enviar um simples HTTP ao mimoLive em vez de usar um comando curl, por exemplo, no caso de aplicações de automatização de terceiros ou da própria camada de automatização mimoLive. Isto requer a conversão do bloco de dados do comando curl para fazer parte do URL. Pode fazê-lo da seguinte forma:

Vamos supor que temos o seguinte comando curl:

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

Tomaria o HTTP parte primeiro:

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

Adicionar ?update= a ele:

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

Obter todas as -data string e remover todos os espaços desnecessários:

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

Codificar isto para o seu URL forma por escapando aos caracteres não conformes com o URL (por exemplo, utilizando 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

Por fim, ponha tudo isto após a ?update= assim:

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

Agora pode utilizar este URL num simples HTTP pedido.