Cloud recording for ARTC channels | Alibaba Cloud - ApsaraVideo Live: Central de Documentação do Alibaba Cloud

Grave fluxos de áudio e vídeo em canais ARTC e armazene as gravações no OSS ou no ApsaraVideo VOD para reprodução, arquivamento ou conformidade.

Visão geral do recurso

A gravação em nuvem captura fluxos de áudio e vídeo em canais ARTC por meio de tarefas baseadas em API. Principais recursos:

Modos de gravação versáteis: Grave cada usuário individualmente (gravação individual) ou combine vários usuários em um único arquivo (gravação composta).
Assinatura flexível: Grave usuários específicos ou tipos de fluxo (câmera ou compartilhamento de tela) dentro de um canal.
Saída personalizável: Layouts compostos personalizados, imagens de fundo e formatos de saída (MP4, MP3, HLS).
Armazenamento em nuvem confiável: Carrega automaticamente as gravações para o OSS ou ApsaraVideo VOD.

Antes de começar

Ative os serviços necessários: Ative o ARTC. Dependendo do método de armazenamento:
- Armazenar no OSS: Ative o OSS e crie um bucket. Taxas de armazenamento são aplicáveis. Taxas de armazenamento.
  
  Nota
  Conceda permissões de service: O ARTC requer acesso de gravação ao seu bucket do OSS, concedido automaticamente na ativação. Se revogado, clique em Grant Cloud Resource Access Authorization para restaurá-lo.
- Armazenar no VOD: Ative o ApsaraVideo VOD e gerencie seu bucket de armazenamento. Taxas de armazenamento são aplicáveis. Faturamento básico do service.
Importante
- Consistência de região: O bucket de armazenamento e o endpoint da API devem estar na mesma região.
- Geração de arquivos de gravação: Após o término da gravação, o sistema salva os arquivos no bucket especificado na solicitação de API.
Entenda o faturamento:
- A gravação em nuvem vem ativada por padrão, sem necessidade de ativação separada.
- A gravação em nuvem é um recurso pago. Taxas de gravação em nuvem.

Conceitos principais

Modos de gravação

Escolha um modo de gravação com base no seu caso de uso.

Gravação individual

Grava o áudio e o vídeo de cada usuário em um arquivo separado. Ideal para análise individual ou pós-processamento.
- Por padrão, os parâmetros de gravação correspondem ao fluxo original.
- Se um fluxo for interrompido, o sistema preenche com silêncio, tela preta ou o último quadro para manter a continuidade.
Gravação composta

Mistura áudio e vídeo de vários usuários em um único arquivo. Adequado para cenários com múltiplas pessoas, como reuniões e educação online.
- Personalize a resolução, a taxa de bits e a taxa de quadros do vídeo de saída.
- Layouts de vídeo personalizados (até 17 painéis) e imagens de fundo da tela.
- Se o fluxo de um usuário for interrompido, o painel dele exibirá uma imagem de fundo predefinida ou uma tela preta.

Ciclo de vida da tarefa de gravação

Nota

Uma tarefa para automaticamente após 72 horas de execução (ciclo de vida máximo), independentemente do status.
Uma tarefa parada aciona um callback de parada. Use-o para confirmar o término da tarefa e consultar os arquivos gravados.
Se uma tarefa permanecer ociosa por mais tempo que MaxIdleTime, ela para automaticamente. Intervalo válido: 10–14.400 segundos (4 horas). Padrão: 300 segundos.
- No modo composto, uma tarefa fica ociosa quando todos os fluxos assinados param de publicar.
- No modo individual, o sistema rastreia cada fluxo independentemente. Um fluxo para de gravar após o próprio MaxIdleTime decorrer. A tarefa só para após todos os fluxos assinados atingirem o tempo limite.

Geração e armazenamento de arquivos

Formatos de arquivo de gravação

Apenas áudio: Suporta os formatos MP3 e AAC.
Áudio e vídeo: Suporta os formatos MP4 e HLS.

Nota

O sistema sempre gera um arquivo HLS, mesmo se não for especificado na solicitação.
Cada formato de arquivo adicional incorre em cobranças separadas.

Regras de nomenclatura de arquivos

As gravações são armazenadas em um diretório TaskId no caminho especificado do OSS ou ApsaraVideo VOD. Personalize os nomes dos arquivos com variáveis predefinidas.

Variáveis de nome de arquivo:

Parâmetro	Descrição
`AppId`	O ID do aplicativo.
`ChannelId`	O ID do canal.
`UserId`	O ID do usuário. Válido apenas para gravação individual.
`RecordMode`	O modo de gravação. 0: individual, 1: composta.
`StreamType`	O tipo de fluxo. A: áudio, V: vídeo, AV: áudio e vídeo.
`SourceType`	A source de vídeo. C: câmera, S: compartilhamento de tela.
`StartTime`	A hora de início da gravação em UTC, em milissegundos.
`Sequence`	O número de índice do segmento HLS.

Nomes de arquivo padrão:

Gravação individual:
- Formato HLS: {AppId}_{ChannelId}_{UserId}_{StartTime}_{Sequence}
- Outros formatos: {AppId}_{ChannelId}_{UserId}_{StartTime}
Gravação composta:
- Formato HLS: {AppId}_{ChannelId}_{StartTime}_{Sequence}
- Outros formatos: {AppId}_{ChannelId}_{StartTime}

Nota

Se você assinar diferentes valores de StreamType ou SourceType para o mesmo UserId, o sistema anexa {SourceType} após {UserId} no nome de arquivo padrão.
Quando um arquivo é nomeado como filename, o caminho final é TaskId/filename.M3U8. O sistema adiciona automaticamente o prefixo TaskId, gerado no início da tarefa, ao caminho de armazenamento.

Estratégia de segmentação de arquivos

A segmentação de arquivos divide uma gravação em vários arquivos. Defina a duração máxima do segmento com MaxFileDuration: 180–7.200 segundos (padrão: 7.200 segundos / 2 horas).

Procedimento

O fluxo de trabalho de gravação em nuvem é totalmente orientado por API. As etapas a seguir cobrem as operações principais com exemplos de parâmetros.

Etapa 1: Iniciar uma tarefa de gravação

Chame a API Start an ARTC cloud recording task. Configure os parâmetros de assinatura, gravação e armazenamento na solicitação.

Parâmetros principais:

Especifique o modo de gravação: Escolha individual (RecordMode: 0) ou composta (RecordMode: 1).
Defina os alvos de assinatura: Em SubscribeParams, liste os valores de UserId e StreamType a serem gravados.
Defina o formato de saída: Em RecordParams, defina apenas áudio (StreamType: 1) ou áudio e vídeo (StreamType: 0).
Configure o armazenamento: Em StorageParams, especifique OSS ou ApsaraVideo VOD e forneça o bucket e o endpoint.

Cenários de exemplo

Gravação individual apenas de áudio

Cenário: No canal myRoom, existem três usuários: userA, userB e userC. Grave os fluxos de áudio de userA e userB individualmente, sem gravar userC. Além disso, gere arquivos M3U8 e MP3.

Resultados da gravação: Os arquivos gravados são armazenados no bucket do Object Storage Service (OSS) especificado, my-bucket. Arquivos no formato M3U8 são armazenados no caminho hls/{taskId}, e arquivos no formato MP3 são armazenados no caminho mp3/{taskId}.

Exemplo de parâmetro:

{
  "AppId": "my-app-id", // The AppId used for streaming
  "ChannelId": "myRoom", // The channel to record
  "SubscribeParams": {
    "SubscribeUserIdList": [
      {
        "UserId": "userA", // The user to be recorded
        "StreamType": 1 // Subscribe to audio-only stream
      },
      {
        "UserId": "userB", // The user to be recorded
        "StreamType": 1 // Subscribe to audio-only stream
      }
    ]
  },
  "RecordParams": {
    "RecordMode": 0, // Specify individual recording mode
    "StreamType": 1, // Specify audio-only output format
    "MaxFileDuration": 180 // Set the file slice duration to 180 seconds (3 minutes)
  },
  "StorageParams": {
    "StorageType": 1, // Specify storing to OSS
    "FileInfo": [ // Generate M3U8 and MP3 files, storing them under "hls" and "mp3" paths respectively
      {
        "Format": "HLS",
        "FilePathPrefix": [
          "hls"
        ]
      },
      {
        "Format": "MP3",
        "FilePathPrefix": [
          "mp3"
        ]
      }
    ],
    "OSSParams": {
      "OSSEndpoint": "oss-cn-shanghai.aliyuncs.com",
      "OSSBucket": "my-bucket"
    }
  },
  "NotifyUrl": "http://mytest/callback", // Optional: The URL to receive callback messages
  "NotifyAuthKey": "12345678abcdefghikj" // Optional: The authentication key for callback messages
}

Gravação individual de áudio e vídeo

Cenário: No canal myRoom, existem três usuários: userA, userB e userC. Grave os fluxos de áudio e vídeo de userA e userB individualmente, sem gravar userC. Além disso, gere arquivos M3U8 e MP4.

Resultados da gravação: Os arquivos são salvos no bucket do OSS especificado, my-bucket. Arquivos M3U8 são armazenados no caminho hls/{taskId}, e arquivos MP4 são armazenados no caminho mp4/{taskId}.

Exemplo de parâmetro:

{
  "AppId": "my-app-id", // The AppId used for streaming
  "ChannelId": "myRoom", // The channel specified for streaming
  "SubscribeParams": {
    "SubscribeUserIdList": [
      {
        "UserId": "userA", // The user to be recorded
        "StreamType": 0 // Subscribe to audio and video stream
      },
      {
        "UserId": "userB", // The user to be recorded
        "StreamType": 0 // Subscribe to audio and video stream
      }
    ]
  },
  "RecordParams": {
    "RecordMode": 0, // Specify individual recording mode
    "StreamType": 0, // Specify audio and video output format
    "MaxFileDuration": 180 // Set the file slice duration to 180 seconds (3 minutes)
  },
  "StorageParams": {
    "StorageType": 1, // Specify storing to OSS
    "FileInfo": [ // Generate M3U8 and MP4 files, storing them under "hls" and "mp4" paths respectively
      {
        "Format": "HLS",
        "FilePathPrefix": [
          "hls"
        ]
      },
      {
        "Format": "MP4",
        "FilePathPrefix": [
          "mp4"
        ]
      }
    ],
    "OSSParams": {
      "OSSEndpoint": "oss-cn-shanghai.aliyuncs.com",
      "OSSBucket": "my-bucket"
    }
  },
  "NotifyUrl": "http://mytest/callback", // Optional: The URL to receive callback messages
  "NotifyAuthKey": "12345678abcdefghikj" // Optional: The authentication key for callback messages
}

Gravação composta apenas de áudio

Cenário: No canal myRoom, existem três usuários: userA, userB e userC. Grave a conversa entre userA e userB como um único fluxo composto, sem gravar userC. Além disso, gere arquivos M3U8 e MP3.

Resultados da gravação: Os arquivos são salvos no bucket do OSS especificado, my-bucket. Arquivos M3U8 são armazenados no caminho hls/{taskId}, e arquivos MP3 são armazenados no caminho mp3/{taskId}.

Exemplo de parâmetro:

{
  "AppId": "my-app-id", // The AppId used for streaming
  "ChannelId": "myRoom", // The channel specified for streaming
  "SubscribeParams": {
    "SubscribeUserIdList": [
      {
        "UserId": "userA", // The user to be recorded
        "StreamType": 1 // Subscribe to audio-only stream
      },
      {
        "UserId": "userB", // The user to be recorded
        "StreamType": 1 // Subscribe to audio-only stream
      }
    ]
  },
  "RecordParams": {
    "RecordMode": 1, // Specify composite recording mode
    "StreamType": 1, // Specify audio-only output format
    "MaxFileDuration": 180 // Set the file slice duration to 180 seconds (3 minutes)
  },
  "StorageParams": {
    "StorageType": 1, // Specify storing to OSS
    "FileInfo": [ // Generate M3U8 and MP3 files, storing them under "hls" and "mp3" paths respectively
      {
        "Format": "HLS",
        "FilePathPrefix": [
          "hls"
        ]
      },
      {
        "Format": "MP3",
        "FilePathPrefix": [
          "mp3"
        ]
      }
    ],
    "OSSParams": {
      "OSSEndpoint": "oss-cn-shanghai.aliyuncs.com",
      "OSSBucket": "my-bucket"
    }
  },
  "MixTranscodeParams": {
    "AudioBitrate": 128, // Audio bitrate
    "AudioChannels": 2, // Number of audio channels
    "AudioSampleRate": 44100 // Sample rate
  },
  "NotifyUrl": "http://mytest/callback", // Optional: The URL to receive callback messages
  "NotifyAuthKey": "12345678abcdefghikj" // Optional: The authentication key for callback messages
}

Gravação composta de áudio e vídeo

Cenário: No canal myRoom, existem três usuários: userA, userB e userC. Grave os fluxos de áudio e câmera de userA e userB, e apenas o fluxo de áudio de userC. Além disso, gere arquivos M3U8 e MP4.

O vídeo resultante organiza os painéis para userA e userB da seguinte forma:

Resultados da gravação: Os arquivos são armazenados no bucket do OSS especificado, my-bucket. Arquivos M3U8 são armazenados no caminho hls/{taskId}, e arquivos MP4 são armazenados no caminho mp4/{taskId}.

Exemplo de parâmetro:

{
  "AppId": "my-app-id", // The AppId used for streaming
  "ChannelId": "myRoom", // The channel specified for streaming
  "SubscribeParams": {
    "SubscribeUserIdList": [
      {
        "UserId": "userA", // The user to be recorded
        "StreamType": 0, // Subscribe to audio and video stream
        "SourceType": 0 // Subscribe to camera stream
      },
      {
        "UserId": "userB", // The user to be recorded
        "StreamType": 0, // Subscribe to audio and video stream
        "SourceType": 0 // Subscribe to camera stream
      },
      {
        "UserId": "userC", // The user to be recorded
        "StreamType": 1 // Subscribe to audio-only stream
      }
    ]
  },
  "RecordParams": {
    "RecordMode": 1, // Specify composite recording mode
    "StreamType": 0, // Specify audio and video output format
    "MaxFileDuration": 180 // Set the file slice duration to 180 seconds (3 minutes)
  },
  "StorageParams": {
    "StorageType": 1, // Specify storing to OSS
    "FileInfo": [ // Generate M3U8 and MP4 files, storing them under "hls" and "mp4" paths respectively
      {
        "Format": "HLS",
        "FilePathPrefix": [
          "hls"
        ]
      },
      {
        "Format": "MP4",
        "FilePathPrefix": [
          "mp4"
        ]
      }
    ],
    "OSSParams": {
      "OSSEndpoint": "oss-cn-shanghai.aliyuncs.com",
      "OSSBucket": "my-bucket"
    }
  },
  "MixTranscodeParams": {
    "AudioBitrate": 128,
    "AudioChannels": 2,
    "AudioSampleRate": 44100,
    "VideoCodec": "H.264",
    "VideoBitrate": 500,
    "VideoFramerate": 30,
    "VideoGop": 30,
    "VideoHeight": 480, // Height of the final video
    "VideoWidth": 640 // Width of the final video
  },
  "MixLayoutParams": {
    "UserPanes": [
      {
        "userId": "userA",
        "sourceType": 0,
        "height": "1", // Occupies the full height of the canvas
        "width": "0.5", // Occupies half the width of the canvas
        // Positions the pane at the canvas's top-left corner
        "x": "0",
        "y": "0"
      },
      {
        "userId": "userB",
        "sourceType": 0,
        "height": "1", // Occupies the full height of the canvas
        "width": "0.5", // Occupies half the width of the canvas
        // Positions the pane starting at the canvas's horizontal midpoint
        "x": "0.5",
        "y": "0"
      }
    ]
  },
  "NotifyUrl": "http://mytest/callback", // Optional: The URL to receive callback messages
  "NotifyAuthKey": "12345678abcdefghikj" // Optional: The authentication key for callback messages
}

Etapa 2 (Opcional): Atualizar uma tarefa de gravação

Chame a API Update an ARTC cloud recording task para alterar os parâmetros de gravação enquanto uma tarefa está em execução.

Nota

Modo individual: É possível atualizar apenas a assinatura.
Modo composto: É possível atualizar tanto a assinatura quanto o layout.

Etapa 3: Parar uma tarefa de gravação

Para encerrar a gravação, chame a API Stop an ARTC cloud recording task.

Nota

O sistema processa e carrega os arquivos finais de gravação após esta chamada. A tarefa só é concluída após você receber o callback stop. Não exclua nem modifique recursos de armazenamento antes de recebê-lo.

Etapa 4: Consultar tarefas e arquivos

Chame a API Query ARTC cloud recording files and task status para verificar o status da tarefa e os arquivos gravados.

Nota

É possível consultar apenas tarefas existentes. A API retorna um erro para tarefas inexistentes.
As informações sobre arquivos de gravação estão disponíveis para tarefas iniciadas com sucesso e executadas por menos de 72 horas. A API retorna um erro após 72 horas.