Guía práctica: Administrar canales

¿Qué sucede cuando tiene dispositivos en su ecosistema que no pueden conectarse a Internet y comunicarse directamente con Frame.io, pero que sí pueden comunicarse con su dispositivo habilitado para C2C? Es posible que algunas integraciones deseen realizar acciones en representación de dichos dispositivos, como una grabadora de sonido que carga en nombre de un micrófono, o una cámara que hace comentarios en tiempo real en representación de los botones de un accesorio.

Para cumplir estas solicitudes, es necesario entender los canales de un dispositivo. Si su integración no va a administrar dispositivos secundarios, puede saltarse esta guía.

¿Qué necesitaré?

Si no ha leído la guía Implementar C2C: Configuración, échele un vistazo rápido antes de continuar. Necesitará el access_token que recibió durante la guía sobre la autenticación y autorización de dispositivos.

También necesitará una lista de ID de modelos de dispositivo para los dispositivos secundarios que deberían poder conectarse a Frame.io a través de su dispositivo principal.

¿Qué es un canal?

Los canales se tratan brevemente en nuestra Información general sobre la arquitectura. Cada dispositivo de proyecto tiene al menos un canal y, aunque generalmente los hemos tratado como si fueran lo mismo, ahora necesitamos separar sus conceptos. Profundicemos más.

Un dispositivo de proyecto tiene la capacidad de comunicarse directamente con Frame.io. Un canal recopila datos para que el dispositivo de proyecto se comunique. En la mayoría de los casos, el ProjectDevice y el primer canal son lo mismo. Pensemos en una cámara: conceptualmente, el dispositivo de proyecto representa la tarjeta de red de la cámara, que envía datos directamente a Frame.io, mientras que el canal representa el sensor CMOS de la cámara, que recopila datos de vídeo para enviarlos a través de la tarjeta de red (dispositivo de proyecto).

Lo más importante es que el dispositivo de proyecto se autentica con Frame a través de una OauthApp, mientras que los canales no lo hacen. Utilizan la autenticación de su dispositivo de proyecto principal.

Nuestro modelo permite que un dispositivo de proyecto tenga varios canales, que pueden o no ser parte del dispositivo físico. Los canales pueden ser componentes de hardware que se comunican con el dispositivo principal a través de TCP/IP, Bluetooth, SDI, etc. El dispositivo de proyecto actúa como un enrutador para enviar estos datos a Frame.io. Cómo se suministran esos datos desde los canales al dispositivo de proyecto depende de usted, el integrador.

Imagine una grabadora de sonido, conectada a Frame.io como dispositivo de proyecto, con muchos micrófonos cada uno conectado como canales independientes. La grabadora puede enviar el archivo de mezcla en su canal principal, y las pistas de los micrófonos individuales en los canales de su dispositivo secundario. Cómo usa los canales y qué representa cada uno depende de usted. Los canales no están autenticados, el dispositivo puede añadirlos y sustraerlos en cualquier momento.

Dado que los canales pueden pertenecer a un dispositivo secundario físico independiente, cada canal estará asociado a un modelo de dispositivo, como cualquier otra integración de hardware o software. Esto permite que Frame.io muestre el modelo del dispositivo secundario, que puede ser diferente del dispositivo host, y permite que las integraciones definan el comportamiento para cada dispositivo secundario por separado. Los modelos de dispositivos que se pueden añadir a una integración determinada como canales deben definirse con antelación.

Hay algunos motivos por los que podría querer conectar nuevos canales a su dispositivo de C2C:

• Permitir varias configuraciones para una integración según el canal y modelo de dispositivo. Esto incluye: estructura de carpetas fija de activos, rutas de carpetas tokenizadas, enrutamiento de extensión de archivos, etc. Imagine una estación DIT que usa diferentes canales para cargar proxies editoriales o Camera Raw.
• Permite que el usuario de Frame.io vea sus dispositivos secundarios.
• Los canales se pueden configurar con entradas humanas, también conocidas como botones, que se pueden configurar para funciones de registro en tiempo real.

Profundicemos un poco más en cómo administrar canales con la API de C2C.

Enumerar canales

Se puede recuperar una lista de canales mediante el punto final de identidad en el campo channels. Echemos un vistazo al campo "channels" de la carga útil de respuesta:

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 el device_id para el primer canal coincide con el device_id de nuestro dispositivo de proyecto en su conjunto.

Conectar un canal

Podemos conectar un nuevo canal con la siguiente solicitud:

$
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

Obtenemos la siguiente respuesta:

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 respuesta refleja el campo channels del punto final identity.

El client_id es lo que determina la unicidad, por lo que debe ser un valor estable, como el número de serie.

El device_model_id es lo que le comunica a Frame.io el tipo subyacente de dispositivo de hardware que representa este canal, como un modelo específico de micrófono. Estos valores los habrá configurado su administrador de partners.

Si un canal ya se ha declarado, recibirá un error 409 con el título de error Already Exists.

Al crear un canal con los mismos identificadores de uno que se conectó previamente y luego se desconectó, se restaurará toda la configuración de usuario anterior para el canal.

Desconectar un canal

Un canal se desconecta mediante el ID definido por Frame.io. No mediante client_id ni 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 devuelve una respuesta 204 con una carga útil en blanco.

Al eliminar un canal que no existe, obtendrá un mensaje 404. No puede desconectar el primer canal principal para el dispositivo principal.

Desconectar todos los canales de dispositivos secundarios

Puede desconectar todos los canales de dispositivos secundarios actuales en un dispositivo de proyecto con la siguiente llamada:

$
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 devuelve una respuesta 204 con una carga útil en blanco. Esta llamada siempre tendrá éxito, incluso si el dispositivo de proyecto no tiene canales de dispositivo cliente. Ahora podemos enumerar todos nuestros canales con el punto final identity; solo permanecerá el canal principal del dispositivo host.

Flujo de administración de canales

No recomendamos que los ProjectDevice administren el estado del canal internamente para evitar problemas de integridad de los datos que pueden surgir debido a ciclos de encendido que ocurran en momentos poco ideales. Por ejemplo:

• Apagar después de que se haya procesado una llamada de Channel Connect, pero antes de que el id devuelto pueda confirmarse en un almacén de datos
• Dispositivos secundarios que se conecten/desconecten del dispositivo host mientras el dispositivo está apagado.

En su lugar, se recomienda que todos los dispositivos host ejecuten los siguientes pasos cuando se inicien por primera vez:

• Llamar al punto final Bulk Channel Disconnect para borrar todos los canales de dispositivos secundarios existentes
• Llamar al punto final Channel Connect para cada dispositivo secundario conectado actualmente

Tras la configuración inicial, un dispositivo host DEBE llamar al punto final Channel Disconnect cada vez que se desconecte un dispositivo secundario, y al punto final Channel Connect cada vez que se añada un nuevo dispositivo secundario. Los dispositivos host NO PUEDEN borrar dispositivos secundarios cada vez que se conecte un nuevo dispositivo.

Los dispositivos host DEBEN gestionar correctamente las condiciones deficientes de la red al administrar dispositivos, y añadir/quitar adecuadamente los dispositivos conectados actualmente cuando se restablezca la conexión a la red.

Próximos pasos

Si aún no lo ha hecho, le recomendamos que se ponga en contacto con nuestro equipo y que luego continúe con la siguiente guía. Quedamos a la espera de tener noticias suyas.