Guida pratica: Gestire i canali

Cosa succede se nel tuo ecosistema esistono dei dispositivi che non possono connettersi a Internet e comunicare direttamente con Frame.io, ma che possono comunicare con il tuo dispositivo abilitato per C2C? Alcune integrazioni potrebbero voler eseguire azioni per conto di tali dispositivi, ad esempio nel caso di un registratore audio che carica contenuti per conto di un microfono o nel caso di una fotocamera che fa commenti in tempo reale per conto dei pulsanti di un dispositivo collegato.

Queste richieste vengono soddisfatte mediante l’interpretazione dei canali di un dispositivo. Se la tua integrazione non gestisce dispositivi secondari, puoi saltare questa guida.

Cosa serve?

Se non hai letto la guida Implementazione C2C: configurazione, dalle un’occhiata veloce prima di continuare! Ti serve il access_token che hai ricevuto durante la guida per l’autenticazione e autorizzazione del dispositivo.

Ti servirà anche un elenco di ID del modello di per i dispositivi secondari che dovrebbero essere in grado di connettersi a Frame.io tramite il tuo dispositivo primario.

Che cos’è un canale?

I canali vengono spiegati brevemente nella nostra panoramica dell’architettura. Ogni dispositivo di progetto ha almeno un canale e, sebbene li abbiamo trattati in genere come una cosa sola, ora dobbiamo separare questi concetti. Approfondiamo l’argomento.

Un dispositivo di progetto ha la capacità di comunicare direttamente con Frame.io. Un canale raccoglie i dati che il dispositivo di progetto deve comunicare. Nella maggior parte dei casi, il dispositivo di progetto (ProjectDevice) e il primo canale sono la stessa cosa. Facciamo l’esempio di una videocamera: concettualmente, il dispositivo di progetto rappresenta la scheda di rete della videocamera, che invia dati direttamente a Frame.io, mentre il canale rappresenta il sensore CMOS della videocamera, che raccoglie i dati video da inviare attraverso la scheda di rete (dispositivo di progetto).

In particolare, il dispositivo di progetto è autenticato con Frame attraverso un’OauthApp, mentre i canali non lo sono. Utilizzano l’autenticazione del dispositivo di progetto padre.

Il nostro modello consente a un dispositivo di progetto di avere più canali, che possono fare o non fare parte del dispositivo fisico. I canali possono essere componenti hardware che comunicano con il dispositivo primario tramite TCP/IP, Bluetooth, SDI ecc. Il dispositivo di progetto funge da router per inviare questi dati a Frame.io. Il modo in cui questi dati vengono forniti dai canali al dispositivo di progetto dipende dall’integratore.

Immagina un registratore audio connesso a Frame.io come dispositivo di progetto: ha molti microfoni e ciascuno è collegato come canale separato. Il registratore può inviare il file mix sul suo canale primario e le tracce dei singoli microfoni sui canali dei suoi dispositivi secondari. Come utilizzi i canali e cosa rappresentano singolarmente dipende da te. I canali non sono autenticati: possono essere aggiunti e sottratti dal dispositivo in qualsiasi momento.

Poiché i canali possono appartenere a dispositivi secondari fisici separati, ciascun canale sarà associato a un modello di dispositivo, come qualsiasi altra integrazione hardware o software. Questo permette a Frame.io di visualizzare il modello del dispositivo secondario, che può essere diverso dal dispositivo host. Inoltre, consente alle integrazioni di definire il comportamento per ciascun dispositivo secondario separatamente. I modelli di dispositivo che possono essere aggiunti a una determinata integrazione come canali devono essere definiti in anticipo.

Ci sono alcuni motivi per cui potresti voler collegare nuovi canali al tuo dispositivo C2C:

• Consenti configurazioni multiple per un’integrazione a seconda del canale e del modello di dispositivo. Questo include la struttura delle cartelle fisse delle risorse, i percorsi delle cartelle tokenizzate, l’instradamento delle estensioni dei file ecc. Immagina una postazione DIT che utilizza canali diversi per caricare proxy editoriali o Camera Raw.
• Offre all’utente in Frame.io visibilità sui tuoi dispositivi secondari.
• I canali possono essere configurati con input umani (ovvero pulsanti) che possono essere configurati per funzioni di registrazione in tempo reale.

Approfondiamo un po’ come gestire i canali con l’API C2C.

Elenco dei canali

L’elenco dei canali esistenti può essere recuperato dall’endpoint identity nel campo dei canali. Diamo un’occhiata al campo "channels" del payload di risposta:

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
}

Il device_id per il primo canale corrisponde al device_id del nostro dispositivo di progetto nel suo complesso.

Connessione di un canale

Possiamo collegare un nuovo canale con la seguente richiesta:

$
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

Otterremo la seguente risposta:

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
}

Questa risposta rispecchia il campo “channels” dall’endpoint identity.

Il client_id è ciò che determina l’unicità, quindi deve essere un valore stabile, ad esempio il numero di serie.

Il device_model_id indica a Frame.io il tipo sottostante di dispositivo hardware che questo canale rappresenta, ad esempio un modello specifico di microfono. Questi devono essere configurati dal tuo partner manager.

Se un canale è già stato dichiarato, riceverai un errore 409 con la dicitura “Already Exists”.

Quando crei un canale con gli stessi identificatori di uno precedentemente connesso e poi disconnesso, verrà ripristinata tutta la configurazione utente precedente per il canale.

Disconnessione di un canale

Un canale viene disconnesso in base all’ID definito da Frame.io, non in base al client_id o al 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

Viene restituita una risposta 204 con un payload vuoto.

Quando elimini un canale che non esiste, otterrai un errore 404. Non puoi disconnettere il primo canale primario per il dispositivo padre.

Disconnessione di tutti i canali dei dispositivi secondari

Puoi disconnettere tutti i canali attuali dei dispositivi secondari su un dispositivo di progetto con la seguente chiamata:

$
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

Viene restituita una risposta 204 con un payload vuoto. Questa chiamata riuscirà sempre, anche se il dispositivo di progetto non ha canali di dispositivi client. Ora possiamo elencare tutti i nostri canali usando l’endpoint identity; rimarrà solo il canale primario del dispositivo host.

Flusso di gestione dei canali

Sconsigliamo di lasciare che siano i ProjectDevice a gestire lo stato dei canali internamente per evitare problemi di integrità dei dati, che potrebbero derivare da cicli di alimentazione che avvengono in momenti non ideali. Ad esempio:

• Spegnimento dopo che una chiamata Channel Connect è stata elaborata, ma prima che l’id restituito possa essere salvato in un archivio dati
• Dispositivi secondari collegati o scollegati dal dispositivo host mentre il dispositivo è spento.

Consigliamo, invece, che tutti i dispositivi host eseguano i seguenti passaggi al primo avvio:

• Chiamata dell’endpoint Bulk Channel Disconnect per cancellare tutti i canali dei dispositivi secondari esistenti
• Chiamata dell’endpoint Channel Connect per ogni dispositivo secondario attualmente connesso

Dopo la configurazione iniziale, un dispositivo host DEVE chiamare l’endpoint Channel Disconnect ogni volta che un dispositivo secondario viene disconnesso. Inoltre, DEVE chiamare l’endpoint Channel Connect ogni volta che viene aggiunto un nuovo dispositivo secondario. I dispositivi host NON POSSONO cancellare i dispositivi secondari ogni volta che viene connesso un nuovo dispositivo.

I dispositivi host DEVONO gestire correttamente le condizioni di rete scadenti quando gestiscono i dispositivi, e aggiungere/rimuovere correttamente i dispositivi attualmente connessi al ripristino della connessione di rete.

Avanti

Se non l’hai già fatto, ti incoraggiamo a contattare il nostro team, poi continua con la prossima guida. A presto!