Жизнь трансляции

Введение

В этом документе описывается процесс прямой трансляции на YouTube, которая создается и управляется с помощью API YouTube Live Streaming и API YouTube Content ID .

Ресурсы и типы ресурсов

Как объясняется в руководстве по началу работы , ресурс — это отдельный объект данных с уникальным идентификатором. Для создания и управления прямыми трансляциями на YouTube вам понадобится ряд различных типов ресурсов, которые определены либо как часть API данных YouTube , либо как часть API идентификатора контента YouTube . Ресурсы, перечисленные в заголовке API прямых трансляций YouTube , технически определены в этих API, но перечислены отдельно, поскольку они используются только для прямых трансляций.

Ресурсы API YouTube Live Streaming

Ресурсы API данных YouTube

Ресурсы API YouTube Content ID

Создание и управление прямой трансляцией

Ниже описан процесс создания и управления прямой трансляцией на YouTube. Эти шаги делятся на следующие этапы:

  1. Настройте свою трансляцию
  2. Заявите права на свой контент
  3. Тест
  4. Транслировать
  5. Завершите свою трансляцию
  6. Создать ссылку

Этап 1: Настройте трансляцию

Шаг 1.1: Создайте свою трансляцию

Чтобы добавить трансляцию в расписание прямых трансляций YouTube, вызовите метод liveBroadcasts.insert . Вставляемый ресурс liveBroadcast должен определять значения для перечисленных ниже свойств.

При настройке трансляции примите во внимание следующие рекомендации:

  • Если вы хотите включить этап тестирования трансляции, когда вы можете смотреть видеотрансляцию без того, чтобы другие зрители могли её видеть, необходимо установить свойство contentDetails.monitorStream.enableMonitorStream в true , а свойство contentDetails.enableAutoStart — в false . Это значения по умолчанию для обоих свойств.

  • Если вы хотите создать ссылку на записанную трансляцию, необходимо установить свойство contentDetails.recordFromStart трансляции в true . Чтобы сделать записанное видео доступным для воспроизведения сразу после окончания трансляции, необходимо также установить свойство contentDetails.enableDvr в значение true . (Оба этих свойства имеют значение по умолчанию true .)

  • Вы можете обновить любое из свойств contentDetails , пока статус вашей трансляции все еще created или ready .

  • Вы можете обновить запланированное время начала и окончания трансляции, если статус трансляции — created , ready » или testing .

  • Название трансляции, ее описание, статус конфиденциальности и другие поля метаданных, являющиеся частью video трансляции, можно обновить в любое время.

    Примечание: Если вы хотите, чтобы ваше видео было доступно только определенным пользователям YouTube, задайте для свойства status.privacyStatus значение unlisted или private в зависимости от ваших потребностей.

Обработка ответа API

При вызове метода liveBroadcasts.insert ответ API содержит созданный вами ресурс liveBroadcast . Ваш код должен извлечь и сохранить id этого ресурса. Это значение понадобится вам для идентификации трансляции в будущих запросах API. (Вы также можете определить video , соответствующий ресурсу liveBroadcast , используя тот же идентификатор.)

Шаг 1.2: Создайте свой поток

Ресурс liveStream позволяет вам транслировать видео на YouTube и описывает транслируемый контент. Каждая трансляция должна быть связана только с одним потоком.

Вызовите метод liveStreams.insert , чтобы создать видеопоток для вашего события. При создании потока необходимо задать значения для перечисленных ниже свойств:

За исключением названия потока, эти значения нельзя обновить после его создания. Если вам нужно их изменить, вам нужно создать другой поток, повторив этот шаг. Этот процесс более подробно обсуждается в шаге 3.5 далее в этом документе.

У вас также есть возможность задать значения для следующих свойств:

  • snippet.description — как и название трансляции, описание трансляции можно обновить после её создания. Ни название, ни описание не видны пользователям YouTube.

  • contentDetails.isReusable — указывает, является ли поток повторно используемым, то есть может ли он быть привязан к нескольким трансляциям. Значение этого свойства фактически определяет, имеет ли канал отношение «многие к одному» или «один к одному» между ресурсами liveBroadcast и liveStream :

    • Если вы используете значение свойства по умолчанию true , то можете использовать один и тот же ресурс liveStream для всех трансляций канала. Это означает, что вам не нужно повторять этот шаг (1.2) для каждой трансляции. Вместо этого вы можете просто повторно использовать идентификатор потока для последующих трансляций.
    • Если установить значение свойства равным false , то необходимо создавать новый поток для каждой трансляции.

После отправки API-запроса к потоку ответ API содержит созданный вами ресурс liveStream . Ваш код должен извлечь и сохранить id этого ресурса. Это значение понадобится вам для идентификации потока в будущих API-запросах.

Шаг 1.3: Привяжите свою трансляцию к ее потоку

После создания ресурсов liveBroadcast и liveStream вам нужно связать их с помощью метода liveBroadcasts.bind . Это действие связывает видеофрагменты, которые вы будете передавать на YouTube, с трансляцией события для этого видео.

При вызове метода liveBroadcasts.bind установите параметр id на идентификатор трансляции, полученный на шаге 1.1, а параметр streamId на идентификатор потока, полученный на шаге 1.2.

Этап 2: Заявите права на свой контент

Если вы хотите показывать рекламу во время трансляции, вам необходимо заявить права на видеотрансляцию до её начала. Ниже описан этот процесс. Обратите внимание, что все вызовы API, обсуждаемые на этом этапе, определены в API YouTube Content ID .

Шаг 2.1: Создание актива

Ресурс asset представляет собой объект интеллектуальной собственности. В данном случае активом является ваша трансляция. Вызовите метод assets.insert для создания актива.

Ответ API будет содержать созданный вами ресурс asset . Ваш код должен извлечь и сохранить id этого ресурса, так как это значение понадобится вам для идентификации ресурса в будущих запросах API.

Шаг 2.2: Определите свои права собственности на актив

Данные о владельце актива идентифицируют владельцев актива, а также территории, на которых им принадлежит актив. YouTube использует эти данные, чтобы определить, где владелец может установить политику для заявленного видео.

Например, если у вас есть права на трансляцию мероприятия в США, а другой вещатель владеет теми же правами в Канаде, вы можете определить разные политики для транслируемого видео и для загруженных пользователями видео, соответствующих этому видео. Ваша политика соответствия будет применяться к соответствующим видео, загруженным пользователями в США, в то время как политика другого владельца будет применяться к соответствующим видео в Канаде.

Чтобы определить территории владения активом, вызовите метод ownership.update . В этом запросе укажите в параметре assetId id , сохранённый на шаге 2.1.

Шаг 2.3: Установите политику соответствия актива

Политика соответствия для объекта определяет, что должен делать YouTube, когда пользователь загружает видео, совпадающее с отпечатком, связанным с этим объектом. В этом случае политика соответствия определяет, как YouTube должен обрабатывать загруженное видео, совпадающее с вашей прямой трансляцией.

Примечание: Если вы планируете создать ссылку на видео вашей трансляции и использовать её для определения загруженных пользователями видео, соответствующих вашей трансляции, вам следует настроить политику соответствия. В противном случае этот шаг можно пропустить.

Чтобы задать политику соответствия, необходимо сначала определить политику, которую вы хотите применить. Вы можете получить список существующих политик, вызвав метод policies.list , или определить новую политику, вызвав метод policies.insert . В любом случае вам необходимо получить id политики, которую вы хотите применить.

После определения политики вызовите метод assetMatchPolicy.update . В этом запросе укажите в параметре assetId id , сохранённый на шаге 2.1.

Шаг 2.4: Заявите права на свое видео

На этом этапе вы создаёте заявку, которая связывает видео, которое вы будете транслировать, с активом, созданным на этапе 2.1. Заявка устанавливает политику, применяемую только к вашему транслируемому видео. (На загруженные пользователями видео, совпадающие с вашим транслируемым видео, распространяется политика соответствия, установленная на предыдущем этапе.)

Чтобы создать заявку, вызовите метод claims.insert . В вставляемом ресурсе claim необходимо задать значения следующих свойств:

  • assetId – это значение вы получили на шаге 2.1.
  • videoId – это идентификатор трансляции, полученный вами на шаге 1.1.
  • policy – это ресурс policy . Вы можете применить существующую политику, установив свойство id ресурса равным идентификатору существующей политики. В предыдущем шаге объясняется, как получить идентификатор существующей политики.
  • contentType – Установите это значение на audiovisual .

Обработка ответа API

При добавлении заявки ответ API будет содержать созданный вами ресурс claim . Ваш код должен извлечь и сохранить id из этого ресурса. Это значение понадобится вам позже для создания ссылки на обработанное видео.

Шаг 2.5: Обновите настройки рекламы для трансляции

Вам необходимо настроить параметры рекламы для вашего видео, если вы хотите показывать рекламу в начале трансляции или во время перерывов в трансляции.

  • Если вы включите показ рекламы в начале трансляции, то все зрители увидят рекламу, когда начнут смотреть трансляцию, даже если они начнут смотреть ее в середине.
  • Если вы включите рекламу в середине трансляции, то вы сможете вставлять рекламные метки во время трансляции.

Чтобы включить рекламу, вызовите метод videoAdvertisingOptions.update . В запросе укажите в параметре videoId id трансляции, полученный на шаге 1.1. Используйте свойство adFormats[] ресурса videoAdvertisingOption , чтобы указать форматы рекламы ( preroll , midroll или postroll ), которые нужно включить.

Этап 3: Тест

На этом этапе вы встраиваете плеер, который отображает потоковое видео вашей трансляции, чтобы вы могли протестировать качество просмотра. Потоковое видео — это приватный поток, позволяющий вам предварительно просматривать видео трансляции так, как оно будет выглядеть для зрителей YouTube.

Обратите внимание, что протестировать видеотрансляцию можно только при включённом потоке мониторинга. По умолчанию потоки мониторинга трансляций включены. Вы можете отключить поток мониторинга трансляции, установив свойство contentDetails.monitorStream.enableMonitorStream в значение false при создании или обновлении трансляции.

Шаг 3.1: Встраивание проигрывателя потокового видео

Получите вашу трансляцию с помощью метода liveBroadcasts.list и извлеките значение свойства contentDetails.streamDetails.monitorStreamEmbedHtml . Это значение содержит HTML-код, необходимый для встраивания проигрывателя YouTube, воспроизводящего вашу трансляцию.

Шаг 3.2: Начните видео

Начните трансляцию видео на вашем видеопотоке.

Шаг 3.3: Убедитесь, что ваш видеопоток активен

Вызовите метод liveStreams.list , чтобы получить ресурс liveStream , связанный с вашей трансляцией. Убедитесь, что свойство status.streamStatus имеет значение active , что означает, что серверы YouTube корректно получают данные от вашего видеокодера.

Шаг 3.4: Переведите свою трансляцию в статус тестирования

Вызовите метод liveBroadcasts.transition для обновления статуса трансляции. Присвойте параметру id значение идентификатора трансляции, полученное на шаге 1.1, а параметру broadcastStatus — значение testing .

После вызова метода liveBroadcasts.transition завершение перехода может занять несколько секунд или даже минуту. В течение этого времени следует опрашивать API, чтобы проверить статус трансляции. До завершения перехода статус трансляции будет testStarting . После завершения перехода статус будет testing .

Шаг 3.5: Завершение тестирования

Если тестирование прошло успешно, можно переходить к этапу 4. Однако в некоторых случаях может потребоваться дополнительное тестирование. Например, если в ходе тестирования выяснится, что видеопоток настроен неправильно, необходимо исправить это, прежде чем продолжить трансляцию.

Если видеопоток настроен неправильно, необходимо отвязать (и удалить) существующий поток и создать новый. Например, поток может быть настроен неправильно, если в нём указан неверный формат видео.

  1. Чтобы отвязать видеопоток, вызовите метод liveBroadcasts.bind из шага 1.3. В API-запросе укажите в качестве параметра id id , полученный на шаге 1.1. Параметр streamId в запросе не указывайте.

  2. Чтобы удалить видеопоток, вызовите метод liveStreams.delete . В запросе укажите в качестве параметра id id , полученный на шаге 1.2.

  3. Повторите шаг 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, а параметру broadcastStatus — значение live .

Если свойству contentDetails.enableAutoStart ресурса liveBroadcast присвоено значение true , то вызывать метод liveBroadcasts.transition не нужно.

После вызова этого API (или, если свойство contentDetails.enableAutoStart установлено в true , после начала трансляции) обычно требуется подождать 5–10 секунд для завершения перехода. Переход может занять до минуты. В течение этого времени следует опрашивать 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, а значение параметра broadcastStatus — complete .

Если бы вы установили свойства трансляции contentDetails.recordFromStart и contentDetails.enableDvr в true , то после окончания прямой трансляции ваша аудитория могла бы сразу же посмотреть воспроизведение прямой трансляции.

Этап 6: Создание ссылки

После завершения записи прямой трансляции вы можете создать ссылку на записанное видео. Это действие предписывает YouTube искать загруженные пользователями видео, соответствующие трансляции, и обрабатывать их в соответствии с политикой соответствия, установленной на шаге 2.3 .

Важно: чтобы создать ссылку, необходимо установить свойство contentDetails.recordFromStart трансляции в true .

Шаг 6.1: Опрос API данных на предмет статуса видео

YouTube должен завершить обработку трансляции или загруженного видео, прежде чем вы сможете создать ссылку на это видео. Чтобы определить, завершена ли обработка видео, опросите метод videos.list API данных YouTube, установив параметр part равным status , а параметр id — идентификатор трансляции, сохранённый на шаге 1.1 .

Ответ API на ваш запрос на опрос будет содержать video . После processed значения свойства status.uploadStatus этого ресурса перейдите к шагу 6.2.

Шаг 6.2: Создание референса из обработанного видео

Чтобы создать ссылку, вызовите метод references.insert API Content ID и задайте для параметра claimId идентификатор заявки, сохраненный на шаге 2.4 .

Доставка идентификатора контента в реальном времени

Некоторые партнёры YouTube могут создавать отпечатки до перехода трансляции в режим testing , но эта функция доступна не всем партнёрам. В этом случае YouTube генерирует и постоянно обновляет отпечатки из потока трансляции вашей прямой трансляции во время трансляции. Кроме того, YouTube ищет соответствующие видео, загруженные пользователями, во время трансляции. Обратите внимание, что создание отпечатков до начала трансляции автоматически включает запись трансляции, и её невозможно отключить после создания отпечатка.

Чтобы включить функцию Content ID для вашей трансляции в режиме реального времени, выполните действия, описанные в шаге 6.2, после подачи заявки на видео в шаге 2.4. Если ваша учётная запись партнёра не была одобрена для создания ссылки для прямой трансляции до её начала, API вернёт ошибку fingerprintingNotAllowed . В этом случае вам необходимо дождаться завершения трансляции, как описано в шагах 6.1 и 6.2 выше, прежде чем создавать ссылку.