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 YouTube Content ID. Los recursos que se enumeran en el encabezado de la API de YouTube Live Streaming se definen técnicamente en esas otras APIs, pero se enumeran por separado porque solo se usan para las transmisiones en vivo.

Recursos de la API de YouTube Live Streaming

Recursos de la API de YouTube Data

Recursos de la API de Content ID de YouTube

Crea y administra 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. Cómo finalizar 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 verla sin que otros usuarios también puedan hacerlo, 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 la 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).

  • 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 la hora de finalización programadas de la transmisión, siempre y cuando el estado de la transmisión sea created, ready o testing.

  • El título, la descripción, el estado de privacidad y otros campos de metadatos de la transmisión, 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 corresponda a tus necesidades.

Procesa 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 solicitudes futuras 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 un flujo.

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 otro flujo 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 crearla. Ni el título ni la descripción son visibles para los usuarios de YouTube.

  • 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 muchos 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 que repitas este paso (1.2) para cada transmisión. En cambio, puedes volver a usar 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 para transmitir el video, 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 los recursos liveBroadcast y liveStream, debes asociarlos 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. En los siguientes pasos, se explica este proceso. 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 una obra 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 activo en futuras solicitudes a la API.

Paso 2.2: Definir la propiedad de un elemento

Los datos de propiedad de un activo identifican a sus propietarios y los territorios en los que poseen el activo. YouTube usa estos datos para determinar dónde puede establecer la política un propietario para 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 los usuarios que coincidan con el video de la transmisión. Tu política de coincidencias se aplicará a los videos subidos por usuarios que coincidan 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 cualquier caso, 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.

Procesa 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 los descansos 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 comienzan a mirarla en el medio.
  • 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, configura el parámetro videoId en la transmisión id 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 deseas habilitar.

Etapa 3: Realizar una prueba

Durante esta etapa, incorporarás un reproductor que muestre la transmisión de supervisión de tu emisió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 la 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 supervisión.

Paso 3.2: Comenzar la transmisión de un video

Comienza la transmisión de video en tu transmisión continua de video.

Paso 3.3: Confirmar que la transmisión continua 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 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 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 cuando se complete la transición.

Paso 3.5: Completar las pruebas

Si la prueba se realizó sin problemas, puedes continuar con la etapa 4. Sin embargo, en algunos casos, podría ser necesario realizar más pruebas. Por ejemplo, si las pruebas revelan que la transmisión de video no está configurada correctamente, debes corregir el 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, configura el parámetro id en el valor de 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 valor de 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 emisió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 comenzara 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 la transmisión de video en tu transmisión continua 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 público podrá ver el video.

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 estableces la propiedad contentDetails.enableAutoStart del recurso liveBroadcast en true, no es necesario que llames al método liveBroadcasts.transition.

Después de realizar esta llamada a la API o, si configuraste la propiedad contentDetails.enableAutoStart como 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 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á liveStarting. El estado será live una vez que se complete la transición y los usuarios puedan ver tu transmisión desde ese punto en tu transmisión de monitoreo.

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 referencia. 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 deseas 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 del anuncio 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.

En la guía de Primeros pasos, se 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 completada

Cuando quieras detener la transmisión, 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 que obtuviste en el paso 1.1 y 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 finalice 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 finalizó el procesamiento del video, sondea el método videos.list de la API de YouTube Data, configura el parámetro part como status y el parámetro id como 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.

Publicación de Content ID en vivo

Algunos socios de YouTube pueden crear una referencia antes de que su transmisión pase 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 produzca, la API devolverá un error fingerprintingNotAllowed. En ese caso, debes esperar a que se complete la transmisión, como se describe en los pasos 6.1 y 6.2 anteriores, antes de crear la referencia.