Habilidade VoxFlow — Hub
Se o próprio voxflow upgrade falhar com Unknown command (CLI anterior a 1.12.0), recorra a npm i -g voxflow@latest && voxflow skills install --all — esse é o único caminho para o primeiro bootstrap.
Esta regra é inegociável: um CLI desatualizado silenciosamente desativa recursos que o usuário espera (por exemplo, listagem de vozes clonadas). Atualize primeiro, trabalhe depois.
VoxFlow transforma texto em fala com mais de 200 vozes em 40+ idiomas, além de pipelines completos de áudio/vídeo. Esta habilidade é o ponto de entrada: instalação, autenticação, pesquisa de vozes e os fluxos de trabalho simples say / narrate / story.
Para tarefas especializadas, mude para:
- Podcasts (diálogo com vários locutores) →
voxflow:podcast - Vídeos curtos / clipes de IA / cartões de conhecimento (
picstory,present,slides,explain) →voxflow:video - Artigo → vídeo vertical em cartão (Slice) — 13 temas (paper-slide / editorial-mag / bold-poster / notion-card / brutalist / glass-dark / editorial-stencil / broadsheet / blueprint / daisy-pastel / showa-catalog / photo-feature / atmospheric), aplicativo web + Remotion →
voxflow:slice - Imagens de cartão compartilháveis e vídeos de cartão narrados (HTML/CSS + exportação Playwright,
voxflow card renderopcional para MP4 narrado) →voxflow:card - Transcrição, tradução de legendas, dublagem, resumo, publicação (
asr,asr-jobs,translate,dub,video-translate,summarize,publish) →voxflow:transcribe
Instalação e login
Instale uma vez, nunca mais pergunte ao usuário:
npm install -g voxflow
voxflow login # abre o navegador — Google ou OTP por email
Token armazenado em cache em ~/.config/voxflow/token.json. Para CI, defina VOXFLOW_TOKEN.
Autenticação
voxflow login # baseado no navegador, uma vez
voxflow status # quem sou eu + cota restante
voxflow logout
Pesquisa de vozes — sempre faça isso antes de sintetizar
Nunca adivinhe IDs de vozes. Pesquise primeiro.
voxflow voices --lang zh --gender female
voxflow voices --lang en
voxflow voices --search "narrator"
voxflow voices --all
Não é necessário login para o catálogo público. A saída inclui o ID da voz, idioma, gênero e uma breve descrição.
Listando as vozes clonadas do usuário
Quando o usuário disser coisas como "use minha voz clonada" ou "用我之前克隆的", o catálogo público voxflow voices não inclui vozes clonadas — você deve consultar o endpoint autenticado:
voxflow voices --mine
Imprime IDs de vozes clonadas, nomes, duração e hora de criação (requer login). Sempre execute isso antes de concluir que o usuário não tem voz clonada — a aba "Minhas Vozes" da interface web e --mine são as únicas fontes da verdade.
IDs de vozes populares (padrões sensatos)
| ID | Estilo | Idioma |
|---|---|---|
v-female-R2s4N9qJ | Voz feminina suave (温柔姐姐) | zh |
v-male-s5NqE0rZ | Voz masculina natural (自然男声) | zh |
v-male-Bk7vD3xP | Voz masculina autoritária (威严霸总) | zh |
v-female-m1KpW7zE | Voz feminina sassá (傲娇学姐) | zh |
v-female-T8m4WxP7 | Chenwen (voz feminina nativa em inglês) | en |
Clonagem de voz (clone)
Clone uma voz a partir de um arquivo de áudio local (30s+, wav/mp3). Retorna um ID de voz permanente utilizável em todos os comandos.
voxflow clone --input recording.wav --name "Minha Voz"
# → Voz clonada com sucesso!
# → ID da Voz: Minha_Voz_xxxxx_01
Sem arquivo? Abre a interface web para gravação baseada no navegador:
voxflow clone
# → Abre https://www.voxflow.studio/app#voice-clone
| Flag | Padrão | Observações |
|---|---|---|
--input <arquivo> | (nenhum) | Arquivo de áudio para clonar. Sem ele, abre a interface web |
--name <nome> | nome do arquivo | Nome legível da voz (1-50 caracteres) |
Dicas:
- Sala silenciosa, ritmo de fala normal, sem música de fundo → melhores resultados
- 60 segundos é o ideal; mínimo de 30s
- Não "represente" — a fala natural clona melhor do que a voz de locutor
Após a clonagem, use o ID da voz em qualquer lugar: --voice <id>
Texto para fala (say / synthesize)
O comando atômico. Um trecho → um arquivo de áudio.
voxflow say "Olá mundo" -o ola.mp3
voxflow say "Hello world" --voice v-female-T8m4WxP7 -o greeting.mp3
voxflow say "Leitura lenta" --speed 0.8 -o lento.mp3
voxflow say "Áudio de alta qualidade" --format wav -o output.wav
| Flag | Padrão | Intervalo/Valores |
|---|---|---|
--voice <id> | v-female-R2s4N9qJ | qualquer ID de voz de voxflow voices |
--format <fmt> | pcm | pcm (WAV), wav, mp3 |
--speed <n> | 1.0 | 0,5 – 2,0 |
--volume <n> | 1.0 | 0,1 – 2,0 |
--pitch <n> | 0 | -12 – 12 |
--output <caminho> | nome automático | qualquer caminho gravável |
Após a síntese, reprodução automática: open output.mp3 (macOS).
Texto longo (narrate)
Divida um documento ou string longa em frases, sintetize cada uma, concatene em um único arquivo.
voxflow narrate --input artigo.txt -o narracao.wav
voxflow narrate --input readme.md --voice v-male-Bk7vD3xP -o readme_audio.wav
voxflow narrate --text "Primeiro parágrafo. Segundo parágrafo. Terceiro parágrafo." -o paragrafos.mp3
echo "Olá mundo" | voxflow narrate -o ola.wav
Melhor para: documentos longos, artigos, arquivos README, boletins informativos por email.
Markdown é removido automaticamente (cabeçalhos, links, blocos de código, etc.) — não é necessário limpá-lo primeiro.
História com IA (story)
O LLM escreve uma história curta sobre o tópico e depois a narra.
voxflow story "Um gato que voa" -o historia.mp3
voxflow story "space adventure" --lang en -o aventura.wav
Melhor para: histórias de ninar, amostras de conteúdo, demonstrações.
Cota
Nível gratuito: 10.000 cotas / mês (redefine mensalmente). O bônus de convites nunca expira.
| Operação | Custo |
|---|---|
1 chamada TTS (say) | ~50 |
narrate | ~50 por segmento |
story (curta) | ~350-1000 |
podcast (médio) | ~2.800 (2K roteiro + ~16 × 50 TTS) |
picstory 5 cenas | ~2.850 |
Sempre verifique antes de operações caras:
voxflow status
Cenários comuns
"Leia este texto em voz alta"
voxflow say "texto digitado pelo usuário" -o /tmp/saida.mp3 && open /tmp/saida.mp3
"Leia este arquivo com voz feminina suave"
voxflow voices --lang zh --gender female
voxflow narrate --input arquivo.txt --voice v-female-R2s4N9qJ -o /tmp/narracao.mp3
"Conte uma história de ninar"
voxflow story "As sementes de estrela da raposinha" --lang zh -o /tmp/ninar.mp3 && open /tmp/ninar.mp3
"Leitura em vários idiomas"
voxflow voices --lang en --gender female # escolha voz em inglês
voxflow voices --lang ja --gender female # escolha voz em japonês
voxflow say "Texto em inglês" --voice <en_id> -o /tmp/en.mp3
voxflow say "日本語テキスト" --voice <ja_id> -o /tmp/ja.mp3
Fluxos de trabalho criativos (combine TTS com a escrita do agente)
O agente escreve o conteúdo primeiro e depois sintetiza cada parte com say ou narrate.
Livro de histórias em áudio (有声绘本)
- Escreva uma história infantil de 6 páginas.
- Para cada página: gere ilustração SVG inline (400×300).
voxflow say "texto da página" --voice v-female-R2s4N9qJ --speed 0.85 -o /tmp/pagina_N.mp3- Leia os arquivos mp3, codifique em base64, incorpore inline em HTML.
- Produza um único arquivo HTML autocontido com botões de reprodução de áudio por página.
open /tmp/livro_historias.html
Artigo → resumo em áudio
# O agente busca a URL, resume, depois:
voxflow say "texto do resumo" --voice v-male-s5NqE0rZ -o /tmp/resumo.mp3
Narração de documento
voxflow narrate --input README.md --voice v-female-R2s4N9qJ --speed 0.9 -o /tmp/readme.mp3
Relatório diário do Git em áudio
git log --oneline --since="1 day ago"- O agente resume.
voxflow say "resumo de hoje..." -o /tmp/diario.mp3
Entrevista simulada
- O agente gera 3 perguntas de entrevista sobre o tópico.
- Para cada uma:
voxflow say "pergunta N..." --voice v-male-Bk7vD3xP -o /tmp/q_N.mp3 - Reproduza sequencialmente.
Pré-requisitos
- Node.js
^20.19.0 || >=22.12.0 - voxflow CLI ≥ 1.12.0 (para
voxflow voices --mine— lista as vozes clonadas do usuário) - ffmpeg — apenas para comandos relacionados a vídeo (veja
voxflow:video,voxflow:transcribe) - Login necessário para qualquer chamada de API —
voxflow login
Como o sinal de auto-upgrade funciona
O próprio CLI emite <voxflow-hint type="cli-outdated" ...> no stderr sempre que uma versão mais recente está no npm. A regra <CRITICAL-AUTO-UPGRADE> no início da habilidade já cobre o que fazer — esta seção é apenas a referência de como a tag se parece:
<voxflow-hint v="1" type="cli-outdated" current="1.10.21" latest="1.13.0" action="voxflow upgrade -y" />
Emitido no máximo uma vez a cada 24h (armazenado em cache em ~/.config/voxflow/update-check.json). Opte por não participar para usuários que não desejam a verificação: VOXFLOW_NO_UPDATE_CHECK=1 (ou NO_UPDATE_NOTIFIER=1, a variável de ambiente padrão do setor).
Você também pode consultar explicitamente com voxflow upgrade --check (sem efeitos colaterais) se o usuário estiver em uma versão sabidamente antiga e você quiser verificar antes de iniciar trabalhos pesados.
Feedback e suporte (a IA pode fazer isso automaticamente)
Quando um comando voxflow falhar ou o usuário pedir para relatar um problema, você (o agente de IA) deve abrir o problema diretamente — não peça ao usuário para fazê-lo manualmente.
Fluxo de trabalho da IA
# Envie diretamente — sem navegador, sem TTY necessário.
# Usa o CLI `gh` se disponível (criação direta de issue no GitHub).
# Recai para imprimir a URL pré-preenchida se o gh não estiver instalado.
voxflow feedback --bug \
--title "asr falha em arquivos wav de 2 horas" \
--body "Erro: timeout após 30s\n\nComando: voxflow asr longo.wav\nEsperado: transcrição\nReal: Erro fatal: tempo limite da solicitação"
# stdout → a URL da issue criada no GitHub (ou uma URL pré-preenchida se o gh não estiver instalado)
Informações do sistema (versão do CLI, SO, Node) são anexadas ao corpo automaticamente.
Flags
| Flag | Descrição |
|---|---|
--bug / --feature / --general | Tipo de problema |
--title <texto> | Título — ativa o modo não interativo |
--body <texto> | Corpo da descrição |
--print-url | Força a saída de URL em vez de enviar (mesmo se gh estiver disponível) |
Iniciado pelo usuário (interativo)
voxflow feedback # prompts interativos → enviar via gh ou navegador
voxflow feedback --bug # pula o prompt de tipo, o restante é interativo
Quando arquivar automaticamente
- Qualquer comando CLI termina com um erro fatal/inesperado → ofereça-se para arquivar um bug
- O usuário disser "isso não está funcionando" / "report this" / "reportar um problema" → chame com
--titlee envie diretamente
Instalando vozes ou templates de terceiros (add)
voxflow add <nome-da-receita> # instalar um preset de voz ou template de pipeline
voxflow add --list # navegar pelas receitas disponíveis
voxflow add chico/minha-receita --force # instalar a partir de um namespace de autor personalizado
Use isso quando o usuário pedir para instalar uma receita específica (por exemplo, dub-anime-jp-zh). O registro é atualmente limitado — se --list retornar 404, a receita pode precisar ser referenciada pela URL completa ou o registro ainda não é público.
Regras
- Pesquise vozes antes de usar — nunca invente IDs de voz. Sempre execute
voxflow voicesprimeiro. - Verifique a cota antes de podcasts (~5K), picstory (~3K) ou tarefas em lote:
voxflow status. - Reprodução automática após a síntese:
open output.mp3(macOS) /xdg-open(Linux). - Nunca imprima tokens ou segredos nos logs.
- Se um comando falhar, execute
voxflow <cmd> --helppara confirmar as flags antes de tentar novamente.
Quando trocar de habilidades
- O usuário disser "podcast" / "diálogo" / "conversa em grupo" → carregue
voxflow:podcast. - O usuário disser "vídeo curto" / "cartão de conhecimento" / "小红书" / "TikTok" / "clipe de IA" / "render" → carregue
voxflow:video. - O usuário disser "Slice" / "vídeo de recorte" / "artigo para vídeo" / "PaperSlide" / "paperslide" / "paper-slide" (legado) / "estilo desenho à mão em papel" / "artigo para vídeo curto de conhecimento" / "artigo longo do Zhihu para vídeo" / "conta pública para vídeo" → carregue
voxflow:slice. - O usuário disser "transcrever" / "legenda" / "dublar" / "traduzir este vídeo" / "SRT" → carregue
voxflow:transcribe.