채널 관리 방법 | Frame.io API Documentation

생태계 내에 인터넷에 연결하여 Frame.io와 직접 통신할 수는 없지만 C2C 지원 디바이스와는 통신할 수 있는 디바이스가 있다면 어떻게 될까요? 일부 통합 환경에서는 이러한 디바이스를 대신하여 작업을 수행하고자 할 수 있습니다. 예를 들어 마이크를 대신해 업로드하는 녹음기, 또는 부착물의 버튼을 대신해 실시간 코멘트를 작성하는 카메라 등이 있습니다.

이러한 요청은 디바이스의 채널을 이해함으로써 충족됩니다. 통합 환경에서 하위 디바이스를 관리하지 않는 경우 이 가이드를 건너뛰어도 됩니다.

무엇이 필요할까요?

C2C 구현: 설정 가이드를 읽지 않으셨다면, 다음으로 넘어가기 전에 빠르게 살펴보세요! 디바이스 인증 및 권한 부여 가이드에서 받은 access_token이 필요합니다.

또한 기본 디바이스를 통해 Frame.io에 연결할 수 있어야 하는 하위 디바이스의 디바이스 모델 ID 목록도 필요합니다.

채널이란 무엇인가요?

채널에 대해서는 아키텍처 개요에서 간략하게 설명합니다. 모든 프로젝트 디바이스에는 최소 하나의 채널이 있으며, 지금까지는 이 둘을 동일한 것으로 간주해 왔지만 이제는 개념을 분리해야 합니다. 좀 더 깊이 들어가 보겠습니다.

프로젝트 디바이스는 frame.io와 직접 통신할 수 있습니다. 채널은 프로젝트 디바이스가 통신할 데이터를 수집합니다. 대부분의 경우 ProjectDevice와 첫 번째 채널은 동일합니다. 카메라를 예로 들어보겠습니다. 개념적으로 프로젝트 디바이스는 Frame.io로 데이터를 직접 전송하는 카메라의 네트워킹 카드를 나타내고, 채널은 네트워크 카드(프로젝트 디바이스)를 통해 전송할 비디오 데이터를 수집하는 카메라의 CMOS 센서를 나타냅니다.

가장 중요한 점은 프로젝트 디바이스는 OauthApp을 통해 Frame에 인증되는 반면 채널은 그렇지 않다는 것입니다. 채널은 상위 프로젝트 디바이스의 인증을 사용합니다.

이 모델에서는 프로젝트 디바이스가 여러 채널을 가질 수 있으며, 이 채널들은 물리적 디바이스의 일부일 수도 있고 아닐 수도 있습니다. 채널은 TCP/IP, Bluetooth, SDI 등을 통해 기본 디바이스와 통신하는 하드웨어일 수 있습니다. 프로젝트 디바이스는 이 데이터를 frame.io로 전송하는 라우터 역할을 합니다. 해당 데이터가 채널에서 프로젝트 디바이스로 제공되는 방식은 연동 개발자인 귀하에게 달려 있습니다.

Frame.io에 프로젝트 디바이스로 연결된 사운드 레코더에 여러 마이크가 각각 별도의 채널로 연결되어 있다고 가정해 보겠습니다. 레코더는 기본 채널로 믹스 파일을 전송하고, 하위 디바이스의 채널로 개별 마이크의 트랙을 전송할 수 있습니다. 채널을 사용하는 방법과 각 채널이 의미하는 바는 전적으로 귀하에게 달려 있습니다! 채널은 인증되지 않으며 디바이스에서 언제든지 추가하거나 제거할 수 있습니다.

채널은 별개의 물리적 하위 디바이스에 속할 수 있으므로, 다른 하드웨어 또는 소프트웨어 통합과 마찬가지로 각 채널은 디바이스 모델과 연결됩니다. 이를 통해 frame.io는 호스트 디바이스와 다를 수 있는 하위 디바이스의 모델을 표시할 수 있으며, 통합 환경에서 각 하위 디바이스의 동작을 개별적으로 정의할 수 있습니다. 특정 통합 환경에 어떤 디바이스 모델을 채널로 추가할 수 있는지는 사전에 정의되어야 합니다.

C2C 디바이스에 새 채널을 연결하려는 이유는 다음과 같습니다.

채널 및 디바이스 모델에 따라 통합 환경에 대한 여러 구성을 허용할 수 있습니다. 여기에는 에셋 고정 폴더 구조, 토큰화된 폴더 경로, 파일 확장자 라우팅 등이 포함됩니다. 여러 채널을 사용하여 편집용 프록시나 Camera Raw를 업로드하는 DIT 스테이션을 예로 들 수 있습니다.
frame.io 사용자에게 하위 디바이스에 대한 가시성을 제공합니다.
채널은 실시간 로깅 기능으로 구성할 수 있는 사람의 입력, 즉 버튼으로 구성할 수 있습니다.

C2C API로 채널을 관리하는 방법에 대해 좀 더 자세히 살펴보겠습니다.

채널 나열

identity 엔드포인트의 channels 필드에서 기존 채널 목록을 가져올 수 있습니다. 응답 payload의 "channels" 필드를 살펴보겠습니다.

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 }

첫 번째 채널의 device_id가 프로젝트 디바이스 전체의 device_id와 일치한다는 점에 유의하세요.

채널 연결

다음 요청을 사용하여 새 채널을 연결할 수 있습니다.

$ 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

다음과 같은 응답을 받게 됩니다.

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 }

이 응답은 identity 엔드포인트의 channels 필드를 반영합니다.

client_id는 고유성을 제어하므로, 일련번호와 같이 변하지 않는 값이어야 합니다.

device_model_id는 특정 마이크 모델과 같이 이 채널이 나타내는 하드웨어 디바이스의 기본 유형을 Frame.io에 알려줍니다. 이는 귀하의 파트너 매니저가 미리 설정해 두었을 것입니다.

채널이 이미 선언된 경우, Already Exists라는 오류 제목과 함께 409 오류가 반환됩니다.

이전에 연결되었다가 연결이 해제된 채널과 동일한 식별자로 채널을 생성하면, 해당 채널에 대한 이전의 모든 사용자 구성이 복원됩니다.

채널 연결 해제

채널은 Frame.io에서 정의한 id로 연결 해제됩니다. client_id 또는 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

이는 빈 payload와 함께 204 응답을 반환합니다.

존재하지 않는 채널을 삭제할 경우 404가 반환됩니다. 상위 디바이스의 첫 번째 기본 채널은 연결을 해제할 수 없습니다.

모든 하위 디바이스 채널 연결 해제

다음 호출을 사용하여 프로젝트 디바이스의 현재 모든 하위 디바이스 채널을 연결 해제할 수 있습니다.

$ 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

이는 빈 payload와 함께 204 응답을 반환합니다. 이 호출은 프로젝트 디바이스에 클라이언트 디바이스 채널이 없는 경우에도 항상 성공합니다. 이제 identity 엔드포인트를 사용하여 모든 채널을 나열할 수 있으며, 호스트 디바이스의 기본 채널만 남게 됩니다.

채널 관리 흐름

원치 않은 시점에 발생하는 전원 사이클로 인한 데이터 무결성 문제를 방지하기 위해, ProjectDevice가 채널 상태를 내부적으로 관리하는 것은 권장하지 않습니다. 예를 들면 다음과 같습니다.

채널 연결 호출이 처리된 후 반환된 id가 데이터 저장소에 커밋되기 전에 전원이 꺼지는 경우
디바이스가 꺼져 있는 동안 호스트 디바이스에서 하위 디바이스가 연결되거나 분리되는 경우.

대신, 모든 호스트 디바이스가 처음 부팅될 때 다음 단계를 실행할 것을 권장합니다.

Bulk Channel Disconnect 엔드포인트를 호출하여 기존의 모든 하위 디바이스 채널 지우기
현재 연결된 각 하위 디바이스에 대해 Channel Connect 엔드포인트 호출

초기 설정 후 호스트 디바이스는 하위 디바이스의 연결이 해제될 때마다 Channel Disconnect 엔드포인트를 호출하고, 새 하위 디바이스가 추가될 때마다 Channel Connect 엔드포인트를 호출해야 합니다. 호스트 디바이스는 새 디바이스가 연결될 때마다 하위 디바이스를 지워서는 안 됩니다.

호스트 디바이스는 디바이스 관리 시 열악한 네트워크 상태를 올바르게 처리해야 하며, 네트워크 연결이 복구되었을 때 현재 연결된 디바이스를 적절히 추가/제거해야 합니다.

다음 단계

아직 연락하지 않으셨다면 저희 팀에 문의하신 후 다음 가이드를 계속 진행하시기 바랍니다. 여러분의 연락을 기다리겠습니다!