El ciclo de una transmisión

Introducción

En este documento, se explica el ciclo de una transmisión en vivo en YouTube que se crea y administra mediante la API de transmisión en vivo de YouTube 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, debes usar diferentes tipos de recursos definidos como parte de la API de datos de YouTube o la API de Content ID de YouTube. Los recursos enumerados en el encabezado de la API de transmisión en vivo de YouTube se definen técnicamente en esas otras API, pero se enumeran por separado porque solo se usan para las transmisiones en vivo.

Recursos de la API de transmisión en vivo de YouTube

Recursos de la API de datos de YouTube

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. Configura tu transmisión
  2. Reclama tu contenido
  3. Prueba
  4. Anuncio
  5. Finaliza tu transmisión
  6. Cómo crear una referencia

Etapa 1: Configurar una transmisión

Paso 1.1: Crear una transmisión

Invoca el método liveBroadcasts.insert para agregar tu transmisión a la programación de eventos en vivo de YouTube. El recurso liveBroadcast que vas a insertar debe definir los valores de las propiedades de la lista a continuación.

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

  • Si quieres tener una fase de prueba de la transmisión, cuando puedas ver la transmisión de video sin que otros usuarios también puedan ver la transmisión, 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 deseas crear una referencia a partir de una transmisión grabada, debes establecer la propiedad contentDetails.recordFromStart de la transmisión en true. Si quieres que la reproducción del video grabado esté disponible inmediatamente después de que termine la transmisión, debes establecer la propiedad contentDetails.enableDvr en true. (El valor predeterminado de estas dos propiedades es true).

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

  • Puedes actualizar la hora de inicio y de finalización programada de la transmisión, siempre y cuando el estado de la transmisión sea created, ready o testing.

  • El título, la descripción y el estado de privacidad de la transmisión y otros campos de metadatos que forman parte del recurso video de la transmisión pueden actualizarse 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.

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 debería extraer y almacenar la id de ese recurso. Lo necesitarás 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 un video a YouTube y describe el contenido que vas a transmitir. Cada transmisión debe estar asociada con solo una transmisión.

Llama al método liveStreams.insert a fin de crear la transmisión de video por Internet para tu evento. Cuando creas una transmisión continua, debes establecer valores para las propiedades que se enumeran a continuación:

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

También tiene la opción de configurar 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 forma efectiva si una canal tiene una relación de varios a uno o uno a uno entre los recursos liveBroadcast y liveStream:

    • Si usas el valor predeterminado de la propiedad de true, puedes usar el mismo recurso liveStream para todas las transmisiones de un canal. Esto significa que no necesitas repetir este paso (1.2) para cada transmisión. En su lugar, puedes volver a usar el ID de transmisión para las transmisiones posteriores.
    • Si configuras el valor de la propiedad en false, debes crear una transmisión nueva para cada transmisión.

Después de emitir la solicitud a la API, la respuesta de la API contiene el recurso liveStream que creaste. Tu código debe extraer y almacenar la 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 mediante el método liveBroadcasts.bind. Esta acción vincula los bits de video que vas a transmitir 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 deseas mostrar anuncios durante la 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 mencionan en esta etapa se definen en la YouTube Content ID API.

Paso 2.1: Crear un elemento

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

La respuesta de la API contendrá el recurso asset que creaste. Tu código debe extraer y almacenar la id de ese recurso, ya que la necesitarás 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 elemento identifican a los propietarios y los territorios en los que poseen el elemento. YouTube usa estos datos para determinar dónde un propietario puede establecer la política para un video reclamado.

Por ejemplo, si tienes derecho a transmitir un evento en Estados Unidos y otra emisora posee los mismos derechos para Canadá, cada uno puede definir diferentes políticas 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 coincidentes subidos por el usuario en los Estados Unidos, mientras que la política del otro propietario se aplicará a los videos coincidentes en Canadá.

Para definir los territorios en los que eres propietario 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 elemento explica qué debe hacer YouTube cuando un usuario sube un video que coincide con una referencia asociada con el elemento. En este caso, la política de coincidencias indicará cómo YouTube debe manejar 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 del video de tu 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 políticas existentes llamando al método policies.list, o puedes definir una nueva política llamando al método policies.insert. En cualquier caso, debes capturar la 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 vincula el video que vas a transmitir al elemento que creaste en el paso 2.1. La reclamación 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 contemplan en 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 insertas, debes establecer los valores de las siguientes propiedades:

  • assetId: Obtienes este valor en el paso 2.1.
  • videoId: es el ID de transmisión que obtuviste en el paso 1.1.
  • policy: Este es un recurso policy. Puedes aplicar una política existente si configuras la propiedad id de ese recurso en el ID de esa política. 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 la reclamación, la respuesta de la API contendrá el recurso claim que creaste. Tu código debe extraer y almacenar la id de ese recurso. Usarás ese valor más adelante para crear una referencia a partir del 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 deseas publicar un anuncio previo al video cuando los espectadores comienzan a ver la 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 los verán cuando comiencen a mirar tu transmisión, incluso si comienzan a verla a la mitad.
  • Si habilitas los anuncios durante el video para tu transmisión, podrás insertar puntos de inserción de anuncios durante la misma.

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

Etapa 3: Realizar una prueba

Durante esta etapa, deberás incorporar un reproductor que muestre la transmisión continua de monitor de tu transmisión a fin de que puedas probar la experiencia de visualización. La transmisión continua de monitor es una transmisión privada que te permite obtener una vista previa del video de la transmisión del mismo modo en que aparece para los usuarios de YouTube.

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

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 la transmisión continua de monitor.

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 a tu transmisión. Confirma que el valor de la propiedad status.streamStatus sea active, lo que indica que los servidores de YouTube reciben los datos de tu codificador correctamente.

Paso 3.4: Cambiar el estado de una 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, la transición puede tomar varios segundos, o incluso hasta un minuto, en completarse. 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á testStarting. El estado será testing una vez que se complete la transición.

Paso 3.5: Completar las pruebas

Si te fue 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 por Internet no está configurada correctamente, debes solucionar este problema antes de continuar con la transmisión.

Si la transmisión de video por Internet 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 un formato de video incorrecto.

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

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

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

Paso 3.6: Habilitar las propiedades autoStart y autoStop

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

Etapa 4: Realizar una transmisión

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

Paso 4.1: Iniciar tu video

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

Paso 4.2: Confirmar que la transmisión de video por Internet está activa

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

Paso 4.3: Cambiar el estado de una transmisión a publicada

Importante: Este paso permite que tu público vea 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 establece el valor del parámetro broadcastStatus en live.

Si configuras 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 en true, después de comenzar la transmisión, por lo general, debes esperar entre 5 y 10 segundos para que se complete esa 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 espectadores podrán ver la transmisión desde ese punto en la transmisión continua de monitor.

Ten en cuenta los siguientes efectos de este comando:

  • Si habilitaste la transmisión continua de monitor de tu transmisión (consulta el paso 3.1), podrás ver la transmisión continua de monitor en un reproductor insertado.
  • Si estableciste un valor para la propiedad contentDetails.streamDetails.broadcastStreamDelayMs de la transmisión, la transmisión continua, visible para otros usuarios, se retrasará durante ese período.

Paso 4.4: Insertar pausas publicitarias en la transmisión

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

En este momento, YouTube intenta reproducir un anuncio en el reproductor de video para todos los espectadores que miraban la transmisión cuando se insertó el punto de inserción del anuncio. La reproducción de un anuncio depende de diversos factores, como la disponibilidad del anuncio y el historial de reproducciones de un espectador. Los usuarios que sí tienen una pausa publicitaria vuelven a tu transmisión cuando la pausa publicitaria finaliza, mientras que los usuarios a los que no se les muestra un anuncio siguen viendo la transmisión continua durante la pausa.

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

Etapa 5: Finalizar una transmisión

Paso 5.1: Detener la transmisión

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

Paso 5.2: Cambiar el estado de una transmisión a completa

Cuando estés listo para detener la transmisión, llama al método liveBroadcasts.transition de la API a fin de 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 complete.

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

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 da una instrucción a YouTube de buscar videos subidos por los usuarios que coincidan con la transmisión y administrarlos según la política de coincidencias que estableciste en el paso 2.3

Importante: Para crear la referencia, debes establecer 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 datos de YouTube. Para ello, 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 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 de reclamación que almacenaste en el paso 2.4.

Publicación de Content ID para transmisiones en vivo

Algunos socios de YouTube pueden crear una referencia antes de que sus transmisiones pasen 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 coincidencias entre los videos subidos por usuarios mientras la transmisión está en curso. Ten en cuenta que crear una referencia antes de que comience una transmisión activa la grabación de la transmisión y no se puede desactivar después de que se crea la referencia.

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