Se usó la API de Cloud Translation para traducir esta página.

Descripción general de la API de transmisión en directo de YouTube

La API de transmisión en directo de YouTube 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 consta de los 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 YouTube Content ID API permite interacciones con el sistema de administración de derechos de YouTube. Sin embargo, todos los recursos que conforman la API de Live Streaming solo se usan para crear y administrar eventos en vivo.

Este documento está dirigido a programadores que deseen crear aplicaciones para facilitar la transmisión en directo 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 API

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 las transmisiones (testing, live, etc.) y permite que los usuarios inserten puntos de inserción.

Antes de comenzar

Necesitas una Cuenta de Google para acceder a Google API Console, solicitar una clave de API y registrar tu aplicación.
Registra tu aplicación en Google para que pueda enviar solicitudes de API.
Después de registrar tu aplicación, selecciona YouTube Data API como uno de los servicios que usa:
1. Ve a API Console y selecciona el proyecto que acabas de registrar.
2. Visita la página de las API habilitadas. En la lista de las API, asegúrate de que el estado es ON para la API de datos de YouTube v3 y, si eres un socio de contenido de YouTube, la API de YouTube Content ID.
Aprende los conceptos básicos del formato de datos JSON (JavaScript Object Notation). 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 transmisión en directo API utiliza una funcionalidad que técnicamente es parte de la API de datos de YouTube o la API de Content ID de YouTube. Puedes usar la API de Content ID para proporcionar a YouTube metadatos, información de propiedad e información de políticas para tus elementos. (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 son diferentes de los requisitos para autorizar otras solicitudes de Live Streaming API.

Llamando a Data API: La solicitud de la API debe estar autorizada por la cuenta de Google propietaria del canal de YouTube que realiza la transmisión.
Llamando 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 los diferentes tipos de recursos con los que interactuarás mediante el Live Streaming API. Técnicamente, todos estos recursos se definen como parte de YouTube Data API o YouTube Content ID API. Sin embargo, los recursos liveBroadcast, liveStream y cuepoint solo se usan para crear y administrar eventos en vivo.

Recursos
`liveBroadcast`	Contiene información sobre un evento que transmites en YouTube. Un recurso `liveBroadcast` es una extensión de un recurso de video de YouTube y establece los metadatos de video que pertenezcan a una transmisión en vivo, 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 recurso `liveBroadcast` y el recurso `video` comparten el mismo ID. Y, después de crear la transmisión con la API de transmisión en vivo, puedes usar la API de datos de YouTube para proporcionar metadatos adicionales sobre el video.
`liveStream`	Contiene información sobre 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 un solo recurso `liveBroadcast`. (De forma similar, el recurso `liveBroadcast` solo se puede vincular a un recurso `liveStream`.
`cuepoint`	Inserta un punto de inserción en la transmisión continua de video, lo que puede activar una pausa publicitaria. Usa el método `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 recursos `asset`.
`claim`	Vincula un video a un elemento que corresponde a un video. Crea una solicitud usando 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:

Operations
`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 bien 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 de list admiten solicitudes tanto autorizadas como no autorizadas. Mientras que las solicitudes no autorizadas solo recuperan datos públicos, las solicitudes autorizadas también recuperan información restringida al usuario autenticado actual.

Operaciones admitidas
	list	insert	update	bind	transition	cuepoint	delete
transmisión en vivo
transmisión en vivo

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 recupera o muestra 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. Como tal, 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 Socio de contenido de YouTube y participar 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 explica las llamadas YouTube Content ID API que te permiten crear tu reclamo.

Obtén una vista previa y prueba tu contenido

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. YouTube permite publicar anuncios durante el video durante la transmisión.

Las pausas publicitarias tienen las siguientes características:

Tiene una duración predefinida, que se establece con la propiedad durationSecs del recurso cuepoint. Cuando finaliza la pausa publicitaria, los usuarios regresan a la transmisión en vivo.
Cuando se produce una pausa publicitaria, el anuncio solo se reproduce en el reproductor de video para los usuarios que miran la transmisión cuando se inserta el punto de inserción. Un anuncio no se publica cuando los espectadores actualizan la página en la que se reproduce la transmisión o cuando los visitantes comienzan a mirar la transmisión después de insertar el 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, puedes especificar que se inserte de inmediato o en un punto específico de la emisión. Las opciones dependen de si la transmisión continua de tu video está retrasada.

Si tu transmisión continua no se retrasa, puedes insertar el punto de referencia de inmediato o usar la propiedad 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 el recurso del cuerpo de la solicitud, establece el valor de la propiedad insertionOffsetTimeMs en 0 o no especifiques un valor para esa propiedad ni especifiques un valor para la propiedad walltimeMs.
  
  Importante: Ten en cuenta que los espectadores no ven el contenido del anuncio resultante de inmediato. Es posible que haya una demora de alrededor de 30 segundos antes de que los usuarios puedan ver el contenido del anuncio. Durante ese retraso, los espectadores pueden seguir viendo la transmisión continua y debes mirarla para determinar cuándo se mostrará el contenido del anuncio en lugar de la transmisión continua de monitor.
- Para iniciar la pausa publicitaria en un momento determinado, llama al método liveBroadcasts.cuepoint y usa la propiedad 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 tu transmisión continua está retrasada, puedes insertar el punto de referencia de inmediato, como se describió anteriormente, indicar una hora 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 la emisión en el que los espectadores deben ver un anuncio.

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

Cuando insertes un punto de referencia, establece la propiedad insertionOffsetTimeMs del recurso cuepoint en la compensación deseada.

Calcular el valor de compensación horaria

Para recuperar el valor de compensación, invoca la función getCurrentTime de la API del reproductor de YouTube para el reproductor que está reproduciendo 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 cuando YouTube no puede insertar con precisión un punto de inserció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.
La emisora está insertando el punto de referencia cuatro minutos después de que la transmisión cambia al estado live. (O sea, tres minutos después de que la transmisión continua se hace visible).

En este caso, el intervalo posible de compensación horaria 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 supervisión 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: el búfer de cinco segundos cuando el punto de inserción no se puede insertar de forma confiable.

Solucionar problemas y controlar errores

En las siguientes pautas se explica cómo resolver posibles problemas específicos. También puedes consultar la documentación sobre errores para obtener una lista de errores que cada método de la API pueda mostrar.

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 establece el estado de la transmisión en testStarting y, luego, completa las acciones asociadas con el cambio de estado. Cuando se completan todas estas acciones, YouTube actualiza el estado de la transmisión a testing, lo que indica que la transición está completa.

Si una transmisión queda atascada con el estado testStarting o liveStarting, debes llamar al método liveBroadcasts.delete y borrarla. 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 es active antes de llamar a ese método.