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

Введение

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

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

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

Ресурсы YouTube Live Streaming API

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

Ресурсы YouTube Content ID API

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

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

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

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

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

Вызовите метод liveBroadcasts.insert , чтобы добавить свою трансляцию в расписание прямых трансляций YouTube. Ресурс 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 Content ID YouTube .

Шаг 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 . Когда значение свойства status.uploadStatus этого ресурса будет processed , перейдите к шагу 6.2.

Шаг 6.2: Создайте ссылку из обработанного видео

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

Доставка Live Content ID

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

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