Общие сведения о YouTube Live Streaming API

YouTube Live Streaming API позволяет создавать прямые трансляции на YouTube, управлять ими и обновлять данные о них. С его помощью вы можете запланировать трансляцию и связать ее с видеопотоком.

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

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

Основные понятия

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

Примеры использования API

Ниже приведены некоторые способы использования API в приложении.

  • Планируйте трансляции и задавайте их настройки. В приложении можно задать настройки трансляции, а затем выбрать, какие из них применить к определенной трансляции.

  • Связывание видеопотоков и трансляций.

  • Позволяет вещателям одновременно задавать информацию о трансляции и ее видео (с помощью YouTube Data API).

  • Упростите переходы между состояниями трансляции (например, testing или live) и разрешите пользователям вставлять временные метки.

Подготовка

  1. Чтобы получить доступ к Google Cloud console, запросить ключ API и зарегистрировать приложение, вам потребуется аккаунт Google.

  2. Зарегистрируйте свое приложение в Google, чтобы можно было отправлять запросы на сервер API.

  3. После регистрации приложения выберите YouTube Data API в качестве одного из сервисов, которые использует ваше приложение:

    1. Перейдите в Cloud console и выберите проект, который вы только что зарегистрировали.
    2. Откройте страницу включенных API. Убедитесь, что в списке API для YouTube Data API v3 установлен статус ВКЛ. Если вы являетесь партнером YouTube по контенту, то же самое должно быть сделано для YouTube Content ID API.

  4. Ознакомьтесь с основными концепциями формата данных JavaScript Object Notation (JSON). JSON – это общедоступный формат данных, совместимый со всеми языками и позволяющий получать данные любой структуры в простом текстовом представлении. Более подробную информацию вы найдете на сайте json.org.

Авторизация запросов к API

Как отмечалось выше, Live Streaming API использует функции, которые технически являются частью YouTube Data API или YouTube Content ID API. С помощью Content ID API вы можете передавать YouTube метаданные, информацию о правах собственности и правилах в отношении ваших объектов. (Пример объекта – прямая видеотрансляция.) Кроме того, с помощью API можно заявлять права на видео и задавать правила размещения рекламы в них.

В этом разделе объясняются требования к авторизации запросов к Content ID API, которые отличаются от требований к авторизации других запросов Live Streaming API.

Звонок в Data API
Запрос к API должен быть авторизован аккаунтом Google, которому принадлежит канал YouTube, где проводится трансляция.
Звонок в Content ID API
Запрос к API должен быть авторизован аккаунтом Google, связанным с владельцем контента, которому принадлежит канал YouTube, где проводится трансляция.

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

Ресурс – это отдельный объект данных с уникальным идентификатором. В таблице ниже описаны различные типы ресурсов, с которыми вы будете взаимодействовать при использовании Live Streaming API. Технически все эти ресурсы определены как часть YouTube Data API или YouTube Content ID API. Однако ресурсы liveBroadcast, liveStream и cuepoint используются только для создания прямых трансляций и управления ими.

Ресурсы
liveBroadcast Содержит информацию о трансляции на YouTube. Ресурс liveBroadcast – это расширение ресурса видео YouTube, в котором задаются метаданные, относящиеся к прямой трансляции, но не к другим видео на YouTube.

Таким образом, ресурс liveBroadcast соответствует ровно одному ресурсу видео YouTube. Ресурсы liveBroadcast и video имеют один и тот же идентификатор. После того как вы создадите трансляцию с помощью Live Streaming API, вы можете использовать YouTube Data API, чтобы добавить к видео дополнительные метаданные.
liveStream Содержит информацию о видеопотоке, который вы передаете на YouTube. Трансляция содержит контент, который будет показан пользователям YouTube. После создания ресурс liveStream можно связать только с одним ресурсом liveBroadcast. Аналогично, ресурс liveBroadcast может быть связан только с одним ресурсом liveStream.
cuepoint Вставляет в видеопоток временную метку, которая может запустить рекламную паузу. Чтобы вставить точку перехода во время трансляции, используйте метод liveBroadcasts.cuepoint.
video Представляет одно видео YouTube. Как уже упоминалось, ресурс liveBroadcast является расширением ресурса video. С помощью YouTube Data API можно изменять метаданные видео, например место съемки или регионы, в которых будет доступна трансляция.
videoAdvertisingOptions Определяет настройки рекламы для видео или трансляции. Для настройки параметров рекламы используется YouTube Content ID API.
asset Объект интеллектуальной собственности, например фильм или серия сериала. В этом случае объектом является транслируемое видео. Вы будете использовать YouTube Content ID API для создания ресурсов asset и управления ими.
claim Связывает видео с объектом, которому оно соответствует. Вы создаете заявку, используя YouTube Content ID API, чтобы идентифицировать себя как владельца транслируемого видео.
policy Определяет правила, которые указывают, при каких обстоятельствах ваш контент должен быть доступен для просмотра на YouTube или заблокирован. Вам нужно применить политику к трансляции, а также можно указать политику, которую YouTube будет применять к пользовательским видео, совпадающим с вашей трансляцией.

Поддерживаемые операции

В таблице ниже перечислены поддерживаемые API методы.

Операции
list Получает (GET) список ресурсов (от нуля и более).
insert Создает (POST) новый ресурс.
update Изменяет (PUT) существующий ресурс, чтобы отразить данные в запросе.
bind Связывает ресурс liveBroadcast с ресурсом liveStream или удаляет такую связь.
transition Изменяет статус ресурса liveBroadcast и запускает все процессы, связанные с новым статусом. Например, когда вы меняете статус трансляции на testing, YouTube начинает передавать видео в контрольный поток этой трансляции.
delete Удаляет (DELETE) определенный ресурс.

В таблице ниже перечислены операции, поддерживаемые для разных типов ресурсов. Операции, которые вставляют, обновляют или удаляют ресурсы, всегда требуют авторизации пользователя. В некоторых случаях методы list поддерживают как авторизованные, так и неавторизованные запросы. При этом неавторизованные запросы позволяют получить только общедоступные данные, а авторизованные – также информацию, доступную только аутентифицированному пользователю.

Поддерживаемые операции
list insert update bind transition cuepoint delete
liveBroadcast
liveStream

Частичные ресурсы

API позволяет и даже требует извлекать частичные ресурсы, чтобы приложения не передавали, не анализировали и не хранили ненужные данные. Такой подход также позволяет API более эффективно использовать ресурсы сети, ЦП и памяти.

Параметр part является обязательным для любого запроса к API, который получает или возвращает ресурс YouTube Data API. Этот параметр определяет одно или несколько свойств ресурса верхнего уровня (не вложенных), которые должны быть включены в ответ API. Например, ресурс liveStream состоит из следующих частей:

  • snippet
  • cdn
  • status

Все эти части представляют собой объекты, содержащие вложенные свойства. Их можно рассматривать как группы полей метаданных, которые сервер API может извлекать. Поэтому в параметре part нужно выбрать компоненты ресурса, которые действительно используются в приложении. Это требование необходимо по двум причинам:

  • Это позволяет снизить задержку, так как серверу API не нужно тратить время на получение полей метаданных, которые не используются в вашем приложении.
  • Это позволяет снизить нагрузку на сеть за счет уменьшения или полного исключения ненужных данных, которые может получать приложение.

Со временем, когда в ресурсах будет появляться больше частей, эти преимущества будут только расти, поскольку ваше приложение не будет запрашивать новые свойства, которые оно не поддерживает.

Советы и рекомендации

Заявите права на контент

Если вы хотите показывать рекламу во время трансляции, вам нужно заявить права на видео до начала мероприятия. Заявлять права на контент могут только партнеры YouTube по контенту, участвующие в программе Content ID.

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

Как посмотреть и протестировать контент

Получив входящий видеопоток, YouTube может транслировать его в двух разных исходящих потоках:

  • Мониторинговый стрим позволяет просматривать и тестировать видео перед трансляцией. Это частная трансляция, доступная только вам. Перевести трансляцию в фазу testing можно только в том случае, если включен поток мониторинга трансляции. В контрольном потоке не показываются рекламные паузы.

  • Трансляция – это стрим, который видят зрители. Вы можете выбрать для трансляции статус доступа public, private или unlisted. (Трансляции с ограниченным доступом видны только тем, кого вы пригласили, а трансляции с доступом по ссылке – всем, у кого есть ссылка.)

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

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

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

показ рекламы в середине трансляции;

Во время трансляции вы можете вставить cuepoint, чтобы указать, что рекламная пауза должна начаться как можно скорее или в определенное время. Рекламная пауза позволяет YouTube показывать рекламу в середине трансляции.

Рекламные паузы имеют следующие характеристики:

  1. Она имеет заданную продолжительность, которую вы указываете в свойстве durationSecs ресурса cuepoint. После окончания рекламной паузы зрители возвращаются к просмотру трансляции.

  2. Когда начинается рекламная пауза, объявление показывается только в видеопроигрывателе для зрителей, которые смотрят трансляцию в момент вставки точки перехода. Объявление не показывается, когда зрители обновляют страницу, на которой идет трансляция, или начинают смотреть трансляцию после того, как была вставлена временная метка.

Вот как лучше всего вставлять рекламные паузы в трансляции:

Как задать смещение по времени

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

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

    • Чтобы немедленно начать рекламную паузу, вызовите метод liveBroadcasts.cuepoint. В ресурсе в теле запроса задайте для свойства insertionOffsetTimeMs значение 0 или не указывайте значение для этого свойства и не указывайте значение для свойства walltimeMs.

      Важно! Зрители не сразу видят контент, который вы добавили в рекламу. Контент объявления может стать виден пользователям с задержкой около 30 секунд. В течение этой задержки ваша трансляция по-прежнему будет видна зрителям, и вам нужно следить за трансляцией, чтобы определить, когда вместо потока с вашего монитора отобразится содержание объявления.

    • Чтобы рекламная пауза начиналась в определенное время, вызовите метод liveBroadcasts.cuepoint и укажите нужное время в свойстве walltimeMs. Значение свойства – целое число, представляющее временную метку эпохи.

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

    Значение смещения измеряется в миллисекундах с начала контрольного потока трансляции. Если у трансляции есть этап тестирования, то монитор трансляции начинается, когда трансляция переходит в статус testing. В противном случае трансляция с монитора начнется, когда трансляция получит статус live.

    При вставке точки перехода задайте для свойства insertionOffsetTimeMs ресурса cuepoint нужное смещение.

Как рассчитать значение смещения по времени

Чтобы получить значение смещения, вызовите функцию getCurrentTime API проигрывателя YouTube для проигрывателя, который воспроизводит поток мониторинга. Используйте полученное значение, чтобы вставить временную метку в трансляцию.

Возможные значения для времени смещения можно рассчитать как следующий диапазон:

[(elapsed_time - broadcast_delay + Δ), (elapsed_time - Δ)]

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

  • У трансляции есть пятиминутный этап тестирования.
  • Трансляция отстает от контрольного потока на 60 секунд.
  • Вещатель вставляет маркер через четыре минуты после того, как трансляция переходит в статус live. (через три минуты после того, как трансляция станет видна).

В этом случае возможный диапазон времени смещения – [(485,000), (535,000)].

Время указывается в миллисекундах и рассчитывается на основе следующих значений:

  • elapsed_time=540000 – поток монитора работает девять минут (540 секунд, 540 000 миллисекунд) на момент вызова метода liveBroadcasts.cuepoint.
  • broadcast_delay=60000 – трансляция задерживается на 60 секунд или 60 000 миллисекунд.
  • Δ=5000 – пятисекундный буфер, когда временную метку нельзя вставить с достаточной надежностью.

Устранение неполадок и обработка ошибок

Ниже приведены инструкции по устранению некоторых проблем. Список ошибок, которые могут возвращать методы API, приведен в статье YouTube Live Streaming API – ошибки.

  • Когда трансляция переходит из одного статуса в другой, ей может быть временно присвоен другой статус, пока YouTube выполняет действия, связанные с переходом. Например, если вы отправите запрос liveBroadcasts.transition, чтобы изменить статус трансляции с ready на testing, YouTube установит статус testStarting, а затем выполнит действия, связанные с изменением статуса. Когда все эти действия будут выполнены, YouTube изменит статус трансляции на testing.

    Если трансляция зависла со статусом testStarting или liveStarting, вам нужно вызвать метод liveBroadcasts.delete и удалить трансляцию. Затем создайте новую трансляцию, свяжите ее со стримом и продолжите тестирование.

    Как указано в документации к методу liveBroadcasts.transition, перед его вызовом необходимо убедиться, что свойство status.streamStatus для потока, связанного с трансляцией, имеет значение active.