Guias práticos

Instruções: Gerenciar canais

O que acontece quando você tem dispositivos no ecossistema que não conseguem se conectar à internet e falar diretamente com o Frame.io, mas que podem se comunicar com o dispositivo habilitado para C2C? Algumas integrações podem precisar realizar ações em nome desses dispositivos, como um gravador de som que faz uploads em nome de um microfone ou uma câmera que faz comentários em tempo real em nome dos botões de um anexo.

Essas solicitações são atendidas por meio da compreensão dos canais de um dispositivo. Se a sua integração não for gerenciar subdispositivos, você pode pular este guia.

O que vou precisar?

Caso ainda não tenha lido o guia Implementação do C2C: Configuração, dê uma olhada rápida nele antes de continuar! Você precisará do access_token recebido durante o guia de autenticação e autorização do dispositivo.

Você também precisará de uma lista de IDs de modelos de dispositivos para os subdispositivos que devem poder se conectar ao Frame.io por meio do seu dispositivo principal.

O que é um canal?

Os canais são brevemente abordados em nossa Visão geral da arquitetura. Cada dispositivo do projeto possui pelo menos um canal e, embora geralmente tenhamos tratado ambos como um mesmo conceito, agora precisamos diferenciá-los. Vamos nos aprofundar no assunto.

Um dispositivo do projeto tem a capacidade de se comunicar diretamente com o Frame.io. Um canal coleta dados para que o dispositivo do projeto se comunique. Na maioria dos casos, o ProjectDevice e o primeiro canal são a mesma coisa. Vamos considerar uma câmera: conceitualmente, o dispositivo de projeto representa a placa de rede da câmera, que envia dados diretamente para o Frame.io, enquanto o canal representa o sensor CMOS da câmera, coletando dados de vídeo para enviar através da placa de rede (dispositivo de projeto).

Mais importante ainda, o dispositivo de projeto é autenticado com o Frame através de um OauthApp, enquanto os canais não são. Eles usam a autenticação do dispositivo de projeto principal.

Nosso modelo permite que um dispositivo de projeto tenha múltiplos canais, que podem ou não fazer parte do dispositivo físico. Os canais podem ser peças de hardware que se comunicam com o dispositivo principal através de TCP/IP, Bluetooth, SDI, etc. O dispositivo de projeto atua como um roteador para enviar esses dados para o Frame.io. Como esses dados são fornecidos dos canais para o dispositivo de projeto fica a seu critério, o integrador.

Imagine um gravador de som, conectado ao Frame.io como dispositivo de projeto, com vários microfones conectados como canais separados. O gravador pode enviar o arquivo de mixagem no canal principal e as faixas dos microfones individuais nos canais dos subdispositivos. Como você usa os canais e o que cada um representa é com você! Os canais não são autenticados, podem ser adicionados e subtraídos pelo dispositivo a qualquer momento.

Como os canais podem pertencer a subdispositivos físicos separados, cada canal será associado a um modelo de dispositivo, como qualquer outra integração de hardware ou software. Isso permite que o Frame.io exiba o modelo do subdispositivo, que pode ser diferente do dispositivo host, e permite que as integrações definam o comportamento para cada subdispositivo separadamente. Quais modelos de dispositivo podem ser adicionados a uma determinada integração como canais devem ser definidos antecipadamente.

Há alguns motivos pelos quais você pode querer conectar novos canais ao dispositivo C2C:

  • Permitir várias configurações para uma integração dependendo do canal e modelo de dispositivo. Isso inclui estrutura de pasta fixa de ativo, caminhos de pasta tokenizada, roteamento de extensão de arquivo etc. Imagine uma estação DIT que usa canais diferentes para fazer upload de proxies editoriais ou Camera Raw.
  • Dá ao usuário no Frame.io visibilidade dos subdispositivos.
  • Os canais podem ser configurados com entradas humanas, ou seja, botões, que podem ser configurados para funções de registro em tempo real.

Vamos nos aprofundar um pouco mais em como gerenciar canais com a API C2C.

Listar canais

Uma lista de canais existentes pode ser obtida pelo ponto de acesso de identidade no campo canais. Vamos dar uma olhada no campo "channels" do conteúdo de resposta:

1{
2    "_type": "project_device",
3    ...
4    "channels": [
5        {
6            "_type": "project_device_channel",
7            "actor_id": null,
8            "asset_type": "video",
9            "device_id": "98e9367a-b26b-4c60-8e64-da83dfd9540b",
10            "external_index": 0,
11            "id": "5919e9bc-7fc2-4629-97e5-852ce27cfa1a",
12            "inserted_at": "2023-07-14T19:11:43.217565Z",
13            "name": "Test Host Device",
14            "project_device_id": "bf30fc66-f126-4336-bdfc-75d3e659b95a",
15            "project_id": "1eb3587f-6bca-4e8d-a2f6-e7413d82c1ad",
16            "real_time_logging_capable": false,
17            "status": "online",
18            "updated_at": "2023-07-14T19:11:43.217565Z"
19        },
20        {
21            "_type": "project_device_channel",
22            "actor_id": null,
23            "asset_type": "video",
24            "device_id": "057b33c4-9f92-4eeb-a3d5-2fd0f4932292",
25            "external_index": 0,
26            "id": "0b17e1e3-588c-4365-be51-5cf097c8f004",
27            "inserted_at": "2023-07-14T19:11:43.217565Z",
28            "name": "Test Client Device 01234",
29            "project_device_id": "bf30fc66-f126-4336-bdfc-75d3e659b95a",
30            "project_id": "1eb3587f-6bca-4e8d-a2f6-e7413d82c1ad",
31            "real_time_logging_capable": false,
32            "status": "offline",
33            "updated_at": "2023-07-14T19:11:43.217565Z"
34        }
35    ],
36    ...
37    "device_id": "98e9367a-b26b-4c60-8e64-da83dfd9540b",
38    ...
39    "id": "bf30fc66-f126-4336-bdfc-75d3e659b95am"
40}

Observe que o device_id do primeiro canal corresponde ao device_id do dispositivo de projeto como um todo.

Conectar um canal

Podemos conectar um novo canal com a seguinte solicitação:

$curl -X POST https://api.frame.io/v2/devices/channels/connect \
>    --header 'Authorization: Bearer [access_token]' \
>    --header 'Content-Type: application/json' \
>    --header 'x-client-version: 2.0.0' \
>    --data-binary @- <<'__JSON__'{
>            "client_id": [client_id],
>            "device_model_id": [device_model_id]
>        }
$__JSON__
$    | python -m json.tool

Recebemos a seguinte resposta:

1{
2   "_type": "project_device_channel",
3   "actor_id": null,
4   "asset_type": "video",
5   "device_id": "057b33c4-9f92-4eeb-a3d5-2fd0f4932292",
6   "external_index": 0,
7   "id": "0b17e1e3-588c-4365-be51-5cf097c8f004",
8   "inserted_at": "2023-07-14T19:11:43.217565Z",
9   "name": "Test Client Device 01234",
10   "project_device_id": "bf30fc66-f126-4336-bdfc-75d3e659b95a",
11   "project_id": "1eb3587f-6bca-4e8d-a2f6-e7413d82c1ad",
12   "real_time_logging_capable": true,
13   "status": "offline",
14   "updated_at": "2023-07-14T19:11:43.217565Z"
15}

Esta resposta espelha o campo canais do ponto de acesso identity.

O client_id é o que governa a exclusividade, portanto deve ser um valor estável, como o número de série.

O device_model_id é o que informa ao Frame.io o tipo subjacente de dispositivo de hardware que este canal representa, como um modelo específico de microfone. Eles serão configurados pelo parceiro.

Se um canal já foi declarado, você receberá um erro 409 com o título de erro Já existe.

Ao criar um canal com os mesmos identificadores de um que foi conectado anteriormente e depois desconectado, toda a configuração anterior do usuário para o canal será restaurada.

Desconectar um canal

Um canal é desconectado pelo id definido pelo Frame.io. Não por client_id ou device_model_id.

$curl -X POST https://api.frame.io/v2/devices/channels/:channel_id/disconnect \
>    --header 'Authorization: Bearer [access_token]' \
>    --header 'x-client-version: 2.0.0' \
>    | python -m json.tool

Que retorna uma resposta 204 com conteúdo em branco.

Ao excluir um canal que não existe, você receberá um erro 404. Não é possível desconectar o primeiro canal principal do dispositivo principal.

Desconectar todos os canais de subdispositivo

Você pode desconectar todos os canais de subdispositivos atuais em um dispositivo de projeto com a seguinte chamada:

$curl -X POST https://api.frame.io/v2/devices/channels/disconnect \
>    --header 'Authorization: Bearer [access_token]' \
>    --header 'x-client-version: 2.0.0' \
>    | python -m json.tool

Que retorna uma resposta 204 com conteúdo em branco. Esta chamada sempre será bem-sucedida, mesmo se o dispositivo do projeto não tiver canais de dispositivo cliente. Agora podemos listar todos os nossos canais usando o ponto de acesso identity. Apenas o canal principal do dispositivo host permanecerá.

Fluxo de gerenciamento de canais

Não recomendamos que os dispositivos do ProjectDevice gerenciem o estado do canal internamente, a fim de evitar problemas de integridade de dados que possam resultar de reinicializações ocorrendo em momentos inadequados. Por exemplo:

  • Desligamento após o processamento de uma chamada Channel Connect, mas antes que o id retornado possa ser gravado em um repositório de dados
  • Subdispositivos sendo conectados/desconectados do dispositivo host enquanto este está desligado.

Em vez disso, recomenda-se que todos os dispositivos host executem as seguintes etapas ao serem inicializados pela primeira vez:

  • Chamar o ponto de acesso Desativação em massa de canais para limpar todos os canais de subdispositivos existentes
  • Chamar o ponto de acesso Conexão do canal para cada subdispositivo conectado no momento

Após a configuração inicial, um dispositivo host DEVE chamar o ponto de acesso Desconexão do canal sempre que um subdispositivo for desconectado e o ponto de acesso Conexão do canal sempre que um novo subdispositivo for adicionado. Os dispositivos host NÃO DEVEM limpar os subdispositivos sempre que um novo dispositivo for conectado.

Os dispositivos host DEVEM lidar corretamente com condições de rede adversas ao gerenciar dispositivos e devem adicionar/remover adequadamente os dispositivos atualmente conectados assim que a conexão com a rede for restabelecida.

Próximas etapas

Se ainda não o fez, recomendamos que entre em contato com nossa equipe e, em seguida, siga para o próximo guia. Estamos ansiosos para ter notícias suas!