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
-
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 el YouTube Data API como uno de los servicios que usa:
- Ve a API Console y selecciona el proyecto que acabas de registrar.
- 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.
-
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
ounlisted
. (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:
-
Tiene un período predefinido, que se establece con la propiedad
durationSecs
del recursocuepoint
. Cuando termina la pausa publicitaria, los usuarios regresan a la transmisión en vivo. -
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 propiedadinsertionOffsetTimeMs
en0
o no especifiques un valor para esa propiedad ni especifiques un valor para la propiedadwalltimeMs
.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 propiedadwalltimeMs
para especificar la hora deseada. El valor de la propiedad es un número entero que representa una marca de tiempo de época.
-
Para iniciar la pausa publicitaria de inmediato, llama al método
-
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 estadolive
.Cuando insertes un punto de inserción, establece la propiedad
insertionOffsetTimeMs
del recursocuepoint
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étodoliveBroadcasts.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 deready
atesting
, YouTube establecerá el estado de la transmisión entestStarting
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 atesting
, lo que indicará que se completó la transición.Si una transmisión deja de tener el estado
testStarting
oliveStarting
, debes llamar al métodoliveBroadcasts.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 propiedadstatus.streamStatus
para la transmisión vinculada a tu transmisión seaactive
antes de llamar a ese método.