YouTube Live Streaming API 개요

YouTube Live Streaming API를 사용하면 YouTube에서 라이브 이벤트를 만들고 업데이트하고 관리할 수 있습니다. API를 사용하여 이벤트 (방송)를 예약하고 실제 방송 콘텐츠를 표시하는 동영상 스트림과 연결할 수 있습니다.

Live Streaming API는 실제로 YouTube Data API와 YouTube Content ID API의 구성요소로 이루어져 있습니다. Data API를 사용하면 YouTube 사용자가 YouTube 계정을 관리할 수 있으며 YouTube Content ID API를 사용하면 YouTube의 권리 관리 시스템과 상호작용할 수 있습니다. 하지만 Live Streaming API를 구성하는 모든 리소스는 라이브 이벤트를 만들고 관리하는 데만 사용됩니다.

이 문서는 YouTube에서 라이브 방송을 지원하는 애플리케이션을 작성하려는 개발자를 대상으로 합니다. YouTube 및 API 자체의 기본 개념을 설명합니다. 또한 API가 지원하는 다양한 기능에 대한 개요를 제공합니다.

핵심 개념

방송

방송 은 YouTube에서 실시간으로 시청할 수 있는 이벤트를 나타냅니다. 방송은 사용자가 나중에 볼 수 있도록 YouTube 동영상으로 녹화하거나 저장할 수 있습니다.

스트림

스트림 은 YouTube에 전달되는 오디오-동영상 콘텐츠를 식별합니다. 각 방송은 1개의 동영상 스트림과 연결됩니다.

큐 시점

cuepoint 은 라이브 방송에 삽입할 수 있는 광고 시점을 나타냅니다.

API 사용 사례

아래 목록에서는 애플리케이션에서 API를 사용하는 몇 가지 방법을 제시합니다.

• 방송을 예약하고 방송 설정을 정의합니다. 애플리케이션에서 사용자가 방송 설정을 사전 정의한 다음, 설정을 선택하여 특정 방송에 적용하도록 할 수 있습니다.

• 동영상 스트림과 방송을 연결합니다.

• 방송사가 방송 및 동영상에 관한 정보를 동시에 정의할 수 있도록 합니다 (YouTube Data API 사용).

• 방송 상태 (예: testing 또는 live) 간 전환을 간소화하고 사용자가 큐 시점을 삽입할 수 있도록 합니다.

시작하기 전에

1. Google 계정이 있어야 Google Cloud console에 액세스하고 API 키를 요청하고 애플리케이션을 등록할 수 있습니다.

2. 애플리케이션을 등록하여 API 요청을 제출할 수 있도록 Google에 등록합니다.

3. 애플리케이션을 등록한 후 애플리케이션에서 사용하는 서비스 중 하나로 YouTube Data API를 선택합니다.

   1. Cloud console으로 이동하여 방금 등록한 프로젝트를 선택합니다.
   2. 사용 설정된 API 페이지로 이동합니다. API 목록에서 YouTube Data API v3의 상태가 사용 설정 되어 있는지 확인하고 YouTube 콘텐츠 파트너인 경우 YouTube Content ID API의 상태도 확인합니다.

4. JavaScript 객체 표기법 (JSON) 데이터 형식의 핵심 개념을 숙지합니다. JSON은 특정 언어에 의존하지 않는 일반적인 데이터 형식으로, 임의의 데이터 구조를 간단한 텍스트로 표현할 수 있습니다. 자세한 내용은 json.org를 참조하세요.

API 요청 승인

위에서 언급한 바와 같이 Live Streaming API는 기술적으로 YouTube Data API 또는 YouTube Content ID API의 일부인 기능을 사용합니다. Content ID API를 사용하여 YouTube에 애셋의 메타데이터, 소유권 정보, 정책 정보를 제공할 수 있습니다. (라이브 동영상 방송은 애셋의 한 예입니다.) 또한 API를 사용하여 동영상에 대한 소유권을 주장하고 동영상에 대한 광고 정책을 설정할 수 있습니다.

이 섹션에서는 다른 Live Streaming API 요청을 승인하는 요구사항과 다른 Content ID API 요청의 승인 요구사항을 설명합니다.

Data API 호출

API 요청은 방송 YouTube 채널을 소유한 Google 계정으로 승인되어야 합니다.

Content ID API 호출

API 요청은 방송 YouTube 채널을 소유한 콘텐츠 소유자와 연결된 Google 계정으로 승인되어야 합니다.

리소스 및 리소스 유형

리소스는 고유 식별자를 갖는 개별 데이터 항목입니다. 아래 표에서는 다양한 리소스 유형을 설명합니다. Live Streaming API를 사용하여 상호작용할 Live Streaming API. 기술적으로 이러한 모든 리소스는 실제로 YouTube Data API 또는 YouTube Content ID API의 일부로 정의됩니다. 하지만 liveBroadcast, liveStream, cuepoint 리소스는 라이브 이벤트를 만들고 관리하는 데만 사용됩니다.

지원되는 작업

아래 표는 API가 지원하는 다양한 메소드를 보여줍니다.

다음 표에서는 다양한 리소스 유형에 지원되는 작업을 식별합니다. 리소스를 삽입, 업데이트 또는 삭제하는 작업에는 항상 사용자 승인이 필요합니다. 경우에 따라 list 메서드는 승인된 요청과 승인되지 않은 요청을 모두 지원합니다. 승인되지 않은 요청은 공개 데이터만 검색하는 반면 승인된 요청은 인증된 사용자에게만 제한된 정보도 검색할 수 있습니다.

부분 리소스

API를 사용하면 애플리케이션에서 불필요한 데이터를 전송, 파싱, 저장하지 않도록 부분 리소스를 검색할 수 있으며 실제로 검색해야 합니다. 이를 통해 API가 네트워크, CPU, 메모리 리소스를 더 효율적으로 사용할 수 있도록 합니다.

part 매개변수는 YouTube Data API 리소스를 검색하거나 반환하는 모든 API 요청에 필요한 매개변수입니다. 이 매개변수는 API 응답에 포함되어야 하는 하나 이상의 최상위 (중첩되지 않은) 리소스 속성을 식별합니다. 예를 들어 liveStream 리소스에는 다음과 같은 부분이 있습니다.

• snippet
• cdn
• status

이러한 모든 부분은 중첩된 속성을 포함하는 객체이며 이러한 객체를 API 서버에서 검색할 수도 있고 검색하지 않을 수도 있는 메타데이터 필드 그룹으로 생각할 수 있습니다. 따라서 part 매개변수를 사용하려면 애플리케이션에서 실제로 사용하는 리소스 구성요소를 선택해야 합니다. 이 요구사항은 다음과 같은 두 가지 중요한 목적을 달성합니다.

• 애플리케이션에서 사용하지 않는 메타데이터 필드를 API 서버에서 검색하는 데 시간을 소비하지 않도록 하여 지연 시간을 줄입니다.
• 애플리케이션에서 검색할 수 있는 불필요한 데이터양을 줄이거나 없앰으로써 대역폭 사용량을 감소시킵니다.

리소스가 점점 더 많은 부분을 추가하게 되면 애플리케이션에서 지원하지 않는 새로 정의된 속성을 요청하지 않게 되므로 이와 같은 장점은 더 커질 것입니다.

팁 및 권장사항

콘텐츠 소유권 주장

방송 중에 광고를 게재하려면 이벤트가 시작되기 전에 방송 동영상의 소유권을 주장해야 합니다. 콘텐츠의 소유권을 주장하려면 YouTube 콘텐츠 파트너로서 Content ID 프로그램에 참여해야 합니다.

라이브 방송 동영상의 소유권을 주장하는 절차는 동영상의 소유권을 주장하는 일반적인 절차와 다릅니다. 라이브 동영상의 소유권을 주장할 때는 동영상이 실제로 존재하기 전에 소유권 주장을 만들어야 합니다. API는 이를 지원하며 방송 문서의 수명은 소유권 주장을 만들 수 있는 YouTube Content ID API 호출을 설명합니다.

콘텐츠 미리보기 및 테스트

내부 동영상 스트림을 수신한 후 YouTube는 해당 동영상을 2개의 다른 외부 스트림에서 방송할 수 있습니다.

• 모니터 스트림 을 사용하면 동영상 방송을 미리 보고 테스트할 수 있습니다. 나만 액세스할 수 있는 비공개 스트림입니다. 방송의 모니터 스트림이 사용 설정된 경우에만 방송을 testing 단계로 전환할 수 있습니다. 모니터 스트림에는 광고 시점이 표시되지 않습니다.

• 방송 스트림 은 시청자에게 표시되는 스트림입니다. 방송의 공개 상태를 public, private 또는 unlisted로 설정할 수 있습니다. (비공개 방송은 시청하도록 명시적으로 초대된 사용자만 볼 수 있는 반면 미등록 방송은 볼 수 있는 링크를 가진 모든 사용자가 볼 수 있습니다.)

  방송 스트림이 모니터 스트림과 동시에 실행되지 않도록 지연시킬 수 있습니다. 방송 스트림을 지연시키면 방송에 삽입하는 큐 시점 시간을 보다 세밀하게 조정할 수 있습니다.

  하지만 방송 스트림을 지연시키면 라이브 발표자가 시청자와 상호작용하기가 어려워집니다. 또한 방송을 지연시키면 시청자가 방송 이외의 소스에서 이벤트에 관한 주요 세부정보를 발견할 가능성이 높아집니다. 예를 들어 60초가 지연되도록 스포츠 경기를 방송 중인 경우 시청자는 해당 방송이 아닌 다른 실시간 뉴스 매체에서 경기의 중요한 순간을 미리 볼 수 있습니다.

콘텐츠를 테스트할 수 있도록 방송의 모니터 스트림을 사용 설정하는 것이 좋습니다. 잠재고객과의 상호작용보다는 큐 시점의 타이밍 조정을 위해 방송을 지연시킬지 아니면 이벤트를 실시간으로 방송할지 여부를 결정해야 합니다.

방송 스트림 중에 미드롤 광고 게재

방송 중에 cuepoint 을 삽입하여 방송에서 가능한 한 빨리 또는 지정된 시간에 광고 시점을 시작해야 함을 나타낼 수 있습니다. 광고 시점을 사용하면 YouTube에서 방송 중에 미드롤 광고를 게재할 수 있습니다.

광고 시점에는 다음과 같은 특징이 있습니다.

1. 미리 정의된 시간 길이로, cuepoint 리소스의 durationSecs 속성을 사용하여 설정합니다. 광고 시점이 끝나면 시청자는 라이브 방송으로 돌아갑니다.

2. 광고 시점이 발생하면 큐 시점이 삽입될 때 방송을 시청하는 시청자의 동영상 플레이어에서만 광고가 재생됩니다. 시청자가 방송이 재생되는 페이지를 새로고침하거나 방문자가 큐 시점이 삽입된 후 방송을 시청하기 시작하면 광고가 게재되지 않습니다.

다음은 방송 중 광고 시점 삽입에 권장하는 단계를 설명합니다.

시간 오프셋 설정

큐 시점을 삽입할 때 즉시 삽입하거나 방송의 특정 지점에 삽입하도록 지정할 수 있습니다. 옵션은 동영상의 방송 스트림이 지연되는지 여부에 따라 다릅니다.

• 방송 스트림이 지연되지 않으면 큐 시점을 즉시 삽입하거나 walltimeMs 속성을 사용하여 특정 시간에 광고 시점을 시작할 수 있습니다.

  • 광고 시점을 즉시 시작하려면 liveBroadcasts.cuepoint 메서드를 호출합니다. 요청 본문의 리소스에서 insertionOffsetTimeMs 속성의 값을 0으로 설정하거나 해당 속성의 값을 지정하지 않고 walltimeMs 속성의 값을 지정하지 않습니다.

    중요: 시청자에게 결과 광고 콘텐츠가 즉시 표시되지는 않습니다. 광고 콘텐츠가 사용자에게 표시되기까지 약 30초의 지연 시간이 있을 수 있습니다. 지연 시간 동안 방송 스트림은 시청자에게 계속 표시되며 모니터 스트림 대신 광고 콘텐츠가 실제로 표시되는 시점을 확인하려면 방송 스트림을 시청해야 합니다.

  • 특정 시간에 광고 시점을 시작하려면 liveBroadcasts.cuepoint 메서드를 호출하고 walltimeMs 속성을 사용하여 원하는 시간을 지정합니다. 속성 값은 에포크 타임스탬프를 나타내는 정수입니다.

• 방송 스트림이 지연되면 위에서 설명한 대로 큐 시점을 즉시 삽입하거나 위에서 설명한 대로 시계 시간을 지정하거나 시간 오프셋을 지정하여 광고 시점이 시작되는 시점을 결정할 수 있습니다. 시간 오프셋은 시청자에게 광고가 표시되어야 하는 방송의 지점 을 지정합니다.

  오프셋 값은 방송의 모니터 스트림 시작부터 밀리초 단위로 측정됩니다. 방송에 테스트 단계가 있는 경우 방송이 testing 상태로 전환될 때 모니터 스트림 이 시작됩니다. 그렇지 않으면 방송이 live 상태로 전환될 때 모니터 스트림이 시작됩니다.

  큐 시점을 삽입할 때 cuepoint 리소스의 insertionOffsetTimeMs 속성을 원하는 오프셋으로 설정합니다.

시간 오프셋 값 계산

오프셋 값을 검색하려면 모니터 스트림을 재생하는 플레이어에 대해 YouTube Player API의 getCurrentTime 함수를 호출합니다. 검색된 값을 사용하여 해당 시간의 방송 스트림에 큐 시점을 삽입합니다.

오프셋 시간으로 사용 가능한 값은 다음 범위로 계산됩니다.

[(elapsed_time - broadcast_delay + Δ), (elapsed_time - Δ)]

Δ는 YouTube에서 큐 시점을 정확하게 삽입할 수 없는 경우 가능한 타임스탬프의 시작과 끝에 있는 5초 버퍼입니다. 예를 들면 다음과 같습니다.

• 방송에 5분 간의 테스트 단계가 있습니다.
• 방송 스트림이 모니터 스트림 후 60초 간 지연됩니다.
• 방송사가 방송이 live 상태로 전환된 후 4분 후에 큐 시점을 삽입합니다. (방송 스트림이 표시되기 시작하고 3분 후입니다.)

이 경우 가능한 오프셋 시간 범위는 [(485,000), (535,000)]입니다.

시간은 밀리초 단위로 지정되며 다음 값을 사용하여 계산됩니다.

• elapsed_time=540000 – liveBroadcasts.cuepoint 메서드가 호출될 때 모니터 스트림이 9분 (540초, 540,000밀리초) 동안 실행되었습니다.
• broadcast_delay=60000 – 방송 스트림이 60초 또는 60, 000밀리초 지연됩니다.
• Δ=5000 – 큐 시점을 안정적으로 삽입할 수 없는 경우의 5초 버퍼입니다.

문제해결 및 오류 처리

다음 가이드라인에서는 발생할 수 있는 특정 문제를 해결하는 방법을 설명합니다. 각 API 메서드가 반환할 수 있는 오류 목록은 YouTube Live Streaming API - 오류를 참고하세요.

• 방송이 한 상태에서 다른 상태로 전환되면 YouTube에서 전환과 연결된 작업을 완료하는 동안 일시적으로 다른 상태가 할당될 수 있습니다. 예를 들어 방송의 상태를 ready에서 testing으로 변경하는 liveBroadcasts.transition 요청을 보내면 YouTube에서 방송의 상태를 testStarting으로 설정한 다음 상태 변경과 연결된 작업을 완료합니다. 이러한 모든 작업이 완료되면 YouTube에서 방송의 상태를 testing으로 업데이트하여 전환이 완료되었음을 나타냅니다.

  방송이 testStarting 또는 liveStarting 상태로 멈추면 liveBroadcasts.delete 메서드를 호출하고 방송을 삭제해야 합니다. 그런 다음 새 방송을 만들고 라이브 스트림에 바인딩한 후 테스트 프로세스를 계속합니다.

  liveBroadcasts.transition 메서드의 문서에 설명된 대로 해당 메서드를 호출하기 전에 방송에 바인딩된 스트림의 status.streamStatus 속성 값이 active인지 확인해야 합니다.