Descripción general de la API de YouTube Live Streaming

La API de transmisión en vivo 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 está compuesta en realidad por los componentes de la API de datos de YouTube y 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 habilita interacciones con el sistema de administración de derechos de YouTube. Sin embargo, todos los recursos que componen la API de transmisión en directo se utilizan solamente 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 la 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 transmisión (testing, live, etc.) 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 el 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 APIs habilitadas. En la lista de las API, asegúrate de que el estado esté ACTIVADO para la versión 3 de la API de datos de YouTube 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 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 señaló anteriormente, la API de transmisión en directo 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 sobre políticas para 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 son diferentes de los requisitos para autorizar otras solicitudes de Live Streaming API.

Llamando al 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.
Llamando al 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 Live Streaming API. Técnicamente, todos estos recursos en realidad 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 estás transmitiendo en YouTube. Un recurso liveBroadcast es una extensión de un recurso de video de YouTube y define metadatos de video que son pertinentes para una transmisión en vivo, pero no para otros videos de YouTube.

Por lo tanto, un recurso liveBroadcast corresponde a exactamente un recurso de video de YouTube. De hecho, los recursos liveBroadcast y video comparten el mismo ID. 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 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, que podría activar una pausa publicitaria. Usa el método liveBroadcasts.cuepoint para insertar un punto de inserción 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). Usas 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 de asset.
claim Vincula un video a un elemento que corresponde a un video. Puedes crear un reclamo con 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 estos casos, las solicitudes no autorizadas solo recuperan datos públicos, mientras que las solicitudes autorizadas también recuperan información que está 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 Socio de contenido de YouTube que forme parte del 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 sobre la vida de una transmisión, se explican 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?

Publicación de anuncios durante el video durante una transmisión

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

Las pausas publicitarias tienen las siguientes características:

  1. Tiene un período predefinido, que se establece con la propiedad durationSecs del recurso cuepoint. Cuando termina la pausa publicitaria, los usuarios regresan a la transmisión en vivo.

  2. Cuando se produce una pausa publicitaria, solo se reproduce un anuncio en el reproductor de video para los usuarios que están mirando la transmisión cuando se inserta el punto de inserción. No se publica un anuncio cuando los espectadores actualizan la página en la que se está reproduciendo 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

Cuando insertas un punto de inserción, puedes especificar que se inserte de inmediato o en un punto específico de la transmisión. Las opciones dependen de si la transmisión continua de tu video está retrasada.

  • Si tu transmisión no se retrasa, puedes insertar el punto de inserción 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 usuarios no ven el contenido del anuncio resultante de inmediato. Puede haber una demora de alrededor de 30 segundos antes de que el contenido del anuncio sea visible para los usuarios. Durante ese retraso, los usuarios podrán ver la transmisión continua, y deberás mirar la transmisión continua para determinar cuándo se muestra realmente 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 está retrasada, puedes insertar el punto de inserción de inmediato como se describió anteriormente, especificar una hora de reloj como se indicó anteriormente o especificar una compensación horaria para determinar cuándo comenzará la pausa publicitaria. La compensación horaria especifica un punto en la transmisión en el que los usuarios deberían ver un anuncio.

    El valor de desplazamiento 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 de monitor comienza cuando tu transmisión pasa al estado testing. De lo contrario, la transmisión de monitor comienza cuando la transmisión realiza la transición al estado live.

    Cuando insertes un punto de inserción, 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 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 principio 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.
  • Quien transmite inserta el punto de inserción 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 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 se retrasa en 60 segundos o 60, 000 milisegundos.
  • Δ=5000: Es el búfer de cinco segundos cuando el punto de inserción no puede insertarse de manera 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 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 deja de tener el 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 señaló 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.