Exportação do arquivo¶

Um troço do arquivo gravado é descarregado num só ficheiro MP4 que abre em reprodutores vulgares, por exemplo o VLC. O ficheiro é montado a partir do arquivo no momento do pedido: não é preciso preparar nada de antemão, e a exportação não ocupa espaço em disco.

A exportação funciona num stream com a gravação ativada. Só se exporta MP4: a cabeça de rede não monta um ficheiro MPEG-TS, e um pedido .ts é recusado com 422.

Endereço de exportação¶

http://<endereço-da-cabeça-de-rede>/streaming/v/<stream>/archive-<desde>-<duração>.mp4

• desde — o início do troço, em UTC e segundos;
• duração — o comprimento do troço, em segundos.

Por exemplo, archive-1789546139-600.mp4 são dez minutos de arquivo a partir do momento indicado.

A cabeça de rede responde a GET com o ficheiro e a HEAD apenas com os seus cabeçalhos. Vale a pena sondar o endereço com HEAD antes de descarregar: o Content-Length chega sem o corpo, portanto o tamanho do ficheiro sabe-se de antemão. GET e HEAD têm os mesmos desfechos: uma recusa que a descarga daria já se vê na sondagem.

Escolha das pistas¶

Sem parâmetros, o ficheiro recebe todas as pistas de vídeo e de áudio do troço. As pistas necessárias escolhem-se com o parâmetro filter.tracks:

http://<endereço-da-cabeça-de-rede>/streaming/v/<stream>/archive-<desde>-<duração>.mp4?filter.tracks=v1a1

As pistas designam-se como nas listas: v1, v2 são vídeo, a1 é áudio. Se no ficheiro não entrar nenhuma pista de vídeo, é servido como audio/mp4.

As legendas e as pistas de serviço não entram na exportação: quebram a compatibilidade do contentor clássico pela qual ele foi escolhido. O pedido de uma pista dessas é recusado.

O que entra no ficheiro¶

• O início — o ficheiro começa no quadro-chave não posterior ao momento pedido, por isso pode ser uns segundos mais longo do que o pedido. Se o início cair num buraco de gravação, o ficheiro começa no primeiro quadro-chave depois do buraco;
• os buracos de gravação — são unidos: no ficheiro só há tempo gravado, e pode sair mais curto do que o troço pedido;
• uma mudança de parâmetros da pista — se dentro do troço os parâmetros mudaram, por exemplo a resolução, o ficheiro termina no ponto da mudança. O corte é comum a todas as pistas: de outro modo a imagem terminaria a meio do som.

A cabeça de rede propõe o nome do ficheiro no cabeçalho Content-Disposition:

<stream>_<AAAA-MM-DD>_<HH-MM-SS>Z_<segundos>s.mp4

A hora do nome é UTC e a duração é a realmente gravada, não a largura da seleção: o nome não deve mentir sobre o conteúdo.

Limites¶

Dois limites vivem na configuração do arquivo da máquina e sobrevivem ao reinício: mudam ao aplicar a configuração, não ao reiniciar.

• export_max_duration_secs — a duração máxima de uma exportação, em segundos. 10800 por omissão — três horas, o mesmo que a linha de tempo permite selecionar por omissão;
• export_max_concurrent — quantas exportações a cabeça de rede executa ao mesmo tempo. 4 por omissão.

Um pedido mais longo do que o teto é recusado com 422 antes de ler o arquivo. Um pedido acima do número de simultâneas recebe 503 com o cabeçalho Retry-After: repetir passados os segundos indicados não perde nada, o trabalho não tinha começado.

O valor zero não é admitido. O teto de duração corta uma exportação, mas não o seu número: dezenas ao mesmo tempo põem o disco em apuros, e a cabeça de rede está ainda a gravar.

Respostas do servidor¶

Motivos do código 422:

• a duração ultrapassa o teto export_max_duration_secs;
• é nomeada uma pista inexistente — ou o stream não tem essa pista, ou no troço não tem gravação;
• são pedidas legendas ou uma pista de serviço;
• o contentor não é MP4 — a extensão no endereço é outra;
• o parâmetro packing não é compat — só se exporta o MP4 clássico;
• filter.tracks não é uma designação de pistas;
• a duração vem como now — a exportação «até ao momento atual» não é admitida: entre a sondagem e a descarga o bordo do arquivo anda, e o comprimento anunciado não bateria certo com o corpo.

Se a entrega se cortar já depois dos cabeçalhos — por exemplo, o disco falha —, a resposta termina como uma transferência incompleta: o curl indica uma ligação cortada e o navegador marca a descarga como falhada. Um ficheiro que chegou inteiro contém todo o troço.

Contadores¶

A exportação é contada em conjunto com o resto das métricas do processo (ver Monitoramento):

• archive_export_requests_total — número de exportações servidas;
• archive_export_recorded_secs_total — segundos de gravação exportados;
• archive_export_bytes_total — bytes exportados;
• archive_export_failures_total — recusas com a etiqueta reason.

As recusas por culpa do cliente e por culpa da cabeça de rede são separadas de propósito: um pedido inválido não é sinal de avaria, e não há que acordar ninguém por causa dele.

O que se segue¶

• Reprodução do arquivo — retrocesso e janela por tempo absoluto.
• Gravação e leitura — onde o arquivo é escrito e como a gravação é verificada.
• Monitoramento — para onde vão os contadores de exportação.