Жизненный цикл трансляции

Введение

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

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

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

Ресурсы YouTube Live Streaming API

Ресурсы YouTube Data API

Ресурсы 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.availabilityConfig. Это свойство позволяет заблокировать определенные регионы или ограничить доступность определенным списком регионов. Вы также можете указать временные интервалы для региональной доступности.

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

  • Вы можете изменить любое из 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](

    /youtube/data/live/reference/rest/v3/liveStreams#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, описанные в этом разделе, определены в YouTube Content ID API.

Шаг 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. Чтобы указать, какие форматы объявлений (preroll, midroll или postroll) вы хотите включить, используйте свойство adFormats[] ресурса videoAdvertisingOption.

Этап 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. Измените статус трансляции на "Завершена"

Когда вы будете готовы завершить трансляцию, вызовите метод liveBroadcasts.transition, чтобы изменить ее статус. Задайте для параметра id значение идентификатора трансляции, полученного на шаге 1.1, а для параметра broadcastStatus – значение complete.

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

Шаг 6. Создайте цифровой отпечаток

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

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

Шаг 6.1. Запросите статус видео через Data API

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

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

Шаг 6.2. Создайте цифровой отпечаток на основе обработанного видео

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

Загрузка отпечатков в систему Content ID

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

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