Communitygithub.com

VoxFlowStudio/skills

Use quando o usuário quiser ler texto em voz alta (TTS), pesquisar vozes VoxFlow, ouvir histórias de IA, ou configurar instalação/autenticação/cota do VoxFlow — o kit de ferramentas de voz de entrada. Para podcasts use voxflow:podcast; para vídeos curtos/clipes de IA use voxflow:video; para reels de artigo para cartão (Slice) use voxflow:slice; para imagens de cartão ou vídeos narrados use voxflow:card; para transcrição/dublagem/tradução de legendas use voxflow:transcribe.

O que é skills?

VoxFlow é uma habilidade central para agentes de IA que precisam de síntese de fala, narração e processamento de áudio. Ela fornece uma interface de linha de comando unificada para converter texto em fala com mais de 200 vozes em 40+ idiomas, além de pipelines completos de áudio e vídeo. O fluxo de trabalho principal inclui instalação via npm, autenticação por navegador ou token, pesquisa de vozes, clonagem de voz a partir de arquivos de áudio, síntese de texto (say), narração de documentos longos (narrate) e geração de histórias com IA (story). A habilidade também gerencia cotas de uso (10.000/mês no plano gratuito) e possui um mecanismo crítico de auto-upgrade para garantir que o CLI esteja sempre na versão mais recente. Para tarefas especializadas, como podcasts, vídeos curtos, cartões de vídeo narrados ou transcrição, a habilidade redireciona o usuário para submódulos específicos (voxflow:podcast, voxflow:video, voxflow:slice, voxflow:card, voxflow:transcribe).

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/VoxFlowStudio/skills/tree/HEAD/skills/hub

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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 render opcional 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)

IDEstiloIdioma
v-female-R2s4N9qJVoz feminina suave (温柔姐姐)zh
v-male-s5NqE0rZVoz masculina natural (自然男声)zh
v-male-Bk7vD3xPVoz masculina autoritária (威严霸总)zh
v-female-m1KpW7zEVoz feminina sassá (傲娇学姐)zh
v-female-T8m4WxP7Chenwen (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
FlagPadrãoObservações
--input <arquivo>(nenhum)Arquivo de áudio para clonar. Sem ele, abre a interface web
--name <nome>nome do arquivoNome 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
FlagPadrãoIntervalo/Valores
--voice <id>v-female-R2s4N9qJqualquer ID de voz de voxflow voices
--format <fmt>pcmpcm (WAV), wav, mp3
--speed <n>1.00,5 – 2,0
--volume <n>1.00,1 – 2,0
--pitch <n>0-12 – 12
--output <caminho>nome automáticoqualquer 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çãoCusto
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 (有声绘本)

  1. Escreva uma história infantil de 6 páginas.
  2. Para cada página: gere ilustração SVG inline (400×300).
  3. voxflow say "texto da página" --voice v-female-R2s4N9qJ --speed 0.85 -o /tmp/pagina_N.mp3
  4. Leia os arquivos mp3, codifique em base64, incorpore inline em HTML.
  5. Produza um único arquivo HTML autocontido com botões de reprodução de áudio por página.
  6. 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

  1. git log --oneline --since="1 day ago"
  2. O agente resume.
  3. voxflow say "resumo de hoje..." -o /tmp/diario.mp3

Entrevista simulada

  1. O agente gera 3 perguntas de entrevista sobre o tópico.
  2. Para cada uma: voxflow say "pergunta N..." --voice v-male-Bk7vD3xP -o /tmp/q_N.mp3
  3. 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

FlagDescrição
--bug / --feature / --generalTipo de problema
--title <texto>Título — ativa o modo não interativo
--body <texto>Corpo da descrição
--print-urlForç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 --title e 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

  1. Pesquise vozes antes de usar — nunca invente IDs de voz. Sempre execute voxflow voices primeiro.
  2. Verifique a cota antes de podcasts (~5K), picstory (~3K) ou tarefas em lote: voxflow status.
  3. Reprodução automática após a síntese: open output.mp3 (macOS) / xdg-open (Linux).
  4. Nunca imprima tokens ou segredos nos logs.
  5. Se um comando falhar, execute voxflow <cmd> --help para 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.

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

VoxFlowStudio/skills

Use when the user wants to turn text content into a set of polished, shareable visual CARD IMAGES or narrated card VIDEOS — knowledge cards, quote cards, 小红书图文, carousel cards, poster cards — rendered as HTML/CSS and exported via Playwright at ratios like 1:1 / 3:4 / 9:16; optionally produces a narrated MP4 video from those cards via `voxflow card render` (per-card TTS + FFmpeg static-image clips with optional subtitle bar / intro+outro cards / BGM mix). Triggers: card / 卡片 / 知识卡 / 文字卡片 / 金句卡 / 图文卡片 / 卡片生成 / make cards / card video / 卡片视频. For article → Slice-themed card VIDEO use voxflow:slice; for short videos / AI clips use voxflow:video; for podcasts use voxflow:podcast.

VoxFlowStudio/skills

Use when the user wants to turn a long article / note / report into a vertical 1080×1920 card video — VoxFlow Slice. 13 themes — paper-slide (纸面), editorial-mag (编辑刊), bold-poster (大字海报), notion-card (Notion 卡), brutalist (粗野), glass-dark (玻璃夜), editorial-stencil (编辑·海报), broadsheet (财经刊), blueprint (蓝晒图), daisy-pastel (雏菊), showa-catalog (昭和目录), photo-feature (摄影刊), atmospheric (深夜刊). Triggers — Slice / slice video / 切片视频 / 文章转视频 / 知识卡片视频 / 抖音知识号 / 小红书图文转视频 / 知乎长文转视频 / 公众号转视频 / PaperSlide / paperslide / paper-slide (legacy name).

VoxFlowStudio/skills

Use when the user wants AI-generated short-form video — knowledge cards (picstory / 小红书 / TikTok / Reels), narrated explainers, presentations, AI clips, or slides — covering picstory, present, slides, explain, and image generation. For article-to-card reels (Slice — 13 themes including paper-slide), use voxflow:slice. For shareable HTML/CSS card images or narrated card MP4 videos (`voxflow card render`) use voxflow:card.

Habilidades Relacionadas