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

Puedes crear una grabación de archivo de una sesión utilizando una de las SDK de servidor. Cuando creas un archivo, comienza 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 Iniciará una nueva grabación cada 4 horas hasta que la grabación se detenga.

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 la información de las grabaciones archivadas
• Borrar un archivo

Cuando se detiene la grabación de un archivo, la plataforma de vídeo de Vonage crea un archivo MP4 o (en el caso de los archivos de transmisiones individuales) un archivo ZIP. (Véase Archivos de una sola fuente y archivos combinados.)

Eventos de cliente y traspaso de interfaz de usuario

Cuando se inicia y se detiene una grabación de archivo, se envían notificaciones a los clientes. Por ejemplo, el OpenTok.js La biblioteca incluye archiveStarted y archiveStopped enviados por el objeto Session.

Archivos compuestos frente a archivos individuales de un vistazo

• Archivos organizados 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 registran hasta 16 flujos de vídeo simultáneos (y hasta 50 flujos de audio).
• Archivos de flujo individuales crear un archivo ZIP que contenga un archivo multimedia para cada transmisión ( .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.
• Especifica 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 se refiere al tiempo acumulado durante el cual se publican (y se graban) las transmisiones.

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 tratarse de tu propio bucket de Amazon S3, de un bucket de un proveedor de almacenamiento compatible con S3 distinto de Amazon o de 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 subir el archivo de grabación al destino especificado (por ejemplo, un depósito de 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 Azure, o si falla la subida al bucket o contenedor especificado (tras varios intentos), los archivos grabados estarán disponibles para su descarga desde la nube de Vonage. En tal caso, el estado de la grabación del archivo se establece en "available". Los archivos disponibles en la nube de Vonage se pueden descargar durante 72 horas a partir del momento en que se crean. Además, recibirás un correo electrónico en el que se te informará del error de carga en la dirección de correo electrónico que figura en tu Account de Vonage.

Para evitar el almacenamiento alternativo en la nube de Vonage, inicia sesión en tu Cuenta de Vonage, ve a «Applications» > selecciona tu aplicación de vídeo y desactiva la opción de almacenamiento de grabaciones en el archivo.

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 archivada hasta que se haya subido a la ubicación que hayas indicado o esté 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 habrá que solicitar una nueva URL prefirmada mediante la API REST o el método del servidor para obtener 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 (para lo cual se necesitan las credenciales de tu 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).

Archivos de una sola fuente y archivos combinados

El archivo 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 organizados

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 los archivos compuestos.

Por defecto, los archivos compuestos tienen una resolución de 640 x 480 píxeles (SD horizontal). Para configurar un archivo compuesto con una resolución de 480 x 640 (SD vertical), 1280 x 720 (HD horizontal), 720 x 1280 (HD vertical), 1920 x 1080 (FHD horizontal) o 1080 x 1920 (FHD vertical), configura el resolution propiedad a 480x640, 1280x720, 1920x1080, 720x1280, o 1080x1920 al llamar al método «start archive» del SDK del servidor de Vonage Video. Es posible que te interese utilizar una relación de aspecto vertical al grabar archivos que incluyan transmisiones de vídeo procedentes de dispositivos móviles (que suelen utilizar la relación de aspecto vertical).

Puedes establecer la tasa de bits máxima de vídeo de una grabación en archivo compuesto para controlar el tamaño del archivo. Establece el 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 configurar el parámetro de cuantificación (QP) de un archivo compuesto para ajustar el equilibrio entre la calidad del vídeo y el tamaño del archivo. Configura el quantizationParameter al llamar a la función crear nuevo archivo método. Al establecer el parámetro de cuantificación, el archivo utiliza una tasa de bits variable y una cuantificación de compresión constante, lo que da como resultado un nivel de calidad uniforme entre los cambios de escena. Los valores válidos oscilan entre 15 y 40, y los valores comprendidos entre 20 y 30 producen resultados razonables sin una gran diferencia perceptible en la calidad. Los valores de QP más bajos producen una cuantización de compresión de vídeo más fina, lo que se traduce en una mayor calidad de vídeo (conservando más detalles) y un tamaño de archivo mayor. Los valores de QP más altos producen una cuantización de compresión de vídeo más gruesa, lo que reduce la calidad de vídeo y da lugar a un tamaño de archivo menor. No se pueden establecer a la vez el quantizationParameter y la propiedad maxBitrate ya que, de lo contrario, se produce un error.

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

Por defecto, si no se configura quantizationParameter o maxBitrate Al crear un archivo compuesto, este utiliza una codificación de velocidad de bits variable con un parámetro de cuantificación que garantiza una 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 individuales del archivo de retransmisiones

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 archivo del modo de transmisión manual, el archivo ZIP incluirá archivos independientes para cada uno de los segmentos de la transmisión.

• Los contenedores de flujo son del tipo .webm, o .mkv, dependiendo de la configuración de tu aplicación. Los archivos de las aplicaciones que tienen VP8 configurado 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 cada flujo son una grabación de todo el vídeo y el audio recibidos por el servidor de archivo. Este material multimedia no se procesa y, por lo tanto, en la mayoría de los casos el contenedor no es apto para su reproducción directa.

El contenedor de flujos se trata como un flujo de transporte: todos los contenidos multimedia recibidos en el servidor de archivo se guardan directamente en un archivo, sin inspección ni posprocesamiento. Este diseño tiene implicaciones para el consumo posterior de los contenedores de flujos. En la mayoría de los casos, la reproducción directa de un contenedor de archivo de flujo individual no será posible, o presentará 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 características de la editorial.

Las marcas de tiempo de presentación de tramas (PTS) se registran basándose en las marcas de tiempo NTP obtenidas en el momento de la captura, con un desfase respecto a la marca de tiempo de la primera trama recibida. Aunque una pista se silencie y posteriormente se desactive el silencio, el desfase de la marca de tiempo debería mantenerse constante a lo largo de toda la duración de la transmisión. Al decodificar en el posprocesado, existirá una diferencia en las PTS entre tramas consecutivas durante el tiempo que la pista haya estado silenciada: no hay tramas «silenciosas» 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 cada transmisión incluyen un archivo de metadatos en formato JSON, que proporciona información sobre las grabaciones de la transmisión 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 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 flujos durante la grabación de archivo. Además, 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 indicándolo al crearla, utilizando 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 transmisiones en un 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, de modo que no se pierda ningún dato grabado.

Puedes llamar al método del SDK del lado del servidor de Vonage Video para obtener la lista de archivos y pasarle el 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 propiedad de cada archivo que figura en los datos JSON devueltos.

No es posible detener un archivo automático mediante 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.

Debes evitar por completo reutilizar los identificadores de sesión si vas a utilizar el archivado automático. La reutilización de un identificador de sesión puede provocar que los archivados automáticos fallen si un archivado automático anterior de esa 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).

Postprocesamiento de archivos compuestos

Las grabaciones del archivo de vídeo tienen una duración de la grabación archivada 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 vídeo que no se hayan creado como archivos de Vonage Video, siempre que haya cierto solapamiento entre los archivos multimedia y que las grabaciones de vídeo cumplan una serie de características, como el uso de los códecs H264 y AAC LC para el vídeo y el 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 diferentes configuraciones y asignar diferentes señales a cada grabación simultánea en archivo.

En sesiones archivadas automáticamente, fije el multiArchiveTag Opción para iniciar un nuevo archivo simultáneo que se realice al mismo tiempo que los archivos automáticos. Los archivos automáticos comienzan 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 iniciados manualmente 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:

Utiliza tu Account de Vonage para indicar 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 indiques. El Content-Type para la solicitud es application/json. Los datos de la solicitud son un objeto JSON con el siguiente formato:

{
    "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 que aparece a la izquierda de la página, selecciona la aplicación que contenga las sesiones que deseas archivar.
3. En la sección de archivado, haz clic en la pestaña «Lista de archivos». Se muestran 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 respaldo en sus servidores si no ha podido cargar el archivo en el servidor S3 o Azure que hayas especificado. Para evitar este almacenamiento de respaldo (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 de respaldo.
• 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 — Para el cifrado se utilizan claves de cifrado gestionadas por Amazon S3. 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 Experiencia con Composer.