El ciclo de una transmisión

Introducción

En este documento, se explica el ciclo de vida de una transmisión en vivo en YouTube que se crea y administra con la API de YouTube Live Streaming y la API de Content ID de YouTube.

Recursos y tipos de recursos

Como se explica en la guía de introducción, un recurso es una entidad de datos individual con un identificador único. Para crear y administrar eventos en vivo en YouTube, usarás varios tipos de recursos diferentes que se definen como parte de la API de YouTube Data o la API de Content ID de YouTube. Los recursos que se indican en el encabezado de la API de YouTube Live Streaming se definen técnicamente en esas otras APIs, pero se indican por separado porque solo se usan para las transmisiones en vivo.

Recursos de la API de Live Stream de YouTube

Recursos de la API de YouTube Data

Recursos de la API de Content ID de YouTube

Cómo crear y administrar una transmisión en vivo

Los siguientes pasos explican cómo crear y administrar un evento en directo en YouTube. Los pasos se dividen en las siguientes etapas:

  1. Cómo configurar tu transmisión
  2. Reclama tu contenido
  3. Prueba
  4. Anuncio
  5. Concluye tu transmisión
  6. Crea una referencia

Etapa 1: Configurar una transmisión

Paso 1.1: Crear una transmisión

Llama al método liveBroadcasts.insert para agregar tu transmisión al programa de eventos en vivo de YouTube. El recurso liveBroadcast que insertas debe definir valores para las propiedades que se indican a continuación.

Ten en cuenta las siguientes pautas cuando configures una transmisión:

  • Si quieres tener una fase de prueba para tu transmisión, en la que puedas ver tu transmisión de video sin que otros usuarios también puedan verla, debes establecer la propiedad contentDetails.monitorStream.enableMonitorStream en true y la propiedad contentDetails.enableAutoStart en false. Estos son los valores predeterminados para ambas propiedades.

  • Si quieres crear una referencia a partir de tu transmisión grabada, debes establecer la propiedad contentDetails.recordFromStart de la transmisión en true. Si quieres que el video grabado esté disponible para su reproducción inmediatamente después de que finalice la transmisión, también debes establecer la propiedad contentDetails.enableDvr en true. (Ambas propiedades tienen un valor predeterminado de true).

  • Si deseas restringir las regiones en las que se puede ver tu transmisión, puedes establecer la propiedad contentDetails.availabilityConfig. Esta propiedad te permite bloquear regiones específicas o limitar la disponibilidad a una lista definida de regiones. También puedes especificar períodos para la disponibilidad regional.

  • De manera opcional, puedes especificar la categoría del video de la transmisión con la propiedad snippet.categoryId. Si no se especifica, la categoría predeterminada es Entertainment.

  • Puedes actualizar cualquiera de las propiedades de contentDetails siempre y cuando el estado de tu transmisión siga siendo created o ready.

  • Puedes actualizar la hora de inicio y de finalización programadas de la transmisión siempre que su estado sea created, ready o testing.

  • El título, la descripción, la categoría y el estado de privacidad de la transmisión, así como otros campos de metadatos que forman parte del recurso video de la transmisión, se pueden actualizar en cualquier momento.

    Nota: Si solo quieres que tu video esté disponible para usuarios específicos de YouTube, establece el valor de la propiedad status.privacyStatus en unlisted o private, según tus necesidades.

Procesamiento de la respuesta de la API

Cuando llamas al método liveBroadcasts.insert, la respuesta de la API contiene el recurso liveBroadcast que creaste. Tu código debe extraer y almacenar el id de ese recurso. Necesitarás ese valor para identificar la transmisión en futuras solicitudes a la API. (También puedes identificar el recurso video que corresponde al recurso liveBroadcast con el mismo ID).

Paso 1.2: Crear una transmisión continua

Un recurso liveStream te permite transmitir tu video a YouTube y describe el contenido que transmites. Cada transmisión debe estar asociada con exactamente una transmisión.

Llama al método liveStreams.insert para crear la transmisión de video de tu evento. Cuando crees tu transmisión, debes establecer valores para las propiedades que se indican a continuación:

Con la excepción del título de la transmisión, estos valores no se pueden actualizar después de que se crea la transmisión. Si necesitas cambiarlos, debes crear un flujo diferente repitiendo este paso. Este proceso se analiza con más detalle en el paso 3.5 más adelante en este documento.

También tienes la opción de establecer valores para las siguientes propiedades:

  • snippet.description: Al igual que el título de la transmisión, la descripción se puede actualizar después de que se crea la transmisión. Ni el título ni la descripción son visibles para los usuarios de YouTube.

  • [contentDetails.isReusable](

    /youtube/data/live/reference/rest/v3/liveStreams#contentDetails.isReusable)

    Indica si la transmisión es reutilizable, lo que significa que se puede vincular a varias transmisiones. El valor de esta propiedad determina de manera efectiva si un canal tiene una relación de varios a uno o de uno a uno entre los recursos liveBroadcast y liveStream:

    • Si usas el valor predeterminado de la propiedad, true, puedes usar el mismo recurso liveStream para todas las transmisiones de un canal. Esto significa que no es necesario repetir este paso (1.2) para cada transmisión. En su lugar, puedes reutilizar el ID de transmisión para las transmisiones posteriores.
    • Si estableces el valor de la propiedad en false, deberás crear una nueva transmisión para cada emisión.

Después de que envías la solicitud a la API, la respuesta de la API contiene el recurso liveStream que creaste. Tu código debe extraer y almacenar el id de ese recurso. Necesitarás ese valor para identificar la transmisión en futuras solicitudes a la API.

Paso 1.3: Vincular una transmisión a su transmisión continua

Después de crear tus recursos liveBroadcast y liveStream, ahora debes asociar los dos con el método liveBroadcasts.bind. Esta acción vincula los fragmentos de video que transmitirás a YouTube con la transmisión del evento para ese video.

Cuando llames al método liveBroadcasts.bind, establece el parámetro id en el ID de transmisión que obtuviste en el paso 1.1 y el parámetro streamId en el ID de transmisión que obtuviste en el paso 1.2.

Etapa 2: Reclamar contenido

Si quieres mostrar anuncios durante tu transmisión, debes reclamar el video de la transmisión antes de que comience el evento. Sigue estos pasos para configurar la transmisión, su video y sus anuncios. Ten en cuenta que el canal del propietario de la transmisión debe ser apto para mostrar anuncios.

Ten en cuenta que todas las llamadas a la API que se analizan en esta etapa se definen en la API de Content ID de YouTube.

Paso 2.1: Crear un elemento

Un recurso asset representa un elemento de propiedad intelectual. En este caso, el elemento es tu transmisión. Llama al método assets.insert para crear tu recurso.

La respuesta de la API contendrá el recurso asset que creaste. Tu código debe extraer y almacenar el id de ese recurso, ya que necesitarás ese valor para identificar el recurso en futuras solicitudes a la API.

Paso 2.2: Definir la propiedad de un elemento

Los datos de propiedad de un activo identifican a los propietarios del activo y los territorios en los que son propietarios del activo. YouTube usa estos datos para determinar dónde un propietario puede establecer la política de un video reclamado.

Por ejemplo, si tienes derecho a transmitir un evento en Estados Unidos y otro emisor tiene los mismos derechos para Canadá, cada uno puede definir políticas diferentes para el video de la transmisión y para los videos subidos por usuarios que coincidan con el video de la transmisión. Tu política de coincidencias se aplicará a los videos que coincidan con el contenido subido por el usuario en Estados Unidos, mientras que la política del otro propietario se aplicará a los videos que coincidan en Canadá.

Para definir los territorios de propiedad del activo, llama al método ownership.update. En esa solicitud, establece el parámetro assetId en el id que almacenaste en el paso 2.1.

Paso 2.3: Establecer la política de coincidencias de un elemento

La política de coincidencias de un activo explica qué debe hacer YouTube cuando un usuario sube un video que coincide con una referencia asociada al activo. En este caso, la política de coincidencias indicará cómo debe manejar YouTube un video subido que coincida con tu transmisión en vivo.

Nota: Debes establecer una política de coincidencias si planeas crear una referencia a partir de tu video de transmisión y usarla para identificar los videos subidos por usuarios que coincidan con tu transmisión. En caso contrario, puede omitir este paso.

Para establecer la política de coincidencias, primero debes identificar la política que deseas aplicar. Puedes recuperar una lista de las políticas existentes llamando al método policies.list o definir una política nueva llamando al método policies.insert. En ambos casos, debes capturar el id de la política que deseas aplicar.

Una vez que hayas identificado la política, llama al método assetMatchPolicy.update. En esa solicitud, establece el parámetro assetId en el id que almacenaste en el paso 2.1.

Paso 2.4: Reclamar un video

En este paso, crearás un reclamo que vinculará el video que transmitirás al activo que creaste en el paso 2.1. El reclamo establece una política que se aplica solo a tu video de transmisión. (Los videos subidos por usuarios que coincidan con tu video de transmisión se rigen por la política de coincidencias establecida en el paso anterior).

Para crear un reclamo, llama al método claims.insert. En el recurso claim que insertes, debes establecer valores para las siguientes propiedades:

  • assetId: Obtuviste este valor en el paso 2.1.
  • videoId: Es el ID de transmisión que obtuviste en el paso 1.1.
  • policy: Es un recurso policy. Puedes aplicar una política existente configurando la propiedad id de ese recurso en el ID de la política existente. En el paso anterior, se explica cómo recuperar el ID de una política existente.
  • contentType: Establece este valor en audiovisual.

Procesamiento de la respuesta de la API

Cuando insertes el reclamo, la respuesta de la API contendrá el recurso claim que creaste. Tu código debe extraer y almacenar el id de ese recurso. Usarás ese valor más adelante para crear una referencia a partir de tu video procesado.

Paso 2.5: Actualizar la configuración de anuncios de una transmisión

Debes configurar las opciones de publicidad de tu video si quieres publicar un anuncio previo al video cuando los usuarios comiencen a mirar tu transmisión o publicar anuncios durante las pausas de la transmisión.

  • Si habilitas los anuncios previos al video para tu transmisión, todos los usuarios verán un anuncio cuando comiencen a mirar tu transmisión, incluso si empiezan a mirarla en medio de la transmisión.
  • Si habilitas los anuncios durante el video para tu transmisión, podrás insertar puntos de inserción de anuncios durante la transmisión.

Para habilitar los anuncios, llama al método videoAdvertisingOptions.update. En tu solicitud, establece el parámetro videoId en el id de transmisión que obtuviste en el paso 1.1. Usa la propiedad adFormats[] del recurso videoAdvertisingOption para identificar los formatos de anuncios (preroll, midroll o postroll) que quieres habilitar.

Etapa 3: Realizar una prueba

Durante esta etapa, incorporarás un reproductor que muestre la transmisión de supervisión de tu transmisión para que puedas probar la experiencia de visualización. La transmisión de supervisión es una transmisión privada que te permite obtener una vista previa del video de la transmisión tal como aparecería para los usuarios de YouTube.

Ten en cuenta que solo puedes probar tu transmisión de video si su transmisión de supervisión está habilitada. Las transmisiones continuas de monitor están habilitadas de forma predeterminada. Puedes inhabilitar la transmisión de supervisión de una transmisión en vivo si configuras la propiedad contentDetails.monitorStream.enableMonitorStream en false cuando crees o actualices esa transmisión en vivo.

Paso 3.1: Insertar un reproductor de transmisión continua de monitor

Recupera tu transmisión con el método liveBroadcasts.list y extrae el valor de la propiedad contentDetails.streamDetails.monitorStreamEmbedHtml. Ese valor contiene el código HTML que necesitas para incorporar un reproductor de YouTube que muestre tu transmisión de monitoreo.

Paso 3.2: Comenzar la transmisión de un video

Comienza a transmitir video en tu transmisión de video.

Paso 3.3: Confirma que tu transmisión de video esté activa

Llama al método liveStreams.list para recuperar el recurso liveStream asociado con tu transmisión. Confirma que el valor de la propiedad status.streamStatus sea active, lo que indica que los servidores de YouTube están recibiendo datos de tu codificador correctamente.

Paso 3.4: Cambia el estado de tu transmisión a prueba

Llama al método liveBroadcasts.transition para actualizar el estado de la transmisión. Establece el valor del parámetro id en el ID de transmisión que obtuviste en el paso 1.1 y establece el valor del parámetro broadcastStatus en testing.

Después de llamar al método liveBroadcasts.transition, es posible que la transición tarde varios segundos, o incluso hasta un minuto, en completarse. Durante ese tiempo, debes sondear la API para verificar el estado de la transmisión. Hasta que se complete la transición, el estado de la transmisión será testStarting. El estado será testing una vez que se complete la transición.

Paso 3.5: Completar las pruebas

Si la prueba se realizó sin problemas, puedes avanzar a la etapa 4. Sin embargo, en algunos casos, podría ser necesario realizar más pruebas. Por ejemplo, si tus pruebas revelan que la transmisión de video no está configurada correctamente, debes solucionar ese problema antes de continuar con la transmisión.

Si la transmisión de video no está configurada correctamente, debes desvincular (y borrar) la transmisión existente y crear una nueva. Por ejemplo, es posible que una transmisión no esté configurada correctamente si especifica el formato de video incorrecto.

  1. Para desvincular la transmisión de video, llama al método liveBroadcasts.bind del paso 1.3. En la solicitud a la API, establece el parámetro id en el id que obtuviste en el paso 1.1. No incluyas el parámetro streamId en la solicitud.

  2. Para borrar la transmisión de video, llama al método liveStreams.delete. En la solicitud, establece el parámetro id en el id que obtuviste en el paso 1.2.

  3. Repite el paso 1.2 para crear un recurso liveStream nuevo y configurado correctamente. Luego, repite el paso 1.3 para vincular la nueva transmisión a tu transmisión y los pasos del 3.1 al 3.3 para probar la nueva transmisión.

Paso 3.6: Habilita las propiedades autoStart y autoStop

Después de completar correctamente la etapa de pruebas, tienes la opción de configurar las propiedades de contentDetails.enableAutoStart y contentDetails.enableAutoStop de la transmisión como true antes de que comience la transmisión real. Estas propiedades no se pueden establecer en true antes de la etapa de prueba, ya que la prueba haría que se iniciara la transmisión.

Etapa 4: Realizar una transmisión

Durante esta etapa, el video de tu transmisión puede ser visto por tu audiencia.

Paso 4.1: Comienza tu video

Comienza a transmitir video en tu transmisión de video.

Paso 4.2: Confirma que tu transmisión de video esté activa

Llama al método liveStreams.list para recuperar el recurso liveStream asociado con tu transmisión. Confirma que el valor de la propiedad status.streamStatus sea active, lo que indica que los servidores de YouTube están recibiendo datos de tu codificador correctamente.

Paso 4.3: Cambia el estado de tu transmisión a en vivo

Importante: Con este paso, tu video será visible para el público.

Llama al método liveBroadcasts.transition para actualizar el estado de la transmisión. Establece el valor del parámetro id en el ID de transmisión que obtuviste en el paso 1.1 y el valor del parámetro broadcastStatus en live.

Si configuras la propiedad contentDetails.enableAutoStart del recurso liveBroadcast como true, no necesitas llamar al método liveBroadcasts.transition.

Después de realizar esta llamada a la API o, si estableciste la propiedad contentDetails.enableAutoStart en true, después de comenzar la transmisión, por lo general, debes esperar entre 5 y 10 segundos para que se complete la transición. La transición puede tardar hasta un minuto. Durante ese tiempo, debes consultar la API para verificar el estado de la transmisión. Hasta que se complete la transición, el estado de la transmisión será liveStarting. El estado será live una vez que se complete la transición y los usuarios puedan mirar tu transmisión desde ese punto en tu transmisión de supervisión.

Ten en cuenta los siguientes efectos de este comando:

  • Si habilitaste la transmisión de supervisión para tu emisión (consulta el paso 3.1), podrás verla en un reproductor integrado.
  • Si estableciste un valor para la propiedad contentDetails.streamDetails.broadcastStreamDelayMs de la transmisión, el flujo de la transmisión, que es visible para otros usuarios, se retrasará en esa cantidad de tiempo.

Paso 4.4: Inserta pausas publicitarias en tu transmisión

Llama al método liveBroadcasts.cuepoint para insertar un punto de inserción. Es posible que el punto de referencia active una pausa publicitaria. En el recurso cuepoint proporcionado en el cuerpo de la solicitud, establece la propiedad durationSecs en la duración deseada de la pausa (en segundos) que quieres mostrar. (El valor predeterminado es 30).

En ese momento, YouTube intenta reproducir un anuncio en el reproductor de video para los usuarios que estaban mirando la transmisión cuando se insertó el punto de inserción de anuncio. La reproducción de un anuncio depende de varios factores, como la disponibilidad de anuncios y el historial de visualización de anuncios del usuario. Los usuarios que vean una pausa publicitaria volverán a tu transmisión cuando finalice, mientras que los usuarios a los que no se les muestre un anuncio seguirán viendo la transmisión durante la pausa.

La guía de introducción proporciona más información sobre la experiencia de visualización durante la pausa publicitaria de una transmisión en vivo.

Etapa 5: Finalizar una transmisión

Paso 5.1: Detén la transmisión

Con este paso concluye tu prueba del sistema de transmisión en directo de YouTube.

Paso 5.2: Cambia el estado de tu transmisión a completado

Cuando quieras dejar de transmitir, llama al método liveBroadcasts.transition de la API para actualizar el estado de la transmisión. Establece el valor del parámetro id en el ID de transmisión obtenido en el paso 1.1 y establece el valor del parámetro broadcastStatus en complete.

Si configuraste las propiedades contentDetails.recordFromStart y contentDetails.enableDvr de la transmisión como true, cuando finalice el evento en vivo, tu público podrá mirar de inmediato la reproducción del evento en vivo.

Paso 6: Crear una referencia

Una vez que se complete la grabación en vivo, podrás crear una referencia a partir del video grabado. Esta acción le indica a YouTube que busque videos subidos por usuarios que coincidan con la transmisión y que los administre según la política de coincidencias que establezcas en el paso 2.3.

Importante: Para crear la referencia, debes haber establecido la propiedad contentDetails.recordFromStart de la transmisión en true.

Paso 6.1: Consulta el estado del video a la API de datos

YouTube debe terminar de procesar una transmisión o un video subido antes de que puedas crear una referencia a partir de ese video. Para determinar si el video terminó de procesarse, sondea el método videos.list de la API de YouTube Data, establece el parámetro part en status y el parámetro id en el ID de transmisión que almacenaste en el paso 1.1.

La respuesta de la API a tu solicitud de sondeo contendrá un recurso video. Cuando el valor de la propiedad status.uploadStatus de ese recurso sea processed, continúa con el paso 6.2.

Paso 6.2: Crear una referencia a partir del video procesado

Para crear tu referencia, llama al método references.insert de la API de Content ID y establece el parámetro claimId en el ID del reclamo que almacenaste en el paso 2.4.

Envío de contenido en vivo a Content ID

Algunos socios de YouTube pueden crear una referencia antes de que su transmisión cambie al estado testing, pero esa función no está disponible para todos los socios. En ese flujo, YouTube genera y actualiza continuamente la referencia de la transmisión de tu evento en vivo mientras la transmisión está en curso. Además, YouTube busca videos subidos por usuarios que coincidan mientras la transmisión aún está en curso. Ten en cuenta que, si creas una referencia antes de que comience una transmisión, se activará automáticamente la grabación de la transmisión, y no se podrá desactivar después de que se cree la referencia.

Para habilitar tu transmisión para la publicación de Content ID en vivo, intenta realizar las acciones descritas en el paso 6.2 después de reclamar tu video en el paso 2.4. Si tu cuenta de socio no se aprobó para crear una referencia de una transmisión en vivo antes de que se realice, la API devolverá un error fingerprintingNotAllowed. En ese caso, debes esperar a que finalice la transmisión, como se describe en los pasos 6.1 y 6.2 anteriores, antes de crear la referencia.