zaddy99999/captions

O que captions faz?

Transcrição local no nível da palavra, estilização e gravação de legendas em formato curto.

Os scripts estão em scripts/:

Script	Função
transcribe.py	faster-whisper com word_timestamps=True para words.json (cache)
make-captions.mjs	words.json para ASS (estilizado, destaque de palavra ativa) e SRT
burn.mjs	grava ASS/SRT com libass (filtro ass / subtitles)
snap-to-words.mjs	move pontos de corte para o intervalo mais próximo entre palavras

Fluxo de trabalho

1. Transcrever (uma vez por fonte; o resultado é cacheado):

   pip install faster-whisper            # uma vez
   python3 scripts/transcribe.py --input clip.mp4 --out edit/clip.words.json --model small --language pt
   

   A primeira execução baixa o modelo do Hugging Face. Se isso estiver bloqueado, o script termina com código 4 e uma mensagem JSON fix em vez de um traceback; ele nunca escreve uma transcrição falsa. Aponte --model para uma pasta de modelo CTranslate2 local para trabalhar offline.
2. Criar legendas:

   node scripts/make-captions.mjs --words edit/clip.words.json --out-ass edit/clip.ass --out-srt edit/clip.srt
   

   O estilo vem do pacote de marca (bloco captions: tamanho, margem, contorno, destaque; colors.accent é a cor da palavra ativa).
3. Gravar como a última etapa visual:

   node scripts/burn.mjs --input edit/clip-hook.mp4 --subs edit/clip.ass --out edit/clip-captionado.mp4
   

   Use --fonts-dir quando a fonte da legenda for um arquivo em vez de uma fonte instalada.
4. Verificar com uma folha de prova render-qc: legível, dentro da área segura, sem sobrepor a placa de gancho.

Regras

• Nunca corte dentro de uma palavra. Antes de dividir a fala, ajuste os cortes para intervalos entre palavras: node scripts/snap-to-words.mjs --words edit/clip.words.json --markers edit/cuts.json --out edit/cuts.json
• Legendas vão por último: após cortes, sobreposições e correção de cor. Se você cortar o clipe após transcrever, passe --offset -<segundos_cortados> para make-captions.mjs.
• 1 a 3 palavras por bloco para shorts (maxWords, maxChars). Os blocos quebram em pontuação e pausas.
• Mantenha as legendas fora dos ~15% inferiores (UI da plataforma) e longe da placa de gancho: ajuste captions.marginV.
• As transcrições são cacheadas: execute novamente com --force apenas se o áudio mudou.
• Verifique palavras aleatórias em relação ao áudio; o whisper pode entender errado nomes e jargões. Corrija words.json manualmente se necessário.

Sem libass no ffmpeg

Se burn.mjs informar que não há filtro ass, a compilação do ffmpeg não tem libass. Instale uma compilação completa (a maioria dos gerenciadores de pacotes fornece uma), ou carregue o SRT como uma faixa de legenda separada em vez de gravá-lo.