Arquivamento

O recurso de arquivamento da Video API da Vonage permite gravar, salvar e recuperar sessões.

Este tópico inclui as seguintes seções:

Fluxo de trabalho básico

Importante: Só é possível arquivar sessões que utilizam o OpenTok Media Router (sessões com o modo de mídia (definido como “roteado”).

Você pode criar um arquivo de uma sessão do OpenTok usando o API REST do OpenTok ou um dos SDKs do servidor OpenTok. Ao criar um arquivo, a gravação é iniciada. Só é possível criar um arquivo para sessões que tenham pelo menos um cliente conectado. (Um cliente deve começar a publicar um stream em até um minuto; caso contrário, o arquivo é interrompido.)

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

Importante: É possível gravar até 16 fluxos de vídeo com arquivamento agrupado ou 50 com arquivamento individual de fluxos. (Tanto os arquivos agrupados quanto os individuais podem incluir até 50 fluxos de áudio.) Consulte Arquivos individuais e arquivos compostos. Após esse limite ser atingido, se forem publicados fluxos adicionais na sessão, eles não serão gravados. O máximo registrado A duração de um arquivo (o tempo acumulado durante o qual os streams são publicados na sessão) é de 4 horas (14.400 segundos). Consulte Período de arquivamento para mais detalhes.

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

A API REST da OpenTok e os SDKs de servidor da OpenTok incluem métodos para o seguinte:

  • Iniciando uma gravação de arquivo
  • Interromper uma gravação em arquivo
  • Arquivos de listagens
  • Recuperação de informações do arquivo
  • Excluindo um arquivo

Quando você interrompe a gravação de um arquivo, o servidor OpenTok cria um arquivo MP4 ou (no caso de arquivos de transmissões individuais) um arquivo ZIP. (Consulte Arquivos individuais e arquivos compostos.)

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

Período de arquivamento

O máximo registrado A duração de um arquivo é de 4 horas (14.400 segundos). Isso registrado duração refere-se ao tempo acumulado durante o qual as transmissões são publicadas (e gravadas). Enquanto as transmissões são 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 um arquivo, incluindo os estados “iniciado” e “em pausa”, é de 12 horas (43.200 segundos). Os arquivos 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 arquivos

Use seu Account da Video API para especificar um destino para o upload dos arquivos de arquivamento concluídos. Pode ser seu próprio bucket do Amazon S3, um bucket em um provedor de armazenamento compatível com 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. Consulte Utilização do armazenamento S3 com o arquivamento do OpenTok e Utilização de um contêiner do Windows Azure com o recurso de arquivamento do OpenTok.

Quando o arquivamento estiver concluído (o status do arquivo está definido como "stopped"), tentaremos fazer o upload do arquivo de arquivamento para o destino especificado (como um bucket do S3 ou um contêiner do Azure) por até 72 horas após a criação do arquivo de arquivamento (ou por pelo menos 6 horas, se o plano de contingência estiver ativado), repetindo a tentativa várias vezes por meio de uma política de agendamento de upload distribuída.

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

Se o envio para o destino especificado falhar (após tentativas repetidas) e a opção de recurso alternativo para o armazenamento da OpenTok estiver ativada, disponibilizamos o arquivo para download na nuvem da OpenTok, e o status do arquivo é definido como "available". Assim que o arquivo estiver disponível para download na nuvem da OpenTok, não tentaremos mais fazer o upload para o destino especificado por você. Os arquivos disponibilizados na nuvem da OpenTok ficam disponíveis por 72 horas a partir do momento em que são criados. Para evitar o armazenamento de fallback na nuvem da OpenTok, desative essa função durante o S3 ou Azure processo de configuração.

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

Você não poderá acessar o arquivo até que ele seja enviado para o destino especificado ou esteja disponível no armazenamento do OpenTok.

Para arquivos armazenados na nuvem do OpenTok, o URL de download é fornecido no url propriedade do arquivo quando o status do arquivo está definido como "available". Cada URL de download utilizada com o recurso de armazenamento de arquivos de emergência é uma URL pré-assinada que utiliza credenciais de segurança para conceder permissão limitada no tempo 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 de métodos do servidor para recuperar a URL de download. Por motivos de segurança, a URL de download só está disponível por meio de chamadas à API REST ou métodos do SDK do servidor para recuperação de informações do arquivo ou arquivos de listagens (que exigem as credenciais da sua conta).

Arquivos apenas de áudio e apenas de vídeo

Ao criar um arquivo usando o API REST do OpenTok ou um dos SDKs do servidor OpenTok, você pode especificar se o arquivo irá gravar áudio, vídeo ou ambos. (Por padrão, grava-se ambos.)

Arquivos individuais e arquivos compostos

O arquivo de saída do arquivo pode ter um dos seguintes formatos:

  • Arquivos compostos — O arquivo é um único arquivo MP4 composto por todos os fluxos. Essa é a configuração padrão. Também é usada para sessões arquivadas automaticamente (consulte Sessões arquivadas automaticamente). O arquivo MP4 utiliza vídeo no formato H.264 e áudio no formato 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 paisagem). Para definir um arquivo composto para ter uma 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 iniciar arquivo método da API REST do OpenTok. Talvez seja recomendável usar a proporção retrato ao gravar arquivos que incluam transmissões 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 um arquivo composto para controlar o tamanho do arquivo. Defina a opção `maxBitrate` ao chamar a função iniciar 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 iniciar 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 OpenTok.

    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.

  • Arquivos individuais de transmissão — O arquivo é um arquivo ZIP que contém vários arquivos de mídia individuais para cada transmissão e um arquivo de metadados em JSON para sincronização de vídeo. Você pode especificar esse formato ao usar uma das SDKs de servidor do OpenTok para iniciar o arquivamento. Esse formato não está disponível para sessões arquivadas automaticamente (consulte Sessões arquivadas automaticamente).

Notas:

  • Em um arquivo compilado, se o processo de arquivamento for iniciado e nenhum dado for transmitido durante o período em que o arquivo estiver sendo criado (nenhum áudio ou vídeo for publicado), o tamanho do arquivo será de 0 bytes.
  • Em um arquivo compilado, o vídeo de cada transmissão incluída pode começar um pouco depois do áudio (com a imagem ficando preta até que comece).

Trabalhando com arquivos de transmissões individuais

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 arquivos para cada fluxo de áudio e vídeo:

  • Cada contêiner de stream no arquivo corresponde a um stream publicado no OpenTok. 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 projeto. Arquivos de sessões que utilizam VP8 ou VP9 como o codec de vídeo preferido ter webm contêineres e projetos que tenham 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 obter mais detalhes importantes sobre o vídeo VP9 nos arquivos de transmissões individuais.

  • Os contêineres de arquivo de fluxo individuais 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 — toda a mídia recebida no servidor de arquivamento é gravada diretamente em arquivo, sem inspeção ou pós-processamento. Esse projeto tem implicações para o consumo posterior dos contêineres de fluxo. Na maioria dos casos, a reprodução direta de um contêiner de arquivo de fluxo individual não será possível ou apresentará problemas devido ao conteúdo do contêiner:

  • As dimensões declaradas no 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 640 x 480 pixels, independentemente das dimensões dos quadros de vídeo codificados.
  • As dimensões dos quadros de vídeo podem variar ao longo do tempo. Isso também pode incluir mudanças 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 um tempo, utilizando uma das publishVideo ou publishAudio propriedades da editora.

Os carimbos de tempo de apresentação de 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 tempo deve permanecer consistente durante toda a duração do fluxo. 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 passar a mídia por um pós-processador para reparar contêineres de fluxos individuais ou multiplexar/compor vários contêineres em um produto final. Sugestões para começar a trabalhar com o processamento posterior estão descritas em nosso repositório “archiving-composer” no GitHub: https://github.com/opentok/archiving-composer.

Manifesto do arquivo de uma transmissão específica

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"
}

Este arquivo JSON inclui as seguintes propriedades:

  • id — O identificador exclusivo deste arquivo.

  • partnerId — O ID do parceiro/projeto deste arquivo

  • sessionId — O ID da sessão deste arquivo

  • nome — O nome deste arquivo. Este campo fica vazio se o nome não tiver sido especificado na chamada para iniciar arquivo.

  • createdAt — O tempo Unix, em milissegundos, correspondente ao momento em que o arquivo foi iniciado.

  • arquivos — Uma matriz de arquivos incluídos no contêiner ZIP. Cada arquivo possui as seguintes propriedades:

    • streamId — O ID do stream correspondente ao stream gravado neste 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 da transmissão incluirá arquivos separados para cada um dos segmentos individuais da transmissão.

    • nome do arquivo — O nome do arquivo de mídia gravado. Será um .webm para um arquivo de uma sessão em um projeto do OpenTok que utiliza o VP8 como o codec de vídeo preferido, e será um .mkv para um arquivo de uma sessão em um projeto que utiliza o H.264 como o codec de vídeo preferencial.

      Se um fluxo for interrompido e retomado devido à reconexão automática ou quando um fluxo for adicionado e removido repetidamente em um arquivo do modo de transmissão manual, podem existir vários arquivos para o mesmo fluxo (correspondentes a cada segmento), e o nome do arquivo de cada segmento do fluxo terá um número de índice (como “_1” ou “_2”) acrescentado após o ID do fluxo, a fim de identificar a ordem do segmento.

    • startTimeOffset — O deslocamento, em milissegundos, do momento em que este arquivo começou a gravar (a partir da hora “createdAt” do arquivo) — consulte a observação importante abaixo.

    • stopTimeOffset — O deslocamento, em milissegundos, que indica quando este arquivo interrompeu a gravação (a partir da hora de criação do arquivo) — consulte a observação importante abaixo.

    • connectionData — O dados de conexão para o cliente da editora.

    • videoType — Ou "camera", "screen", ou "custom". A "screen" O vídeo utiliza o compartilhamento de tela no editor como fonte de vídeo; um vídeo “personalizado” é publicado por um cliente web utilizando um elemento VideoTrack em HTML como fonte de vídeo. Para uma transmissão publicada a partir de um dispositivo móvel, o tipo de tela pode mudar de uma câmera para um tipo de vídeo de compartilhamento de tela. No entanto, a propriedade no manifesto do arquivo indica apenas o tipo inicial de vídeo.

Importante: Em um arquivo de transmissão individual, se houver um curto período em que nenhuma transmissão seja publicada durante a gravação, o startTimeOffset e os valores de stopTimeOffset podem apresentar um pequeno desvio. Esse é um problema conhecido.

Pós-processamento de arquivos individuais

Um exemplo de aplicativo de pós-processador está disponível em https://github.com/opentok/archiving-composer.

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 fluxos durante a gravação do arquivo. Além disso, você pode especificar se o arquivo incluirá o áudio ou o vídeo de um fluxo (ou ambos). Caso contrário, com o streamMode definir como "auto" (por padrão), todos os fluxos são incluídos (com áudio e vídeo) no arquivo. Consulte Iniciando uma gravação de arquivo e Seleção dos fluxos a serem incluídos 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 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 arquivadas automaticamente

Você também pode fazer com que uma sessão seja arquivada automaticamente. É possível definir isso ao criar a sessão, usando a API REST do OpenTok ou um dos SDKs de servidor do OpenTok:

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

O método da API REST para criar uma sessão inclui uma opção para definir o nome do arquivo e a resolução do arquivo ao criar uma sessão arquivada automaticamente.

Observação: Se o arquivamento for iniciado e nenhum dado for transmitido durante o período do arquivamento (nenhum áudio ou vídeo for publicado), o tamanho do arquivo de arquivamento será de 0 bytes.

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 o arquivamento seja interrompido. Os arquivamentos automáticos consecutivos de uma sessão se sobreporão ligeiramente, para que nenhum dado gravado seja perdido.

Você pode chamar o método REST do OpenTok para arquivos de listagens e passar o sessionID parâmetro de consulta para listar arquivos de uma sessão com um ID especificado. Em seguida, é possível determinar a sequência dos arquivos MP4 individuais, verificando o createdAt propriedade de cada arquivo listado nos dados JSON retornados pela chamada ao método REST.

Não é possível interromper um arquivamento automático usando a API REST da OpenTok ou os SDKs de 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 transmitir para a sessão.

Importante:

  • Se você prevê que haverá longos períodos em que o arquivamento ficará suspenso, deve considerar iniciar e interromper os arquivamentos utilizando os métodos descritos no API REST do OpenTok ou um dos SDKs do servidor OpenTok (em vez de a sessão ser arquivada automaticamente).
  • 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).

Observação: Se você quiser unir suavemente duas gravações consecutivas com alguma sobreposição entre o final do primeiro arquivo e o início do segundo, pode usar nossa ferramenta de pós-processamento para arquivos compostos, explicada logo a seguir.

Pós-processamento de arquivos compactados

As gravações do arquivo de vídeo fazem parte do arquivo duração 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.

Arquivos simultâneos

Para gravar vários arquivos da mesma sessão simultaneamente, defina o multiArchiveTag opção quando iniciando cada arquivo. É necessário definir isso como uma sequência de caracteres exclusiva para cada arquivamento simultâneo 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 arquivo simultâneo que é gravado simultaneamente com os arquivos automáticos. Os arquivos automáticos começam e terminam quando a sessão é iniciada e encerrada por conta própria (seguindo as regras para arquivos automáticos), enquanto os iniciados manualmente são encerrados separadamente.

Alterações no status do arquivo

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:

  • "started" — O arquivo foi iniciado e está em processo de gravação.

  • "paused" — Quando um arquivamento é pausado, nada é gravado. O arquivamento é pausado se ocorrer qualquer uma das seguintes condições:

    • Nenhum cliente está publicando fluxos na sessão. Nesse caso, há um tempo limite de 60 minutos; após esse período, o arquivamento é interrompido e o status do arquivamento passa a ser "stopped".
    • Todos os clientes encerram a sessão. Após 60 segundos, o arquivamento é interrompido e o status do arquivamento passa a ser "stopped".

    Se um cliente retomar a publicação enquanto o arquivo estiver no "paused" nesse estado, a gravação do arquivo é retomada e o status volta a ser "started".

  • "stopped" — O arquivo parou de gravar.

  • "uploaded" — O arquivo está disponível para download no destino de envio de arquivos que você especificou em seu Account da Video API. Observe que, para arquivos muito pequenos, o "uploaded" o evento de status pode ocorrer antes do "stopped" evento de status. Se você tiver solução alternativa para armazenamento em arquivo ativado; em caso de falha, armazenaremos o arquivo na nuvem da OpenTok (e o status será "available").

  • "available" — O arquivo está disponível para download na nuvem da OpenTok.

  • "expired" — O arquivo não está mais disponível para download na nuvem da OpenTok. (Os arquivos na nuvem da OpenTok ficam disponíveis apenas por 72 horas a partir do momento em que são criados.)

  • "failed" — A gravação para arquivo falhou (ou o envio do arquivo para o arquivo falhou e o armazenamento alternativo na nuvem do OpenTok está desativado).

  • "streamAdded" — Um stream foi adicionado ao arquivo. Isso se aplica a modo manual apenas arquivos.

  • "streamRemoved" — Uma transmissão foi removida do arquivo. Isso se aplica a modo manual apenas arquivos.

Use seu Account da Video API para especificar uma URL de retorno de chamada.

Callbacks seguros: É possível proteger as solicitações de retorno de chamada do webhook com retornos de chamada assinados, utilizando um segredo de assinatura. Consulte Callbacks seguros.

Quando o status de um arquivo é alterado, o servidor envia solicitações HTTP POST para a URL que você fornecer. O tipo de conteúdo (Content-Type) da solicitação é application/json. Os dados da solicitação consistem em um objeto JSON no 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://example.com/archive.mp4"
}

O objeto JSON inclui as seguintes propriedades:

  • createdAt — O carimbo de data e hora correspondente ao momento em que o chamada o momento em que o arquivo foi iniciado, expresso em milissegundos desde a época Unix (1º de janeiro de 1970, 00:00:00 UTC). Observe que esse valor é arredondado para o segundo mais próximo. Observe também que esse valor difere do createdAt valor no Método REST para recuperar um arquivo e o createdAt valor no manifesto de um arquivo de stream individual Nesses casos, o createdAt O valor é definido como a hora em que a gravação começou efetivamente nos servidores da OpenTok (e não a hora em que ocorreu a chamada para iniciar a gravação). Observe que, mesmo que seja emitida uma chamada para iniciar um arquivo, a gravação não começará efetivamente no servidor da OpenTok até que pelo menos um cliente publique um fluxo na sessão.
  • duration — A duração do arquivo em segundos. Para arquivos que estão sendo gravados (com a propriedade status definida "started"), esse valor é definido como 0.
  • id — O ID exclusivo do arquivo.
  • name — O nome do arquivo que você forneceu (isso é opcional)
  • partnerId — Sua chave da API do OpenTok.
  • resolution — A resolução do arquivo (seja “640x480”, “480x640”, “1280x720”, “720x1280”, “1920x1080” ou “1080x1920”). Essa propriedade é definida apenas para arquivos compostos. É possível definir a resolução de um arquivo composto ao chamar o iniciar arquivo método da API REST do OpenTok.
  • reason — Uma sequência de caracteres que descreve o motivo da alteração do status.
    • Para arquivos com o status "stopped" ou "failed", essa sequência de caracteres descreve o motivo pelo qual o arquivamento foi interrompido ou falhou. Para arquivamentos com o status "stopped", isso pode ser definido como "maximum duration exceeded", "maximum idle time exceeded", "session ended", ou "user initiated".
    • Para arquivos com o status "failed", isso pode ser definido como "Internal server failure".
    • Para arquivos com o status "streamRemoved", isso pode ser definido como o motivo pelo qual a transmissão foi removida da sessão (e do arquivo): "clientDisconnected", "networkDisconnected", "forceDisconnected", "forceUnpublished", "mediaStopped".
  • sessionId — O ID da sessão do OpenTok que foi arquivada.
  • size — O tamanho do arquivo compactado. Para arquivos compactados que ainda não foram gerados, esse valor é definido como 0.
  • status — O status do arquivo:

    • "available" — O arquivo está disponível para download no site da OpenTok.

    • "expired" — O arquivo não está mais disponível para download na nuvem da OpenTok. (Os arquivos na nuvem da OpenTok ficam disponíveis apenas por 72 horas a partir do momento em que são criados.)

    • "failed" — O arquivamento da gravação falhou.

    • "paused" — Quando um arquivamento é pausado, nada é gravado. O arquivamento é pausado se ocorrer qualquer uma das seguintes condições:

      • Nenhum cliente está publicando fluxos na sessão. Nesse caso, há um tempo limite de 60 minutos; após esse período, o arquivamento é interrompido e o status do arquivamento passa a ser "stopped".
      • Todos os clientes encerram a sessão. Após 60 segundos, o arquivamento é interrompido e o status do arquivamento passa a ser "stopped".

      Se um cliente retomar a publicação enquanto o arquivo estiver no "paused" nesse estado, a gravação do arquivo é retomada e o status volta a ser "started".

    • "started" — O arquivo foi iniciado e está em processo de gravação.

    • "stopped" — O arquivo parou de gravar.

    • "uploaded" — O arquivo está disponível para download no bucket do S3 ou no contêiner do Azure que você especificou em seu Account da Video API. Observe que, para arquivos muito pequenos, o "uploaded" o evento de status pode ocorrer antes do "stopped" evento de status.

  • streamMode — Se todas as transmissões estão incluídas no arquivo ("auto") ou você seleciona os fluxos a serem incluídos no arquivo ("manual"). Veja Seleção dos fluxos a serem incluídos em um arquivo.
  • streams — Uma matriz de objetos correspondentes aos fluxos que estão sendo arquivados no momento. Esse valor só é definido para um arquivo cujo status esteja definido como "started". Cada objeto da matriz possui as seguintes propriedades:
    • streams — O ID do stream incluído no arquivo.
    • hasAudio — Se o áudio da transmissão está incluído no arquivo.
    • hasVideo — Se o vídeo da transmissão está incluído no arquivo.
  • url — A URL de download do arquivo compactado disponível. Esse campo só é preenchido para um arquivo compactado cujo status esteja definido como "available"; para outros arquivos (incluindo aqueles com o status "uploaded") essa propriedade é definida como nula. Por motivos de segurança, a URL de download só está disponível por meio de chamadas à API REST (ou ao SDK do servidor) para recuperação de informações do arquivo ou arquivos de listagens, ou acessando a URL ao fazer login na sua Account da Video API online (todos exigem autenticação). Após 10 minutos, o link para download expira e um novo link é atribuído mediante uma nova solicitação.
  • timestamp — Para manual atualizações do fluxo, o carimbo de data e hora em que o evento ocorreu, expresso em milissegundos desde a época Unix (1º de janeiro de 1970, 00:00:00 UTC)
  • stream - Para manual atualizações do fluxo, propriedades:
    • id — O ID do stream adicionado ou removido do arquivo.
    • connection — O objeto de conexão do fluxo, que inclui uma propriedade: id. O id A propriedade é o ID de conexão do fluxo adicionado ou removido do arquivo.
    • createdAt — O carimbo de data/hora do início da transmissão, expresso em milissegundos desde a época Unix (1º de janeiro de 1970, 00:00:00 UTC). Observe que esse valor é arredondado para o segundo mais próximo

Você também pode verificar o status dos arquivos em Account da Video API:

  1. Acesse seu Account da Video API página.
  2. Na lista de projetos à esquerda da página, selecione o projeto que conterá as sessões que você deseja arquivar.
  3. No Arquivamento seção, clique no Lista de arquivos guia. São exibidos detalhes sobre os arquivos do projeto.

Segurança do arquivo

Você pode proteger seus arquivos das seguintes maneiras:

  • Desativar o recurso de fallback do armazenamento de arquivos — Por padrão, a Vonage armazena um arquivo de backup nos servidores da OpenTok caso não consiga fazer o upload do arquivo para o servidor S3 ou Azure especificado por você. Para desativar esse armazenamento alternativo (que está habilitado por padrão), faça login na sua Account da Video API, selecione o projeto e configure a opção para desativar o recurso de armazenamento de arquivo como alternativa.
  • Usar a criptografia do OpenTok — Isso permite que você crie arquivos do OpenTok nos quais os dados nunca ficam armazenados em estado não criptografado. Entre os métodos disponíveis para proteger seus arquivos do OpenTok, esse oferece o mais alto nível de segurança. Essa funcionalidade está disponível como um recurso adicional. Para obter mais informações, consulte o Criptografia do OpenTok documentação.
  • 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.

Aplicativos de exemplo

Os aplicativos de exemplo a seguir demonstram como fazer o arquivamento com o OpenTok:

Mais informações

Consulte a documentação sobre os métodos relacionados ao arquivamento no API REST do OpenTok e nas referências da API para o SDKs de servidor do OpenTok. Além disso, cada um dos SDKs de servidor inclui um aplicativo de arquivamento de exemplo.