/video-translate — Tradução e Transcrição de Vídeos
Capacidade e Identificação de Intenção (Devem Ser Rigorosamente Seguidas)
- Transcrever e gerar documento: Capturar legendas ou áudio e transcrever → Gerar documento Markdown (prioridade para legendas, mais rápido e gratuito).
- Traduzir vídeo: Transcrever → Traduzir e refinar → Queimar legendas em chinês → Gerar arquivo de vídeo legendado + documento Markdown.
Regras de decisão:
- O usuário disser "transcrever", "converter em texto", "gerar documento", "converter para markdown" → Apenas gerar documento Markdown (seguir o fluxo 'apenas documento').
- O usuário disser "traduzir", "traduzir vídeo", "adicionar legenda", "colocar legenda" → Deve executar o pipeline de tradução completo (extrair áudio → transcrever com Whisper para SRT → traduzir e refinar → queimar legenda no vídeo → gerar Markdown simultaneamente), não pode apenas gerar o documento e encerrar.
- A entrada for uma URL → Baixar primeiro e depois processar; caminho de arquivo local → processar diretamente.
Interpretador Python: Todos os comandos desta skill seguem a sintaxe Windows usando python. Em macOS/Linux, substitua por python3.
Definir SKILL_DIR (Faça Isso Antes de Executar Qualquer Comando)
Defina SKILL_DIR como o caminho absoluto do diretório onde este SKILL.md que você acabou de ler está localizado. Os scripts estão sempre em SKILL_DIR/scripts/. Primeiro, a verificação:
SKILL_DIR="<caminho absoluto do diretório do SKILL.md que você leu>"
if [ ! -f "$SKILL_DIR/scripts/transcribe_srt.py" ]; then
echo "ERROR: scripts not found under SKILL_DIR=$SKILL_DIR" >&2
exit 1
fi
Etapa -1: Definir a Raiz de Saída (⛔ Obrigatório, Antes de Tudo)
Antes de executar qualquer comando/escrever qualquer arquivo, primeiro leia a configuração para obter output_dir como <raiz de saída>:
python -c "import sys; sys.path.insert(0, r'${SKILL_DIR}/scripts'); import config; c = config.load_translate_config(); config.ensure_output_root(c['output_dir']); print(c['output_dir'])"
- O arquivo de configuração está em
~/.config/video-skills/translate.json(na primeira execução, pode executarpython "${SKILL_DIR}/scripts/setup.py"para gerar o template). output_dirdeve ser um caminho absoluto ou começar com~. Se estiver ausente/inválido, o comando acima reportará um erro — pare imediatamente, avise o usuário para editar o arquivo e inserir um caminho absoluto. Não preencha automaticamente com um valor padrão e continue.- Artefatos intermediários sempre escreva em
<raiz de saída>/tmp/; produtos finais (vídeo, Markdown) escreva em<raiz de saída>/data/. - ⛔ Todos os
<raiz de saída>/...no texto devem ser substituídos pelo caminho absoluto real antes da execução; é proibido incluir placeholders nos comandos (eles seriam gravados no diretório atual, resultando em 'salvamento incorreto'). - Apenas quando o usuário especificar explicitamente um "caminho absoluto para a saída" e confirmar, é permitido escrever no caminho especificado pelo usuário.
Execute também uma verificação de ambiente (compartilhada com /watch, silenciosa se aprovada):
python "${SKILL_DIR}/scripts/setup.py" --check
Se falhar, execute python "${SKILL_DIR}/scripts/setup.py" para instalar dependências (ffmpeg/yt-dlp são instalados automaticamente; mecanismo de transcrição pip install faster-whisper). Para mais detalhes de instalação, em caso de erro, consulte references/guia-de-instalacao.md.
Visão Geral do Pipeline
Entrada (URL / arquivo local)
│
▼
Etapa 0 Tipo de legenda (pipeline de tradução deve primeiro confirmar: chinês / bilíngue)
Etapa 1 Download + extrair áudio → <raiz de saída>/tmp/
Etapa 2 Transcrição de palavras com Whisper para SRT original → <raiz de saída>/tmp/<nome>.srt
Etapa 3 Tradução e refinamento (você mesmo executa, 8 regras) → <nome>-zh.srt (bilíngue com duas linhas/item)
Etapa 4 Queimar legenda (+ marca d'água opcional) → <raiz de saída>/data/<título>-legenda-chinesa.mp4
Etapa 4.5 Verificação de quadros (≥2 quadros)
Etapa 5 Gerar documento Markdown → <raiz de saída>/data/
Cenário de apenas documento pula Etapa 0/3/4, segue a seção 'Apenas Documento'.
Etapa 0: Confirmar o Tipo de Legenda (⛔ Portão, Pipeline de Tradução deve Executar Primeiro)
- Legenda em chinês: Apenas exibe a tradução em chinês (interface limpa).
- Legenda bilíngue chinês-inglês: Chinês em cima (fonte maior), inglês embaixo (fonte menor).
Se o usuário especificou explicitamente o tipo de legenda na conversa (disse "chinês", "bilíngue", "chinese", "bilingual" etc.) → Execute conforme a especificação do usuário. Em todos os outros casos → Deve usar AskUserQuestion para exibir as opções:
AskUserQuestion(
question="Selecione o tipo de legenda",
options=["Legenda em chinês (apenas chinês)", "Legenda bilíngue chinês-inglês (chinês em cima, inglês embaixo)"]
)
⛔ Proibido ignorar: O tipo de legenda incluído em ARGUMENTS não conta como especificação do usuário — apenas o que o usuário disser pessoalmente na conversa é válido. Começar a Etapa 1 sem exibir as opções é um erro de fluxo. O subtitle_type em translate.json é apenas um valor padrão, não pode substituir a confirmação do usuário.
Etapa 1: Download + Extrair Áudio
Fonte URL (unificado via script — cookies do navegador integrados como fallback automático, para lidar com YouTube 403/SABR/PO-token e paywall de login do Bilibili):
# Vídeo completo (pipeline de tradução precisa do vídeo em si para queimar legenda)
python "${SKILL_DIR}/scripts/download.py" "<URL do vídeo>" "<raiz de saída>/tmp/dl"
# Apenas documento e sem necessidade de queima → áudio é suficiente, mais rápido
python "${SKILL_DIR}/scripts/download.py" "<URL do vídeo>" "<raiz de saída>/tmp/dl" --audio
- O script gera JSON (video_path / subtitle_path / info.title).
- Primeira tentativa sem cookies; se o artefato não for salvo, tenta automaticamente
--cookies-from-browser chrome. Se o navegador comum não for Chrome: adicione--browser firefox/--browser edge. - Ainda assim falhar (proteção mais forte) → Avise o usuário para trocar de proxy (
--proxy http://127.0.0.1:7890) e tentar novamente. Não tente infinitamente. - Vídeos longos (>10 minutos) não use
--download-sectionsdo yt-dlp (ele baixaria o vídeo completo primeiro e depois cortaria, extremamente lento); baixe o vídeo completo diretamente, e se precisar de um trecho, corte com ffmpeg-ss.
Extrair áudio (arquivo local ou vídeo baixado → mp3):
ffmpeg -y -i "<arquivo de vídeo>" -vn -acodec libmp3lame -q:a 2 "<raiz de saída>/tmp/<nome do arquivo>.mp3"
Etapa 2: Transcrição de Palavras com Whisper para SRT Original
⛔ Regra de Ferro: O SRT original para queima de legenda só pode ser gerado pela transcrição de palavras do Whisper. É proibido usar legendas automáticas da plataforma (yt-dlp --write-auto-subs) como fonte de tempo. Motivo: Legendas automáticas do YouTube são no formato de sobreposição rolante (cada uma contém o texto da anterior), impossível extrair texto limpo por frase com timestamps precisos, resultando em queima fora de sincronia. Timestamps de palavra são a única fonte de tempo confiável.
python "${SKILL_DIR}/scripts/transcribe_srt.py" "<raiz de saída>/tmp/<nome do arquivo>.mp3" \
--output "<raiz de saída>/tmp/<nome do arquivo>.srt"
# Em caso de detecção de idioma incorreta / múltiplos idiomas misturados, force a especificação: adicione --language en (ou zh/ja/…)
- Mecanismo padrão = faster-whisper local (timestamps de palavra, zero custos de API, na primeira execução baixa automaticamente o modelo do HuggingFace).
- Se faster-whisper não puder ser instalado → Configure
GROQ_API_KEY/OPENAI_API_KEYe adicione--engine api(fallback de API para timestamps de palavra, compartilha a mesma lógica de quebra de frase que a rota local). Se a API não retornar timestamps de palavra, o script fará o downgrade para nível de segmento e indicará claramente no stderr 'precisão da legenda reduzida' — informe isso ao usuário. - ⛛ Não escreva código de transcrição Python diretamente na conversa — O script quebra por 'frase + pausa' (segmento como base / quebra por palavra apenas se >6s / mescla apenas se <400ms). Ignorar o script e escrever uma quebra gulosa pode colocar o final da frase A e o início da frase B no mesmo quadro (problema real já enfrentado e resolvido).
--max-line-mscontrola a duração máxima de uma legenda (padrão 6000ms),--pause-mscontrola o limiar de pausa para quebra de frase (padrão 500ms).
Etapa 3: Tradução e Refinamento (Você Mesmo Executa — Isto é Trabalho de LLM, Sem Script)
Leia o SRT original da Etapa 2, traduza e refine cada entrada, e gere o SRT refinado em <raiz de saída>/tmp/<nome do arquivo>-zh.srt. Seu papel: Editor profissional de legendas, especializado em escrita em chinês, restauração da fala e normas de formatação de legendas.
8 Regras de Refinamento (Núcleo)
- Corrigir erros de reconhecimento ASR: Palavras homófonas/parônimas, nomes próprios (ex: Claude ouvido como cloud, MCP ouvido como NCP), números/abreviações/unidades. Pode consultar o vídeo para auxiliar na decisão.
- Pontuação e formalização: Primeiro, complete a pontuação para tornar a fala em texto escrito (preservando o tom do falante), mas o texto final da legenda deve remover toda a pontuação (vírgula, ponto final, interrogação, exclamação, todos removidos); adicione um espaço em branco entre caracteres chineses e ingleses (ex:
Isto é um produto da Google). - Remover redundâncias: Elimine palavras de preenchimento, repetições e interjeições sem informação ("aquele", "é", "tipo"), garantindo continuidade semântica sem perder informações críticas. É melhor ter um pouco de redundância do que perder o significado.
- Alinhamento de timestamps (rigoroso): Preserve estritamente os timestamps originais, não os desloque arbitrariamente. Nunca adiante manualmente o start time (isso faria a legenda aparecer antes do falante). Corte de legendas muito longas: Se uma legenda tiver >6 segundos e texto curto = Whisper incluiu silêncio/música de fundo após a fala no mesmo segmento. Use detecção de silêncio do ffmpeg para localizar precisamente o ponto final da fala, não use estimativa por fórmula:
Pegue o primeiroffmpeg -i <áudio> -ss <start> -to <end> -af silencedetect=n=-30dB:d=0.5 -f null - 2>&1 | grep silence_startsilence_start(adicione o offset do start) como o end cortado; se todo o segmento tiver som, não corte. Se uma legenda tiver >8 segundos e texto longo, pode ser dividida em várias, com timestamps razoavelmente distribuídos dentro do intervalo original. Proibido mesclar entradas adjacentes, apenas dividir; após a divisão, renumerie consecutivamente; proibido timestamps sobrepostos. - Quebra de linhas e parágrafos: Princípio central: pode dividir, não pode mesclar. Uma entrada original corresponde a uma entrada traduzida. Se exceder 12 caracteres chineses, divida em duas entradas nos pontos de quebra semântica (timestamps distribuídos proporcionalmente). Priorize uma única linha, cada linha ≤12 caracteres chineses (incluindo espaços e inglês), quebre nos pontos de pausa de entonação, não quebre frases completas em duas linhas. É melhor dividir em várias curtas do que empilhar várias linhas na tela.
- Nomes próprios: Mantenha nomes de pessoas/lugares/empresas/produtos no original (primeira letra maiúscula); mantenha termos técnicos em inglês (API, GPU, AI, ASR); marcas amplamente conhecidas não traduza (Google, iPhone, YouTube); termos obscuros na primeira aparição podem incluir uma breve explicação em chinês.
- Estilo de linguagem: Alinhe com o uso da linguagem jovem contemporânea; traduza gírias/internetês de forma natural e coloquial, evite 'tradução' ("isto é muito empolgante" → "isto é muito legal"). Narração use linguagem escrita concisa, diálogo/letras de música mantenham tom coloquial.
- Letras de música: Use ♪ para envolver (
♪ letra ♪), priorize a ambientação e rima, não traduza palavra por palavra. Quando alternar com narração, garanta que o público possa distinguir.
Formato de Saída (SRT Rigoroso)
1
00:00:00,000 --> 00:00:03,500
Esta é a primeira linha de legenda
2
00:00:03,500 --> 00:00:07,200
Esta é a segunda linha de legenda
Números consecutivos começando em 1; timestamp HH:MM:SS,mmm (vírgula separa milissegundos); texto sem pontuação; espaço entre caracteres chineses e ingleses; linha em branco entre entradas; linha em branco no final do arquivo.
Modo Bilíngue (Quando o Usuário Selecionou Bilíngue na Etapa 0)
Gere 'SRT bilíngue': Cada entrada duas linhas — chinês em cima, inglês (original) embaixo, timestamps alinhados um a um com o SRT original (não requebre, não mescle; como o original corta, o chinês segue igual). Linha em chinês: remova pontuação normalmente, padronize termos; linha em inglês: preserve o original (apenas corrija erros de ASR):
1
00:00:19,239 --> 00:00:21,239
Como estão todos
Hello everyone, how are you?
Processamento Paralelo para Vídeos Longos (>10 minutos)
Quando houver muitas legendas, divida em segmentos e processe em paralelo: Cada segmento com aproximadamente 500 entradas, tarefas paralelas de desenvolvedor para tradução. Após traduzir, mescle e renumerie. Após a mesclagem, faça validação global: timestamps sem sobreposição ou saltos, numeração consecutiva, coerência semântica, conformidade de formato.
⛔ Não pare o pipeline: Após o refinamento, execute imediatamente a Etapa 4 (queima), sem relatórios intermediários, sem esperar confirmação do usuário. O pipeline inteiro só reporta uma vez quando todos os produtos finais (vídeo + Markdown) estiverem completos.
Etapa 4: Queimar Legenda (+ Marca d'Água Opcional)
Sempre use burn.py — não monte comandos ffmpeg manualmente. O script concentra: escape de caminhos Windows em filtros (C:\a.srt → 'C\:/a.srt', manualmente erra 9 em 10), conversão forçada de áudio para AAC (faixas Opus do yt-dlp podem falhar upload em X/WeChat/Weibo, ⛔ proibido -c:a copy), parse de fontfile para marca d'água e distribuição temporal, legenda + marca d'água na mesma -vf codificação única (evita perda de qualidade secundária).
Apenas chinês (SRT direto):
python "${SKILL_DIR}/scripts/burn.py" "<arquivo de vídeo>" \
--subs "<raiz de saída>/tmp/<nome do arquivo>-zh.srt" \
--output "<raiz de saída>/data/<título do vídeo>-legenda-chinesa.mp4"
Bilíngue chinês-inglês (converter para ASS primeiro e depois queimar — ⛔ deve usar ASS):
python "${SKILL_DIR}/scripts/bilingual_ass.py" "<raiz de saída>/tmp/<nome do arquivo>-zh.srt" \
--output "<raiz de saída>/tmp/<nome do arquivo>-zh.ass" [--cn-size N] [--height altura_do_vídeo]
python "${SKILL_DIR}/scripts/burn.py" "<arquivo de vídeo>" \
--subs "<raiz de saída>/tmp/<nome do arquivo>-zh.ass" \
--output "<raiz de saída>/data/<título do vídeo>-legenda-chinesa.mp4"
- ⛔ Por que bilíngue precisa de ASS: O filtro
subtitlescom force_style FontSize é uniforme para toda a linha, impossível ter chinês grande e inglês pequeno dentro da mesma linha. Inline{\fsN}em SRT é removido pelo decodificador SRT do ffmpeg (testado com 3 tamanhos de fonte e md5 todos iguais). Apenas ASS verdadeiro alimentado no libass pode ter\Npara nova linha + tamanho de fonte inline.bilingual_ass.pyfaz exatamente isso, não escreva ASS manualmente. - Tamanho da fonte: Se o usuário especificou explicitamente o tamanho da fonte chinesa na conversa (ex: "fonte 24") → passe
--cn-size 24, o inglês é calculado automaticamente como chinês/1.7; se não especificou → o script escolhe o padrão com base na resolução. Chinês : Inglês ≈ 1.7 é a proporção de contraste limpa testada. - ⛔ ASS FontSize/MarginV são valores relativos a PlayResY=288, não pixels. O libass dimensiona automaticamente com a resolução do vídeo; não multiplique linearmente o tamanho da fonte pela resolução (17 em 1080p multiplicado por 2 em 4K ocuparia meia tela); MarginV=N em 1080p ≈ N×3.75px da borda inferior (MarginV=110 ≈ meio da tela, não 110px), não ajuste pela intuição de pixels.
Marca d'água (desligada por padrão; ative se translate.json tiver settings.watermark_enabled: true ou se o usuário solicitar):
python "${SKILL_DIR}/scripts/burn.py" "<arquivo de vídeo>" --subs <legenda> \
--watermark-text "<texto da marca d'água>" --output <saída>
Os pontos de tempo são distribuídos automaticamente com base na duração (<30min: 3 vezes de 4s / 30-60min: 5 vezes de 5s / >60min: a cada 15min uma vez de 10s; primeiro e último pontos fixos), opacidade 0.28, fade-in/fade-out de 0.5s, canto superior esquerdo. Parâmetros podem ser substituídos com --watermark-opacity/--watermark-fontsize etc.; parâmetros especificados na conversa têm prioridade sobre o arquivo de configuração.
Evitando legendas duras existentes na parte inferior do vídeo original: A nova legenda deve subir, não pode cobrir a legenda original:
# Legenda dura de uma linha
python "${SKILL_DIR}/scripts/burn.py" <vídeo> --subs <legenda> --avoid-hardsub single ...
# Duas linhas ou linhas dinâmicas (uma linha, depois duas) → evite como duas linhas; uma linha com chinês um pouco mais alto é um custo aceitável
python "${SKILL_DIR}/scripts/burn.py" <vídeo> --subs <legenda> --avoid-hardsub double ...
As faixas de evitação (single=MarginV 42/FontSize 19, double=MarginV 60/FontSize 19) são valores empíricos. Se a verificação de quadros falhar, use --margin-v para ajustar ±3-5 e requeime.
Se não tiver certeza do comando final, use --dry-run primeiro para imprimir o comando para revisão antes de executar de fato.
Etapa 4.5: Verificação de Quadros (⛔ Obrigatório, ≥2 Quadros)
Após a queima, extraia quadros e use Read para confirmar: legenda exibida completamente, não cobre legendas duras existentes, contraste de tamanho bilíngue evidente, chinês sem quadrados (falta de fonte):
ffmpeg -y -i "<vídeo de saída>" -ss <ponto_tempo_1> -vframes 1 "<raiz de saída>/tmp/check1.jpg"
ffmpeg -y -i "<vídeo de saída>" -ss <ponto_tempo_2> -vframes 1 "<raiz de saída>/tmp/check2.jpg"
Com necessidade de evitação, os dois quadros devem selecionar momentos de 1 linha e 2 linhas da legenda original, respectivamente. Ambos os quadros devem passar sem sobreposição. Olhar apenas um quadro e entregar = uma armadilha já pisada. Se houver problema, ajuste --margin-v/--font-size e requeime, depois verifique novamente.
Etapa 5: Gerar Documento Markdown
Regras gerais (todos os cenários):
- Leia o texto transcrito (SRT removendo números de sequência e linhas de timestamp, ou texto limpo por
vtt_to_text.py), proibido adicionar, remover ou alterar o texto original, apenas pontuação, mesclagem de frases e parágrafos. Deve cobrir todo o conteúdo, sem omissões. - Conteúdo em chinês: Mescle frases curtas, padronize pontuação, paragrife por semântica → Gere 1 arquivo
<raiz de saída>/data/<título do vídeo>-chinês.md. ⛔ Conteúdo em chinês é proibido de usar regras de tradução. - Conteúdo não chinês: Primeiro, gere
<raiz de saída>/data/<título do vídeo>-original.mdno idioma original (também sem adicionar, remover ou alterar). Em seguida, leiareferences/regras-detalhadas-de-documento.mde, seguindo suas regras, crie<raiz de saída>/data/<título do vídeo>-chinês.md(formato de artigo aprofundado, não tradução frase por frase). - Front matter contém apenas
title,source_url.
Cenário de Apenas Documento (Usuário Quer Apenas Transcrição/Documento, Sem Queimar Legenda)
- Priorize capturar legendas de vídeos com legendas (mais rápido e gratuito; ⛔ apenas para geração de documento — queima de legenda proíbe esta rota, veja regra de ferro da Etapa 2):
Texto limpo economiza aproximadamente metade dos tokens. Leiapython "${SKILL_DIR}/scripts/download.py" "<URL do vídeo>" "<raiz de saída>/tmp/dl" --captions-only python "${SKILL_DIR}/scripts/vtt_to_text.py" "<raiz de saída>/tmp/dl/<legenda>.vtt" --output "<raiz de saída>/tmp/cleaned.txt"cleaned.txte siga a Etapa 5 para gerar o documento. - Sem legendas → Baixe áudio (
--audio) → Transcreva comtranscribe_srt.py→ SRT removendo números de sequência e timestamps para obter texto simples → Siga a Etapa 5 para gerar o documento.
Arquivos Temporários e Limpeza
- Artefatos intermediários (áudio, SRT, ASS, quadros) estão todos em
<raiz de saída>/tmp/, podem ser limpos após o processamento; produtos finais em<raiz de saída>/data/não são afetados. - SRT da transcrição pode ser mantido para depuração; o usuário pode limpar tmp/ manualmente a qualquer momento.
Tratamento de Erros
| Sintoma | Tratamento |
|---|---|
| Falha no download (403/proteção/paywall) | O script já tenta novamente com cookies automaticamente; se ainda falhar, troque para --browser firefox/edge, ou sugira ao usuário configurar proxy; se confirmar que é bloqueio regional/conteúdo pago, diga diretamente |
| faster-whisper não instalado | pip install faster-whisper; se não conseguir instalar, use --engine api (precisa de API key) |
| Detecção de idioma incorreta na transcrição | Adicione --language en (ou o idioma correspondente) para forçar a retranscrição |
| Chinês aparece como quadrados após queima | Faltando fonte — burn.py escolhe por plataforma por padrão (Windows Yahei/macOS PingFang/Linux Noto CJK), Linux precisa de sudo apt install fonts-noto-cjk; também pode especificar com --font-name |
| Legenda cobre legenda dura existente | `--avoid-hardsub single |
| Espaço em disco insuficiente | Limpe <raiz de saída>/tmp/ |
| Erro de dependência | Leia references/guia-de-instalacao.md, siga as instruções para instalar e depois volte ao fluxo principal |
Princípio de verificação de dependências: Execute o fluxo principal diretamente, verifique se houver erro — não verifique cada dependência previamente, isso perde tempo. O ambiente padrão já está configurado (a verificação --check da Etapa -1 já cobre os itens básicos).