Descripción general de la API de YouTube Live Streaming

La API de YouTube Live Streaming te permite crear, actualizar y administrar eventos en vivo en YouTube. A través de la API, puedes programar eventos (transmisiones) y asociarlos con transmisiones de video por Internet, los que representan el contenido de la transmisión en sí.

La API de transmisión en directo está compuesta, en realidad, de componentes de la API de datos de YouTube y de la API de Content ID de YouTube. La API de datos permite a los usuarios de YouTube administrar sus cuentas de YouTube, mientras que la YouTube Content ID API permite la interacción con el sistema de administración de derechos de YouTube. Sin embargo, todos los recursos que conforman la API de Live Streaming se utilizan solo para crear y administrar eventos en vivo.

Este documento está dirigido a desarrolladores que deseen crear aplicaciones para facilitar la transmisión en vivo en YouTube. En él se explican conceptos básicos de YouTube y de la API. También proporciona una visión general de las diferentes funciones que admite la API.

Conceptos básicos

transmisiones

Una transmisión representa un evento que se puede mirar en YouTube a medida que ocurre. Las transmisiones también pueden grabarse y guardarse como videos de YouTube, de modo que los usuarios puedan verlas después de que hayan ocurrido.

arroyos

Una transmisión identifica el contenido de audio y video que se comunica a YouTube. Cada transmisión se asocia a una transmisión de video por Internet.

puntos de inserción

Un punto de inserción representa una pausa publicitaria que se puede insertar en una transmisión en vivo.

Casos de uso de APIs

En la siguiente lista se sugieren varias formas de usar la API en tu aplicación:

• Para programar transmisiones y definir la configuración de las transmisiones. Tu aplicación podría permitirle a los usuarios predefinir la configuración de transmisión y, luego, seleccionar la configuración para aplicarla a una transmisión en particular.

• Para asociar transmisiones y transmisiones de video por Internet.

• Permite que las emisoras definan información sobre una transmisión y su video (mediante la API de datos de YouTube) al mismo tiempo.

• Simplifica las transiciones entre estados de transmisión (por ejemplo, testing o live) y permite que los usuarios inserten puntos de inserción.

Antes de comenzar

1. Necesitas una Cuenta de Google para acceder a Google API Console, solicitar una clave de API y registrar tu aplicación.

2. Registra tu aplicación en Google para que pueda enviar solicitudes de API.

3. Después de registrar tu aplicación, selecciona YouTube Data API como uno de los servicios que usa tu aplicación:

   1. Ve a API Console y selecciona el proyecto que acabas de registrar.
   2. Visita la página de APIs habilitadas. En la lista de las APIs, asegúrate de que el estado esté ACTIVADO para la versión 3 de la API de YouTube Data y, si eres un socio de contenido de YouTube, para la API de Content ID de YouTube.

4. Aprende los conceptos básicos del formato de datos JavaScript Object Notation (JSON). JSON es un formato de datos común e independiente del lenguaje que proporciona una representación de texto simple de estructuras de datos arbitrarias. Para obtener más información, visita json.org.

Autoriza solicitudes a la API

Como se mencionó anteriormente, la API de transmisión en vivo utiliza una funcionalidad técnicamente parte de la API de datos de YouTube o de la API de Content ID de YouTube. Puedes usar la API de Content ID para proporcionarle a YouTube metadatos, información sobre la propiedad y políticas de tus activos. (Un ejemplo de un elemento es una transmisión de video en directo). La API también te permite reclamar videos y configurar las políticas de anuncios de tus videos.

En esta sección, se explican los requisitos de autorización para las solicitudes a Content ID API, que difieren de los requisitos para autorizar otras solicitudes de Live Streaming API.

Cómo llamar a Data API

La solicitud a la API debe estar autorizada por la Cuenta de Google propietaria del canal de YouTube que realiza la transmisión.

Cómo llamar a Content ID API

La solicitud a la API debe estar autorizada por una Cuenta de Google que esté vinculada al propietario del contenido que posee el canal de YouTube que realiza la transmisión.

Recursos y tipos de recursos

Un recurso es una entidad de datos individual con un identificador único. En la siguiente tabla, se describen las y los diferentes tipos de recursos con los que interactuarás Live Streaming API. Técnicamente, todos estos recursos están se define como parte de YouTube Data API o YouTube Content ID API. Sin embargo, el liveBroadcast, liveStream y cuepoint recursos tienen las siguientes características: solo se usan para crear y administrar eventos en vivo.

Recursos
liveBroadcast	Contiene información sobre un evento que se está transmitiendo en YouTube. R El recurso liveBroadcast es una extensión de un recurso de video de YouTube y establece el contenido metadatos que serían pertinentes a una transmisión en directo, pero no a otros videos de YouTube. Por lo tanto, un recurso liveBroadcast corresponde exactamente a un recurso de video de YouTube. De hecho, el liveBroadcast y el recurso video comparten la con el mismo ID. Después de crear la transmisión con la API de Live Streaming, puedes usar la La API de datos de YouTube para proporcionar metadatos adicionales acerca del video.
liveStream	Contiene información acerca de la transmisión de video por Internet que estás transmitiendo a YouTube. La transmisión proporciona el contenido que se transmitirá a los usuarios de YouTube. Una vez creado, un recurso liveStream se puede vincular a exactamente un recurso liveBroadcast. (Del mismo modo, el recurso liveBroadcast solo puede vincularse a un recurso liveStream.
cuepoint	Inserta un punto de inserción en la transmisión de video por Internet de la transmisión, lo que podría activar una pausa publicitaria. Usa el liveBroadcasts.cuepoint para insertar un punto de referencia durante una transmisión.
video	Representa un video de YouTube en particular. Como se indicó anteriormente, un recurso liveBroadcast es una extensión de un recurso video. Puedes usar la API de datos de YouTube para actualizar los metadatos sobre el video, tales como el lugar de grabación o las regiones donde será posible ver la transmisión.
videoAdvertisingOptions	Define la configuración de publicidad de un video (o transmisión). Usa YouTube Content ID API para configurar las opciones de publicidad.
asset	Representa una propiedad intelectual, como una película o un episodio de un programa de televisión. En este caso, el elemento es el video de la transmisión. Usarás YouTube Content ID API para crear y administrar los recursos asset.
claim	Vincula un video a un elemento que corresponde a un video. Para crear un reclamo, debes usar el YouTube Content ID API para identificarte como el propietario del video de la transmisión.
policy	Define las reglas que especifican las circunstancias en las que quieres que tu contenido pueda ser visto en YouTube o bloqueado de YouTube. Debes aplicar una política al video de tu transmisión y puedes especificar la política que YouTube aplicará a los videos subidos por los usuarios que coincidan con los videos de tu transmisión.

Operaciones admitidas

En la tabla a continuación se muestran los diferentes métodos que admite la API:

Operaciones
list	Recupera (GET) una lista de cero o más recursos.
insert	Crea (POST) un nuevo recurso.
update	Modifica (PUT) un recurso existente para reflejar los datos de tu solicitud.
bind	Vincula un recurso liveBroadcast con un recurso liveStream o quita el vínculo.
transition	Cambia el estado de un recurso liveBroadcast e inicia cualquier proceso asociado con el estado nuevo. Por ejemplo, cuando cambias el estado de una transmisión a testing, YouTube comienza a transmitir video a la transmisión continua de monitor de esa transmisión.
delete	Elimina (DELETE) un recurso específico.

En la siguiente tabla se identifican las operaciones admitidas para los diferentes tipos de recursos. Las operaciones para insertar, actualizar o eliminar recursos siempre requieren la autorización del usuario. En algunos casos, los métodos list admiten solicitudes tanto autorizadas como no autorizadas, en las que las solicitudes no autorizadas solo recuperan datos públicos, mientras que las solicitudes autorizadas también pueden recuperar información restringida al usuario autenticado actualmente.

Operaciones admitidas
	list	insert	update	bind	transition	cuepoint	delete
liveBroadcast
liveStream

Recursos parciales

La API permite, y requiere, la recuperación de recursos parciales para que las aplicaciones eviten la transferencia, el análisis y el almacenamiento de datos que no son necesarios. Este enfoque también garantiza que la API utilice los recursos de red, CPU y memoria con mayor eficiencia.

El parámetro part es obligatorio para cualquier solicitud a la API que recupere o muestre un recurso YouTube Data API. El parámetro identifica una o más propiedades de recursos de nivel superior (no anidada) que se deben incluir en una respuesta de la API. Por ejemplo, un recurso liveStream tiene las siguientes partes:

• snippet
• cdn
• status

Todas estas partes son objetos que contienen propiedades anidadas. Puedes considerar estos objetos como grupos de campos de metadatos que el servidor de la API podría (o no) recuperar. Por lo tanto, el parámetro part requiere que selecciones los componentes de recursos que tu aplicación usa realmente. Este requisito tiene dos propósitos importantes:

• Reducir la latencia evitando que el servidor de la API se dedique a recuperar campos de metadatos que tu aplicación no utiliza.
• Reducir el uso de ancho de banda al reducir (o eliminar) la cantidad de datos innecesarios que la aplicación podría recuperar.

Con el tiempo, a medida que los recursos agregan más partes, estos beneficios irán en aumento debido a que tu aplicación no solicitará las propiedades nuevas que no admita.

Sugerencias y prácticas recomendadas

Reclamar contenido

Si quieres mostrar anuncios durante una transmisión, debes reclamar el video de la transmisión antes de que comience el evento. Para reclamar contenido, debes ser un Socio de contenido de YouTube que participe en el programa Content ID.

El proceso para reclamar el video de tu transmisión en directo es diferente del proceso normal para reclamar un video. Para reclamar un video en directo, debes crear el reclamo con anterioridad a su transmisión. La API admite esto. En el documento Ciclo de una transmisión, se explican las llamadas YouTube Content ID API que te permiten crear una reclamación.

Obtén una vista previa de tu contenido y pruébalo

Tras recibir tu transmisión de video por Internet de entrada, YouTube puede transmitir el video en dos transmisiones continuas de salida diferentes:

• La transmisión continua de monitor te permite obtener una vista previa y probar la transmisión del video. Es una transmisión privada a la que solo tú tienes acceso. Solo puedes hacer la transición de una transmisión a la fase testing si la transmisión continua de monitor está habilitada. La transmisión continua de monitor no muestra pausas de anuncios.

• La transmisión continua es la transmisión visible a la audiencia. Puedes establecer el estado de privacidad de la transmisión en public, private o unlisted. (Una transmisión privada solo es visible para los usuarios que hayan sido explícitamente invitados a verla, mientras que una transmisión sin listar es visible para cualquier usuario que tenga el vínculo para verla).

  Puedes optar por retrasar la transmisión continua para que no se reproduzca al mismo tiempo que la transmisión continua de monitor. Al retrasar la transmisión, puedes tener un control más preciso a la hora de agregar puntos de inserción en la transmisión.

  Sin embargo, retrasar la transmisión dificulta la interacción entre tus presentadores en directo y tu audiencia. Además, retrasar la transmisión aumenta la posibilidad de que los espectadores descubran detalles clave acerca de los eventos en otras fuentes ajenas a tu transmisión. Por ejemplo, si estás transmitiendo un evento deportivo con un retraso de 60 segundos, los espectadores pueden obtener información sobre los momentos clave del evento en otras fuentes de noticias en tiempo real antes de verlos en tu transmisión.

YouTube recomienda que pruebes tu contenido habilitando la transmisión continua de monitor. Debes elegir si quieres retrasar tu transmisión en función de estos criterios: ¿prefieres mantener el control de los puntos de inserción o consideras más importante poder interaccionar con tu audiencia o cubrir un evento en tiempo real?

Cómo publicar anuncios durante el video durante una transmisión

Durante una transmisión, puedes insertar un punto de inserción para indicar que una pausa publicitaria debe comenzar en la transmisión lo antes posible o en un momento específico. La pausa publicitaria permite que YouTube publique anuncios durante el video durante la transmisión.

Las pausas publicitarias tienen las siguientes características:

1. Tiene un período predefinido, que se establece usando el valor delcuepoint durationSecs propiedad. Cuando termina la pausa publicitaria, los usuarios regresan a la transmisión en vivo.

2. Cuando se produce una pausa publicitaria, este solo se reproduce en el reproductor de video de los usuarios que están mirando la transmisión. la transmisión cuando se inserta el punto de inserción. No se publica un anuncio cuando los usuarios actualizan la página. dónde se está reproduciendo la transmisión o cuando los visitantes comienzan a verla después de punto de inserción.

La secuencia de pasos a continuación describe la forma recomendada de insertar una pausa de anuncios durante tu transmisión:

Establecer compensaciones horarias

Al insertar un punto de inserción, puede especificar que se debe insertar de inmediato o que se debe insertar en un punto específico de la transmisión. Tus opciones dependen de si la transmisión continua de tu video está retrasada.

• Si la transmisión no se retrasa, puedes insertar el punto de inserción inmediatamente o usar walltimeMs para que la pausa publicitaria comience en un momento determinado.

  • Para iniciar la pausa publicitaria de inmediato, llama al método liveBroadcasts.cuepoint. En la en el cuerpo de la solicitud, establece el insertionOffsetTimeMs propiedad valor como 0 o no especifiques un valor para esa propiedad ni especifiques un valor para walltimeMs propiedad.

    Importante: Tenga en cuenta que los usuarios no ven el anuncio resultante. contenido de inmediato. Puede haber un retraso de 30 segundos para que el contenido del anuncio visibles para los usuarios. Durante ese tiempo, la transmisión continua será visible para tu usuarios y debes mirar la transmisión continua de la transmisión para determinar cuándo se muestra en lugar de la transmisión de monitor.

  • Para iniciar la pausa publicitaria en un momento determinado, llama al liveBroadcasts.cuepoint. y utiliza el walltimeMs para especificar la hora deseada. El valor de la propiedad es un número entero que representa una marca de tiempo de época.

• Si la transmisión se retrasa, puedes insertar el punto de inserción inmediatamente como como se describió anteriormente, especifica una hora del reloj como se describió anteriormente, o puedes especificar una compensación horaria para determinar cuándo comenzará la pausa publicitaria. La compensación horaria especifica un punto en tu transmisión cuándo los usuarios deberían ver un anuncio.

  El valor de desplazamiento se mide en milisegundos desde el comienzo de la transmisión de supervisión por tu transmisión. Ten en cuenta que si tu transmisión tiene una fase de prueba, la transmisión continua de monitor comienza cuando tu transmisión pasa al estado testing. De lo contrario, el La transmisión continua de monitor comienza cuando tu transmisión pasa al estado live.

  Cuando insertes un punto de inserción, establece el campo cuepoint del recurso insertionOffsetTimeMs propiedad con el desplazamiento deseado.

Calcular el valor de compensación horaria

Para recuperar el valor de desplazamiento, invoca la función getCurrentTime de la API del reproductor de YouTube para el reproductor que reproduce la transmisión continua de monitor. Usa el valor recuperado para insertar el punto de referencia en la transmisión continua en ese momento.

Los posibles valores de la compensación horaria pueden calcularse acudiendo al siguiente intervalo:

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

Δ es un búfer de cinco segundos al comienzo y al final de las compensaciones horarias posibles cuando YouTube no puede insertar un punto de inserción con precisión. Por ejemplo:

• Una transmisión tiene una fase de prueba de cinco-segundos.
• La transmisión continua tiene un retraso de 60 segundos después de la transmisión continua de monitor.
• Quien transmite inserta el punto de referencia cuatro minutos después de que la transmisión pasa a Estado de live. (O sea, tres minutos después de que la transmisión continua se hace visible).

En este caso, el rango posible de tiempos de compensación es [(485,000), (535,000)].

Estos tiempos se especifican en milisegundos y se calculan utilizando los siguientes valores:

• elapsed_time=540000: la transmisión de monitor se ejecutó durante nueve minutos (540 segundos, 540,000 milisegundos) cuando se llama al método liveBroadcasts.cuepoint.
• broadcast_delay=60000: la transmisión continua tiene un retraso de 60 segundos o 60, 000 milisegundos.
• Δ=5000: Es el búfer de cinco segundos cuando el punto de inserción no se puede insertar de manera confiable.

Solucionar problemas y controlar errores

En las siguientes pautas se explica cómo resolver posibles problemas específicos. Para las listas de errores que puede mostrar cada método de la API, consulta API de YouTube Live Streaming - Errores.

• Cuando la transmisión cambia de un estado a otro, puede ser asignado temporalmente a otro estado mientras YouTube completa las acciones asociadas a la transición. Por ejemplo, si envías una solicitud liveBroadcasts.transition para cambiar el estado de una transmisión de ready a testing, YouTube establecerá el estado de la transmisión en testStarting y, luego, completará las acciones asociadas con el cambio de estado. Cuando se completen todas estas acciones, YouTube actualizará el estado de la transmisión a testing, lo que indicará que se completó la transición.

  Si una transmisión se queda atascada con un estado testStarting o liveStarting, debes llamar al método liveBroadcasts.delete y borrar la transmisión. A continuación, crea una nueva transmisión, vincúlala a tu transmisión continua en directo y continúa con el proceso de prueba.

  Como se indica en la documentación del método liveBroadcasts.transition, debes confirmar que el valor de la propiedad status.streamStatus para la transmisión vinculada a tu transmisión sea active antes de llamar a ese método.