VoxFlowStudio/skills

Habilidade de Vídeo VoxFlow

Gere vídeos curtos com IA: o LLM escreve o roteiro, a IA desenha cartões ou cenas, o TTS narra, o FFmpeg / Remotion renderiza o MP4 final.

Para reels de artigo para 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), mude para voxflow:slice. Para conjuntos de imagens de cartão HTML/CSS compartilháveis ou exportação de cartão narrado para MP4, mude para voxflow:card.

Cinco pontos de entrada — escolha de acordo com o que o usuário deseja:

Comando	Saída	Use quando
picstory	MP4 vertical/panorâmico com cartões desenhados à mão ou cenas cinematográficas	"Vídeos de cartão de conhecimento", 小红书 / Twitter edu, tutoriais sketchnote
present	Vídeo de cartão narrado 1080×1920, 5 esquemas visuais	Pitch decks, reels explicativos, formato curto com marca
explain	MP4 explicativo com cenas de título / tópicos / resumo	Tutoriais "O que é X?", intros de cursos
slides	Apresentação HTML autocontida com áudio TTS embutido	Lançamentos de produtos, palestras, compartilhar como link
image	PNG único	Ilustrações avulsas / thumbnails (Hunyuan TextToImage)

Pré-requisitos

• npm install -g voxflow e voxflow login
• ffmpeg instalado (brew install ffmpeg / sudo apt install ffmpeg) — necessário para renderização MP4
• Para present / explain (com Remotion): a instalação do plugin local inclui remotion-cards/. Se present disser "Remotion not ready", execute npm install dentro do diretório remotion-cards/ empacotado. Para explain, você pode pular o Remotion local com --cloud.

---

🎴 picstory — vídeo de cartão de conhecimento

O LLM escreve um roteiro estruturado, a IA desenha um cartão por cena, o TTS narra, o FFmpeg monta. Melhor para 小红书 / Twitter edu / TikTok.

Início rápido

# Padrão: chinês, estilo sketchnote, retrato, 5 cenas
voxflow picstory --topic "Guia de Introdução ao AI Agent"

# Teste rápido de 2 cenas (sem renderização completa do vídeo)
voxflow picstory --topic "Introdução à IA" --scenes 2 --image-only

# Vídeo panorâmico em inglês
voxflow picstory --topic "How React Hooks Work" --language en --ratio landscape --style photo

Saída: picstory-<timestamp>.mp4 + .json (roteiro).

Estilos de tipo cartão (título estruturado + pontos-chave)

--style	Aparência	Melhor para
sketchnote (padrão)	Diário de balas desenhado à mão e colorido	Compartilhamento de conhecimento, tutoriais
neon_noir	Ciberpunk escuro com brilho neon	Tecnologia, startups
minimal_3d	Clay 3D suave em gradientes pastel	Estilo de vida 小红书
chalkboard	Giz branco em verde escuro	Ciência, acadêmico

Estilos de tipo cena (ilustração livre)

--style	Aparência	Melhor para
photo	Cinematográfico / fotorrealista	Contação de histórias, viagens
manga_panel	Traço de tinta mangá japonês	Drama, guias passo a passo
vintage_newspaper	Jornal dos anos 1940	História, histórias factuais

Proporções

--ratio	Pixels	Plataforma
portrait (padrão)	1080×1920	小红书, TikTok, Reels, 抖音
landscape	1920×1080	YouTube, B站
square	1080×1080	Instagram, Twitter

Predefinições de modelo de roteiro (--script-model)

Predefinição	Provedor	Pontos fortes
omitido	configuração do servidor	Padrão equilibrado (gpt-4o-mini)
gemini-flash	OpenRouter	Multilíngue, bom chinês
deepseek	DeepSeek	Mais barato, chinês excelente
hunyuan	Tencent Hunyuan	Nativo em chinês
moonshot	Moonshot	Contexto longo em chinês

O servidor impõe uma lista de permissões — apenas os nomes das predefinições acima funcionam; IDs de modelo arbitrários são rejeitados.

Qualidade de imagem (--quality)

A geração de imagens é o único custo significativo (~$0,005-0,08 por imagem). O roteiro do LLM (~2K tokens) é insignificante.

--quality	Provedor	Pontos fortes	Custo de 5 imagens
fast (padrão)	OpenRouter Gemini Flash	Mais barato, equilibrado	~$0,025
hd	OpenRouter Gemini Pro	Maior detalhe	médio
ultra	OpenRouter gpt-5.4-image-2	Melhor no geral, ~16× o custo	~$0,40
fast-aiberm	Aiberm Gemini Flash	Nível Aiberm barato	baixo
hd-aiberm	Aiberm Gemini Pro	Renderização de texto chinês mais forte — melhor para cartões 小红书 com cabeçalhos em chinês	médio

Use fast para iteração; hd-aiberm quando os cartões precisarem conter caracteres chineses precisos; ultra para exportações de destaque.

Opções completas

Flag	Padrão	Descrição
--topic <texto>	obrigatório (ou --text)	Tópico da história
--text <conteúdo>	—	Cole o artigo completo em vez de um tópico
--style <nome>	sketchnote	Veja os estilos acima
--ratio <nome>	portrait	portrait | landscape | square
--language <código>	zh	zh | en | ja | ko | ...
--scenes <n>	5	2–10. Use 2 para testes rápidos.
--script-model <predefinição>	padrão do servidor	Veja as predefinições acima
--quality <nível>	fast	Veja a tabela acima
--voice <id>	padrão	Voz TTS de voxflow voices
--speed <n>	1.0	Velocidade TTS 0,5–2,0
--bgm <arquivo>	—	Música de fundo (mp3/wav) mixada sob a narração
--bgm-volume <n>	0.1	Volume BGM 0–1
--fade <n>	0.4	Fade in/out por cena em segundos (0 para desabilitar)
--image-only	false	Salvar imagens + áudio sem renderização final do vídeo
--output-dir <dir>	—	Diretório para todas as saídas
--output <caminho>	automático	Caminho final do MP4

Custo de cota

Operação	Cota
Roteiro LLM	100
TTS / cena	50
Imagem / cena	500
Teste de 2 cenas	~1.200
Completo de 5 cenas	~2.850

Nível gratuito (10K/mês) ≈ 3 vídeos picstory completos.

Pipeline

Tópico / Texto
  ├─[1] Roteiro LLM → { title, scenes: [{ heading, keyPoints, narration }] }
  ├─[2] TTS por cena → áudio PCM
  ├─[3] Imagem por cena (paralelo) → JPEG via /api/image/generate
  └─[4] FFmpeg: imagem + WAV → Ken Burns zoompan MP4 → concat → +BGM → final.mp4

Solução de problemas

Problema	Correção
ffmpeg not found	brew install ffmpeg (mac) / sudo apt install ffmpeg
Image generation failed	Tente novamente; se travar em hd, mude para --quality fast
Renderização muito lenta	Ken Burns é pesado para CPU. Use --scenes 2 --image-only para validar o conteúdo primeiro.
model_not_allowed	Use um nome de predefinição --script-model, não um ID de modelo bruto
Texto chinês distorcido nos cartões	Mude para --quality hd-aiberm

---

📑 present — vídeo de cartão narrado (Remotion local)

Texto ou URL → Cartões LLM → TTS → Renderização Remotion. 1080×1920, 5 esquemas visuais.

voxflow present --text "Claude Code é uma ferramenta de programação com IA" --style aurora
voxflow present --url https://example.com/article --style noir
voxflow present --text "Panorama dos chips de IA em 2025" --web-search --style neon
voxflow present --cards pre-generated.json --no-audio

Flag	Padrão	Notas
--text / --url / --cards	um obrigatório	Fonte de entrada
--style	aurora	noir | neon | editorial | aurora | brutalist
--voice <id>	v-female-R2s4N9qJ	Voz TTS
--speed <n>	1.0	0,5–2,0
--no-audio	false	Apenas vídeo silencioso
--web-search	false	Aumente o LLM com fatos atualizados da web
--output <caminho>	./present-<ts>.mp4	.mp4 ou .wav

Se present relatar "Remotion not ready", execute npm install dentro do diretório remotion-cards/ empacotado para configurar o renderizador local.

---

🧠 explain — vídeo explicativo com IA

Fluxo de cenas de título / tópicos / resumo. Melhor para tutoriais "O que é X?".

voxflow explain --topic "O que é React?"
voxflow explain --topic demo --output demo.mp4         # demonstração embutida (sem chamada de API)
voxflow explain --topic "Introdução ao Blockchain" --style chalkboard --voice v-male-Bk7vD3xP
voxflow explain --topic "Machine Learning" --audio-only
voxflow explain --topic "Introdução ao AI Agent" --cloud         # renderizar no servidor

Flag	Padrão	Notas
--topic <texto>	obrigatório	Use demo para roteiro de demonstração embutido
--style	modern	modern | playful | corporate | chalkboard
--language	en	en | zh | ja | ko | ...
--voice <id>	v-female-R2s4N9qJ
--scenes <n>	5	3–12
--audio-only	false	Pular renderização, saída apenas WAV
--cloud	false	Usar Remotion em nuvem em vez de local
--output <caminho>	./explain-<ts>.mp4

---

📊 slides — apresentação HTML com TTS

Gera uma apresentação HTML autocontida com áudio base64 embutido por slide. Abra em qualquer navegador, sem necessidade de servidor.

voxflow slides "IA na Saúde"
voxflow slides "Relatório de Receitas Q4" --template report --theme paper
voxflow slides "Tutorial de React" --template tutorial --model balanced
voxflow slides "Pitch de Startup" --template pitch --theme ocean --no-audio

Flag	Padrão	Notas
--text <texto> (ou posicional)	obrigatório	Tópico
--template	free	product | report | tutorial | pitch | free
--theme	midnight	midnight | paper | ember | forest | ocean
--model	swift	swift | balanced | pro | creative
--voice <id>	v-female-R2s4N9qJ
--no-audio	false	Pular TTS, apenas slides
--output <caminho>	./slides-<ts>.html

10 layouts: hero, title-bullets, two-column, three-cards, image-left, image-right, quote, timeline, stats, section. Os templates escolhem automaticamente uma sequência de layout.

---

🖼 image — ilustração única Hunyuan

Síncrono texto → imagem (PNG). Útil para thumbnails ou arte avulsa.

voxflow image "um gato dormindo em uma janela ensolarada" --resolution 1024:1024 -o gato.png

Resoluções: 768:768, 768:1024, 1024:768, 1024:1024, 720:1280, 1280:720, 768:1280, 1280:768, 1080:1920, 1920:1080.

Máximo de 1000 caracteres no prompt. Saída: PNG local + URL COS.

---

Lista de verificação para escolher a ferramenta certa

"Cartão de conhecimento estilo 小红书"           → picstory
"Vídeo curto com IA + legenda"                  → picstory --style sketchnote
"Explicativo / O que é X?"                       → explain
"Vídeo curto com marca e meu texto"              → present
"Já tenho cartões/roteiro"                       → present --cards
"Apresentação HTML compartilhável com áudio"     → slides
"Ilustrações avulsas"                            → image

Regras

1. Pesquise vozes com voxflow voices antes de passar --voice. Nunca adivinhe IDs.
2. Verifique a cota antes de chamadas de vídeo (voxflow status): picstory ≈ 3K, present/explain ≈ 500–2K.
3. Teste barato primeiro: picstory --scenes 2 --image-only valida o roteiro antes de pagar pela renderização completa.
4. Após a renderização, reproduza automaticamente: open output.mp4 (macOS).