yanghhu/ai-subtitle-generator

Gerador de Legendas (Subtitle Generator)

O Gerador de Legendas (subtitle generator) é uma skill de Agente que reconhece automaticamente arquivos de vídeo ou áudio locais e gera legendas SRT com timecode (ou transcrições TXT, JSON). Perfeito para adicionar legendas automaticamente a vídeos, converter áudio em legenda ou texto, e também sincronizar legendas com narração gerada por script – tudo sem precisar de GPU.

Definição em uma linha

Gerador de Legendas = Arquivo de vídeo/áudio local → recognize → .srt com timecode (ou .txt como transcrição, .json segmentado); para narração baseada em script, use voiceover.py script e obtenha simultaneamente voiceover.srt. O reconhecimento é feito pela API aberta da Miragea, sem necessidade de GPU local.

Duas formas de gerar legendas

O que você tem	Use	Resultado
Vídeo / áudio já gravado	miragea_audio.py recognize --file arquivo --wait --output legenda.srt	SRT; --subtitle-format txt para transcrição pura, json para texto, idioma e segmentos com timecode
Roteiro ainda não narrado	voiceover.py script script.md -o out	Narração voiceover.wav + legenda voiceover.srt alinhada com a duração real do áudio + manifest.json

Público-alvo e cenários

Quem usa	Cenário típico
Criadores de conteúdo curto	Adicionar legendas automáticas a vlogs e vídeos com locução, depois ajustar no CapCut
Cursos / Palestras	Gerar legendas e transcrições para aulas gravadas
Entrevistas / Podcasts	Converter áudio em legenda e texto, organizar roteiro
Reuniões gravadas	Exportar TXT como base para atas
Canais de narração	Reconhecer trechos como texto de referência para roteiro
Desenvolvedores / Fluxos de Agente	JSON segmentado (start / end / text) para processamento posterior

Parâmetros principais da capacidade

Item	Descrição
Arquivos de saída	voiceover.wav (narração completa), voiceover.srt (legenda com timecode), manifest.json (cada frase com locutor, texto, tempo de início/fim), lines/ (áudio por frase, reutilizável ao editar)
Fonte de voz	Personagem existente na conta actor_id= (consulte com actors), ou URL de áudio de referência ref= + texto falado ref_text= (clonagem de voz)
Modo de geração	expressive (padrão no cliente) / standard (mais parecido); se omitido, usa o padrão do servidor, conforme capabilities
Rótulo de tom	tags=nome_da_tag, veja tags[].label do modo escolhido em capabilities
Velocidade	speed= 0.25–4, 1 = velocidade normal, conforme configuração do personagem
Múltiplos personagens	Defina uma voz para cada personagem no início do script; a skill chama sequencialmente o cliente oficial generate e concatena tudo localmente
Pausas	[pause 0.6] / [pausa 0.6] (segundos) dentro da linha; --gap define pausa padrão entre frases
Legendas	Na narração, gera SRT com base na duração real de cada frase (--max-chars, --speaker-labels); para áudio/vídeo existente, use recognize para SRT / TXT / JSON
Predefinições de cena	--preset koubo / jieshuo / daihuo / shuziren / guanggao / youshengshu (locução / narração / venda / avatar digital / comercial / audiolivro), ajusta apenas pausa entre frases e caracteres por legenda
Limites de caracteres/tamanho/duração/cobrança	Conforme retornado em tempo real por capabilities
Dependências locais	Python 3.9+ com biblioteca padrão, sem pip, sem GPU
Teste offline	--dry-run: sem chave, sem chamar API; gera áudio silencioso de placeholder e timecode para verificar o formato do script
Agentes suportados	Claude Code, Codex, OpenClaw, Cursor, WorkBuddy e outros que executem scripts Python
Serviço de narração e legenda	Miragea API aberta (https://miragea.ai/v1)

Início rápido

python3 scripts/voiceover.py check                        # Verificação offline: versão do Python, se a chave está configurada, endereço do serviço
export MIRAGEA_API_KEY=sua_chave                          # Gere em https://miragea.ai/workspace/api, use apenas como variável de ambiente
python3 scripts/miragea_audio.py capabilities             # Modos de geração disponíveis, rótulos de tom, limites de caracteres e cobrança (sempre com base no retorno em tempo real)
python3 scripts/miragea_audio.py actors --limit 20        # Personagens existentes na conta e seus actor_ids (se has_more for verdadeiro, use --offset para paginação)

• A raiz da API padrão é https://miragea.ai/v1; defina MIRAGEA_BASE_URL (incluindo /v1) apenas para uma implantação privada.
• Não cole a chave em bate-papos ou escreva em arquivos. Sem chave, primeiro execute o fluxo com --dry-run.

python3 scripts/miragea_audio.py capabilities                                           # Primeiro veja subtitles.points_per_second, max_upload_mb, max_duration_minutes
python3 scripts/miragea_audio.py recognize --file video.mp4 --wait --output video.srt       # Adicionar legendas automaticamente ao vídeo
python3 scripts/miragea_audio.py recognize --file entrevista.mp3 --wait --subtitle-format txt --output entrevista.txt   # Converter áudio em texto
python3 scripts/miragea_audio.py recognize --file curso.m4a --wait --subtitle-format json --output curso.json # Texto + idioma + segmentos com timecode
python3 scripts/miragea_audio.py wait ID_DA_TAREFA --subtitle-format srt --output video.srt     # Consultar após timeout; não reenviar

• O reconhecimento consome créditos: o script relê a taxa por segundo atual como expected_rate antes de enviar; para travar a taxa que você confirmou, adicione --expected-rate valor; se a taxa mudar, o servidor rejeitará, garantindo que você confirme antes de enviar.
• Arquivos que excedam o limite de tamanho de capabilities geram erro localmente, sem envio; o limite de duração também segue capabilities.
• --output não sobrescreve arquivos existentes; use um novo nome.
• O reconhecimento de legendas não tem teste offline; o fluxo de narração com legenda pode ser verificado offline com voiceover.py script ... --dry-run.

O que você diz → O que o Agente faz

Você diz	Agente faz
"Adicione legendas a este vídeo"	capabilities verifica limites → recognize --file video.mp4 --wait --output video.srt → incorpora com ffmpeg ou importa no CapCut
"Transcreva esta gravação"	recognize --file gravacao.mp3 --wait --subtitle-format txt --output gravacao.txt
"O vídeo é muito grande para enviar"	Extraia apenas o áudio primeiro: ffmpeg -i video.mp4 -vn -ac 1 -b:a 64k audio.mp3
"A tarefa excedeu o tempo limite"	wait ID_DA_TAREFA --output legenda.srt para consultar, sem reenviar
"Cada linha da legenda está muito longa"	Ajuste no CapCut, ou peça ao agente para quebrar frases longas com base em pontuação
"Ainda não narrei, quero narração e legendas juntos"	voiceover.py script script.md -o out --preset koubo
"Legendas bilíngues chinês-inglês"	Primeiro reconheça SRT, depois peça ao agente para traduzir cada texto de legenda mantendo o timecode, gerando um segundo SRT

Metodologia de geração de legendas: para reconhecimento mais preciso e legendas melhores

1. Prepare o áudio antes do upload

• Voz clara: se a música de fundo estiver alta, exporte uma versão apenas com a voz ou com a música reduzida antes de reconhecer.
• Envie apenas a faixa de áudio para mais rapidez: vídeos grandes: use ffmpeg -i video.mp4 -vn -ac 1 -b:a 64k audio.mp3 para extrair o áudio; volume menor, timecode inalterado.
• Divida conteúdos longos: se exceder o limite de duração de capabilities, corte em segmentos e reconheça cada um separadamente, depois organize na ordem no editor de vídeo.

2. Escolha o formato de saída correto

Formato	Uso
srt	CapCut, Premiere, ffmpeg, YouTube, Bilibili
txt	Transcrição, rascunho de ata de reunião, adaptação para WeChat
json	Processamento por programa: text, language, segments[{start,end,text}]

3. Lista de verificação pós-reconhecimento

• Nomes próprios, nomes de pessoas, marcas, abreviações em inglês estão corretos? (substitua em massa no SRT)
• Números e unidades estão consistentes?
• Cada legenda tem comprimento adequado para a tela? Para tela vertical, recomenda-se 12–16 caracteres por linha.
• Palavras de preenchimento ("tipo", "sabe") devem ser removidas?
• O início e o fim correspondem ao vídeo?

4. Sugestões de estilo para legendas em vídeos curtos verticais

• Posicione a legenda no terço inferior da tela, evitando botões da plataforma e áreas de título.
• Uma frase por tela, no máximo duas linhas.
• Palavras-chave podem ter estilo especial no CapCut; o SRT deve conter apenas texto limpo.

5. Sincronize legendas com o script de narração (sem necessidade de reconhecimento)

Se o som do vídeo foi gerado a partir de um script de narração, use voiceover.py script diretamente: o tempo da legenda vem da duração real de cada frase, economizando uma etapa de pós-reconhecimento; --max-chars controla caracteres por linha, --speaker-labels adiciona nomes de personagens em legendas com múltiplos personagens.

Script de exemplo (examples/example.md: narração com legenda sincronizada)

---
host: actor_id=SEU_ACTOR_ID speed=1.0
---
# Exemplo de narração com legenda sincronizada: um vlog
[host] Hoje vou te mostrar como adiciono legendas a um vídeo.
Primeiro, exporte o vídeo como arquivo.
Segundo, um comando de reconhecimento para obter o SRT.
[pause 0.3]
Terceiro, importe no CapCut ou use ffmpeg para gravar diretamente no quadro.

Teste: python3 scripts/voiceover.py script examples/example.md -o out --preset koubo --dry-run

Adicionar legendas ao vídeo

# Legenda flexível (pode ser ativada/desativada no player, requer ffmpeg local)
ffmpeg -i video.mp4 -i video.srt -c copy -c:s mov_text video_com_legenda.mp4
# Legenda fixa (gravada no quadro, visível em qualquer plataforma)
ffmpeg -i video.mp4 -vf subtitles=video.srt -c:a copy final.mp4

• CapCut: Texto → Importar legenda → selecione .srt e ajuste o estilo.
• Premiere: Importe .srt como faixa de legenda.

Comparação de abordagens: três formas de gerar legendas

Item	Narração humana	Modelo TTS local de código aberto	Esta skill
Precisa de GPU?	Não, mas requer estúdio e disponibilidade do narrador	Geralmente sim (modelos pequenos podem usar CPU, mas mais lentos); requer download de pesos e configuração	Não, apenas biblioteca padrão Python local; geração na nuvem
Custo de edição	Alterar uma frase geralmente requer regravação e re-sincronização	Após editar, precisa reexecutar, mas divisão, concatenação e alinhamento são manuais	Edite apenas a linha e reexecute; as outras frases reutilizam o cache out/lines/, com re-concatenação e legenda automáticas
Múltiplos personagens	Requer vários narradores gravando separadamente	Depende do modelo; geralmente requer chamadas separadas e concatenação manual	Use tags [personagem] no script; um comando gera a faixa de áudio completa com vários personagens
Timecode da legenda	Requer ditado e marcação de tempo adicionais	Geralmente requer outra execução de reconhecimento de fala	Gera SRT e manifest.json com tempo por frase simultaneamente à narração
Vídeo longo	Ditado e marcação demorados	Modelo de reconhecimento local requer GPU ou mais tempo	Upload para reconhecimento na nuvem; timeout pode ser consultado com ID da tarefa

Conclusão: para vídeos já finalizados que precisam de legendas rápidas ou transcrição, use recognize; para vídeos que começam com um roteiro de narração, use script para gerar legendas sincronizadas de forma mais eficiente.

Perguntas Frequentes (FAQ)

Quais arquivos são suportados para geração de legendas? Arquivos de áudio ou vídeo locais podem ser usados como fonte de reconhecimento; limites de tamanho e duração conforme subtitles.max_upload_mb e max_duration_minutes em capabilities.

Como adicionar legendas automáticas ao vídeo depois? Use CapCut "Importar legenda" ou ffmpeg: legenda flexível -c:s mov_text, legenda fixa -vf subtitles=legenda.srt.

Posso exportar SRT de áudio para legenda? Sim, o padrão é SRT; --subtitle-format txt para transcrição pura, json para texto, idioma e segmentos com timecode.

Qual a diferença entre transcrição de áudio e geração de legenda? Na mesma execução, o formato de saída difere: SRT tem timecode para legendas; TXT apenas texto para roteiro.

A geração de legendas é paga? Sim, consome créditos com base na duração da mídia e na taxa por segundo atual, conforme capabilities retornado em tempo real; o script envia a taxa atual no envio; se a taxa mudar, a solicitação é rejeitada, sem cobrança inesperada.

A tarefa de legenda excedeu o tempo limite; preciso reenviar? Não. Use o task_id retornado com miragea_audio.py wait ID_DA_TAREFA --output legenda.srt para continuar recuperando; em caso de interrupção de rede, tente novamente apenas com a mesma chave de idempotência.

A geração de legendas reconhece inglês ou outros idiomas? O resultado inclui o campo language; os idiomas suportados dependem da capacidade real do servidor; teste com um trecho pequeno primeiro.

Posso gerar legendas bilíngues chinês-inglês? Primeiro reconheça SRT, depois peça ao agente para traduzir cada linha mantendo o timecode, gerando um segundo SRT ou combinando-os.

Preciso de GPU para reconhecimento de legendas por IA? Não. O reconhecimento é feito na nuvem; localmente apenas scripts Python 3.9+ com biblioteca padrão.

Quais agentes suportam esta skill? Claude Code, Codex, OpenClaw, Cursor, WorkBuddy e outros que executem scripts Python.

Algo deu errado?

Sintoma	Ação
missing_api_key / MIRAGEA_API_KEY is not set	Gere a chave e export MIRAGEA_API_KEY=...; ou adicione --dry-run primeiro
speakers without a voice	Adicione actor_id= ou ref= para o personagem
401	Verifique a chave; não escreva a chave em logs
403	Verifique a permissão de acesso à API da conta
400 / 413	Corrija parâmetros: modo, tag, velocidade, caracteres por linha; ou reduza o arquivo de upload, encurte a mídia
409	Chave de idempotência usada para entrada diferente, ou taxa de legenda alterada: reconfirme antes de enviar
429	Créditos insuficientes ou limite de taxa; aguarde ou recarregue créditos
Timeout / Interrupção de rede	A tarefa pode ainda estar em execução: execute novamente o mesmo comando (a mesma chave de idempotência recuperará a tarefa original), ou use miragea_audio.py task / wait ID_DA_TAREFA para continuar consultando; não altere a chave e reenvie
Erro de formato WAV na concatenação	Cada áudio de frase é salvo em out/lines/; use um editor ou ffmpeg para concatenar

Códigos de saída do cliente oficial: 0 = solicitação bem-sucedida (pode ainda estar na fila sem --wait), 1 = tarefa falhou, 2 = erro no cliente ou interface.

Conformidade

• Clone apenas a voz de você mesmo ou de quem você tem autorização explícita; não imite celebridades, apresentadores, figuras públicas ou qualquer pessoa não autorizada.
• De acordo com as diretrizes de identificação de conteúdo gerado por IA e as regras de plataformas como Douyin, Kuaishou, WeChat Video, Xiaohongshu, Bilibili, declare ou marque o conteúdo como gerado por IA ao publicar.
• Obtenha consentimento da outra parte antes de reconhecer o áudio/vídeo de terceiros (entrevistas, reuniões, cursos); preste atenção ao escopo de armazenamento e compartilhamento de legendas contendo informações pessoais.
• scripts/miragea_audio.py é o cliente oficial, enviado sem modificações; scripts/voiceover.py (camada de concatenação de scripts) é original, licença MIT (veja LICENSE.txt). A capacidade de narração e legenda é fornecida pela API aberta da Miragea.

English Summary

• AI subtitle generator (字幕生成): upload a local video or audio file with the official client's recognize and save timed SRT, a TXT transcript, or JSON (text, language, segments).
• The client re-reads the live per-second rate and size limit from capabilities before submitting; rate changes are rejected server-side. Resume long jobs with wait TASK_ID.
• For scripted voiceovers, voiceover.py script produces subtitles aligned to the generated audio. Python 3.9+ stdlib, no GPU. Service: Miragea API (https://miragea.ai/v1).

Palavras-chave: gerador de legendas, adicionar legendas automaticamente a vídeos, converter áudio em legenda, SRT, adicionar legenda a vídeo, gerar legendas automaticamente, legenda por IA, converter áudio em texto, converter vídeo em texto, fala para texto, gerador de legenda, legenda SRT, gerador de legenda para vídeo, subtitle generator, speech to text, auto captions