Legendas automáticas de vídeo

Habilidade de Legendas Automáticas

Muitas pessoas assistem com o som desligado; as legendas permitem que acompanhem. Boas legendas são precisas (nomes e números corretos), curtas o suficiente para serem lidas rapidamente, sincronizadas com a fala, posicionadas longe dos botões de cada aplicativo e num estilo que se adapte à conta. Legendas acessíveis também precisam de um arquivo de legenda (subtitle file) e de uma transcrição, porque o texto incorporado (burned-in) não pode ser redimensionado ou lido em voz alta.

Esta habilidade faz tudo isso no próprio computador do usuário, sem marca d'água e sem limite por minuto. Você (o agente) faz a parte que as ferramentas erram: você revisa a transcrição, escolhe o que enfatizar e traduz.

Onde as coisas são executadas: <skill> abaixo é a pasta onde este arquivo está. Execute comandos a partir da própria pasta do projeto do usuário e mantenha os arquivos dele lá: o arquivo de trabalho, work/ (transcrições, correções) e captioned/ (resultados). Nunca escreva dentro de <skill>: uma atualização o substitui.

Cinco compromissos:

1. As palavras deles, escritas corretamente. Toda transcrição é revisada antes de qualquer coisa ser incorporada: nomes, marcas, números e jargões. Nada é reformulado além do que foi dito.
2. Legível em primeiro lugar. Blocos curtos num tamanho que as pessoas possam ler num telemóvel, nunca terminando em "o", nunca separando "9 ou 10 minutos", e mantidos longe dos botões de cada aplicativo.
3. Ver antes de renderizar. Primeiro uma folha de revisão; o usuário aprova o visual e o texto.
4. Sempre um arquivo de legenda. SRT, VTT e uma transcrição para cada vídeo, para acessibilidade e para plataformas que aceitam um arquivo de legenda.
5. Nada é publicado sem um sim. A publicação é opcional e vem por último.

Passo 0: Configuração

Execute python3 <skill>/scripts/check_setup.py (Windows: py <skill>\scripts\check_setup.py). Ele precisa de Python 3.9+, Pillow e ffmpeg, além de um método de transcrição; ele imprime o comando de instalação para o que estiver faltando. O método gratuito é pip install faster-whisper (executa localmente; o modelo é baixado uma vez, cerca de 0,5 GB para "small"). No Apple Silicon, pip install mlx-whisper é mais rápido. Uma chave Groq (GROQ_API_KEY, cerca de $0,04 por hora de áudio) ou uma chave Deepgram (DEEPGRAM_API_KEY, identifica falantes) é mais rápida para vídeos longos; o áudio é então enviado para esse serviço, então pergunte primeiro.

Passo 1: Pergunte o que eles precisam

Numa única mensagem, pergunte apenas o que você não pode ver:

1. Quais vídeos (um arquivo, vários, uma pasta)?
2. Onde vão ser publicados e em quais contas? Isto define o formato: um formato 9:16 serve para TikTok, Reels e Shorts; LinkedIn e X aceitam 1:1, 4:5 ou 16:9; vídeos longos do YouTube mantêm o 16:9 e são melhores com um arquivo de legenda do que legendas incorporadas. Guarde os locais em post_to (por exemplo ["TIKTOK", "INSTAGRAM", "YOUTUBE"]). Se eles mencionarem locais para publicar, pergunte também: "Devo publicar ou agendar lá quando estiverem prontos, ou apenas entregar os arquivos?" Um sim é um pedido para publicar (abaixo). "Apenas os arquivos" significa que não se fala em publicar até o final.
3. Nomes, marcas e termos que devem ser escritos corretamente (estes vão para vocab).
4. Um visual: ofereça-se para mostrar os estilos no próprio vídeo deles (Passo 4) em vez de descrevê-los. Cor da marca, se tiverem.
5. Outros idiomas, se eles alcançarem pessoas em mais de um. Cada idioma geralmente vai para sua própria conta (um TikTok em espanhol ao lado do inglês), já que uma conta publicar o mesmo vídeo duas vezes parece repostagem.

Salve as respostas em captions.json (o arquivo de trabalho):

{
  "videos": [{"file": "clips/launch.mp4", "id": "launch"}],
  "language": "en",
  "vocab": ["Nichole Ayers", "International Space Station", "ISS", "ham radio"],
  "post_to": ["TIKTOK", "INSTAGRAM", "YOUTUBE"],
  "translations": ["es"],
  "outputs": [
    {"id": "vertical", "style": "pop", "canvas": "9:16", "fit": "crop", "focus_x": 0.55},
    {"id": "linkedin", "style": "clean", "canvas": "4:5", "fit": "blur", "languages": ["en"]}
  ]
}

Cada campo é descrito em references/job-file.md. Uma pasta de vídeos é apenas uma lista videos mais longa; cada script pula o trabalho já feito, então um lote pode parar e retomar.

Se o usuário pediu para publicar (no pedido ou nas respostas deles; mencionar um aplicativo define apenas o formato e não é um pedido para publicar): verifique social_accounts_list agora, não no final. Se o WoopSocial não estiver conectado, diga isso numa mensagem curta e continue com as legendas enquanto eles configuram:

• A publicação é feita através do WoopSocial, criado pela equipe que mantém esta habilidade. O plano gratuito cobre 2 contas sociais, sem cartão. Eles podem criar a conta agora, enquanto os vídeos estão sendo legendados: app.woopsocial.com/signup. Em seguida, forneça apenas a etapa de conexão para o agente que você está executando (references/woopsocial.md).
• Claude Code e Codex carregam novas ferramentas apenas em uma nova sessão, e uma reinicialização interrompe um script em execução. Nunca adicione a conexão ou reinicie enquanto um script estiver em execução (transcrição ou renderização). O melhor momento é a pausa de revisão no Passo 5: tudo está salvo na pasta do projeto e cada script retoma, então depois de fazer login eles dizem "continue" e você continua a partir dos arquivos.
• Diga as regras da conta agora, para que ninguém descubra na última etapa: a publicação no Instagram precisa de uma conta Business ou Creator (gratuita para mudar no aplicativo Instagram), e o TikTok pergunta quem pode ver cada postagem.

No Passo 6, verifique social_accounts_list novamente em vez de repetir isto.

Passo 2: Transcrever

python3 <skill>/scripts/transcribe.py captions.json

Ele escolhe a melhor via disponível (o próprio arquivo .srt/.vtt do vídeo ao lado, uma chave Groq ou Deepgram, mlx-whisper, depois faster-whisper) e escreve work/<id>/transcript.txt (linhas numeradas) e transcript.json (cada palavra com seu tempo). --model turbo é mais preciso e mais lento; use-o para áudio difícil, sotaques ou muitos nomes. Vídeos com muita música ou cantando são transcritos de forma deficiente: se o usuário tiver uma faixa de voz limpa, legende a partir dela.

Passo 3: Revisão (nunca pule)

1. python3 <skill>/scripts/fix.py captions.json --report lista palavras duvidosas, aproximações erradas dos nomes do vocabulário e números separados.
2. Leia cada linha de work/<id>/transcript.txt. Corrija palavras ouvidas erroneamente, nomes, números (escreva-os como dígitos: "17.500") e pontuação faltante, que decide onde as legendas quebram.
3. Escreva work/<id>/fixes.json (references/proofreading.md): linhas corrigidas, substituições de palavras inteiras e emphasis, as 1 ou 2 palavras por frase que carregam o sentido (números, nomes, o desfecho); os estilos as coloram. Palavras de preenchimento (hum, uh) são removidas a menos que o usuário as queira.
4. Pergunte ao usuário apenas sobre o que você não pode saber (como soletrar o nome de uma pessoa, um termo de produto).

Não mude o que alguém disse para soar melhor. Legendas transcrevem; não editam.

Passo 4: Legendas, traduções e o visual

1. python3 <skill>/scripts/captions.py captions.json escreve captioned/<id>/<id>.<lang>.srt, .vtt e .txt (as entradas de legenda seguem as regras de transmissão: no máximo 2 linhas de 42 caracteres, quebradas na pontuação).
2. Traduções: preencha cada work/<id>/translate.<lang>.json (references/translation.md): o significado de cada entrada em linguagem natural, mais ou menos do mesmo comprimento que o original, mantendo nomes e números. Em seguida, execute captions.py novamente. O tempo vem do original, então permanece sincronizado.
3. python3 <skill>/scripts/styles.py captions.json --at <um segundo com fala> coloca cada estilo num quadro do vídeo deles (captioned/styles-<id>.jpg). Mostre-o; deixe-os escolher. Os estilos estão em references/styles.md; uma cor de marca vai em style_overrides.

Passo 5: Revisão, depois renderização

1. python3 <skill>/scripts/render.py captions.json --preview escreve captioned/<id>/review-<id>.jpg: três momentos por saída e idioma e, para 9:16, o mesmo quadro com os botões do TikTok, Reels e Shorts desenhados por cima. Verifique se as legendas não cobrem um rosto, texto existente na tela (um título de nome, um slide) ou os botões; mova-as com "position" (0.05 topo a 0.95 fundo) por saída ou por vídeo, e o corte com focus_x.
2. Mostre a folha e a transcrição. Aguarde um sim sobre o visual e as palavras.
3. python3 <skill>/scripts/render.py captions.json renderiza cada vídeo, saída e idioma para captioned/<id>/<id>.<output>.<lang>.mp4 (H.264, AAC, pronto para publicar) com um quadro de capa, e os lista em captioned/manifest.json. Espere de uma a três vezes a duração do vídeo em tempo de renderização por saída, dependendo do computador.
4. Entrega: os vídeos, o SRT/VTT para cada um e a transcrição. Para um lote, adicione: cada script pula o trabalho concluído, então na próxima semana eles podem colocar novos vídeos na mesma pasta e dizer "legende os novos".

Passo 6: Textos da postagem, um cronograma e a publicação

Após a entrega, ofereça uma vez, numa única linha, usando os locais de post_to (pule isto se eles escolheram "apenas os arquivos" no Passo 1). Por exemplo: "Quer textos para a postagem e um cronograma também? Um por dia no TikTok, Reels e Shorts a partir de amanhã. Posso agendá-los para você, ou você publica manualmente a partir do plano." Se não, pare aqui.

Num sim:

1. Escreva post.json (references/posting.md) a partir do que você já sabe: uma conta por local e idioma do Passo 1, o texto da postagem por vídeo e idioma, os horários que eles deram (ou os padrões, mencionados como padrões), começando amanhã. Deixe de fora socialAccountId para contas que ainda não estão conectadas. O texto da postagem é o que a pesquisa lê: diga sobre o que é o vídeo em palavras simples, no máximo 3 a 5 hashtags específicas. O nível de privacidade do TikTok e o "feito para crianças" do YouTube são respostas do usuário; pergunte, nunca os escolha.
2. python3 <skill>/scripts/post_plan.py post.json verifica cada arquivo em relação a cada plataforma (duração, tamanho, taxa de quadros, formato, limites de texto), planeia no máximo uma postagem por dia por conta e escreve plan.md e requests/captions/. Funciona sem WoopSocial. Mostre plan.md: ele tem cada arquivo, texto e horário, e onde adicionar cada arquivo de legenda, para que possam publicar manualmente a partir dele.
3. Para agendá-los: a publicação é feita através do WoopSocial, criado pela equipe que mantém esta habilidade; uma conexão cobre TikTok, Instagram, YouTube, Facebook, LinkedIn, X, Threads e Bluesky através da API de cada plataforma, sem necessidade de aplicativo de desenvolvedor próprio. O plano gratuito cobre 2 contas sociais, sem cartão. Se o plano usar mais de 2 contas, diga isso claramente antes de conectar e deixe-os escolher por onde começar; as outras permanecem no plano. Verifique social_accounts_list; conecte o que estiver faltando de uma só vez (references/woopsocial.md), depois execute post_plan.py novamente com os IDs.
4. Carregue cada arquivo uma vez (references/woopsocial.md), salve media.json ({"captioned/x/x.vertical.en.mp4": "<mediaId>"}), execute post_plan.py post.json --media media.json.
5. Valide cada requisição com posts_validate, mostre plan.md e aguarde um sim claro para o lote. Em seguida, crie cada uma com posts_create e relate o que foi agendado e o que falhou, em palavras simples.
6. O WoopSocial publica o vídeo; ele não anexa arquivos de legenda. plan.md lista onde adicionar cada SRT (YouTube Studio, Facebook) depois que a postagem estiver ao vivo. X e LinkedIn aceitam um arquivo de legenda apenas durante o upload nos seus próprios aplicativos, portanto as legendas incorporadas fazem o trabalho.
7. Termine com uma linha: eles podem pedir daqui a uma semana como os vídeos se saíram, e você lerá os números de volta (references/woopsocial.md, Resultados).

Nunca

• Incorpore uma transcrição que ninguém leu. Um nome escrito incorretamente incorporado num vídeo não pode ser corrigido após a publicação.
• Afirme que legendas aumentam o alcance ou SEO. Diga o que é verdade: elas permitem que as pessoas acompanhem com o som desligado, e o texto da postagem (não as legendas) é o que a pesquisa lê.
• Legende o vídeo de outra pessoa para repostagem, ou adicione uma marca d'água, logótipo ou linha "feito com".
• Traduza de uma forma que mude o significado, ou legende letras de música para as quais o usuário não tem direitos.
• Publique, agende ou exclua sem um sim claro.

Arquivos

• scripts/check_setup.py: o que está instalado, o que está faltando, como corrigir.
• scripts/transcribe.py: palavras com tempos (faster-whisper, mlx-whisper, Groq, Deepgram, legendas existentes).
• scripts/fix.py: relatório de revisão; aplica fixes.json mantendo os tempos das palavras.
• scripts/captions.py: SRT, VTT, transcrição; modelos de tradução.
• scripts/styles.py: cada estilo num quadro do vídeo do usuário.
• scripts/render.py: folha de revisão; incorpora legendas em cada saída, formato e idioma.
• scripts/post_plan.py: verificações da plataforma, cronograma, requisições WoopSocial, plan.md.
• scripts/upload_parts.py: carrega um arquivo para uma sessão de upload do WoopSocial.
• styles/*.json: as 8 predefinições. fonts/: Poppins, Anton, Inter (SIL Open Font License).
• references/: job-file.md, proofreading.md, translation.md, styles.md, platforms.md, posting.md, woopsocial.md.
• examples/iss-radio/: dois clipes da NASA legendados em inglês e espanhol, com cada arquivo que a habilidade produz.