ahkamboh/agent-caption

agent-caption — SKILL

Você é um agente de legendas de IA. Este repositório adiciona legendas/gravações precisas e perfeitamente sincronizadas a qualquer vídeo ou áudio, em qualquer idioma (inglês por padrão), tanto para fala quanto para música, com suporte de primeira classe para Hinglish / código misto. Funciona em Windows, macOS e Linux.

Repositório: https://github.com/ahkamboh/agent-caption — clone: git clone https://github.com/ahkamboh/agent-caption Este arquivo, raw (para agentes de chat buscarem): https://raw.githubusercontent.com/ahkamboh/agent-caption/master/SKILL.md

Princípio central: as palavras vêm do reconhecimento de fala, mas o TEMPO vem do alinhamento forçado na forma de onda — nunca dos timestamps brutos do ASR. Portanto, as legendas nunca ficam adiantadas ou atrasadas, mesmo quando a transcrição contém erros de ortografia.

Configuração única (Windows / macOS / Linux)

Requer: Python 3.10+, ffmpeg, ~4 GB de disco. (torch fornece wheels até o 3.14; se whisperx não tiver wheel para um Python muito novo, use 3.11–3.12.)

python setup.py        # multiplataforma: cria ./.venv-whisperx e instala tudo
# macOS/Linux conveniência: bash setup.sh      ·      Windows conveniência: setup.bat

ffmpeg: macOS brew install ffmpeg · Ubuntu sudo apt install ffmpeg · Windows winget install ffmpeg. Modelos (Whisper large-v3 — o padrão — MMS_FA, whisperX) baixam automaticamente na primeira execução.

Caminho mais fácil — o wrapper de comando único (PREFIRA ESTE)

Para solicitações "legendar este vídeo", basta executar o wrapper de nível superior. Ele faz transcrição → alinhamento → queima com legendas de proporção automática (tamanho/espaçamento/alinhamento corretos para qualquer resolução), e recorre a um renderizador sem libass (Pillow + overlay) se o ffmpeg do usuário não tiver suporte a legendas:

python caption.py <video>                                  # Inglês, limpo, proporcionado -> <video>.captioned.mp4
python caption.py <video> --hinglish --style tiktok        # Hinglish + caixa TikTok
python caption.py <video> --lang ur --pos center --size 6  # outro idioma / posição / tamanho
python caption.py <video> --srt                            # apenas escrever um .srt (sem queimar)
python caption.py <video> --from-srt FILE                  # queimar um .srt existente, proporcionado

15 estilos (fontes inclusas): clean (padrão) bold hormozi green beast impact bebas tiktok pill boxed yellow neon gradient minimal subtitle. Recorra aos scripts individuais abaixo apenas quando precisar da transcrição bruta, renderização personalizada ou tradução.

Modelo: large-v3 é o PADRÃO (melhor precisão) — nenhuma flag necessária; setup.py o pré-baixa. Quer velocidade em inglês limpo? adicione --fast (modelo pequeno). --accurate ainda existe, mas agora é redundante. O caminho Hinglish sempre usa large-v3.

Estilo personalizado — crie QUALQUER aparência que o usuário descrever. Mapeie as palavras do usuário para estas flags (elas substituem --style):

• --font <nome|caminho> — uma fonte inclusa (Poppins-Bold, Poppins-Black, Anton-Regular, BebasNeue-Regular, ArchivoBlack-Regular) ou qualquer caminho .ttf
• --fill #hex (cor do texto) · --outline #hex · --box #hex|#hexAA|none (pílula atrás do texto)
• --caps / --no-caps · --gradient "#hex,#hex,#hex" · --glow · --ow N (espessura do contorno)
• --size <pct> (altura) · --pos bottom|center|top

Exemplo — usuário diz "caps rosa choque em uma caixa escura arredondada, grande, fonte Anton" →

python caption.py v.mp4 --fill "#ff3da6" --box "#10141ae0" --caps --font Anton-Regular.ttf --size 6

Para tornar um novo estilo nomeado permanente, adicione uma entrada ao dicionário STYLES em caption.py.

Precisão — elimine palavras mal ouvidas (grátis, sem tokens, sem olhada humana)

O alinhamento forçado torna o timing correto por construção. A única coisa que ele não pode corrigir é se uma palavra foi ouvida corretamente ("seu"/"sua", nomes, gírias). Três alavancas gratuitas empurram isso para zero:

• --glossary "..." — forneça nomes/marcas/gírias (uma lista ou um caminho .txt). Influencia o initial-prompt do ASR para que nomes próprios parem de ser mal interpretados. O maior ganho único em nomes. Lista única.

  python caption.py talk.mp4 --glossary "Xaibridge, Hinglish, Xotion, Kamboh"
  

• --script FILE — se as palavras corretas já existem (letras, um roteiro), passe-as. A ferramenta pula o ASR completamente e apenas alinha forçadamente as palavras fornecidas → 100% de precisão de conteúdo.

  python caption.py song.mp4 --script lyrics.txt
  

• --grammar — passagem offline de homófonos/gramática sobre as legendas ("seu"→"sua", "mais"→"mas"). Executa o LanguageTool localmente (sem upload, sem tokens); o timing nunca é alterado. Dependência opcional — habilite uma vez com python setup.py --grammar (precisa de Java/JRE 8+); ignora corretamente se ausente.

  python caption.py talk.mp4 --accurate --glossary names.txt --grammar    # empilhe-os
  

Ordem custo-benefício: --glossary (nomes) → --script (quando o texto existe) → --grammar (homófonos). O modelo base já é large-v3 por padrão. O único resíduo que estes não conseguem capturar precisa de um humano ou de um LLM — esse é o único custo que vale a pena gastar tokens, e apenas nas palavras sinalizadas, não na transcrição inteira.

Músicas — isole os vocais primeiro (--content)

Para música, separar o stem vocal antes do ASR torna a transcrição da letra muito mais limpa (Whisper para de lutar contra a faixa de fundo). É condicional — inútil/lento em fala limpa — portanto, é controlado:

python caption.py song.mp4 --content music                 # forçar isolamento vocal (demucs)
python caption.py clip.mp4                                  # --content auto (padrão): detecta música, isola apenas então
python caption.py podcast.mp4 --content speech              # nunca isolar (ou --no-isolate)
python caption.py song.mp4 --content music --script lyrics.txt   # músicas mais limpas: palavras conhecidas, temporizadas no stem vocal

auto executa uma sonda rápida de música/fala e isola SOMENTE quando ouve música — assim, podcasts/entrevistas nunca são atrasados. A queima sempre usa o vídeo original; apenas o que transcrevemos/aliamos é o stem. Precisa de demucs (instalado por python setup.py); recai ao áudio original se ausente.

Sempre execute os scripts com o python do venv — escrito aqui como PY:

• macOS / Linux: PY = ./.venv-whisperx/bin/python
• Windows: PY = .venv-whisperx\Scripts\python

Os scripts

• transcribe.py — Whisper → transcrição nível de palavra (inglês padrão; --lang xx para outros).
• align.py — alinhamento forçado para temporização precisa de quadro. --code-switch para Hinglish/misto.
• cs_transcribe.py — reconhecimento de palavras robusto a código misto (identificação de idioma por segmento).
• mms_align.py — alinhador forçado universal MMS_FA (1100+ idiomas, qualquer escrita).
• validate_timing.py — verificação de sanidade de temporização usada pelo caminho de código misto.
• export-subs.py — transcrição → .srt + .vtt.
• multilang-subs.py — traduzir legendas para muitos idiomas, offline.
• grammar_fix.py — correção offline de homófonos/gramática em um .srt (timing preservado); usado por --grammar.
• isolate_vocals.py — isolamento vocal Demucs para músicas + uma sonda de música-vs-fala; usado por --content.
• qa.py — portão de QA determinístico rápido (sanidade de cue + verificação de saída ffprobe) → work/<base>.qa.json. Executa automaticamente após cada queima; --strict faz uma saída quebrada sair com código não zero.
• footprint.py — renderiza <base>.footprint.svg: um mapa de saúde de legendas de relance (cada palavra colorida por confiança de alinhamento forçado + marcadores de lacuna + veredito). Executa automaticamente após cada legenda; --no-footprint para pular.
• benchmark.py — medir o ganho real de precisão: WER do padrão antigo (pequeno) vs o novo padrão (large-v3 [+ Demucs]) contra uma transcrição de referência. PY scripts/benchmark.py CLIP --ref truth.txt [--music] [--hinglish].
• caption.py — tudo-em-um legendas estilizadas (karaokê/palavra/linha; Hormozi/TikTok/neon…) → animadas captions.js.

Legendar um vídeo (a tarefa principal) — idioma padrão = inglês

Para outro idioma, passe --lang <code>. Para Hinglish / misto use --code-switch.

1) Temporizações de palavra precisas de quadro

Fala (conversa, podcast, UGC):

PY scripts/align.py INPUT --lang en --out work/transcript.json

Hinglish / hindi-inglês misto (ou qualquer áudio com código misto):

PY scripts/align.py INPUT --code-switch --dual hi en --out work/transcript.json

Qualquer outro idioma (urdu, espanhol, árabe, chinês, …):

PY scripts/align.py INPUT --lang ur --out work/transcript.json

2a) Legendas (.srt / .vtt) + queima no vídeo

PY scripts/export-subs.py work/transcript.json --out work/subs
ffmpeg -i INPUT -vf "subtitles=work/subs.srt" -c:a copy captioned.mp4

O .srt também é perfeito para enviar diretamente ao YouTube (selecionável + SEO).

2b) Legendas estilizadas / animadas (Hormozi, TikTok, karaokê — formato curto)

PY scripts/caption.py INPUT --lang en --content speech --style karaoke --preset hormozi --out out/

Presets: hormozi, beast, pill, neon, gradient, minimal, tiktok. Use --content music para músicas/letras. Veja docs/caption-styles.md.

3) Traduzir legendas para qualquer idioma (opcional)

PY scripts/multilang-subs.py work/subs.srt --to "hi,ur,es,fr,ar,de" [--burn INPUT]

Regras (incorporadas — não substitua)

• O timing é SEMPRE alinhamento forçado, nunca timestamps brutos do ASR (sem adiantamento/atraso).
• Idioma padrão das legendas = inglês; passe --lang para qualquer outro.
• Música/canto → --content music; fala/conversa → --content speech.
• Execute todo script com PY (o python do venv) para que tenha whisperx/torch.
• Antes de entregar, verifique algumas legendas em seus inícios de palavra para confirmar a sincronia.

Códigos de idioma

en (padrão), hi, ur, pa, es, fr, de, pt, ar, zh, ja, ko, ru, it, tr, id, nl, pl, uk, … — Whisper suporta ~99 idiomas; MMS_FA alinha 1100+.