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 콘텐츠 파트너인 경우 YouTube Content ID API가 사용 설정되어 있어야 합니다.

  4. JSON (JavaScript Object Notation) 데이터 형식의 핵심 개념을 익힙니다. 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를 사용하여 상호작용할 다양한 리소스 유형을 설명합니다. 기술적으로 이러한 모든 리소스는 실제로 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
liveStream

부분 리소스

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

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

방송 중에 큐 시점을 삽입하여 최대한 빨리 또는 지정된 시간에 방송에서 광고 시간이 시작되어야 함을 나타낼 수 있습니다. 광고 시간을 사용하면 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인지 확인해야 합니다.