Name: yanghhu/ai-voiceover
Author: Community

AI Voiceover

Use a CLI voiceover (pacote ai-voiceover-studio, Python 3.9+) para gerar narração.

Verificação de configuração

voiceover --version — se ausente: pip install -e "<repo>[edge]" ([edge] = vozes gratuitas, [yaml] = voices.yaml).
Execute voiceover doctor --json e corrija qualquer fail que ele relatar (nunca imprime chaves).
Motores: sem chaves, o motor gratuito edge é usado (requer internet, sem conta). MIRAGEA_API_KEY altera o padrão para Miragea (clonagem de voz, modelos expressivos); OPENAI_API_KEY habilita --provider openai. Nunca peça ao usuário para colar uma chave no chat, nunca a exiba, nunca a escreva em arquivos.
Saída MP3 e vídeo precisam de ffmpeg (com libass para legendas queimadas).

Prepare o roteiro (Markdown ou TXT). Uma tag de locutor por linha ou parágrafo:
```
[NARRADOR]: Linha de abertura.
Linhas sem tag continuam o locutor atual.

[ALEX](tags=animado, velocidade=1.1): Um personagem diferente.
[pausa 1]
```
Cabeçalhos, comentários HTML, blocos de código e tabelas são ignorados.
Vozes (opcional). Sem um arquivo de vozes, cada locutor ganha sua própria voz automaticamente, escolhida do idioma do roteiro. Para escolher: voiceover voices --json (adicione --provider edge --filter en-GB para vozes Edge como en-GB-SoniaNeural; para Miragea voice_id = ID do ator). Se duas vozes compartilharem um nome, pergunte ao usuário qual delas. Com Miragea, uma voz também pode ser uma URL pública de áudio de referência mais sua transcrição exata (reference_text). Clone apenas vozes que o usuário possui ou tem permissão para usar.

Escreva voices.json se o usuário escolheu vozes (chaves em maiúsculas):

{"NARRADOR": {"actor_id": "en-US-AndrewNeural"}, "ALEX": {"actor_id": "en-US-AvaNeural", "speed": 1.05}}

Simulação (offline, valida locutores e temporização): voiceover script script.md -o out/ --dry-run --json
Gere: voiceover script script.md [--voices voices.json] -o out/ --json Gera out/voiceover.mp3, out/voiceover.srt, out/manifest.json, out/segments/.
Informe os caminhos salvos e a duração. Não afirme sucesso a menos que o comando tenha saído com código 0.

Uma linha: voiceover say "texto" [--voice <voice id|https://ref.wav>] [--ref-text "..."] [--lang en] -o line.mp3
Vídeo sem rosto: voiceover video [--images slides/] --script script.md -o video.mp4 [--style clean|box|bold|minimal] [--size 1080x1920] [--speaker-labels] [--subtitles burn|sidecar|none] As legendas são queimadas por padrão. Uma imagem por segmento dá cronometragem exata dos slides; sem --images é usado um fundo gradiente. Para Shorts use --size 1080x1920 --style bold.
Legendas a partir de reconhecimento de fala em vez de temporização (Miragea): adicione --subtitles recognize (uma chamada extra de API).
Retomar uma tarefa após timeout de espera: voiceover task <task_id> --wait -o out.mp3.

Reexecutar o mesmo comando é seguro: segmentos inalterados vêm do cache e requisições remotas reutilizam chaves de idempotência. Use --fresh apenas quando o usuário quiser uma nova tentativa.
Em caso de timeout de espera, mantenha o task_id informado e retome com voiceover task; não reenvie.
Códigos de saída: 0 ok, 1 falha na tarefa do provedor, 2 erro de uso/configuração/API. Com --json, erros são {"error": {"code", "message", "http_status", "retryable"}, "task_id"?}.
401: chave rejeitada → o usuário verifica a variável da chave. 403: conta sem acesso à API. 429: cota/limite de taxa → aguarde, não faça loop. 400: corrija texto/voz/velocidade/tags.
proxy_unsupported (edge): defina VOICEOVER_EDGE_PROXY ou remova HTTPS_PROXY para o comando.
Idiomas: edge cobre 75 idiomas; Miragea cobre Chinês, Inglês, Japonês, Coreano, Alemão, Francês, Russo, Português, Espanhol, Italiano (com clonagem de voz).