VoxFlowStudio/skills

VoxFlow Video Skill

Generate short-form videos with AI: LLM writes the script, AI draws cards or scenes, TTS narrates, FFmpeg / Remotion renders the final MP4.

For article-to-card reels (Slice — 13 themes: paper-slide / editorial-mag / bold-poster / notion-card / brutalist / glass-dark / editorial-stencil / broadsheet / blueprint / daisy-pastel / showa-catalog / photo-feature / atmospheric), switch to voxflow:slice. For shareable HTML/CSS card image sets or narrated card-to-MP4 export, switch to voxflow:card.

Five entry points — pick by what the user wants:

Command	Output	Use when
picstory	Vertical/landscape MP4 with hand-drawn cards or cinematic scenes	"知识卡片视频", 小红书 / Twitter edu, sketchnote tutorials
present	1080×1920 narrated card video, 5 visual schemes	Pitch decks, explainer reels, branded short-form
explain	MP4 explainer with title / bullets / summary scenes	"What is X?" tutorials, course intros
slides	Self-contained HTML deck with embedded TTS audio	Product launches, talks, share-as-link
image	Single PNG	One-off illustrations / thumbnails (Hunyuan TextToImage)

Prerequisites

• npm install -g voxflow and voxflow login
• ffmpeg installed (brew install ffmpeg / sudo apt install ffmpeg) — required for MP4 render
• For present / explain (Remotion-backed): the local plugin install includes remotion-cards/. If present says "Remotion not ready", run npm install inside the bundled remotion-cards/ directory. For explain, you can skip local Remotion with --cloud.

---

🎴 picstory — knowledge-card video

LLM writes a structured script, AI draws one card per scene, TTS narrates, FFmpeg assembles. Best for 小红书 / Twitter edu / TikTok.

Quick start

# Default: Chinese, sketchnote style, portrait, 5 scenes
voxflow picstory --topic "AI Agent 入门指南"

# 2-scene quick test (no full video render)
voxflow picstory --topic "AI 入门" --scenes 2 --image-only

# English landscape video
voxflow picstory --topic "How React Hooks Work" --language en --ratio landscape --style photo

Output: picstory-<timestamp>.mp4 + .json (script).

Card-type styles (structured heading + key points)

--style	Look	Best for
sketchnote (default)	Colorful hand-drawn bullet journal	Knowledge sharing, tutorials
neon_noir	Cyberpunk dark with neon glow	Tech, startup
minimal_3d	Soft 3D clay on pastel gradients	小红书 lifestyle
chalkboard	White chalk on dark green	Science, academic

Scene-type styles (free-form illustration)

--style	Look	Best for
photo	Cinematic / photo-real	Storytelling, travel
manga_panel	Japanese manga ink linework	Drama, step-by-step guides
vintage_newspaper	1940s broadsheet	History, factual stories

Ratios

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

Script-model presets (--script-model)

Preset	Provider	Strength
omitted	server config	Balanced default (gpt-4o-mini)
gemini-flash	OpenRouter	Multilingual, good Chinese
deepseek	DeepSeek	Cheapest, excellent Chinese
hunyuan	腾讯混元	Chinese-native
moonshot	Moonshot	Chinese long context

Server enforces an allowlist — only the preset names above work; arbitrary model IDs are rejected.

Image quality (--quality)

Image generation is the only meaningful cost (~$0.005-0.08 per image). LLM script (~2K tokens) is negligible.

--quality	Provider	Strength	5-image cost
fast (default)	OpenRouter Gemini Flash	Cheapest, balanced	~$0.025
hd	OpenRouter Gemini Pro	Higher detail	mid
ultra	OpenRouter gpt-5.4-image-2	Best overall, ~16× cost	~$0.40
fast-aiberm	Aiberm Gemini Flash	Cheap Aiberm tier	low
hd-aiberm	Aiberm Gemini Pro	Strongest Chinese text rendering — best for 小红书 cards with Chinese headers	mid

Use fast for iteration; hd-aiberm when cards must contain accurate Chinese characters; ultra for hero exports.

Full options

Flag	Default	Description
--topic <text>	required (or --text)	Story topic
--text <content>	—	Paste full article instead of a topic
--style <name>	sketchnote	See styles above
--ratio <name>	portrait	portrait | landscape | square
--language <code>	zh	zh | en | ja | ko | ...
--scenes <n>	5	2–10. Use 2 for quick tests.
--script-model <preset>	server default	See presets above
--quality <tier>	fast	See table above
--voice <id>	default	TTS voice from voxflow voices
--speed <n>	1.0	TTS speed 0.5–2.0
--bgm <file>	—	Background music (mp3/wav) mixed under narration
--bgm-volume <n>	0.1	BGM volume 0–1
--fade <n>	0.4	Per-scene fade in/out seconds (0 to disable)
--image-only	false	Save images + audio without final video render
--output-dir <dir>	—	Directory for all outputs
--output <path>	auto	Final MP4 path

Quota cost

Operation	Quota
LLM script	100
TTS / scene	50
Image / scene	500
2-scene test	~1,200
5-scene full	~2,850

Free tier (10K/month) ≈ 3 full picstory videos.

Pipeline

Topic / Text
  ├─[1] LLM script → { title, scenes: [{ heading, keyPoints, narration }] }
  ├─[2] TTS per scene → PCM audio
  ├─[3] Image per scene (parallel) → JPEG via /api/image/generate
  └─[4] FFmpeg: image + WAV → Ken Burns zoompan MP4 → concat → +BGM → final.mp4

Troubleshooting

Problem	Fix
ffmpeg not found	brew install ffmpeg (mac) / sudo apt install ffmpeg
Image generation failed	Retry; if stuck on hd, drop to --quality fast
Render too slow	Ken Burns is CPU-heavy. Use --scenes 2 --image-only to validate content first.
model_not_allowed	Use a --script-model preset name, not a raw model ID
Chinese text mangled in cards	Switch to --quality hd-aiberm

---

📑 present — narrated card video (Remotion local)

Text or URL → LLM cards → TTS → Remotion render. 1080×1920, 5 visual schemes.

voxflow present --text "Claude Code 是一个 AI 编程工具" --style aurora
voxflow present --url https://example.com/article --style noir
voxflow present --text "2025 AI 芯片格局" --web-search --style neon
voxflow present --cards pre-generated.json --no-audio

Flag	Default	Notes
--text / --url / --cards	one required	input source
--style	aurora	noir | neon | editorial | aurora | brutalist
--voice <id>	v-female-R2s4N9qJ	TTS voice
--speed <n>	1.0	0.5–2.0
--no-audio	false	Silent video only
--web-search	false	Augment LLM with up-to-date web facts
--output <path>	./present-<ts>.mp4	.mp4 or .wav

If present reports "Remotion not ready", run npm install inside the bundled remotion-cards/ directory to set up the local renderer.

---

🧠 explain — AI explainer video

Title / bullets / summary scene flow. Best for "What is X?" tutorials.

voxflow explain --topic "What is React?"
voxflow explain --topic demo --output demo.mp4         # built-in demo (no API call)
voxflow explain --topic "区块链入门" --style chalkboard --voice v-male-Bk7vD3xP
voxflow explain --topic "Machine Learning" --audio-only
voxflow explain --topic "AI Agent 入门" --cloud         # render on server

Flag	Default	Notes
--topic <text>	required	Use demo for built-in demo script
--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	Skip render, output WAV only
--cloud	false	Use cloud Remotion instead of local
--output <path>	./explain-<ts>.mp4

---

📊 slides — HTML presentation with TTS

Generates a self-contained HTML deck with embedded base64 audio per slide. Open in any browser, no server needed.

voxflow slides "AI in Healthcare"
voxflow slides "Q4 Revenue Report" --template report --theme paper
voxflow slides "React Tutorial" --template tutorial --model balanced
voxflow slides "Startup Pitch" --template pitch --theme ocean --no-audio

Flag	Default	Notes
--text <text> (or positional)	required	Topic
--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	Skip TTS, slides only
--output <path>	./slides-<ts>.html

10 layouts: hero, title-bullets, two-column, three-cards, image-left, image-right, quote, timeline, stats, section. Templates auto-pick a layout sequence.

---

🖼 image — single Hunyuan illustration

Synchronous text → image (PNG). Useful for thumbnails or one-off art.

voxflow image "a sleeping cat in a sunlit window" --resolution 1024:1024 -o cat.png

Resolutions: 768:768, 768:1024, 1024:768, 1024:1024, 720:1280, 1280:720, 768:1280, 1280:768, 1080:1920, 1920:1080.

Prompt max 1000 chars. Output: local PNG + COS URL.

---

Pick-the-right-tool checklist

"小红书风格知识卡片"           → picstory
"AI 短视频 + caption"          → picstory --style sketchnote
"explainer / What is X?"        → explain
"branded short with my text"    → present
"already have cards/script"     → present --cards
"shareable HTML deck w/ audio"  → slides
"single illustration"           → image

Rules

1. Search voices with voxflow voices before passing --voice. Never guess IDs.
2. Check quota before video calls (voxflow status): picstory ≈ 3K, present/explain ≈ 500–2K.
3. Test cheap first: picstory --scenes 2 --image-only validates the script before paying for full render.
4. After render finishes, auto-play: open output.mp4 (macOS).