소개
이 문서에서는 YouTube Live Streaming API와 YouTube Content ID API를 사용하여 만들고 관리하는 YouTube 라이브 방송의 수명 주기를 설명합니다.
리소스 및 리소스 유형
시작하기 가이드에서 설명한 것처럼 리소스는 고유 식별자를 갖는 개별 데이터 항목입니다. YouTube에서 라이브 이벤트를 만들고 관리하려면 YouTube Data API 또는 YouTube Content ID API의 일부로 정의된 여러 유형의 리소스를 사용합니다. YouTube 라이브 스트리밍 API 헤더 아래에 나열된 리소스는 기술적으로 다른 API에 정의되어 있지만 라이브 방송에만 사용되므로 별도로 나열됩니다.
YouTube Live Streaming API 리소스
YouTube Data API 리소스
YouTube Content ID API 리소스
라이브 방송 만들기 및 관리
다음 단계에서는 YouTube에서 라이브 이벤트를 만들고 관리하는 방법을 설명합니다. 단계는 다음과 같이 구분됩니다.
1단계: 방송 설정
1.1단계: 방송 만들기
liveBroadcasts.insert 메서드를 호출하여 YouTube의 라이브 이벤트 일정에 브로드캐스트를 추가합니다. 삽입하는 liveBroadcast 리소스는 아래에 나열된 속성의 값을 정의해야 합니다.
방송을 설정할 때 다음 가이드라인을 고려하세요.
다른 시청자가 방송을 볼 수 없는 상태에서 동영상 방송을 볼 수 있는 방송 테스트 단계를 진행하려면
contentDetails.monitorStream.enableMonitorStream속성을true로,contentDetails.enableAutoStart속성을false로 설정해야 합니다. 두 속성의 기본값은 다음과 같습니다.녹화된 방송에서 참조를 만들려면 방송의
contentDetails.recordFromStart속성을true로 설정해야 합니다. 방송이 종료된 후 녹화된 동영상을 즉시 재생할 수 있도록 하려면contentDetails.enableDvr속성을true로 설정해야 합니다. 두 속성 모두 기본값은true입니다.방송을 시청할 수 있는 지역을 제한하려면
contentDetails.availabilityConfig속성을 설정하면 됩니다. 이 속성을 사용하면 특정 지역을 차단하거나 정의된 지역 목록으로 사용 가능 여부를 제한할 수 있습니다. 지역별 사용 가능 시간도 지정할 수 있습니다.선택적으로
snippet.categoryId속성을 사용하여 방송의 동영상 카테고리를 지정할 수 있습니다. 지정하지 않으면 카테고리는 기본적으로Entertainment입니다.브로드캐스트 상태가
created또는ready인 동안에는contentDetails속성을 업데이트할 수 있습니다.방송 상태가
created,ready또는testing인 경우 방송의 예약 시작 시간과 예약 종료 시간을 업데이트할 수 있습니다.브로드캐스트의 제목, 설명, 카테고리, 개인 정보 보호 상태, 브로드캐스트의
video리소스에 포함된 기타 메타데이터 필드는 언제든지 업데이트할 수 있습니다.
참고: 특정 YouTube 사용자만 동영상을 사용할 수 있도록 하려면 필요에 따라status.privacyStatus속성 값을unlisted또는private로 설정하세요.
API 응답 처리
liveBroadcasts.insert 메서드를 호출하면 API 응답에 생성한 liveBroadcast 리소스가 포함됩니다. 코드에서 해당 리소스의 id를 추출하고 저장해야 합니다. 향후 API 요청에서 브로드캐스트를 식별하려면 이 값이 필요합니다. 동일한 ID를 사용하여 liveBroadcast 리소스에 해당하는 video 리소스를 식별할 수도 있습니다.
1.2단계: 스트림 만들기
liveStream 리소스를 사용하면 동영상을 YouTube로 전송할 수 있으며 전송하는 콘텐츠를 설명합니다. 각 방송은 정확히 하나의 스트림과 연결되어야 합니다.
liveStreams.insert 메서드를 호출하여 이벤트의 동영상 스트림을 만듭니다. 스트림을 만들 때는 아래에 나열된 속성의 값을 설정해야 합니다.
스트림 제목을 제외하고 이러한 값은 스트림이 생성된 후 업데이트할 수 없습니다. 변경해야 하는 경우 이 단계를 반복하여 다른 스트림을 만들어야 합니다. 이 프로세스는 이 문서의 뒷부분에 있는 3.5단계에서 자세히 설명합니다.
다음 속성의 값을 설정할 수도 있습니다.
snippet.description- 스트림 제목과 마찬가지로 스트림 설명은 스트림이 생성된 후 업데이트할 수 있습니다. 제목과 설명은 YouTube 사용자에게 표시되지 않습니다.[
contentDetails.isReusable](/youtube/data/live/reference/rest/v3/liveStreams#contentDetails.isReusable)
스트림을 재사용할 수 있는지 여부를 나타냅니다. 즉, 여러 방송에 바인딩할 수 있습니다. 이 속성의 값은 채널이
liveBroadcast및liveStream리소스 간에 다대일 관계 또는 일대일 관계를 갖는지 여부를 효과적으로 결정합니다.- 속성의 기본값인
true를 사용하면 채널의 모든 방송에 동일한liveStream리소스를 사용할 수 있습니다. 즉, 모든 방송에 대해 이 단계 (1.2)를 반복할 필요가 없습니다. 대신 후속 방송에 스트림 ID를 재사용하면 됩니다. - 속성 값을
false로 설정하면 각 브로드캐스트에 대해 새 스트림을 만들어야 합니다.
- 속성의 기본값인
스트림에 API 요청을 실행하면 API 응답에 생성한 liveStream 리소스가 포함됩니다. 코드는 해당 리소스에서 id을 추출하여 저장해야 합니다.
향후 API 요청에서 스트림을 식별하려면 이 값이 필요합니다.
1.3단계: 방송을 스트림에 연결
liveBroadcast 및 liveStream 리소스를 만들었으므로 이제 liveBroadcasts.bind 메서드를 사용하여 두 리소스를 연결해야 합니다. 이 작업을 통해 YouTube에 전송할 동영상 비트를 해당 동영상의 이벤트 브로드캐스트와 연결합니다.
liveBroadcasts.bind 메서드를 호출할 때 id 매개변수를 1.1단계에서 획득한 브로드캐스트 ID로 설정하고 streamId 매개변수를 1.2단계에서 획득한 스트림 ID로 설정합니다.
2단계: 콘텐츠 소유권 주장
브로드캐스트 중에 광고를 게재하려면 이벤트가 시작되기 전에 브로드캐스트 동영상을 소유권 주장해야 합니다. 다음 단계에 따라 브로드캐스트, 동영상, 광고를 설정합니다. 방송 소유자의 채널이 광고를 게재할 수 있어야 합니다.
이 단계에서 설명하는 모든 API 호출은 YouTube Content ID API에 정의되어 있습니다.
2.1단계: 저작물 만들기
asset 리소스는 지식 재산을 나타냅니다. 이 경우 애셋은 방송입니다. assets.insert 메서드를 호출하여 애셋을 만듭니다.
API 응답에는 생성한 asset 리소스가 포함됩니다. 향후 API 요청에서 애셋을 식별하려면 이 값이 필요하므로 코드에서 해당 리소스의 id를 추출하고 저장해야 합니다.
2.2단계: 저작물의 소유권 정의
저작물의 소유권 데이터는 저작물의 소유자와 소유자가 저작물을 소유하는 지역을 식별합니다. YouTube는 이 데이터를 사용하여 소유자가 소유권 주장이 제기된 동영상에 정책을 설정할 수 있는 위치를 결정합니다.
예를 들어 미국에서 이벤트를 방송할 권리가 있고 다른 방송사는 캐나다에서 동일한 권리를 소유하는 경우, 각자 방송 동영상과 방송 동영상과 일치하는 사용자 업로드 동영상에 대해 서로 다른 정책을 정의할 수 있습니다. 미국에서는 내 동영상 일치 관련 정책이 적용되고 캐나다에서는 다른 소유자의 정책이 적용됩니다.
저작물의 소유권 지역을 정의하려면 ownership.update 메서드를 호출합니다.
이 요청에서 assetId 매개변수를 2.1단계에서 저장한 id로 설정합니다.
2.3단계: 저작물의 동영상 일치 관련 정책 설정
저작물의 동영상 일치 관련 정책은 사용자가 저작물과 연결된 참조와 일치하는 동영상을 업로드할 때 YouTube에서 취해야 할 조치를 설명합니다. 이 경우 동영상 일치 관련 정책은 라이브 방송과 일치하는 업로드된 동영상을 YouTube에서 처리하는 방법을 나타냅니다.
참고: 방송 동영상에서 참조를 만들고 해당 참조를 사용하여 내 방송과 일치하는 사용자 업로드 동영상을 식별하려는 경우 동영상 일치 관련 정책을 설정해야 합니다. 그 외의 경우에는 이 단계를 건너뛸 수 있습니다.
동영상 일치 관련 정책을 설정하려면 먼저 적용할 정책을 식별해야 합니다. policies.list 메서드를 호출하여 기존 정책 목록을 검색하거나 policies.insert 메서드를 호출하여 새 정책을 정의할 수 있습니다. 두 경우 모두 적용할 정책의 id를 캡처해야 합니다.
정책을 확인한 후 assetMatchPolicy.update 메서드를 호출합니다. 이 요청에서 assetId 매개변수를 2.1단계에서 저장한 id로 설정합니다.
2.4단계: 동영상 소유권 주장
이 단계에서는 방송할 동영상을 2.1단계에서 만든 저작물에 연결하는 소유권 주장을 만듭니다. 소유권 주장은 방송 동영상에만 적용되는 정책을 설정합니다. (방송 동영상과 일치하는 사용자 업로드 동영상에는 이전 단계에서 설정한 동영상 일치 관련 정책이 적용됩니다.)
클레임을 만들려면 claims.insert 메서드를 호출합니다. 삽입하는 claim 리소스에서 다음 속성의 값을 설정해야 합니다.
assetId: 2.1단계에서 가져온 값입니다.videoId– 1.1단계에서 가져온 방송 ID입니다.policy–policy리소스입니다. 해당 리소스의id속성을 기존 정책의 ID로 설정하여 기존 정책을 적용할 수 있습니다. 이전 단계에서는 기존 정책의 ID를 검색하는 방법을 설명합니다.contentType- 이 값을audiovisual로 설정합니다.
API 응답 처리
소유권 주장을 삽입하면 API 응답에 생성한 claim 리소스가 포함됩니다. 코드는 해당 리소스에서 id을 추출하여 저장해야 합니다. 나중에 이 값을 사용하여 처리된 동영상에서 참조를 만듭니다.
2.5단계: 방송의 광고 설정 업데이트
시청자가 방송 시청을 시작할 때 프리롤 광고를 게재하거나 방송 중 휴식 시간에 광고를 게재하려면 동영상의 광고 옵션을 설정해야 합니다.
- 방송에 프리롤 광고를 사용 설정하면 모든 시청자가 방송 중간에 시청을 시작하더라도 방송 시청을 시작할 때 광고가 표시됩니다.
- 방송에 미드롤 광고를 사용 설정하면 방송 중에 광고 신호점을 삽입할 수 있습니다.
광고를 사용 설정하려면 videoAdvertisingOptions.update 메서드를 호출합니다. 요청에서 videoId 매개변수를 1.1단계에서 가져온 브로드캐스트 id로 설정합니다. videoAdvertisingOption 리소스의 adFormats[] 속성을 사용하여 사용 설정할 광고 형식 (preroll, midroll 또는 postroll)을 식별합니다.
3단계: 테스트
이 단계에서는 시청 환경을 테스트할 수 있도록 방송의 모니터 스트림을 보여주는 플레이어를 삽입합니다. 모니터링 스트림은 YouTube 시청자에게 표시되는 방송 동영상을 미리 볼 수 있는 비공개 스트림입니다.
모니터 스트림이 사용 설정된 경우에만 동영상 방송을 테스트할 수 있습니다. 기본적으로 브로드캐스트의 모니터 스트림은 사용 설정되어 있습니다. 방송을 만들거나 업데이트할 때 contentDetails.monitorStream.enableMonitorStream 속성을 false로 설정하여 방송의 모니터 스트림을 사용 중지할 수 있습니다.
3.1단계: 모니터 스트림 플레이어 삽입
liveBroadcasts.list 메서드를 사용하여 브로드캐스트를 가져오고 contentDetails.streamDetails.monitorStreamEmbedHtml 속성 값을 추출합니다. 이 값에는 모니터 스트림을 표시하는 YouTube 플레이어를 삽입하는 데 필요한 HTML이 포함되어 있습니다.
3.2단계: 동영상 재생
동영상을 동영상 스트림에 전송하기 시작합니다.
3.3단계: 동영상 스트림 활성화 확인
liveStreams.list 메서드를 호출하여 브로드캐스트와 연결된 liveStream 리소스를 가져옵니다. status.streamStatus 속성 값이 active인지 확인합니다. 이 값은 YouTube 서버가 인코더에서 데이터를 올바르게 수신하고 있음을 나타냅니다.
3.4단계: 브로드캐스트 상태를 테스트로 전환
liveBroadcasts.transition 메서드를 호출하여 브로드캐스트의 상태를 업데이트합니다. id 파라미터 값 을 1.1단계에서 획득한 방송 ID로 설정하고 broadcastStatus 파라미터 값 을 testing로 설정합니다.
liveBroadcasts.transition 메서드를 호출한 후 전환이 완료되는 데 몇 초 또는 최대 1분 정도 걸릴 수 있습니다. 이 시간 동안 API를 폴링하여 방송 상태를 확인해야 합니다. 전환이 완료될 때까지는 방송 상태가 testStarting로 표시됩니다. 전환이 완료되면 상태가 testing로 변경됩니다.
3.5단계: 테스트 완료g
테스트가 원활하게 진행되었다면 4단계로 이동합니다. 하지만 경우에 따라 추가 테스트가 필요할 수도 있습니다. 예를 들어 테스트에서 동영상 스트림이 올바르게 구성되지 않은 것으로 나타나면 방송을 진행하기 전에 이를 해결해야 합니다.
동영상 스트림이 올바르게 구성되지 않은 경우 기존 스트림을 바인딩 해제 (및 삭제)하고 새 스트림을 만들어야 합니다. 예를 들어 잘못된 동영상 형식을 지정하면 스트림이 올바르게 구성되지 않을 수 있습니다.
-
동영상 스트림을 바인딩 해제하려면 1.3단계의
liveBroadcasts.bind메서드를 호출합니다. API 요청에서id매개변수를 1.1단계에서 획득한id로 설정합니다. 요청에streamId매개변수를 포함하지 마세요. -
동영상 스트림을 삭제하려면
liveStreams.delete메서드를 호출합니다. 요청에서id파라미터를 1.2단계에서 획득한id로 설정합니다. -
1.2단계를 반복하여 올바르게 구성된 새
liveStream리소스를 만듭니다. 그런 다음 1.3단계를 반복하여 새 스트림을 방송에 결합하고 3.1~3.3단계를 반복하여 새 스트림을 테스트합니다.
3.6단계: autoStart 및 autoStop 속성 사용 설정
테스트 단계를 성공적으로 완료한 후 실제 방송이 시작되기 전에 방송의 contentDetails.enableAutoStart 및 contentDetails.enableAutoStop 속성을 true로 설정할 수 있습니다. 테스트 단계 전에 이러한 속성을 true로 설정할 수 없습니다. 테스트로 인해 브로드캐스트가 실제로 시작되기 때문입니다.
4단계: 방송
이 단계에서 잠재고객이 방송 동영상을 시청할 수 있게 됩니다.
4.1단계: 동영상 시작
동영상을 동영상 스트림에 전송하기 시작합니다.
4.2단계: 동영상 스트림이 활성 상태인지 확인하기
liveStreams.list 메서드를 호출하여 방송과 연결된 liveStream 리소스를 가져옵니다. status.streamStatus 속성 값이 active인지 확인합니다. 이 값은 YouTube 서버가 인코더에서 데이터를 올바르게 수신하고 있음을 나타냅니다.
4.3단계: 방송 상태를 라이브로 전환
중요: 이 단계를 완료하면 시청자가 동영상을 볼 수 있습니다.
liveBroadcasts.transition 메서드를 호출하여 방송 상태를 업데이트합니다. id 파라미터 값은 1.1단계에서 가져온 브로드캐스트 ID로 설정하고 broadcastStatus 파라미터 값은 live로 설정합니다.
liveBroadcast 리소스의 contentDetails.enableAutoStart 속성을 true로 설정하면 liveBroadcasts.transition 메서드를 호출하지 않아도 됩니다.
이 API 호출을 수행한 후 또는 contentDetails.enableAutoStart 속성을 true로 설정한 경우 스트리밍을 시작한 후 일반적으로 전환이 완료될 때까지 5~10초 정도 기다려야 합니다. 전환하는 데 최대 1분이 걸릴 수 있습니다. 이 시간 동안 API를 폴링하여 방송 상태를 확인해야 합니다. 전환이 완료될 때까지 방송 상태는 liveStarting입니다. 전환이 완료되면 상태가 live로 표시되며, 시청자는 모니터 스트림의 해당 지점부터 방송을 시청할 수 있습니다.
이 명령에 해당하는 다음의 효과를 참고하시기 바랍니다.
- 방송에 모니터 스트림을 사용 설정한 경우(3.1단계 참고) 삽입된 플레이어에서 모니터 스트림을 볼 수 있습니다.
- 브로드캐스트의
contentDetails.streamDetails.broadcastStreamDelayMs속성 값을 설정한 경우 다른 시청자에게 표시되는 브로드캐스트 스트림이 해당 시간만큼 지연됩니다.
4.4단계: 방송에 광고 시점 삽입하기
liveBroadcasts.cuepoint 메서드를 호출하여 큐 포인트를 삽입합니다. 큐 포인트는 광고 시점을 트리거할 수 있습니다. 요청 본문에 제공된 cuepoint 리소스에서 durationSecs 속성을 표시하려는 광고 시점의 원하는 길이 (초)로 설정합니다. 기본값은 30입니다.
이때 YouTube는 광고 신호가 삽입될 때 브로드캐스트를 시청하고 있던 모든 시청자의 동영상 플레이어에서 광고를 재생하려고 시도합니다. 광고 게재 여부는 광고 이용 가능 여부, 시청자의 광고 시청 기록 등 다양한 요인에 따라 달라집니다. 광고 시점이 표시되는 시청자는 광고 시점이 끝나면 방송으로 돌아가고, 광고가 표시되지 않는 시청자는 광고 시점 동안 방송 스트림을 계속 시청합니다.
시작하기 가이드에서는 라이브 방송의 광고 시청 환경에 대해 자세히 설명합니다.
5단계: 방송 종료
5.1단계: 스트리밍 중지
YouTube 방송 시스템의 테스트가 종료됩니다.
5.2단계: 브로드캐스트 상태를 완료로 전환
방송을 중지할 준비가 되면 API의 liveBroadcasts.transition 메서드를 호출하여 방송 상태를 업데이트합니다. id 파라미터 값을 1.1단계에서 획득한 브로드캐스트 ID로 설정하고 broadcastStatus 파라미터 값을 complete로 설정합니다.
브로드캐스트의 contentDetails.recordFromStart 및 contentDetails.enableDvr 속성을 true로 설정한 경우 라이브 이벤트가 종료되면 시청자가 즉시 라이브 이벤트 재생을 시청할 수 있습니다.
6단계: 참조 만들기
실시간 녹화가 완료되면 녹화된 동영상에서 참조를 만들 수 있습니다. 이 작업은 YouTube에 브로드캐스트와 일치하는 사용자 업로드 동영상을 찾고 2.3단계에서 설정한 동영상 일치 관련 정책에 따라 처리하도록 지시합니다.
중요: 참조를 만들려면 브로드캐스트의 contentDetails.recordFromStart 속성을 true로 설정해야 합니다.
6.1단계: 동영상 상태 관련 YouTube Data API 폴링
YouTube에서 방송 또는 업로드된 동영상의 처리를 완료해야 해당 동영상에서 참조를 만들 수 있습니다. 동영상 처리가 완료되었는지 확인하려면 YouTube Data API의 videos.list 메서드를 폴링하여 part 매개변수를 status로 설정하고 id 매개변수를 1.1단계에서 저장한 브로드캐스트 ID로 설정합니다.
폴링 요청에 대한 API 응답에는 video 리소스가 포함됩니다.
리소스의 status.uploadStatus 속성 값이 processed이면 6.2단계로 진행합니다.
6.2단계: 처리된 동영상에서 참조 만들기
참조를 만들려면 Content ID API의 references.insert 메서드를 호출하고 claimId 매개변수를 2.4단계에서 저장한 소유권 주장 ID로 설정합니다.
라이브 콘텐츠 ID 전송
일부 YouTube 파트너는 방송이 testing 상태로 전환되기 전에 참조를 만들 수 있지만 이 기능은 모든 파트너에게 제공되지는 않습니다. 이 흐름에서 YouTube는 방송이 진행되는 동안 라이브 이벤트의 방송 스트림에서 참조를 생성하고 지속적으로 업데이트합니다. 또한 YouTube는 방송이 진행되는 동안 일치하는 사용자 업로드 동영상을 찾습니다. 방송이 시작되기 전에 참조를 만들면 방송의 녹화가 자동으로 사용 설정되며, 참조가 생성된 후에는 녹화를 사용 중지할 수 없습니다.
실시간 Content ID 전송을 위해 방송을 사용 설정하려면 2.4단계에서 동영상에 대한 소유권을 주장한 후 6.2단계에 설명된 작업을 시도합니다.
파트너 계정이 라이브 방송이 발생하기 전에 해당 방송의 참조를 만들도록 승인되지 않은 경우 API는 fingerprintingNotAllowed 오류를 반환합니다. 이 경우 위 6.1 및 6.2단계에 설명된 대로 방송이 완료될 때까지 기다린 후 참조를 만들어야 합니다.