Iniciando uma gravação de arquivo com a Video API

A Video API da Vonage permite arquivar, salvar e recuperar sessões.

Fluxo de trabalho básico

Fluxo de trabalho principal para gravação

Você pode criar uma gravação de arquivo para uma sessão usando uma das SDKs de servidor. Ao criar um arquivo, a gravação começa.

Só é possível criar um arquivo para sessões que tenham pelo menos um cliente conectado. (O cliente deve começar a transmitir o stream em até um minuto; caso contrário, a gravação do arquivo será interrompida.)

À medida que os clientes iniciam e interrompem a publicação de fluxos, esses fluxos são gravados.

Não há limite para o número de arquivos que você pode gravar; no entanto, sessões arquivadas automaticamente iniciará uma nova gravação a cada 4 horas até que a gravação seja interrompida.

Os SDKs do servidor incluem métodos para o seguinte:

• Iniciando uma gravação de arquivo
• Interromper uma gravação em arquivo
• Listagem de gravações de arquivo
• Recuperação de informações sobre gravações arquivadas
• Excluindo um arquivo

Quando você interrompe a gravação de um arquivo, a plataforma de vídeo da Vonage cria um arquivo MP4 ou (no caso de arquivos de transmissões individuais) um arquivo ZIP. (Veja Arquivos individuais e arquivos compostos.)

Eventos do cliente e transferência da interface do usuário

Quando uma gravação de arquivo é iniciada e encerrada, são emitidos eventos nos clientes. Por exemplo, o OpenTok.js a biblioteca inclui archiveStarted e archiveStopped eventos disparados pelo objeto Session.

Comparação rápida entre arquivos compostos e individuais

• Arquivos organizados são as configurações padrão. A Vonage gera um único arquivo MP4 (H.264/AAC) utilizando todos os fluxos publicados e as regras de layout que você configurar. Esses arquivos podem ser reproduzidos imediatamente e são usados automaticamente para sessões arquivadas automaticamente. Os arquivos compostos registram até 16 fluxos de vídeo simultâneos (e até 50 fluxos de áudio).
• Arquivos de transmissões individuais gerar um arquivo ZIP que contenha um arquivo de mídia para cada stream ( .webm ou .mkv) além de um manifesto JSON. Escolha essa opção quando pretender realizar o pós-processamento ou a remistura de fluxos. Os arquivos individuais podem capturar até 50 fluxos de vídeo (e até 50 fluxos de áudio), mas exigem processamento posterior antes da reprodução e não são compatíveis com o arquivamento automático.
• Especifique o formato definindo outputMode para composed (padrão) ou individual ao chamar a API REST de arquivamento ou um SDK de servidor. A comparação a seguir detalha essas diferenças.

Duração da gravação arquivada

A duração máxima registrada de uma gravação de arquivo é de 4 horas (14.400 segundos). Essa duração se refere ao tempo acumulado durante o qual as transmissões são publicadas (e estão sendo gravadas).

Enquanto as transmissões estão sendo publicadas (e gravadas), o status do arquivo é definido como "started". (Veja Alterações no status do arquivo).

Enquanto um arquivo estiver gravando sem nenhuma transmissão publicada, o status é definido como "paused".

O máximo total A duração de uma gravação em arquivo, incluindo os estados “iniciada” e “em pausa”, é de 12 horas (43.200 segundos). As gravações expiram automaticamente (e param de gravar) após 1 hora (3.600 segundos) de inatividade (quando nenhum cliente está publicando transmissões).

Notas:

• Sessões arquivadas automaticamente resultar em uma ou mais gravações consecutivas, cada uma com duração máxima de 4 horas.
• Os arquivamentos em andamento são encerrados durante a rotação de servidores (com exceção dos arquivamentos automáticos, que são reiniciados automaticamente quando a sessão é migrada durante a rotação de servidores). É possível reiniciar os arquivamentos em resposta a eventos de notificação de rotação de servidores. Consulte Rotação de servidores e migração de sessões.

Armazenamento de gravações de arquivo

Use seu Account da Vonage para especificar um destino para o qual os arquivos de gravação arquivados devem ser enviados.

Pode ser seu próprio bucket do Amazon S3, um bucket em um provedor de armazenamento compatível com o S3 que não seja a Amazon ou um contêiner do Windows Azure.

Para provedores de armazenamento compatíveis com S3 que não sejam o Amazon S3, oferecemos suporte ao Cloudian e ao Google Cloud Storage (acessados por meio da API do AWS S3). Outros serviços compatíveis com S3 podem apresentar limitações de recursos.

Veja utilização do armazenamento S3 com o recurso de arquivamento da Video API da Vonage e utilizando um contêiner do Windows Azure com o recurso de arquivamento da Video API da Vonage.

Quando a gravação para arquivo estiver concluída (a alteração no status da gravação no arquivo está definido como "stopped"), tentaremos enviar o arquivo de gravação para o destino especificado (como, por exemplo, um bucket do S3 ou Contêiner do Azure) por até 72 horas após a criação da gravação de arquivo (ou pelo menos 6 horas, se o mecanismo de fallback estiver ativado), com várias tentativas por meio de uma política de agendamento de upload distribuído.

Se o envio para o destino especificado for bem-sucedido, o status da gravação do arquivo é definido como "uploaded".

Se você não definir um Bucket do Amazon S3 ou Contêiner do Azure, ou se o envio para o bucket/contêiner especificado falhar (após tentativas de recuperação), os arquivos gravados estarão disponíveis para download na nuvem da Vonage. Nesse caso, o status da gravação do arquivo é definido como "available". Os arquivos disponibilizados na nuvem da Vonage podem ser baixados por 72 horas a partir do momento em que são criados. Você também receberá um e-mail informando a falha no envio no endereço de e-mail cadastrado na sua Account da Vonage.

Para evitar o armazenamento de contingência na nuvem da Vonage, faça login na sua Account da Vonage, acesse Applications > Selecione seu aplicativo de vídeo e desative a opção de armazenamento de gravações em arquivo.

Se o upload para o destino especificado falhar (após as tentativas de repetição) e o recurso de fallback para o armazenamento da Vonage estiver desativado, o status da gravação arquivada será definido como "failed".

Você não poderá acessar a gravação arquivada até que ela seja enviada para o destino especificado ou esteja disponível no armazenamento da Vonage.

Para arquivos armazenados na nuvem da Vonage, o URL de download é fornecido no url propriedade da gravação arquivada quando o status está definido como "available".

Cada URL de download utilizada com o recurso de armazenamento de gravações em arquivo de emergência é uma URL pré-assinada que utiliza credenciais de segurança para conceder permissão por tempo limitado para baixar o arquivo.

Após 10 minutos, a URL pré-assinada expirará e será necessário solicitar uma nova URL pré-assinada por meio da API REST ou do método do servidor para obter a URL de download.

Por motivos de segurança, a URL de download só está disponível por meio de chamadas à API REST ou aos métodos do SDK do servidor para arquivos de listagens (que exigem as credenciais da sua conta).

Arquivos apenas de áudio e apenas de vídeo

Ao criar uma gravação em arquivo usando um dos SDKs do Vonage Video Server, você pode especificar se ela gravará áudio, vídeo ou ambos. (O padrão é gravar ambos.)

Arquivos individuais e arquivos compostos

O arquivo de saída da gravação de arquivo pode estar em um dos seguintes formatos:

Escolha o arquivamento composto quando quiser que a Vonage forneça um arquivo MP4 pronto para reprodução assim que a gravação terminar. Escolha arquivos de stream individuais quando precisar de capturas de stream em formato bruto para edição, conformidade ou experiências de reprodução personalizadas.

Arquivos organizados

A gravação de arquivo é um único arquivo MP4 que reúne todos os fluxos. Essa é a configuração padrão. Ela também é usada para sessões arquivadas automaticamente.

O arquivo MP4 utiliza vídeo H.264 e áudio AAC (a 128 Kbps e uma taxa de amostragem de 48 kHz).

É possível personalizar o layout de um arquivo composto, ajustando a disposição visual dos fluxos e quais fluxos são exibidos. Consulte Personalização do layout do vídeo para arquivos compostos.

Por padrão, os arquivos compostos têm uma resolução de 640x480 pixels (SD na orientação paisagem). Para definir um arquivo composto com resolução de 480x640 (SD retrato), 1280x720 (HD paisagem), 720x1280 (HD retrato), 1920x1080 (FHD paisagem) ou 1080x1920 (FHD retrato), defina o resolution propriedade para 480x640, 1280x720, 1920x1080, 720x1280, ou 1080x1920 ao chamar o método “start archive” do SDK do servidor Vonage Video. Recomenda-se usar a proporção retrato ao gravar arquivos que incluam fluxos de vídeo de dispositivos móveis (que geralmente utilizam a proporção retrato).

É possível definir a taxa de bits máxima de vídeo de uma gravação em arquivo composto para controlar o tamanho do arquivo. Defina a maxBitrate opção ao chamar o criar novo arquivo método. Especifique uma taxa de bits, em bits por segundo, entre 100.000 e 6.000.000. Essa configuração se aplica apenas ao vídeo taxa de bits do arquivo. Se o arquivo de saída contiver áudio, esses bits serão excluídos do limite. Essa opção está disponível apenas para arquivos compostos (não para arquivos de fluxo individuais). Ao definir a taxa de bits máxima, o arquivo utiliza uma taxa de bits constante.

É possível definir o parâmetro de quantização (QP) para um arquivo composto, a fim de ajustar o equilíbrio entre a qualidade do vídeo e o tamanho do arquivo. Defina o quantizationParameter opção ao chamar o criar novo arquivo método. A configuração do parâmetro de quantização faz com que o arquivo utilize uma taxa de bits variável e uma quantização de compressão constante, resultando em um nível de qualidade consistente mesmo entre mudanças de cena. Os valores válidos variam de 15 a 40, e os valores entre 20 e 30 produzem resultados razoáveis sem uma grande diferença perceptível na qualidade. Valores mais baixos de QP produzem uma quantização de compressão de vídeo mais fina, resultando em maior qualidade de vídeo (retendo mais detalhes) e um tamanho de arquivo maior. Valores mais altos de QP produzem uma quantização de compressão de vídeo mais grosseira, diminuindo a qualidade do vídeo e resultando em um tamanho de arquivo menor. Não é possível definir tanto o quantizationParameter propriedade e o maxBitrate propriedade — isso gera um erro.

Observação: Atualmente, a configuração do parâmetro de quantização está disponível apenas na API REST, e não nos SDKs de servidor da Video API da Vonage.

Por padrão, se você não definir quantizationParameter ou maxBitrate Ao criar um arquivo composto, o arquivo utiliza codificação com taxa de bits variável e um parâmetro de quantização que garante alta qualidade.

Gravações individuais do arquivo de transmissões

O arquivo é um arquivo ZIP que contém vários arquivos de mídia individuais para cada transmissão, além de um arquivo de metadados em formato JSON para sincronização de vídeo.

É possível especificar esse formato ao usar um dos SDKs do servidor Vonage Video para iniciar o arquivamento. Esse formato não está disponível para sessões arquivadas automaticamente.

Trabalhando com gravações individuais do arquivo de transmissões

O modo de arquivamento individual de fluxos destina-se ao uso com uma ferramenta de pós-processamento, para produzir conteúdo personalizado gerado pelo seu aplicativo. Há algumas considerações que os desenvolvedores devem levar em conta ao optar por utilizar esse recurso.

Contêineres de fluxo individuais

Os arquivos de mídia de cada fluxo são fornecidos como um arquivo ZIP, contendo os arquivos de cada fluxo de áudio e vídeo:

• Cada contêiner de stream no arquivo corresponde a um stream publicado na plataforma de vídeo da Vonage. O ID do stream do editor corresponde ao nome do arquivo respectivo, e cada ID de stream é declarado no manifesto do arquivo.

Quando um fluxo é interrompido e retomado devido à reconexão automática ou quando um fluxo é adicionado e removido repetidamente em um arquivo do modo de transmissão manual, o arquivo ZIP incluirá arquivos separados para cada um dos segmentos individuais do stream.

• Os contêineres de fluxo podem ser do tipo .webm, ou .mkv, dependendo da configuração do seu aplicativo. Arquivos de aplicativos que têm o VP8 definido como o codec de vídeo preferido ter webm contêineres e aplicativos que têm o H.264 definido como o codec de vídeo preferencial utilizam o mkv formato. Veja Observações sobre o arquivamento de vídeos em VP9 para mais detalhes importantes sobre o vídeo VP9 em indivi

• Os contêineres de arquivo de cada fluxo contêm toda a captura de vídeo e áudio recebida pelo servidor de arquivo. Esses arquivos de mídia não são processados e, portanto, na maioria dos casos, o contêiner não é adequado para reprodução direta.

O contêiner de stream é tratado como um stream de transporte — todo o conteúdo de mídia recebido no servidor de arquivo é gravado diretamente em um arquivo, sem inspeção ou pós-processamento. Esse projeto tem implicações para o consumo posterior dos contêineres de stream. Na maioria dos casos, a reprodução direta de um contêiner de arquivo de stream individual não será possível ou apresentará problemas devido ao conteúdo do contêiner:

• As dimensões declaradas para o cabeçalho do stream raramente estão corretas. Atualmente, os cabeçalhos do contêiner exibem uma trilha de vídeo com dimensões de 640x480 pixels, independentemente das dimensões dos quadros de vídeo codificados.

• As dimensões dos quadros de vídeo podem variar com o tempo. Isso também pode incluir alterações na proporção da imagem, especialmente em transmissões com compartilhamento de tela.

• Os quadros de áudio e vídeo podem não chegar com carimbos de data/hora monotônicos; as taxas de quadros nem sempre são consistentes. Isso é especialmente relevante se a trilha de vídeo ou de áudio for desativada por algum tempo, utilizando uma das publishVideo ou publishAudio propriedades da editora.

Os carimbos de tempo de apresentação dos quadros (PTS) são gravados com base nos carimbos de tempo NTP obtidos no momento da captura, com um deslocamento em relação ao carimbo de tempo do primeiro quadro recebido. Mesmo que uma faixa seja silenciada e posteriormente reativada, o deslocamento do carimbo de data/hora deve permanecer consistente durante toda a duração do stream. Ao decodificar no pós-processamento, haverá uma lacuna no PTS entre quadros consecutivos durante o período em que a faixa estiver silenciada: não há quadros “silenciosos” no contêiner.

Para produzir conteúdo exibível a partir de arquivos individuais de arquivamento de fluxos, é necessário processar a mídia por meio de um pós-processador para reparar contêineres de fluxo individuais ou multiplexar/compor vários contêineres em um produto final.

Manifesto de gravação de stream individual

Os arquivos de transmissões individuais incluem um arquivo de metadados em formato JSON, que fornece informações sobre as gravações das transmissões incluídas no arquivo. Ele tem o seguinte 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"
}

Seleção dos fluxos a serem incluídos em um arquivo

Ao iniciar um arquivo, se você definir o streamMode para manual, você pode escolher os fluxos a serem incluídos no arquivo.

É possível adicionar e remover transmissões durante a gravação de arquivo. Além disso, é possível especificar se a gravação de arquivo incluirá o áudio ou o vídeo de uma transmissão (ou ambos).

Caso contrário, com o streamMode definir como auto (por padrão), todas as transmissões são incluídas (com áudio e vídeo) no arquivo. Consulte “Iniciando uma gravação de arquivo” e “Selecionando transmissões a serem incluídas em um arquivo”.

No entanto, em um arquivo criado, há um limite de 16 fluxos de vídeo e 50 fluxos de áudio incluídos ao mesmo tempo (tanto para o modo automático quanto para o modo manual), e os fluxos são incluídos com base em regras de priorização de fluxos. Para arquivos no modo de stream manual, as atualizações do stream são enviadas como Alterações no status do arquivo.

Sessões de gravação arquivadas automaticamente

É possível fazer com que uma sessão seja arquivada automaticamente, especificando essa opção ao criá-la, usando um dos SDKs do servidor Vonage Video.

O arquivamento de uma sessão arquivada automaticamente começa assim que um cliente se conecta à sessão.

As sessões arquivadas automaticamente incluem áudio e vídeo, e gravam todos os fluxos no mesmo arquivo MP4 (composto).

No entanto, se a gravação durar mais de 4 horas (14.400 segundos), a sessão será gravada em vários arquivos MP4 consecutivos, com duração de até 4 horas cada, até que a gravação seja interrompida. Os arquivos automáticos consecutivos de uma sessão se sobreporão ligeiramente, de modo que nenhum dado gravado seja perdido.

Você pode chamar o método do SDK do lado do servidor do Vonage Video para listar o arquivo e passar o sessionID parâmetro para listar arquivos de uma sessão com um ID especificado.

Você pode, então, determinar a sequência dos arquivos MP4 individuais, verificando o createdAt propriedade de cada arquivo listado nos dados JSON retornados.

Não é possível interromper um arquivamento automático usando os SDKs do servidor. Os arquivamentos automáticos são interrompidos 60 segundos após o último cliente se desconectar da sessão ou 60 minutos após o último cliente parar de publicar um stream na sessão.

Você deve evitar rigorosamente reutilizar IDs de sessão caso pretenda utilizar o arquivamento automático. A reutilização de um ID de sessão pode fazer com que os arquivamentos automáticos falhem caso um arquivamento automático anterior para essa sessão tenha expirado.

Não utilize arquivamentos automáticos para sessões de curta duração, como aquelas utilizadas para testes pré-chamada ou de conectividade. Você será cobrado pelo uso excessivo de recursos de arquivamento, pois os arquivamentos automáticos são interrompidos 60 segundos após o último cliente se desconectar da sessão ou 60 minutos após o último cliente parar de publicar um stream na sessão (caso o cliente permaneça conectado após a publicação).

Pós-processamento de arquivos compactados

As gravações do arquivo de vídeo têm um duração da gravação arquivada de até 4 horas, ou seja, 14.400 segundos. Portanto, uma sessão de vídeo mais longa não será gravada em um único arquivo. Para evitar a perda de parte da sessão, use o sessões arquivadas automaticamente recurso, que permite a geração de vários arquivos para abranger toda a sessão. Como alternativa, use o arquivos simultâneos recurso que permite iniciar uma segunda gravação antes de encerrar a gravação anterior. Em ambos os casos, esses arquivos são gerados com uma breve sobreposição entre o final de um arquivo e o início do próximo.

Se você preferir ter um único arquivo contendo toda a sessão, pode usar o Pós-processamento de arquivos compostos ferramenta que une gravações consecutivas que se sobrepõem e tenta tornar a transição o mais suave possível do ponto de vista perceptivo. Você pode usar essa ferramenta para gerar um único arquivo, porém mais longo, que contenha o conteúdo de vários arquivos de arquivo mais curtos. Para mais detalhes, consulte o guia do desenvolvedor Pós-processamento de arquivos compostos. A ferramenta está disponível em https://github.com/Vonage/archive-post-processing.

Você também pode usar essa ferramenta com gravações de vídeo que não tenham sido criadas como arquivos do Vonage Video, desde que haja alguma sobreposição de mídia e que as gravações de vídeo atendam a uma série de características, como o uso dos codecs H264 e AAC LC para vídeo e áudio, respectivamente.

Gravações simultâneas para arquivo

Para gravar vários arquivos da mesma sessão simultaneamente, defina o multiArchiveTag opção ao iniciar cada arquivamento. É necessário definir uma sequência de caracteres exclusiva para cada gravação simultânea de uma sessão em andamento.

Você pode usar diferentes layouts e atribuir diferentes fluxos a cada gravação simultânea em arquivo.

Em sessões arquivadas automaticamente, defina o multiArchiveTag opção para iniciar um novo arquivamento simultâneo que ocorra ao mesmo tempo que os arquivamentos automáticos. Os arquivamentos automáticos começam e terminam automaticamente quando a sessão é iniciada e encerrada (seguindo as regras dos arquivamentos automáticos), enquanto os iniciados manualmente são encerrados separadamente.

Arquivar alterações no status das gravações

Você pode registrar uma URL de retorno de chamada para receber uma notificação quando o status de um arquivo for alterado. O status de um arquivo pode ser um dos seguintes:

Use sua conta da Vonage para definir uma URL de retorno de chamada. Quando o status de um arquivo for alterado, o servidor enviará solicitações HTTP POST para a URL que você definir. O Content-Type pois a solicitação é application/json. Os dados da solicitação são um objeto JSON com o seguinte 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"
}

O objeto JSON inclui as seguintes propriedades:

Você também pode verificar o status dos arquivos na sua Account da Vonage:

1. Acesse o painel do seu Account da Vonage.
2. Na lista de applications à esquerda da página, selecione o application que conterá as sessões que você deseja arquivar.
3. Na seção de arquivamento, clique na guia “Lista de arquivos”. São exibidos os detalhes dos arquivos no aplicativo.

Segurança na gravação de arquivos

Você pode proteger seus arquivos das seguintes maneiras:

• Desativar o recurso de armazenamento de gravações em arquivo como alternativa — Por padrão, a Vonage armazena um arquivo de backup nos servidores da Vonage caso não consiga fazer o upload do arquivo para o servidor S3 ou Azure especificado por você. Para desativar esse armazenamento de backup (que vem habilitado por padrão), faça login na sua Account da Vonage, selecione o aplicativo e configure a opção para desativar o armazenamento de backup.
• Use a criptografia da Vonage — Isso permite que você crie arquivos da Vonage nos quais os dados nunca ficam armazenados em estado não criptografado. Entre os métodos disponíveis para proteger suas gravações da Vonage, esse oferece o mais alto nível de segurança. Esse recurso está disponível como um complemento. Para obter mais informações, consulte a documentação sobre criptografia da Vonage.
• Usar a criptografia do lado do servidor do Amazon S3 — Esse recurso utiliza chaves de criptografia gerenciadas pelo Amazon S3 para a criptografia. Saiba mais sobre a criptografia do lado do servidor do Amazon S3 aqui.

Combinando o arquivamento com o Experience Composer

É possível combinar o arquivamento e Experiência com o Composer.