Transcodificação

A transcodificação converte um único arquivo enviado em diversas versões MP4 compatíveis com a web, oferecendo ao espectador um menu de qualidade, reprodução de início rápido e um codec consistente independentemente do arquivo enviado. Também incorpora recursos opcionais — marcas d'água e clipes de intro/outro — e gera os sprites de pré-visualização de scrubbing usados pelo player.

Tudo aqui é configurado em /admin/settings?tab=transcode, dividido nas sub-abas Formats, Queue, Servers, Watermark, Intros e Timeline. A transcodificação pode ser executada no próprio servidor CMS ou distribuída para workers dedicados.

Por que transcodificar

Um arquivo enviado pode ter qualquer resolução, codec ou contêiner. A transcodificação o padroniza em versões MP4/H.264 com +faststart para que a reprodução comece antes que o arquivo seja totalmente baixado, e produz vários tamanhos (por exemplo, 720p e 480p) para que o player possa oferecer um seletor de qualidade e servir arquivos menores para telas menores. A mesma passagem é onde marcas d'água e clipes de pré/pós-roll são aplicados, pois precisam ser codificados em cada versão.

O pipeline de transcodificação

Quando um vídeo está pronto para processamento, o TubePress enfileira um job por saída na tabela transcode_jobs e os processa:

1. Fila. Um job é criado para o nível de origem em resolução máxima e para cada formato ativo abaixo da altura da origem, além de um job de timeline se as pré-visualizações estiverem habilitadas.
2. Captura. Um worker — este servidor ou um remoto — assume o próximo job pendente, começando pelo nível de origem.
3. Download. Um worker remoto obtém a origem via HTTP (uma URL direta autenticada por chave que ignora links de mídia assinados).
4. Transcodificação. O FFmpeg codifica a versão, aplicando corte, marca d'água e intros conforme configurado, reportando o progresso em porcentagem.
5. Upload & callback. O resultado é enviado de volta em partes e um callback marca o job como concluído.

O status do vídeo acompanha isso: fica em processing enquanto os jobs rodam, muda para published assim que o nível de origem termina, e só vira error se o nível de origem nunca puder ser produzido. Versões menores continuam sendo preenchidas após a publicação.

Versões & formatos

Os formatos de saída são totalmente editáveis na aba Formats e armazenados na tabela video_formats. Cada formato tem um nome, um sufixo de arquivo (por exemplo _720p.mp4), uma resolução alvo, opções brutas do FFmpeg, um sinalizador de manter proporção e um toggle de ativo. Os padrões integrados são:

Duas regras mantêm a qualidade sensata. O TubePress nunca faz upscaling: qualquer formato com altura igual ou superior à da origem é ignorado. E a qualidade original máxima é sempre mantida — se uma marca d'água ou corte estiver em uso, é recodificada em uma versão de origem em resolução máxima (mostrada com uma estrela na fila); caso contrário, o arquivo de origem é servido como está. Uma opção de Corte inicial (0–300 segundos) pode remover os primeiros segundos de cada vídeo; como a marca d'água, é aplicada a todos os formatos incluindo a origem.

A fila de jobs

A aba Queue (/admin/settings?tab=transcode&sub=queue) agrupa jobs por vídeo e permite filtrar por All / Pending / Processing / Completed / Failed. Cada vídeo mostra um badge por nível — o nível de origem com estrela, depois cada resolução e então TIMELINE — colorido pelo status do job:

Um console por vídeo (o ícone de terminal) transmite ao vivo a lista de jobs, o worker responsável por cada nível, o tempo decorrido e qualquer mensagem de erro. O botão Retry failed jobs recoloca na fila tudo que está com falha com um clique.

Servidores de transcodificação remotos

A transcodificação consome muito CPU, portanto você pode movê-la para fora do servidor web. Na aba Servers, This Server define quantos jobs FFmpeg rodam localmente ao mesmo tempo (1–4, ou 0 para usar somente workers remotos) e permite substituir o caminho do FFmpeg. Abaixo disso você registra workers remotos; os jobs são distribuídos automaticamente para o menos carregado, e cada um tem um limite de max concurrent jobs (uma boa regra é um job por dois núcleos de CPU).

1. Adicione o servidor. Clique em Add Server, dê um nome e uma URL como http://YOUR-IP:8090 e salve. Uma chave API e o comando de inicialização são exibidos imediatamente.
2. Instale FFmpeg + PHP. No servidor worker, execute sudo apt install ffmpeg php-cli php-curl.
3. Implante o worker. Baixe transcode-worker.php (em /api/transcode-worker-download ou um link wget temporário), faça o upload e abra a porta com sudo ufw allow 8090/tcp.
4. Inicie. Execute o worker com sua chave:

php transcode-worker.php --port=8090 --key=YOUR_API_KEY

1. Verifique. Clique em Check; um worker saudável reporta Online com o encoder detectado e o uso ao vivo de CPU/GPU.

A aceleração GPU (NVIDIA, AMD, Intel ou Apple) é detectada e usada automaticamente. O worker obtém a origem, transcodifica, reporta o progresso e envia os resultados em partes de volta ao CMS — o upload em partes é o que mantém cada requisição abaixo do limite de 100 MB do Cloudflare. Para servidores sem supervisão, o guia de configuração inclui uma unidade systemd para que o worker reinicie na inicialização.

Monitoramento & novas tentativas

O sistema é construído para que um vídeo nunca seja abandonado silenciosamente. Uma codificação com falha é repetida automaticamente com um back-off crescente — de cerca de meio minuto a algumas horas — porque a maioria das falhas é transitória (um CDN lento ou instável). Além disso, uma tarefa de recuperação a cada hora recoloca na fila qualquer job ainda marcado como falho, continuando as tentativas até que a versão seja produzida. Nenhum clique manual é necessário, embora o botão Retry failed jobs esteja disponível se quiser forçar.

Se o próprio nível de origem falhar permanentemente, os jobs de sub-formato dependentes são cancelados (não podem prosseguir sem uma origem) e o vídeo é marcado como error; a recuperação ainda tentará restaurá-lo. Quando o nível de origem finalmente concluir, o vídeo é publicado automaticamente.

Requisitos

O FFmpeg deve estar disponível onde quer que a transcodificação seja executada:

• Processamento local: instale o FFmpeg no servidor CMS (sudo apt install ffmpeg). A página Transcode exibe a versão detectada assim que estiver presente.
• Processamento remoto: cada worker precisa do FFmpeg mais php-cli e php-curl, pelo menos 2 núcleos de CPU e 2 GB de RAM, e uma porta de worker aberta.

Próximos passos