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개의 동영상 스트림과 연결됩니다.
큐포인트
큐 시점은 실시간 방송에 삽입할 수 있는 광고 시점을 나타냅니다.

API 사용 사례

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

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

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

  • 브로드캐스터가 방송과 동영상에 대한 정보 (YouTube Data API 사용)를 동시에 정의할 수 있도록 합니다.

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

시작하기 전에

  1. Google API Console에 액세스하고 API 키를 요청하고 애플리케이션을 등록하려면 Google 계정이 필요합니다.

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

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

    1. API Console로 이동하여 방금 등록한 프로젝트를 선택합니다.
    2. 사용 설정된 API 페이지로 이동합니다. API 목록에서 YouTube Data API v3와 YouTube Content ID API의 상태가 사용으로 설정되어 있는지 확인합니다.

  4. JSON (자바스크립트 객체 표기법) 데이터 형식의 핵심 개념을 숙지합니다. JSON은 임의의 데이터 구조를 간단한 텍스트로 표현하는 언어에 독립적인 일반적인 데이터 형식입니다. 자세한 내용은 json.org를 참조하세요.

API 요청 승인

위에서 설명한 것처럼 실시간 스트리밍 API는 기술적으로 YouTube Data API 또는 YouTube Content ID API의 일부인 기능을 사용합니다. Content ID API를 사용하여 저작물에 대한 메타데이터, 소유권 정보, 정책 정보를 YouTube에 제공할 수 있습니다. 애셋의 예로는 실시간 동영상 방송이 있습니다. 또한 API를 사용하여 동영상에 대한 소유권을 주장하고 동영상에 대한 광고 정책을 설정할 수 있습니다.

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

Data API 호출
API 요청은 방송되는 YouTube 채널을 소유한 Google 계정의 승인을 받아야 합니다.
Content ID API 호출
방송용 YouTube 채널을 소유한 콘텐츠 소유자와 연결된 Google 계정에서 API 요청을 승인해야 합니다.

리소스 및 리소스 유형

리소스는 고유 식별자가 있는 개별 데이터 항목입니다. 아래 표에는 Live Streaming API를 사용하여 상호작용할 다양한 유형의 리소스가 설명되어 있습니다. 엄밀히 말하면 이러한 모든 리소스는 실제로 YouTube Data API 또는 YouTube Content ID API의 일부로 정의됩니다. 단, liveBroadcast, liveStream 및 cuepoint 리소스는 실시간 이벤트를 만들고 관리하는 데만 사용됩니다.

자료
liveBroadcast YouTube에서 방송 중인 이벤트에 대한 정보가 포함됩니다. liveBroadcast 리소스는 YouTube 동영상 리소스의 확장 프로그램이며 다른 YouTube 동영상이 아닌 실시간 방송과 관련된 동영상 메타데이터를 설정합니다.

따라서 liveBroadcast 리소스는 정확히 하나의 YouTube 동영상 리소스에 해당합니다. 실제로 liveBroadcast 리소스와 video 리소스는 동일한 ID를 공유합니다. Live Streaming API를 사용하여 방송을 만든 후 YouTube Data API를 사용하여 동영상에 관한 추가 메타데이터를 제공할 수 있습니다.
liveStream YouTube에 전송하는 동영상 스트림에 대한 정보를 포함합니다. 스트림에서 YouTube 사용자에게 방송할 콘텐츠를 제공합니다. liveStream 리소스가 생성되면 정확히 하나의 liveBroadcast 리소스에 바인딩될 수 있습니다. 마찬가지로 liveBroadcast 리소스는 하나의 liveStream 리소스에만 바인딩할 수 있습니다.
cuepoint 광고 시점을 트리거할 수 있는 방송 동영상 스트림에 큐 포인트를 삽입합니다. liveBroadcasts.cuepoint 메서드를 사용하여 브로드캐스트 중에 큐 포인트를 삽입합니다.
video 단일 YouTube 동영상을 표시합. 위에서 언급했듯이 liveBroadcast 리소스는 video 리소스의 확장 프로그램입니다. YouTube Data API를 사용하여 동영상과 관련된 메타데이터(예: 녹화 위치 또는 방송을 볼 수 있는 지역)를 업데이트할 수 있습니다.
videoAdvertisingOptions 동영상 (또는 방송)의 광고 설정을 정의합니다. YouTube Content ID API를 사용하여 광고 옵션을 설정합니다.
asset 영화나 프로그램의 에피소드와 같은 지적 재산을 나타냅니다. 이 경우 방송 동영상이 저작물입니다. YouTube Content ID API를 사용하여 asset 리소스를 만들고 관리합니다.
claim 동영상이 일치하는 저작물에 연결됩니다. 방송 동영상의 소유자임을 확인하기 위해 YouTube Content ID API를 사용하여 소유권 주장을 만듭니다.
policy YouTube에서 콘텐츠를 시청하거나 YouTube에 표시되지 않도록 차단하려는 상황을 지정하는 규칙을 정의합니다. 내 방송 동영상에 정책을 적용해야 하며 YouTube가 방송 동영상과 일치하는 사용자 업로드 동영상에 적용할 정책을 지정할 수도 있습니다.

지원되는 작업

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

운영
list 0개 이상의 리소스 목록을 검색(GET)합니다.
insert 새 리소스를 만듭니다(POST).
update 요청에 포함된 데이터를 반영하도록 기존 리소스를 수정(PUT)합니다.
bind liveBroadcast 리소스를 liveStream 리소스와 연결하거나 이러한 링크를 삭제합니다.
transition liveBroadcast 리소스의 상태를 변경하고 새 상태와 관련된 모든 프로세스를 시작합니다. 예를 들어 방송 상태를 testing로 전환하면 YouTube는 방송의 모니터 스트림으로 동영상을 전송하기 시작합니다.
delete 특정 리소스를 삭제(DELETE)합니다.

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

지원되는 작업
list insert update bind transition cuepoint delete
liveBroadcast
실시간 스트림

부분 리소스

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

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

  • snippet
  • cdn
  • status

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

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

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

팁 및 권장사항

콘텐츠 소유권 주장

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

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

콘텐츠 미리보기 및 테스트

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

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

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

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

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

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

방송 스트림 중에 미드롤 광고 실행하기

방송 중에 큐 시점을 삽입하여 최대한 빨리 또는 지정된 시간에 방송에서 광고 시점을 시작해야 함을 나타낼 수 있습니다. 광고 시점을 사용하면 방송 중에 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가 전환과 관련된 작업을 완료하는 동안 일시적으로 다른 상태가 할당될 수 있습니다. 예를 들어 방송 상태를 ready에서 testing로 변경하도록 liveBroadcasts.transition 요청을 보내면 YouTube에서 방송 상태를 testStarting로 설정한 후 상태 변경과 관련된 작업을 완료합니다. 모든 작업이 완료되면 YouTube는 방송 상태를 testing로 업데이트하여 전환이 완료되었음을 표시합니다.

    방송이 testStarting 또는 liveStarting 상태로 중단된 경우 liveBroadcasts.delete 메서드를 호출하고 방송을 삭제해야 합니다. 그런 다음 새 방송을 만들고 실시간 스트림에 연결한 다음 테스트 절차를 계속 진행합니다.

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