Iniciar una grabación de archivo con la Video API

La Video API de Vonage te permite archivar, guardar y recuperar sesiones.

Flujo de trabajo básico

Flujo de trabajo básico para la grabación

Puede crear una grabación de archivo para una sesión utilizando una de las opciones siguientes SDK de servidor. Al crear un archivo, se inicia la grabación.

Sólo puede crear un archivo para sesiones que tengan al menos un cliente conectado. (Un cliente debe empezar a publicar un flujo en el plazo de un minuto o se detendrá la grabación del archivo).

A medida que los clientes comienzan y dejan de publicar flujos, éstos se registran.

Sin embargo, no hay límite en el número de archivos que puedes grabar, sesiones archivadas automáticamente reiniciará una nueva grabación cada 4 horas hasta que se detenga la grabación.

Los SDK de servidor incluyen métodos para lo siguiente:

• Iniciar una grabación de archivo
• Detener una grabación de archivo
• Listado de grabaciones de archivo
• Recuperación de información de registro de archivo
• Borrar un archivo

Cuando detienes la grabación de un archivo, la plataforma de video de Vonage crea un archivo MP4 o (en el caso de archivos de transmisión individuales) un archivo ZIP. (Consulta Flujo individual y archivos compuestos.)

Eventos de cliente y traspaso de interfaz de usuario

Cuando una grabación de archivo se inicia y se detiene, se emiten eventos en los clientes. Por ejemplo, los eventos OpenTok.js la biblioteca incluye archiveStarted y archiveStopped enviados por el objeto Session.

Archivos compuestos frente a archivos individuales de un vistazo

• Archivos compuestos son los predeterminados. Vonage renderiza un único MP4 (H.264/AAC) utilizando todas las transmisiones publicadas y las reglas de diseño que configures. Se pueden reproducir de inmediato y se utilizan automáticamente para sesiones archivadas automáticamente. Los archivos compuestos graban hasta 16 secuencias de vídeo simultáneas (y hasta 50 secuencias de audio).
• Archivos de flujo individuales producir un ZIP que contenga un archivo multimedia para cada flujo ( .webm o .mkv) más un manifiesto JSON. Elija esta opción si tiene previsto postprocesar o remezclar secuencias. Los archivos individuales pueden capturar hasta 50 secuencias de vídeo (y hasta 50 secuencias de audio), pero requieren un procesamiento posterior antes de la reproducción y no son compatibles con el archivado automático.
• Especifique el formato configurando outputMode a composed (por defecto) o individual cuando se llama a la API REST de archivo o a un SDK de servidor. La comparación que figura a continuación amplía las diferencias.

Duración de la grabación del archivo

La duración máxima registrada de una grabación de archivo es de 4 horas (14.400 segundos). Esta duración grabada se refiere al tiempo acumulado en el que se publican (y se graban) las secuencias.

Mientras se publican (y graban) las secuencias, el estado del archivo se establece en "started". (Véase Cambios en el estado del archivo).

Mientras un archivo está grabando sin ningún flujo publicado, el estado se establece en "paused".

El máximo total La duración de una grabación de archivo, incluidos los estados "iniciado" y "pausado", es de 12 horas (43.200 segundos). Las grabaciones caducan automáticamente (y dejan de grabarse) tras 1 hora (3.600 segundos) de inactividad (cuando no hay clientes publicando secuencias).

Notas:

• Sesiones archivadas automáticamente dar lugar a una o varias grabaciones consecutivas, de una duración máxima de 4 horas cada una.
• Los archivos en curso finalizan durante la rotación del servidor (a excepción de los archivos automáticos, que se reinician automáticamente cuando la sesión migra durante la rotación del servidor). Puede reiniciar archivos en respuesta a eventos de notificación de rotación del servidor. Véase Rotación de servidores y migración de sesiones.

Almacenamiento de grabaciones de archivo

Utiliza tu Cuenta de Vonage para especificar un destino al que cargar los ficheros de grabación de archivo finalizados.

Puede ser su propio bucket de Amazon S3, un bucket de un proveedor de almacenamiento compatible con S3 que no sea Amazon o un contenedor de Windows Azure.

Para proveedores de almacenamiento compatibles con S3 distintos de Amazon S3, admitimos Cloudian y Google Cloud Storage (a los que se accede mediante la API de AWS S3). Otros servicios compatibles con S3 pueden tener limitaciones de funciones.

Véase Uso del almacenamiento S3 con el archivado de Vonage Video API y Uso de un contenedor de Windows Azure con archivo de Video API de Vonage.

Cuando finalice la grabación del archivo (el cambio de estado de grabación del archivo se establece en "stopped"), intentaremos cargar el archivo de grabación en el destino especificado (por ejemplo, un archivo Cubo S3 o Contenedor Azure) durante un máximo de 72 horas después de la creación de la grabación de archivo (o al menos 6 horas si está activada la función fallback), reintentándolo varias veces mediante una política de programación de carga distribuida.

Si la carga en el destino especificado se realiza correctamente, el estado de grabación del archivo se establece en "uploaded".

Si no define un Cubo de Amazon S3 o Contenedor Azureo si falla la carga al bucket/contenedor especificado (después de reintentos), los archivos grabados están disponibles para su descarga desde la nube de Vonage. En tal caso, el estado de grabación del archivo se establece en "available". Los archivos disponibles en la nube de Vonage pueden descargarse durante 72 horas desde el momento de su creación. También recibirás un email informando la falla en la carga a la dirección de email que figura en tu Account de Vonage.

Para evitar el almacenamiento alternativo en la nube de Vonage, inicia sesión en tu Cuenta de VonageDirígete a Applications > Select your video application y establece la opción para desactivar la opción de almacenamiento de grabación de archivos.

Si la carga en el destino especificado falla (después de intentos de reintento) y se desactiva la recuperación en el almacenamiento de Vonage, el estado de grabación del archivo se establece en "failed".

No podrás acceder a la grabación de archivo hasta que esté cargada en el destino especificado o disponible en el almacenamiento de Vonage.

En el caso de los archivos almacenados en la nube de Vonage, la URL de descarga se proporciona en el archivo url de la grabación de archivo cuando el estado se establece en "available".

Cada URL de descarga utilizada con el almacenamiento alternativo de grabaciones de archivo es una URL pre-firmada que utiliza credenciales de seguridad para conceder permiso limitado en el tiempo para descargar el archivo.

Transcurridos 10 minutos, la URL prefirmada caducará y deberá solicitarse una nueva URL prefirmada mediante la API REST o el método del servidor para recuperar la URL de descarga.

Por motivos de seguridad, la URL de descarga sólo está disponible al realizar las llamadas a la API REST o los métodos del SDK del servidor para archivos de listados (que requieren las credenciales de su Account).

Archivos sólo audio y sólo vídeo

Cuando creas una grabación de archivo usando uno de los SDK de Vonage Video Server, puedes especificar si se grabará audio, video o ambos. (El valor predeterminado es grabar ambos).

Flujo individual y archivos compuestos

El fichero de salida de la grabación de archivo puede tener uno de los siguientes formatos:

Elige el archivo compuesto cuando quieras que Vonage entregue un MP4 reproducible tan pronto como finalice la grabación. Elige archivos de transmisión individuales cuando necesites capturas de transmisión sin procesar para edición, cumplimiento o experiencias de reproducción personalizadas.

Archivos compuestos

La grabación de archivo es un único fichero MP4 compuesto por todas las secuencias. Esta es la configuración por defecto. También se utiliza para sesiones archivadas automáticamente.

El archivo MP4 utiliza vídeo H.264 y audio AAC (a 128 Kbps y una frecuencia de muestreo de 48 Khz).

Puede personalizar el diseño de un archivo compuesto, ajustando la disposición visual de los flujos y qué flujos se muestran. Consulte Personalización del diseño de vídeo para archivos compuestos.

Por defecto, los archivos compuestos tienen una resolución de 640x480 píxeles (SD horizontal). Para que un archivo compuesto tenga una resolución de 480x640 (SD vertical), 1280x720 (HD horizontal), 720x1280 (HD vertical), 1920x1080 (FHD horizontal), 1080x1920 (FHD vertical), defina el parámetro resolution propiedad a 480x640, 1280x720, 1920x1080, 720x1280o 1080x1920 al llamar al método de inicio de archivo del SDK del servidor de video de Vonage. Es posible que desees utilizar una relación de aspecto vertical al grabar archivos que incluyan transmisiones de video desde dispositivos móviles (que a menudo utilizan la relación de aspecto vertical).

Puedes establecer la tasa de bits de vídeo máxima de una grabación de archivo compuesta para controlar el tamaño del archivo. Ajusta la maxBitrate al llamar a la función crear nuevo archivo método. Especifique un bitrate, en bits por segundo, entre 100.000 y 6.000.000. Este ajuste sólo se aplica a la vídeo bitrate del archivo. Si el archivo de salida tiene audio, esos bits se excluirán del límite. Esta opción sólo está disponible para archivos compuestos (no para archivos de flujos individuales). Cuando se establece la tasa de bits máxima, el archivo utiliza una tasa de bits constante.

Puedes establecer el parámetro de cuantización (QP) para un archivo compuesto, para ajustar el compromiso entre la calidad de vídeo y el tamaño del archivo. Establece el quantizationParameter al llamar a la función crear nuevo archivo método. El ajuste del parámetro de cuantización hace que el archivo utilice una tasa de bits variable y una cuantización de compresión constante, lo que resulta en un nivel de calidad consistente a través de los cambios de escena. Los valores válidos van de 15 a 40, y de 20 a 30 producen resultados razonables sin una gran diferencia de calidad perceptiva. Los valores de QP más bajos producen una cuantización de compresión de vídeo más fina, lo que resulta en una mayor calidad de vídeo (conservando más detalles de vídeo) y un mayor tamaño de archivo. Los valores de QP más altos producen una cuantización de compresión de vídeo más gruesa, disminuyendo la calidad de vídeo y dando como resultado un tamaño de archivo más pequeño. No es posible ajustar ambos valores de quantizationParameter y la propiedad maxBitrate ya que, de lo contrario, se produce un error.

Nota: Actualmente, la configuración del parámetro de cuantización sólo está disponible en la API REST, no en los SDK del servidor de la Video API de Vonage.

Por defecto, si no se establece quantizationParameter o maxBitrate al crear un archivo compuesto, el archivo utiliza una codificación de velocidad de bits variable con un parámetro de cuantización de 19 (muy alta calidad).

Grabaciones de archivos de flujo individuales

El archivo es un archivo contenedor ZIP con varios archivos multimedia individuales para cada flujo y un archivo de metadatos JSON para la sincronización de vídeo.

Puedes especificar este formato cuando utilices uno de los SDK del servidor de video de Vonage para iniciar el archivo. Este formato no está disponible para sesiones archivadas automáticamente.

Trabajar con grabaciones de archivo de flujos individuales

El modo de archivo de flujo individual está pensado para su uso con una herramienta de postprocesamiento, para producir contenidos personalizados generados por su aplicación. Los desarrolladores deben tener en cuenta algunas consideraciones a la hora de utilizar esta función.

Contenedores individuales

Los soportes de archivo de flujo individuales se entregan como un archivo ZIP, que contiene archivos para cada flujo de audio-vídeo:

• Cada contenedor de flujo en el archivo corresponde a un flujo publicado en la plataforma de vídeo de Vonage. El ID de flujo del editor coincide con su nombre de archivo correspondiente, y cada ID de flujo se declara en el archivo manifiesto de archivo.

Cuando un flujo se interrumpe y se reanuda debido a una reconexión automática o cuando un flujo se añade y se elimina repetidamente en un modo de flujo manual archivoel archivo ZIP incluirá archivos separados para cada uno de los segmentos individuales del flujo.

• Los contenedores de flujo son del tipo .webmo .mkvdependiendo de la configuración de su aplicación. Archivos para aplicaciones que tienen VP8 establecido como el códec de vídeo preferido tienen webm y las aplicaciones que tienen H.264 como códec de vídeo preferido utilizan la opción mkv formato. Véase Notas sobre el archivado con vídeos VP9 para más detalles importantes sobre el vídeo VP9 en indivi

• Los contenedores de archivo de flujo individual son una captura de todo el vídeo y audio recibidos por el servidor de archivo. Estos medios no se procesan, por lo que en la mayoría de los casos el contenedor no es apto para la reproducción directa.

El contenedor de flujo se trata como un flujo de transporte: todos los medios recibidos en el servidor de archivo se escriben directamente en el archivo, sin inspección ni procesamiento posterior. Este diseño tiene implicaciones para el consumo posterior de los contenedores de flujo. En la mayoría de los casos, la reproducción directa de un contenedor de archivo de flujo individual no será posible, o tendrá problemas debido al contenido del contenedor:

• Las dimensiones declaradas para la cabecera del flujo rara vez son correctas. Actualmente, las cabeceras del contenedor mostrarán una pista de vídeo con dimensiones de 640x480 píxeles, independientemente de las dimensiones de los fotogramas de vídeo codificados.

• Las dimensiones de los fotogramas de vídeo cambian con el tiempo. Esto también puede incluir cambios en la relación de aspecto, sobre todo con los flujos de pantalla compartida.

• Es posible que los fotogramas de audio y vídeo no lleguen con marcas de tiempo monótonas; las frecuencias de fotogramas no siempre son coherentes. Esto es especialmente relevante si la pista de vídeo o de audio se desactiva durante un tiempo, utilizando una de las siguientes opciones publishVideo o publishAudio propiedades del editor.

Las marcas de tiempo de presentación de fotogramas (PTS) se escriben basándose en las marcas de tiempo NTP tomadas en el momento de la captura, desplazadas por la marca de tiempo del primer fotograma recibido. Incluso si una pista se silencia y se vuelve a silenciar más tarde, el desfase de la marca de tiempo debe permanecer constante durante todo el flujo. Al descodificar en el postprocesado, existirá un espacio en PTS entre fotogramas consecutivos mientras dure el silenciamiento de la pista: no hay fotogramas "silenciosos" en el contenedor.

Para producir contenidos visibles a partir de archivos de secuencias individuales, es necesario pasar los medios por un postprocesador para reparar los contenedores de secuencias individuales o multiplexar/componer varios contenedores en un producto final.

Manifiesto de grabación de flujo individual

Los archivos de flujo individuales incluyen un archivo de metadatos JSON, que proporciona información sobre las grabaciones de flujo incluidas en el archivo. Tiene el siguiente formato:

{
  "createdAt" : 1429305105162,
  "files" : [
    {
      "connectionData" : "connection data for this stream's connection",
      "filename" : "a1475893-99f5-4f02-b697-5d69e8e30d19.webm",
      "size" : 5558064,
      "startTimeOffset" : 3119,
      "stopTimeOffset" : 48765,
      "streamId" : "a1475893-99f5-4f02-b697-5d69e8e30d19",
      "videoType": "camera"
    },
    {
      "connectionData" : "connection data for this stream's connection",
      "filename" : "5ab71b7b-d998-4683-ad2b-7769d6533666.webm",
      "size" : 5396527,
      "startTimeOffset" : 2799,
      "stopTimeOffset" : 48764,
      "streamId" : "5ab71b7b-d998-4683-ad2b-7769d6533666",
      "videoType": "screen"
    }
  ],
  "id" : "297b9c62-78b3-4152-9e98-7e167354c9e6",
  "name" : "archive name",
  "partnerId" : 123456,
  "sessionId" : "2_MX4xMDB-fjE0MjkzMDQ3NzY3NTZ-WUpRUGVFUmhFSkRmVGljeU5zVnJpaXYxfn4"
}

Selección de los flujos que se incluirán en un archivo

Cuando se inicia un archivo, si se establece la opción streamMode a manualpuede elegir los flujos que desea incluir en el archivo.

Puedes añadir y eliminar secuencias durante la grabación de archivo. Y puedes especificar si la grabación de archivo incluirá el audio o el vídeo de un flujo (o ambos).

De lo contrario, con el streamMode ajustado a auto (valor predeterminado), se incluyen todas las secuencias (con audio y vídeo) en el archivo. Consulte Inicio de una grabación de archivo y Selección de secuencias que se incluirán en un archivo.

Sin embargo, en un archivo compuesto hay un límite de 16 secuencias de vídeo y 50 secuencias de audio incluidas a la vez (para los modos de secuencia automática y manual), y las secuencias se incluyen en función de normas de priorización de flujos. Para los archivos en modo de flujo manual, las actualizaciones de flujo se envían como Cambios en el estado del archivo.

Sesiones de grabación archivadas automáticamente

Puedes hacer que una sesión se archive automáticamente especificando esto cuando creas la sesión, usando uno de los SDK del servidor de Vonage Video.

El archivo de una sesión archivada automáticamente se inicia en cuanto un cliente se conecta a la sesión.

Las sesiones archivadas automáticamente incluyen tanto audio como vídeo, y graban todas las secuencias en el mismo archivo MP4 (compuesto).

Sin embargo, si la grabación dura más de 4 horas (14.400 segundos), la sesión se graba en varios archivos MP4 consecutivos, de hasta 4 horas de duración cada uno, hasta que se detiene la grabación. Los archivos automáticos consecutivos de una sesión se solaparán ligeramente, para que no se pierda ningún dato grabado.

Puedes llamar al método del SDK del lado del servidor de Vonage Video para listar el archivo y pasar el archivo sessionID para listar los archivos de un ID de sesión especificado.

A continuación, puede determinar la secuencia de los distintos archivos MP4 consultando el archivo createdAt de cada archivo enumerado en los datos JSON devueltos.

No se puede detener un archivo automático utilizando los SDK del servidor. Los archivos automáticos se detienen 60 segundos después de que el último cliente se desconecte de la sesión o 60 minutos después de que el último cliente deje de publicar un flujo en la sesión.

Debe evitar estrictamente la reutilización de identificadores de sesión si va a utilizar el archivado automático. La reutilización de un ID de sesión puede hacer que los archivos automáticos fallen si un archivo automático anterior para la sesión ha caducado.

No utilice archivos automáticos para sesiones de corta duración, como las que se utilizan para pruebas previas a la llamada o de conectividad. Se le facturará el uso excesivo de recursos de archivo, ya que los archivos automáticos se detienen 60 segundos después de que el último cliente se desconecte de la sesión o 60 minutos después de que el último cliente deje de publicar un flujo en la sesión (si el cliente sigue conectado después de publicar).

Tratamiento posterior de archivos compuestos

Las grabaciones de archivos de vídeo tienen un duración de la grabación del archivo de hasta 4 horas y 14.400 segundos. Por lo tanto, una sesión de vídeo más larga no se grabará en un único fichero de archivo. Para evitar perder una parte de la sesión, utilice la opción sesiones archivadas automáticamente que permite generar varios ficheros para cubrir toda la sesión. También puede utilizar la función archivos simultáneos para iniciar una segunda grabación antes de finalizar la anterior. En ambos casos, estos archivos se generan con un breve solapamiento entre el final de un archivo y el principio del siguiente.

Si prefiere disponer de un único archivo que contenga toda la sesión, puede utilizar la función Posprocesamiento de archivos compuestos que fusiona grabaciones consecutivas superpuestas e intenta que la transición sea lo más suave posible desde el punto de vista perceptivo. Puede utilizar esta herramienta para generar un único archivo, aunque más largo, que contenga medios de varios archivos más cortos. Para más detalles, consulte la guía del desarrollador Postprocesado de archivos compuestos. La herramienta está disponible en https://github.com/Vonage/archive-post-processing.

También puedes utilizar esta herramienta con grabaciones de video que no hayan sido creadas como archivos de Vonage Video, siempre y cuando exista cierto solapamiento de medios y las grabaciones de vídeo cumplan una serie de características, como el uso de los códecs H264 y AAC LC para vídeo y audio respectivamente.

Grabaciones de archivo simultáneas

Para grabar varios archivos de la misma sesión simultáneamente, configure la opción multiArchiveTag al iniciar cada archivo. Debe establecer una cadena única para cada grabación de archivo simultánea de una sesión en curso.

Puedes utilizar distintos diseños y asignar distintos flujos a cada grabación de archivo simultánea.

En sesiones archivadas automáticamente, fije el multiArchiveTag para iniciar un nuevo archivo simultáneo que se archiva simultáneamente con los archivos automáticos. Los archivos automáticos se inician y finalizan cuando la sesión se inicia y se detiene por sí sola (siguiendo las reglas de los archivos automáticos), mientras que los manuales se detienen por separado.

Cambios en el estado de grabación de archivos

Puede registrar una URL de devolución de llamada para recibir una notificación cuando cambie el estado de un archivo. El estado de un archivo se establece como uno de los siguientes:

Usa tu cuenta de Vonage para especificar una URL de devolución de llamada. Cuando cambia el estado de un archivo, el servidor envía solicitudes HTTP POST a la URL que especifiques. La dirección Content-Type para la solicitud es application/json. Los datos de la solicitud son un objeto JSON de la siguiente forma:

{
    "id" : "b40ef09b-3811-4726-b508-e41a0f96c68f",
    "event": "archive",
    "createdAt" : 1384221380000,
    "duration" : 328,
    "name" : "Foo",
    "partnerId" : 123456,
    "reason" : "",
    "resolution" : "640x480",
    "sessionId" : "2_MX40NzIwMzJ-flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN-MC45NDQ2MzE2NH4",
    "size" : 18023312,
    "status" : "available",
    "url" : "https://tokbox.com.archive2.s3.amazonaws.com/123456/b40ef09b-3811-4726-b508-e41a0f96c68f/archive.mp4"
}

El objeto JSON incluye las siguientes propiedades:

También puedes ver el estado de los archivos en tu Account de Vonage:

1. Ve al panel de tu cuenta de Vonage.
2. En la lista de aplicaciones de la parte izquierda de la página, seleccione la aplicación que contendrá las sesiones que va a archivar.
3. En la sección de archivo, haga clic en la pestaña Lista de archivos. Se enumeran los detalles de los archivos de la aplicación.

Seguridad en la grabación de archivos

Puedes proteger tus archivos de las siguientes maneras:

• Desactivar la reserva de almacenamiento de grabaciones de archivo - De forma predeterminada, Vonage almacena un archivo de almacenamiento en los servidores de Vonage si no pudo cargar el archivo a tu servidor S3 o Azure especificado. Para evitar este almacenamiento alternativo (que está activado de forma predeterminada), inicia sesión en tu Account de Vonage, selecciona la aplicación y configura la opción para desactivar el almacenamiento alternativo de archivos.
• Utiliza el cifrado de Vonage - Esto te permite crear archivos de Vonage donde los datos nunca están en reposo sin encriptar. De los métodos disponibles para proteger tus grabaciones de Vonage, este ofrece el mayor nivel de seguridad. Está disponible como una función adicional. Para obtener más información, consulta la documentación sobre codificación de Vonage.
• Utilizar el cifrado del lado del servidor de Amazon S3 - Esto utiliza claves de cifrado administradas por Amazon S3 para el cifrado. Más información sobre el cifrado del lado del servidor de Amazon S3. aquí.

Combinar el archivado con Experience Composer

Es posible combinar archivo y Compositor de experiencias.