LiveBroadcasts

이제 API에서 실시간 방송을 '아동용'으로 표시하는 기능을 지원하고 liveBroadcast 리소스에 실시간 방송의 '아동용' 상태를 식별하는 속성이 포함됩니다. 2020년 1월 10일에 YouTube API 서비스 약관 및 개발자 정책도 업데이트되었습니다. 자세한 내용은 YouTube Live Streaming API 서비스YouTube API 서비스 서비스 약관의 업데이트 기록을 참고하세요.

liveBroadcast 리소스는 YouTube에서 실시간 동영상을 통해 스트리밍되는 이벤트를 나타냅니다.

방법

API는 liveBroadcasts 리소스에 다음 메서드를 지원합니다.

list
API 요청 매개변수와 일치하는 YouTube 브로드캐스트 목록을 반환합니다. 지금 사용해보기
삽입
브로드캐스트를 만듭니다. 지금 사용해보기
업데이트
브로드캐스트를 업데이트합니다. 예를 들어 liveBroadcast 리소스의 contentDetails 객체에 정의된 브로드캐스트 설정을 수정할 수 있습니다. 지금 사용해 보세요.
delete
브로드캐스트를 삭제합니다. 지금 사용해보기
결합
YouTube 브로드캐스트를 스트림에 바인딩하거나 방송과 스트림 간의 기존 바인딩을 삭제합니다. 하나의 방송은 하나의 동영상 스트림에만 결합될 수 있지만, 하나의 동영상 스트림이 둘 이상의 방송에 결합될 수도 있습니다. 지금 사용해보기
transition
YouTube 실시간 방송 상태를 변경하고 새 상태와 관련된 프로세스를 시작합니다. 예를 들어 방송 상태를 testing로 전환하면 YouTube는 방송의 모니터 스트림으로 동영상을 전송하기 시작합니다. 이 메서드를 호출하기 전에 방송에 바인딩된 스트림의 status.streamStatus 속성 값이 active인지 확인해야 합니다. 지금 사용해 보세요.
큐 시점
실시간 방송에 큐 시점을 삽입합니다. 큐 시점이 광고 시간을 트리거할 수 있습니다.

리소스 표현

다음 JSON 구조는 liveBroadcasts 리소스의 형식을 보여줍니다.

{
  "kind": "youtube#liveBroadcast",
  "etag": etag,
  "id": string,
  "snippet": {
    "publishedAt": datetime,
    "channelId": string,
    "title": string,
    "description": string,
    "thumbnails": {
      (key): {
        "url": string,
        "width": unsigned integer,
        "height": unsigned integer
      }
    },
    "scheduledStartTime": datetime,
    "scheduledEndTime": datetime,
    "actualStartTime": datetime,
    "actualEndTime": datetime,
    "isDefaultBroadcast": boolean,
    "liveChatId": string
  },
  "status": {
    "lifeCycleStatus": string,
    "privacyStatus": string,
    "recordingStatus": string,
    "madeForKids": string,
    "selfDeclaredMadeForKids": string,
  },
  "contentDetails": {
    "boundStreamId": string,
    "boundStreamLastUpdateTimeMs": datetime,
    "monitorStream": {
      "enableMonitorStream": boolean,
      "broadcastStreamDelayMs": unsigned integer,
      "embedHtml": string
    },
    "enableEmbed": boolean,
    "enableDvr": boolean,
    "recordFromStart": boolean,
    "enableClosedCaptions": boolean,
    "closedCaptionsType": string,
    "projection": string,
    "enableLowLatency": boolean,
    "latencyPreference": boolean,
    "enableAutoStart": boolean,
    "enableAutoStop": boolean
  },
  "statistics": {
    "totalChatCount": unsigned long
  },
  "monetizationDetails": {
    "cuepointSchedule": {
      "enabled": boolean,
      "pauseAdsUntil": datetime,
      "scheduleStrategy": string,
      "repeatIntervalSecs": unsigned integer,
    }
  }
}

속성

다음 표는 이 리소스에 표시되는 속성을 정의합니다.

속성
kind string
API 리소스의 유형을 식별합니다. 값은 youtube#liveBroadcast입니다.
etag etag
이 리소스의 Etag입니다.
id string
YouTube가 방송을 고유하게 식별하기 위해 할당하는 ID입니다.
snippet object
snippet 객체에는 제목, 설명, 시작 시간, 종료 시간 등 일정에 대한 기본 세부정보가 포함됩니다.
snippet.publishedAt datetime
방송이 YouTube의 실시간 방송 일정에 추가된 날짜 및 시간입니다. 값은 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 형식으로 지정됩니다.
snippet.channelId string
YouTube가 방송을 게시하는 채널을 고유하게 식별하는 데 사용하는 ID입니다.
snippet.title string
방송의 제목입니다. 브로드캐스트는 정확히 하나의 YouTube 동영상을 나타냅니다. 방송 리소스를 수정하거나 해당하는 동영상 리소스의 title 필드를 설정하여 이 필드를 설정할 수 있습니다.
snippet.description string
브로드캐스트의 설명입니다. title와 마찬가지로 방송 리소스를 수정하거나 상응하는 동영상 리소스의 description 필드를 설정하여 이 필드를 설정할 수 있습니다.
snippet.thumbnails object
방송과 관련된 썸네일 이미지의 맵입니다. 이 객체에 있는 각 중첩된 객체에서 키는 썸네일 이미지의 이름이고 값은 썸네일에 대한 기타 정보가 포함된 객체입니다.
snippet.thumbnails.(key) object
유효한 키 값은 다음과 같습니다.
  • default – 기본 썸네일 이미지입니다. 동영상의 기본 미리보기 이미지 또는 재생목록 항목이나 검색결과와 같이 동영상을 참조하는 리소스로서 너비는 120픽셀, 세로는 90픽셀입니다. 채널의 기본 미리보기 이미지는 88x88픽셀입니다.
  • medium - 썸네일 이미지의 고해상도 버전입니다. 동영상 (또는 동영상을 참조하는 리소스)의 경우 이 이미지는 320x180픽셀입니다. 채널의 경우 이 이미지는 240x240픽셀입니다.
  • high - 썸네일 이미지의 고해상도 버전입니다. 동영상 (또는 동영상을 참조하는 리소스)의 경우 이 이미지는 480x360픽셀입니다. 채널의 경우 이 이미지는 800x800픽셀입니다.
snippet.thumbnails.(key).url string
이미지의 URL입니다.
snippet.thumbnails.(key).width unsigned integer
이미지의 너비입니다.
snippet.thumbnails.(key).height unsigned integer
이미지의 높이입니다.
snippet.scheduledStartTime datetime
방송이 시작되도록 예약된 날짜 및 시간입니다. 값은 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 형식으로 지정됩니다. 크리에이터 스튜디오에서는 시작 시간을 예약하지 않고도 방송을 만들 수 있습니다. 이 경우 채널 소유자가 스트리밍을 시작할 때마다 방송이 시작됩니다. 이러한 방송의 경우 datetime 값은 UNIX 시간 0에 해당하며 이 값은 API 또는 크리에이터 스튜디오를 통해 변경할 수 없습니다.
snippet.scheduledEndTime datetime
방송이 종료되도록 예약된 날짜 및 시간입니다. 값은 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 형식으로 지정됩니다. liveBroadcast 리소스가 이 속성의 값을 지정하지 않으면 방송이 무기한 계속되도록 예약됩니다. 마찬가지로 이 속성의 값을 지정하지 않으면 YouTube가 방송이 무기한 계속되는 것처럼 처리합니다.
snippet.actualStartTime datetime
방송이 실제로 시작된 날짜 및 시간입니다. 이 정보는 브로드캐스트 상태가 live인 경우에만 사용할 수 있습니다. 값은 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 형식으로 지정됩니다.
snippet.actualEndTime datetime
방송이 실제로 종료된 날짜 및 시간입니다. 이 정보는 브로드캐스트 상태가 complete인 경우에만 사용할 수 있습니다. 값은 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 형식으로 지정됩니다.
snippet.isDefaultBroadcast boolean
이 속성은 2020년 9월 1일부터 지원 중단됩니다. 이 시점부터 채널에 실시간 스트리밍이 사용 설정되면 YouTube에서 기본 스트림과 기본 방송의 생성을 중지합니다. 자세한 내용은 지원 중단 공지를 참조하세요.
이 속성은 이 방송이 기본 방송인지를 나타냅니다.

기본 방송 작동 방식

YouTube 채널에서 실시간 스트리밍을 사용 설정하면 YouTube에서 채널의 기본 스트림과 기본 방송을 만듭니다. 스트림은 채널 소유자가 YouTube에 실시간 동영상을 보내는 방법을 정의하며 방송은 시청자가 기본 스트림을 볼 수 있는 방법입니다. 채널 소유자는 liveStreams.listliveBroadcasts.list 메서드를 사용하여 이러한 리소스를 식별할 수 있습니다.

채널에서 기본 스트림으로 동영상 스트리밍을 시작하면 동영상이 채널의 기본 방송에 표시됩니다. 스트림이 종료되면 YouTube는 완료된 방송을 YouTube 동영상으로 변환하고 동영상에 YouTube 동영상 ID를 할당합니다.

변환이 완료되면 동영상이 채널에 업로드된 동영상 목록에 포함됩니다. 이 동영상은 방송이 끝난 직후에 볼 수 없으며 지연 시간은 방송의 실제 길이와 관련이 있습니다.
snippet.liveChatId string
브로드캐스트의 YouTube 실시간 채팅 ID입니다. 이 ID로 liveChatMessage 리소스의 메서드를 사용하여 채팅 메시지를 검색, 삽입 또는 삭제할 수 있습니다. 채팅 운영자를 추가 또는 삭제하거나, 사용자가 실시간 채팅에 참여하지 못하도록 차단하거나, 기존 차단을 해제할 수도 있습니다.
status object
status 객체에는 이벤트의 상태 정보가 포함됩니다.
status.lifeCycleStatus string
방송의 상태입니다. API의 liveBroadcasts.transition 메서드를 사용하여 상태를 업데이트할 수 있습니다.

이 속성에 유효한 값은 다음과 같습니다.
  • complete – 브로드캐스트가 종료됩니다.
  • created - 브로드캐스트에 설정이 완료되지 않아 live 또는 testing 상태로 전환할 준비가 되지 않았지만, 생성되었고 다른 방법으로 유효합니다.
  • live - 브로드캐스트가 활성 상태입니다.
  • liveStarting – 브로드캐스트가 live 상태로 전환하는 중입니다.
  • ready - 방송 설정이 완료되어 방송이 live 또는 testing 상태로 전환될 수 있습니다.
  • revoked – 관리자 작업으로 인해 이 브로드캐스트가 삭제되었습니다.
  • testStarting – 브로드캐스트가 testing 상태로 전환하는 중입니다.
  • testing - 방송이 파트너만 볼 수 있습니다.
status.privacyStatus string
방송의 개인 정보 보호 상태입니다. 브로드캐스트는 정확히 하나의 YouTube 동영상을 나타내므로 공개 범위 설정은 동영상에 지원되는 설정과 동일합니다. 또한 방송 리소스를 수정하거나 해당 동영상 리소스의 privacyStatus 필드를 설정하여 이 필드를 설정할 수 있습니다.

이 속성에 유효한 값은 다음과 같습니다.
  • private
  • public
  • unlisted
status.recordingStatus string
방송의 녹화 상태입니다.

이 속성에 유효한 값은 다음과 같습니다.
  • notRecording
  • recorded
  • recording
status.madeForKids boolean
이 값은 방송이 아동 대상으로 지정되었는지 여부를 나타냅니다. 이 속성 값은 읽기 전용입니다.
status.selfDeclaredMadeForKids boolean
liveBroadcasts.insert 요청에서 이 속성을 사용하면 채널 소유자가 방송을 아동 대상으로 지정할 수 있습니다. liveBroadcasts.list 요청에서 속성 값은 채널 소유자가 API 요청을 승인한 경우에만 반환됩니다.
contentDetails object
contentDetails 객체에는 콘텐츠가 삽입된 동영상 플레이어에 표시될 수 있는지 또는 보관처리되어 이벤트가 종료된 후 볼 수 있는지 여부 등 이벤트의 동영상 콘텐츠에 대한 정보가 포함됩니다.
contentDetails.boundStreamId string
이 값은 방송에 바인딩된 live stream를 고유하게 식별합니다.
contentDetails.boundStreamLastUpdateTimeMs datetime
boundStreamId에서 참조한 실시간 스트림이 마지막으로 업데이트된 날짜 및 시간입니다.
contentDetails.monitorStream object
monitorStream 객체에는 모니터 스트림에 관한 정보가 포함되어 있으며 방송사는 이 정보를 사용하여 방송 스트림이 공개적으로 표시되기 전에 이벤트 콘텐츠를 검토할 수 있습니다.
contentDetails.monitorStream.enableMonitorStream boolean
이 값은 방송에 모니터 스트림을 사용 설정할지 여부를 결정합니다. 모니터 스트림을 사용하도록 설정하면 YouTube가 방송사 전용 특별 스트림에서 이벤트 콘텐츠를 방송합니다. 브로드캐스터는 스트림을 사용하여 이벤트 콘텐츠를 검토하고 큐 포인트를 삽입할 최적의 시간을 파악할 수 있습니다.

방송에 testing 단계를 사용하거나 이벤트에 방송 지연을 적용하려면 이 값을 true로 설정해야 합니다. 또한 이 속성의 값이 true인 경우 브로드캐스트를 testing 상태로 전환해야 live 상태로 전환할 수 있습니다. (속성 값이 false이면 방송에 testing 단계가 있을 수 없으므로 방송을 live 상태로 직접 전환할 수 있습니다.)

update a broadcast를 실행하는 경우 API 요청이 part 매개변수 값에 contentDetails 부분을 포함하는 경우 이 속성을 설정해야 합니다. 그러나 insert a broadcast인 경우 이 속성은 선택사항이며 기본값은 true입니다.

중요: 브로드캐스트가 testing 또는 live 상태이면 이 속성을 업데이트할 수 없습니다.
contentDetails.monitorStream.broadcastStreamDelayMs unsigned integer
enableMonitorStream 속성을 true로 설정한 경우 이 속성은 실시간 방송 지연의 길이를 결정합니다.

update a broadcast를 실행하는 경우 API 요청이 part 매개변수 값에 contentDetails 부분을 포함하는 경우 이 속성을 설정해야 합니다. 그러나 insert a broadcast인 경우 이 속성은 선택사항이며 기본값은 0입니다. 이 값은 방송에 방송 지연이 없음을 나타냅니다. 참고: 방송이 testing 또는 live 상태이면 이 속성을 업데이트할 수 없습니다.
contentDetails.monitorStream.embedHtml string
모니터 스트림을 재생하는 플레이어를 삽입하는 HTML 코드입니다.
contentDetails.enableEmbed boolean
이 설정은 방송 동영상을 내장 플레이어에서 재생할 수 있는지 여부를 나타냅니다. enableArchive 속성을 사용하여 동영상을 보관처리하도록 선택하면 이 설정이 보관처리된 동영상에도 적용됩니다.

update a broadcast를 실행하는 경우 API 요청이 part 매개변수 값에 contentDetails 부분을 포함하는 경우 이 속성을 설정해야 합니다. 그러나 insert a broadcast인 경우 이 속성은 선택사항이며 기본값은 true입니다.

참고: 브로드캐스트가 testing 또는 live 상태이면 이 속성을 업데이트할 수 없습니다.
contentDetails.enableDvr boolean
이 설정은 시청자가 동영상을 시청하는 동안 DVR 컨트롤에 액세스할 수 있는지 결정합니다. DVR 컨트롤을 사용하면 시청자가 콘텐츠를 일시중지, 되감기 또는 빨리 감기하여 동영상 재생 환경을 제어할 수 있습니다. 이 속성의 기본값은 true입니다.

update a broadcast를 실행하는 경우 API 요청이 part 매개변수 값에 contentDetails 부분을 포함하는 경우 이 속성을 설정해야 합니다. 그러나 insert a broadcast인 경우 이 속성은 선택사항이며 기본값은 true입니다.

중요: 방송이 끝난 후 즉시 재생할 수 있도록 하려면 값을 true로 설정하고 enableArchive 속성의 값도 true로 설정해야 합니다. 또한 브로드캐스트가 testing 또는 live 상태이면 이 속성을 업데이트할 수 없습니다.
contentDetails.recordFromStart boolean
이 설정은 이벤트 상태가 실시간으로 변경된 후 YouTube에서 자동으로 방송 녹화를 시작할지 여부를 나타냅니다.

이 속성의 기본값은 true이며 방송 채널에서 실시간 방송 녹화를 사용 중지할 수 있는 경우에만 false로 설정할 수 있습니다.

녹화를 사용 중지할 수 있는 권한이 채널에 없는 상태에서 recordFromStart 속성이 false로 설정된 방송을 삽입하려고 하면 API에서 Forbidden 오류를 반환합니다. 또한 채널에 해당 권한이 없고 recordFromStart 속성을 false로 설정하기 위해 방송을 업데이트하려고 하면 API에서 modificationNotAllowed 오류를 반환합니다.

update a broadcast를 실행하는 경우 API 요청이 part 매개변수 값에 contentDetails 부분을 포함하는 경우 이 속성을 설정해야 합니다. 그러나 insert a broadcast인 경우 이 속성은 선택사항이며 기본값은 true입니다.

중요: 방송이 끝난 후 즉시 재생을 사용할 수 있도록 하려면 enableDvr 속성의 값도 true로 설정해야 합니다. 이 속성의 값을 true로 설정했지만 enableDvr 속성을 true로 설정하지 않은 경우, 보관처리된 동영상을 재생할 수 있게 되기까지 약 1일 정도 지연될 수 있습니다.

참고: 브로드캐스트가 testing 또는 live 상태이면 이 속성을 업데이트할 수 없습니다.
contentDetails.enableClosedCaptions boolean
이 속성은 2015년 12월 17일부로 지원 중단되었습니다. 대신 contentDetails.closedCaptionsType 속성을 사용하세요.

이 설정은 이 방송에 HTTP POST 자막 방송을 사용할지 여부를 나타냅니다. 이미 이 속성을 사용 중인 API 클라이언트의 경우:
  • 속성 값을 true로 설정하는 것은 contentDetails.closedCaptionsType 속성을 closedCaptionsHttpPost로 설정하는 것과 같습니다.
  • 속성 값을 false로 설정하는 것은 contentDetails.closedCaptionsType 속성을 closedCaptionsDisabled로 설정하는 것과 같습니다.
contentDetails.closedCaptionsType string
참고: 이 속성은 contentDetails.enableClosedCaptions 속성을 대체합니다.

이 속성은 방송에 자막이 사용 설정되었는지 여부 및 제공하는 경우 제공하는 자막의 유형을 나타냅니다.
  • closedCaptionsDisabled: 실시간 방송에서 자막이 사용 중지됩니다.
  • closedCaptionsHttpPost: HTTP POST를 통해 실시간 스트림과 연결된 처리 URL로 자막을 전송합니다.
  • closedCaptionsEmbedded: 자막이 EIA-608 또는 CEA-708 형식을 사용하여 동영상 스트림에서 인코딩됩니다.
contentDetails.projection string
이 브로드캐스트의 프로젝션 형식입니다. 속성의 기본값은 rectangular입니다.

이 속성에 유효한 값은 다음과 같습니다.
  • 360
  • rectangular
contentDetails.enableLowLatency boolean
지연 시간이 짧은 스트리밍을 위해 이 브로드캐스트를 인코딩해야 하는지 여부를 나타냅니다. 지연 시간이 짧은 스트림은 방송을 시청하는 사용자에게 동영상이 표시되는 데 걸리는 시간을 줄일 수 있지만 스트림 시청자의 해상도에도 영향을 줄 수 있습니다.
contentDetails.latencyPreference string
이 브로드캐스트에 사용할 지연 시간 설정을 나타냅니다. ultraLow를 지원하지 않는 enableLowLatency 대신 이 속성을 사용할 수 있습니다.

지연 시간이 짧은 스트림은 방송을 시청하는 사용자에게 동영상이 표시되는 데 걸리는 시간을 줄일 수 있지만 재생의 부드러움에도 영향을 줄 수도 있습니다.

지연 시간이 매우 짧은 스트림은 동영상이 시청자에게 표시되는 데 걸리는 시간을 더욱 단축하여 시청자와 더욱 쉽게 상호작용하게 합니다. 단, 0p 또는 매우 짧은 지연 시간 속성은 캡션에 비해 8p 또는 0p보다 높은 캡션을 지원하지 않습니다.

  • normal
  • low
  • ultraLow
contentDetails.enableAutoStart boolean
바인드된 live stream에서 동영상 스트리밍을 시작할 때 이 브로드캐스트를 자동으로 시작할지 여부를 나타냅니다.
contentDetails.enableAutoStop boolean
채널 소유자가 바인딩된 동영상 스트림에서 동영상 스트리밍을 중지한 후 약 1분 후에 이 브로드캐스트를 자동으로 중지해야 하는지 여부를 나타냅니다.
statistics object
statistics 객체에는 실시간 방송과 관련된 통계가 포함됩니다. 이 통계의 값은 방송 중에 변경될 수 있으며 방송이 진행되는 동안에만 검색할 수 있습니다.
statistics.totalChatCount unsigned long
브로드캐스트와 관련된 총 실시간 채팅 메시지 수입니다. 속성 및 값은 브로드캐스트가 사용자에게 표시되고 실시간 채팅 기능이 사용 설정되어 있으며 메시지가 하나 이상 있는 경우 표시됩니다. 이 속성은 방송이 끝난 후 값을 지정하지 않습니다. 따라서 이 속성은 완료된 실시간 방송의 보관처리된 동영상에 대한 채팅 메시지 수를 식별하지 않습니다.
monetizationDetails object
monetizationDetails 객체에는 광고 자동화기의 사용 설정 여부 또는 미드롤 광고 삽입의 지연 여부와 같은 스트림의 수익 창출 세부정보에 대한 정보가 포함됩니다.

monetizationDetails.cuepointSchedule object
cuepointSchedule 객체는 브로드캐스트의 광고 자동화 설정을 지정합니다.
monetizationDetails.cuepointSchedule.enabled boolean
이 값은 광고가 방송에 자동으로 삽입되는지 여부를 결정합니다. 값이 true이면 YouTube에서 자동으로 방송에 미드롤 광고를 삽입합니다. 광고 게재 일정은 monetizationDetails.cuepointSchedule 객체의 다른 필드 값에 따라 결정됩니다.
monetizationDetails.cuepointSchedule.pauseAdsUntil datetime
이 값은 YouTube가 지정된 날짜와 시간이 될 때까지 방송에 미드롤 광고를 삽입하지 않도록 지정합니다. 값은 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 형식으로 지정됩니다. 광고를 일시중지하려면 값을 미래의 날짜/시간으로 설정해야 합니다. 시간이 지나면 광고 일시중지를 해제하려면 필드 값을 가까운 미래의 날짜/시간으로 설정할 수도 있습니다.
monetizationDetails.cuepointSchedule.scheduleStrategy string
이 값은 YouTube에서 큐 지점을 예약하기 위해 따라야 하는 전략을 지정합니다. 유효한 값은 다음과 같습니다.
  • CONCURRENT: 모든 뷰어에 대해 큐 포인트가 동시에 예약됩니다.
  • NON_CONCURRENT: 큐 포인트가 여러 뷰어에 대해 서로 다른 시간에 예약됩니다. 이 접근 방식을 사용하면 시청자가 자격요건을 충족하는 경우 큐 포인트를 수신할 수 있는 높은 속도로 광고를 게재할 수 있습니다.
monetizationDetails.cuepointSchedule.repeatIntervalSecs unsigned integer
이 값은 브로드캐스트 중 자동 광고 삽입 사이의 간격(초)을 지정합니다. 예를 들어 값이 300인 경우 YouTube는 5분 간격으로 미드롤 광고 큐 시점을 삽입할 수 있습니다.

이 값은 연속적인 큐 포인트의 시작 사이의 시간을 지정합니다. 즉, 간격은 한 큐 포인트의 끝에서 다음 큐 포인트의 시작까지 측정되지 않습니다.