사용 방법 가이드

방법: 에셋 구성

소개

이 가이드에서는 연동 시스템의 에셋이 업로드되는 위치를 제어하는 방법과 그 범위에 대해 알아봅니다.

무엇이 필요할까요?

C2C 구현: 설정 가이드를 읽지 않으셨다면, 다음으로 넘어가기 전에 빠르게 살펴보세요! 또한 C2C 하드웨어 또는 C2C 애플리케이션 인증/권한 부여 가이드를 통해 발급받은 access_token도 필요합니다.

에셋 폴더 구조

기본적으로 에셋은 다음 폴더 구조로 생성됩니다.

Cloud Devices > {YYYY}_{MM}_{DD} > {ASSET_TYPE} > {YOUR_DEVICE} > {ASSET_NAME} 여기서 {ASSET_TYPE}은 VIDEO, AUDIO, DATA 중 하나이고(디바이스 모델에 대해 채널별로 구성됨), {YOUR_DEVICE}는 사용자의 프로젝트에 연결된 프로젝트 디바이스의 이름이며, {ASSET_NAME}은 업로드한 에셋의 이름이자 Frame.io에서 실제로 재생 가능한 에셋입니다.

확장자 라우팅

{ASSET_NAME}의 파일 확장자를 기준으로 다양한 에셋을 사용자 지정 {ASSET_TYPE} 폴더로 라우팅하도록 디바이스를 설정할 수 있습니다. 예를 들어, 연동 시스템에서 생성하는 여러 가지 파일 형식이 있으며 각 파일 형식이 특정 출처에 속한다고 가정해 보겠습니다. 이러한 에셋을 다음과 같이 매핑하도록 지정할 수 있습니다.

.mov -> VIDEO
.mp4 -> VIDEO
.raw -> STILLS
.jpeg -> STILLS
.pdf -> CAMERA REPORTS
.las -> LiDAR Scans

이제 다음 에셋을 생성할 때 다음과 같이 적용됩니다.

${
>curl -X POST https://api.frame.io/v2/assets \
>    --header 'Authorization: Bearer [access_codes]' \
>    --header 'Content-Type: application/json' \
>    --header 'x-client-version: 2.0.0' \
>    --data-binary @- <<'__JSON__' 
>        {
>            "name": "IMAGE_0001.jpeg", 
>            "filetype": "image/jpeg", 
>            "filesize": 21136250,
>            "offset": 10
>        }
>__JSON__
>} | python -m json.tool
API 엔드포인트 사양

/v2/assets에 대한 문서는 여기에서 확인할 수 있습니다.

… 에셋은 Cloud Devices > 2022_04_01 > STILLS > MY_DEVICE > IMAGE_0001.jpeg와 같은 위치로 라우팅됩니다. 파일 이름이 A001_C001.mov인 경우에는 Cloud Devices > 2022_04_01 > VIDEO > MY_DEVICE > A001_C001.mov로 라우팅됩니다.

토큰화된 업로드 경로

일부 연동 환경에서는 디바이스가 생성하는 폴더 구조를 더 세밀하게 제어하고자 할 수 있습니다. 이에 따라 Frame.io는 C2C 디바이스에서 Frame.io로 파일이 업로드되는 방식에 일정 수준의 일관성을 유지하고, 특히 Frame.io 고객에게 C2C 디바이스가 프로젝트의 어느 부분과 상호 작용할 수 있는지 보장해야 합니다. 이를 위해 연동 개발자가 {YOUR_DEVICE} 폴더 내에서 에셋 업로드 위치를 사용자 지정할 수 있도록 허용하지만, 해당 폴더 외부로 에셋을 업로드하는 것은 허용하지 않습니다.

사용자 지정 폴더 구조로 업로드하려면 파트너 매니저에게 문의해야 합니다. 사용자 지정 폴더 구조는 에셋 생성 시 반드시 제공해야 하는 토큰화된 메타데이터 세트입니다. 간단한 예를 들어 보겠습니다.

&quot;A001&quot;, &quot;A002&quot;, &quot;A003&quot; 등의 reel_name 값과 &quot;C001&quot;, &quot;C002&quot; 등의 clip_number 값이 있는 3D 카메라 리그가 있다고 가정해 보겠습니다. 각 클립에 대한 폴더를 생성하고 좌안 및 우안 파일로 해당 폴더를 채워 프로젝트에서 파일이 다음과 같이 표시되도록 하려고 합니다. 토큰화된 폴더 경로 - 3D 리그 예시

이렇게 하려면 다음 두 가지 설정을 구성해야 합니다.

  • 필수 메타데이터 필드
  • 토큰화된 파일 경로

필수 메타데이터 필드는 연동 시스템에서 에셋 생성 시 반드시 설정해야 하는 간단한 키 목록입니다.

[reel_name, clip_number]

그런 다음 이러한 키를 사용하여 /로 구분된 경로를 만들 수 있으며, {field_name}을 사용하여 필드 값이 삽입되어야 하는 위치를 나타냅니다.

REEL_{reel_name}/{reel_name}_{clip_number}

연동 세부 정보의 일부로 추가할 수 있도록 이 두 가지 설정 모두 Frame.io 팀에 제공해야 합니다. 해당 설정이 완료된 후 에셋을 생성할 때 에셋 생성을 성공적으로 완료하려면 페이로드의 루트에 해당 값을 제공해야 합니다.

${
>curl -X POST https://api.frame.io/v2/assets \
>    --header 'Authorization: Bearer [access_token]' \
>    --header 'Content-Type: application/json' \
>    --header 'x-client-version: 2.0.0' \
>    --data-binary @- <<'__JSON__' 
>        {
>            "name": "A001_C001_LEFT.mp4", 
>            "filetype": "video/mp4", 
>            "filesize": 21136250,
>            "offset": 10,
>            "metadata": {
>              "reel_name": "A001",
>              "clip_number": "C001"
>            },
>        }
>__JSON__
>} | python -m json.tool

위 설정은 Cloud Devices > 2022_04_01 > VIDEO > MY_DEVICE > REEL_A001 > A001_C001 > A001_C001_LEFT.mp4와 같은 전체 경로를 가진 파일을 생성합니다.

메타데이터 오류

디바이스가 이러한 필드를 허용하도록 명시적으로 설정되지 않은 경우, 동일한 호출을 시도하면 오류가 발생합니다. 마찬가지로 필수 메타데이터 필드를 설정한 경우 에셋 생성 페이로드에 해당 필드를 반드시 제공해야 하며, 그렇지 않으면 오류가 반환됩니다.

페이로드는 모든 유효한 JSON 값을 허용합니다. 문자열이 아닌 값은 다음과 같은 방식으로 렌더링됩니다.

  • 정수: 10진수로 렌더링됩니다(10 -> &quot;10&quot;).
  • 부동 소수점: SIGPLAN ‘96 프로그래밍 언어 설계 및 구현 컨퍼런스 자료집의 “부동 소수점 숫자를 빠르고 정확하게 인쇄하기”에 설명된 알고리즘에 따라 가장 짧은 표현을 사용합니다.
  • 부울: true와 false는 &quot;true&quot;와 &quot;false&quot;로 렌더링됩니다.
  • null: 빈 문자열로 렌더링됩니다. reel_name이 null로 설정된 경우 첫 번째 사용자 지정 폴더는 REEL_로 렌더링됩니다.

일반적으로 값을 문자열로 제한하고 다른 값은 필요에 맞게 서식을 지정하는 것이 좋습니다(예를 들어 정수는 항상 앞에 0 없이 출력되지만 이를 변경하고 싶을 수 있습니다).

일반적으로 모든 클립에 대해 유효한 값을 가진 필드만 사용해야 하며, 필드에 항상 유효한 값이 있는 것이 아니라면 설정되지 않은 값이나 null 값을 표현할 방법에 대한 계획이 있어야 합니다.

버전 스태킹

Frame.io는 UI에서 동일한 콘텐츠의 여러 반복 작업을 묶는 방법인 버전 스택을 지원합니다. C2C API를 통해 디바이스는 이전 버전과 함께 버전 스택에 배치될 에셋의 새로운 반복 작업을 업로드할 수 있습니다. 버전 스택을 생성하려면 에셋이 속한 버전 스택을 식별하는 autoversion_id를 제공해야 합니다. 이 값은 UUID, 파일 이름 등 무엇이든 될 수 있습니다. 에셋 폴더에서 의도치 않게 반복되지 않을 값만 사용하도록 주의하세요. 예를 들어 연동 과정에서 동일한 파일 이름이 여러 번 생성될 가능성이 있다면 filename은 autoversion_id로 사용하기에 적합하지 않습니다.

autoversion_id는 다음과 같이 제공합니다.

${
>curl -X POST https://api.frame.io/v2/assets \
>    --header 'Authorization: Bearer [access_token]' \
>    --header 'Content-Type: application/json' \
>    --header 'x-client-version: 2.0.0' \
>    --data-binary @- <<'__JSON__' 
>        {
>            "name": "A001_C001_v01.mov", 
>            "filetype": "video/webm", 
>            "filesize": 21136250,
>            "offset": 10,
>            "autoversion_id": "033e22ae-8544-4c9b-a84c-fcc140b0dd16"
>        }
>__JSON__
>} | python -m json.tool

이제 새 에셋을 업로드할 때마다 동일한 autoversion_id를 사용하면 해당 에셋이 원본 에셋이 있는 스택에 최신 버전으로 추가됩니다.

${
>curl -X POST https://api.frame.io/v2/assets \
>    --header 'Authorization: Bearer [access_token]' \
>    --header 'Content-Type: application/json' \
>    --header 'x-client-version: 2.0.0' \
>    --data-binary @- <<'__JSON__' 
>        {
>            "name": "A001_C001_v02_with_color.mov", 
>            "filetype": "video/webm", 
>            "filesize": 21136250,
>            "offset": 10,
>            "autoversion_id": "033e22ae-8544-4c9b-a84c-fcc140b0dd16"
>        }
>__JSON__
>} | python -m json.tool

에셋은 동일한 폴더에 업로드된 경우에만 스택되므로 버전 스태킹을 구현하려는 경우 몇 가지 사항을 염두에 두어야 합니다.

  • 버전 스택이 생성되려면 토큰화된 메타데이터가 동일한 상위 폴더로 확인되어야 합니다.
  • 생성 날짜는 파일 경로의 일부이므로 원본 업로드의 생성 시간에 대한 오프셋을 제공하지 않으면 UTC 자정 이후에 생성된 새 버전이 올바르게 스택되지 않을 수 있습니다.

이 두 번째 사항은 중요합니다. 예를 들어 최초 업로드 48시간 후에 새 버전의 에셋이 생성된다고 가정해 보겠습니다. 원본 에셋과 스택하려면 과거 48시간에 해당하는 오프셋인 172800초를 제공해야 합니다.

${
>curl -X POST https://api.frame.io/v2/assets \
>    --header 'Authorization: Bearer [access_token]' \
>    --header 'Content-Type: application/json' \
>    --header 'x-client-version: 2.0.0' \
>    --data-binary @- <<'__JSON__' 
>        {
>            "name": "A001_C001_v03_with_color.mov", 
>            "filetype": "video/webm", 
>            "filesize": 21136250,
>            "offset": 172800,
>            "autoversion_id": "033e22ae-8544-4c9b-a84c-fcc140b0dd16"
>        }
>__JSON__
>} | python -m json.tool

현재 에셋이 2022_04_03에 업로드되었어야 하는 경우, 이제 2022_04_01에 업로드되고 올바른 에셋과 스택됩니다.

다음 단계

이것으로 훌륭한 C2C 연동 시스템을 구축하기 위한 마지막 가이드가 끝났습니다! 스스로를 칭찬해 주세요! 잠시 간식을 드시며 쉬어도 좋습니다. 이제 연동 개발자 체크리스트를 검토하기만 하면 됩니다. 이 체크리스트에는 완벽한 연동 시스템을 구축하는 데 필요한 모든 내용이 요약되어 있습니다.

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