Descripción general de la API de YouTube Live Streaming

La API de Live Streaming 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 Live Streaming se compone de componentes de la API de YouTube Data y la API de YouTube Content ID. La API de Data permite a los usuarios de YouTube administrar sus cuentas de YouTube, mientras que la YouTube Content ID API permite las interacciones con el sistema de administración de derechos de YouTube. Sin embargo, todos los recursos que componen la API de Live Streaming solo se usan para crear y administrar eventos en vivo.

Este documento está dirigido a los desarrolladores que desean escribir 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 ver en YouTube mientras sucede. 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.
Transmisiones
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 cuepoint 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.

  • Para permitir que los emisores definan información sobre una transmisión y su video (con la API de YouTube Data) al mismo tiempo.

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

Antes de comenzar

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

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

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

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

  4. Familiarízate con 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 Live Streaming usa funciones que técnicamente forman parte de la API de YouTube Data o de la API de YouTube Content ID. Puedes usar la API de Content ID para proporcionar a YouTube metadatos, información de propiedad y 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 la Content ID API, que son diferentes de los requisitos para autorizar otras solicitudes de la Live Streaming API.

Cómo llamar a la Data API
La solicitud a la API debe estar autorizada por la Cuenta de Google que posee el canal de YouTube que realiza la transmisión.
Cómo llamar a la Content ID API
La solicitud a la API debe estar autorizada por una Cuenta de Google 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 la Live Streaming API. Técnicamente, todos estos recursos se definen como parte de la YouTube Data API o la YouTube Content ID API. Sin embargo, los liveBroadcast, liveStream y cuepoint recursos solo se usan para crear y administrar eventos en vivo.

Recursos
liveBroadcast Contiene información sobre un evento que transmites en YouTube. Un liveBroadcast recurso es una extensión de un recurso de video de YouTube y establece los metadatos del video que serían pertinentes para una transmisión en vivo, pero no para otros videos de YouTube.

Por lo tanto, un recurso liveBroadcast corresponde exactamente a un recurso de video de YouTube. De hecho, el liveBroadcast recurso y el video recurso comparten el mismo ID. Después de crear la transmisión con la API de Live Streaming, puedes usar la API de YouTube Data para proporcionar metadatos adicionales sobre el video.
liveStream Contiene información sobre la transmisión de video que envías 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 exactamente a un recurso liveBroadcast. Del mismo modo, el liveBroadcast recurso solo se puede vincular a un liveStream recurso.
cuepoint Inserta un punto de inserción en la transmisión de video, lo que podría activar una pausa publicitaria. Usa el liveBroadcasts.cuepoint método para insertar un punto de inserción durante una transmisión.
video Representa un video de YouTube en particular. Como se mencionó anteriormente, un recurso liveBroadcast es una extensión de un recurso video. Puedes usar la API de YouTube Data 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 el YouTube Content ID API para establecer 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 el YouTube Content ID API para crear y administrar recursos asset.
claim Vincula un video a un elemento que corresponde a un video. Creas 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 ese 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 que se admiten para 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 autorizadas y 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.

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 en realidad. Este requisito cumple 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 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, y la vida útil de un documento de transmisión explica las YouTube Content ID API llamadas que te permiten crear tu reclamo.

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 cambiar una transmisión a la fase testing si está habilitada la transmisión continua de monitor de la transmisión. La transmisión continua de monitor no muestra pausas publicitarias.

  • 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 en una transmisión continua

Durante una transmisión, puedes insertar un cuepoint para indicar que una pausa publicitaria debe comenzar en la transmisión lo antes posible o a una hora específica. 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 una duración predefinida, que se establece con la propiedad cuepoint del recurso durationSecs. Después de que finaliza la pausa publicitaria, los usuarios vuelven 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 miran la transmisión cuando se inserta el punto de inserción. No se publica un anuncio cuando los usuarios actualizan la página donde se reproduce la transmisión o cuando los visitantes comienzan a mirar la transmisión después de que se inserta el punto de inserción.

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

Establece compensaciones de tiempo

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

  • Si no se retrasa la transmisión continua, puedes insertar el punto de inserción de inmediato o usar la walltimeMs propiedad para que la pausa publicitaria comience a una hora determinada.

    • 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. Es posible que haya una demora de alrededor de 30 segundos antes de que el contenido del anuncio sea visible para los usuarios. Durante esa demora, la transmisión continua seguirá siendo visible para los usuarios, y deberás mirarla para determinar cuándo se muestra el contenido del anuncio en lugar de la transmisión continua de monitor.

    • Para iniciar la pausa publicitaria a una hora determinada, llama al liveBroadcasts.cuepoint método y usa la walltimeMs propiedad para especificar la hora deseada. El valor de la propiedad es un número entero que representa una marca de tiempo de ciclo de entrenamiento.

  • Si se retrasa la transmisión continua, puedes insertar el punto de inserción de inmediato como se describió anteriormente, especificar una hora del reloj como se describió anteriormente o especificar una compensación de tiempo para determinar cuándo comenzará la pausa publicitaria. La compensación de tiempo especifica un punto en la transmisión en el que los usuarios deberían 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 continua de monitor comienza cuando la 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 inserción, establece la propiedad del recurso cuepointinsertionOffsetTimeMs en la compensación deseada.

Calcula el valor de compensación de tiempo

Para recuperar el valor de compensación, llama a la función getCurrentTime de la API de YouTube Player 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 - Δ)]

El Δ es un búfer de cinco segundos al principio y al final de las posibles compensaciones de tiempo 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.
  • El emisor inserta el punto de inserción cuatro minutos después de que la transmisión cambia al estado live status. (O sea, tres minutos después de que la transmisión continua se hace visible).

En este caso, el intervalo posible de compensaciones horarias es [(485,000), (535,000)].

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

  • elapsed_time=540000 – La transmisión continua 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 se retrasa 60 segundos o 60, 000 milisegundos.
  • Δ=5000 – El búfer de cinco segundos cuando no se puede insertar el punto de inserción de manera confiable.

Solución de problemas y manejo de errores

En las siguientes pautas se explica cómo resolver posibles problemas específicos. Para obtener las listas de errores que cada método de la API puede mostrar, consulta API de Live Streaming de YouTube: 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 esas acciones, YouTube actualizará el estado de la transmisión a testing, lo que indicará que la transición se completó.

    Si una transmisión se atasca con un estado testStarting o liveStarting, debes llamar al método liveBroadcasts.delete y borrar la transmisión. Luego, crea una transmisión nueva, vincúlala a tu transmisión en vivo 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.