Эта страница переведена с помощью Cloud Translation API.

Обзор API потокового вещания YouTube

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

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

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

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

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

Варианты использования API

В приведенном ниже списке предложено несколько способов использования API в вашем приложении:

Запланируйте трансляции и определите настройки трансляции. Ваше приложение может позволить пользователям заранее определять настройки трансляции, а затем выбирать настройки, которые будут применяться к конкретной трансляции.
Объединение видеопотоков и трансляций.
Позвольте вещателям одновременно определять информацию о трансляции и ее видео (с помощью API данных YouTube ).
Упростите переходы между состояниями трансляции (например, testing или live ) и дайте пользователям возможность вставлять ключевые точки.

Прежде чем ты начнешь

Вам понадобится учетная запись Google , чтобы получить доступ к Google API Console , запросить ключ API и зарегистрировать свое приложение.
Зарегистрируйте свое приложение в Google, чтобы оно могло отправлять запросы API.
После регистрации приложения выберите YouTube Data API в качестве одного из сервисов, которые использует ваше приложение:
1. Перейдите в API Console и выберите проект, который вы только что зарегистрировали.
2. Посетите страницу «Включенные API» . Убедитесь, что в списке API включен статус API данных YouTube v3 и, если вы являетесь контент-партнером YouTube, API Content ID YouTube.
Ознакомьтесь с основными понятиями формата данных нотации объектов JavaScript (JSON) . JSON — это распространенный, независимый от языка формат данных, который обеспечивает простое текстовое представление произвольных структур данных. Для получения дополнительной информации посетите json.org .

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

Как отмечалось выше, API прямой трансляции использует функции, которые технически являются частью либо API данных YouTube, либо API идентификации контента YouTube. Вы можете использовать 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` имеют один и тот же идентификатор. А после создания трансляции с помощью API прямой трансляции вы можете использовать API данных YouTube для предоставления дополнительных метаданных о видео.
`liveStream`	Содержит информацию о видеопотоке, который вы передаете на YouTube. Поток предоставляет контент, который будет транслироваться пользователям YouTube. После создания ресурс `liveStream` можно привязать ровно к одному ресурсу `liveBroadcast` . Аналогично, ресурс `liveBroadcast` может быть привязан только к одному ресурсу `liveStream` .
`cuepoint`	Вставляет точку разметки в транслируемый видеопоток, которая может вызвать рекламную паузу. Используйте метод `liveBroadcasts.cuepoint` , чтобы вставить ключевую точку во время трансляции.
`video`	Представляет одно видео YouTube. Как отмечалось выше, ресурс `liveBroadcast` является расширением `video` . Вы можете использовать API данных YouTube для обновления метаданных о видео, таких как место записи или регионы, в которых трансляция будет доступна для просмотра.
`videoAdvertisingOptions`	Определяет настройки рекламы для видео (или трансляции). Вы используете YouTube Content ID API для настройки параметров рекламы.
`asset`	Представляет собой часть интеллектуальной собственности, например фильм или эпизод шоу. В этом случае транслируемое видео является активом. Вы будете использовать YouTube Content ID API для создания ресурсов `asset` и управления ими.
`claim`	Связывает видео с ресурсом, которому соответствует видео. Вы создаете заявку с помощью YouTube Content ID API , чтобы идентифицировать себя как владельца транслируемого видео.
`policy`	Определяет правила, определяющие обстоятельства, при которых вы хотите, чтобы ваш контент был доступен для просмотра на YouTube или заблокирован от показа на 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
прямая трансляция
прямая трансляция

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

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

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

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

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

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

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

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

Установить смещения времени

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

Если ваш широковещательный поток не задерживается, вы можете вставить точку немедленно или использовать свойство 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 секунд или 60000 миллисекунд.
Δ=5000 – пятисекундный буфер, когда точку разметки невозможно надежно вставить.

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

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

Когда трансляция переходит из одного статуса в другой, ей может быть временно присвоен другой статус, пока YouTube выполнит действия, связанные с переходом. Например, если вы отправите запрос liveBroadcasts.transition на изменение статуса трансляции с ready на testing , YouTube установит статус трансляции на testStarting , а затем выполнит действия, связанные с изменением статуса. Когда все эти действия будут выполнены, YouTube обновит статус трансляции на testing , указывая тем самым, что переход завершен.
Если трансляция зависает в состоянии testStarting или liveStarting , вам необходимо вызвать метод liveBroadcasts.delete и удалить трансляцию. Затем создайте новую трансляцию, привяжите ее к прямой трансляции и продолжите процесс тестирования.
Как отмечено в документации метода liveBroadcasts.transition , перед вызовом этого метода необходимо подтвердить, что значение свойства status.streamStatus для потока, привязанного к вашей трансляции, active .