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(YouTube 콘텐츠 파트너인 경우)의 상태가 ON인지 확인합니다.

  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초 간 지연됩니다.
  • 방송사는 방송이 전환된 지 4분 후에 큐 시점을 live 상태입니다. (방송 스트림이 표시되기 시작하고 3분 후입니다.)

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

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

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

문제해결 및 오류 처리

다음 가이드라인은 발생할 수 있는 특정 문제를 해결하는 방법을 설명합니다. 목록의 경우 자세한 내용은 YouTube Live Streaming API - 오류를 참조하세요.

  • 방송이 한 상태에서 다른 상태로 전환되면 YouTube에서 전환과 관련된 작업을 완료하는 동안 일시적으로 다른 상태가 할당될 수 있습니다. 예를 들어 방송 상태를 ready에서 testing로 변경하기 위해 liveBroadcasts.transition 요청을 전송하는 경우 YouTube는 방송 상태를 testStarting로 설정한 다음 상태 변경과 관련된 작업을 완료합니다. 이러한 작업이 모두 완료되면 YouTube는 방송 상태를 testing로 업데이트하여 전환이 완료되었음을 표시합니다.

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

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