slice

Slice Skill

Turn an article, note, paper, or rough topic into a vertical 1080×1920 card video — narrated, paginated to TTS rhythm, with 13 visual themes covering 抖音 / 小红书 / 知乎 / X / 公众号 / 飞书 / TikTok / LinkedIn / 雪球 / 微博 / 即刻 / B 站 / 播客.

Renamed from paper-slide → slice. The product is now called Slice (voxflow.studio/apps/slice); the legacy slug is no longer registered. paper-slide survives only as one of the 13 theme ids.

Pick the Route

Context	Route	Notes
User wants the deck JSON (no render) — fast, scriptable, pipeable	CLI: voxflow slice <article.md> --theme <id>	Hits /api/slice/deck directly (200 quota; renamed from /api/paper-slide/slice in #3307 Deploy 2). Returns the canonical 5–8 card deck JSON validated by the same backend the web app uses, all 13 themes accepted. No mp4 — pipe --json into custom tools, the local Remotion composition (contributors), or paste into the web app for rendering.
User is iterating on a deck — multi-round edits to copy/structure before committing to a render	CLI: voxflow slice stage <deck.json>	Boots a localhost preview page (no quota cost) that hot-reloads on every save of the deck JSON. Useful loop: voxflow slice ... -o deck.json → voxflow slice stage deck.json → tweak prompt → re-run slice → preview updates instantly. See Stage Route below.
User wants a finished mp4 + cover (default consumer flow)	Web app: https://voxflow.studio/apps/slice	The only place that runs the exact 6 Slice themes end-to-end. Free tier ships 9:16 mp4 + multi-aspect cover (9:16/3:4/1:1).
User wants a similar-looking video offline via CLI but the deck-only voxflow slice isn't enough	voxflow present or voxflow picstory --style sketchnote	Approximation only. Different visual schemes; cannot output Slice's editorial-mag / notion-card / brutalist / glass-dark themes. See CLI Approximation below.
Local checkout has video-present/src/compositions/PaperSlide (VoxFlow contributors only)	Local Remotion experiment script	See Local Remotion Route. Note: experiment script only exercises the original paper-slide composition; other 12 themes render via cloud worker only.
User only wants strategy or copy	Produce the deck JSON via voxflow slice (or by hand following the schema); tell them which renderer to use.	The deck schema is renderer-agnostic; same JSON renders in any theme.
User asks to open-source / package	Keep private APIs, tokens, generated audio, MP4 outputs out of the skill package.

Workflow

1. Pick a theme that matches the platform. Read references/themes.md once — it lists all 13 themes, their visual signature, and which platform / content type each one fits. Don't default to paper-slide for everything.
2. Pick a scenario. Concrete use case beats generic filler: paper digest, product update, meeting closeout, career advice, founder lesson, market commentary, incident review.
3. Write a tight deck. 4-6 cards: one title + 3-5 body. One idea per body card. Captions short enough to fit one line.
4. Choose visuals from controlled keywords. Don't search the web or generate random images at render time — pick a canonical figureKeyword; the renderer maps it to a local hand-drawn scene / pose / icon. (See references/deck-schema.md.)
5. Render via the chosen route. Web app for exact themes; CLI for approximation; local script for contributors.
6. Verify the artifact. Check duration, dimensions (1080×1920), and at least one title frame + one body frame before reporting done.
7. Report paths. Absolute paths to MP4 / posters / props.

Read references/deck-schema.md when writing deck JSON, picking keywords, or debugging layout. Read references/example-decks.md for seed decks. Read references/themes.md when picking a theme or explaining theme tradeoffs.

Web App Route (default — works for everyone)

https://voxflow.studio/apps/slice

Workflow:

1. Paste the article / note into the hero composer.
2. AI slices it into 5–8 cards.
3. Pick a theme (13 options — see references/themes.md) + a voice (6 production voices: 男主播 / 霸总男声 / 闲聊男声 / 小美 / 小心 / 小徐).
4. Render → 1080×1920 mp4 + multi-aspect cover (9:16 / 3:4 / 1:1).

Tell the user this is the only route that produces the exact Slice render for all 13 themes — they're private Remotion compositions, not shipped with the CLI.

CLI Deck Route (voxflow slice)

For users who want the structured deck JSON without the render — fast (one round-trip, 200 quota), pipeable, theme-aware. Hits the same /api/slice/deck backend the web app uses, so the deck shape is canonical.

voxflow slice article.md                                  # default theme: paper-slide
voxflow slice article.md --theme editorial-mag -o deck.json
voxflow slice --text "long article ..." --theme bold-poster --json | jq .deck

When to use this route:

• The user wants to inspect / iterate on the AI's slicing quality before committing to a render.
• The user wants to paste the deck into the web app's "import deck" flow to render with a different theme.
• The user is a contributor with the private video-present/src/compositions/PaperSlide Remotion composition and wants to render the deck locally — voxflow slice ... --json -o props.json then feed props.json into the experiment script.
• The user is building automation that needs structured output (e.g. publishing knowledge cards as text on Twitter / 即刻 from deck.cards[*].caption + narration).

Limits:

• No mp4. The cloud renderer that produces the 1080×1920 video lives in the web app.
• No TTS. Pair voxflow slice with voxflow narrate if you want per-card audio without rendering.

Stage Route — voxflow slice stage (iteration preview)

For the human-in-the-loop iteration phase before committing to a cloud render. Stage spins up a localhost HTTP server with hot reload — every save of the deck JSON updates the page instantly. No quota cost, no network round-trip.

voxflow slice deck.md -o deck.json     # 1. produce a deck (200 quota)
voxflow slice stage deck.json          # 2. open localhost preview (free)
                                       # 3. edit deck.json by hand or re-run slice
                                       # 4. preview hot-reloads on save

Want a no-quota, no-login starter? Use the bundled sample directly:

voxflow slice stage examples/11-slice-stage/sample-deck.json

Flags:

voxflow slice stage <deck.json> [--port <n>] [--theme <id>] [--no-open]
  --port      Default 5180. Auto-skips +1 up to 5189 on conflict.
  --theme     Lock the preview to one theme (must be one of the 13 valid ids).
  --no-open   Don't auto-launch the browser (CI / SSH / agent environments).

When to use Stage:

• The user is in a multi-round editing loop — copy tweaks, card re-ordering, theme A/B — and reopening the mp4 each iteration is expensive friction.
• The user wants to publish individual cards as plain text on text-first platforms (X / Twitter / 即刻 / Threads / Mastodon / blog comments). Stage gives each card a "Copy text" button (title + caption + narration), and the deck-level toolbar offers "Copy JSON / Download .json / Copy as Markdown" for pasting into Notion / blog / 飞书. Image / carousel exports for 小红书 / 微博 / 公众号 头图 land in a future Phase once per-card stills are available.
• AI-driven loops where the agent regenerates deck.json and the human reviews via browser — the page updates without the agent having to re-print paths.

Text export utilities (Phase 1.4 text-only)

The Stage UI ships text-first export controls so cards can be reused on text-only platforms without paying for a full render:

• Per-card "Copy text" — click the small button on any card → clipboard gets {title}\n\n{caption (if distinct)}\n\n{narration} (trimmed). Drop into a tweet, 即刻 post, blog snippet.
• Deck toolbar — "Copy JSON" — copies the full deck JSON to clipboard (for piping into custom tools / sharing with another agent / saving a snapshot).
• Deck toolbar — "Download .json" — saves the deck as <seriesTitle>.json (filename auto-sanitised, capped at 60 chars + .json).
• Deck toolbar — "Copy as Markdown" — formats the whole deck as Markdown (H1 = seriesTitle, H2 per card, narration as blockquote). Paste into Notion / blog editor / 飞书 docs.

Formatters live in lib/stage-core/deck-format.js (formatCardAsText, formatDeckAsMarkdown, suggestDeckFilename) and are unit-tested in tests/deck-format.test.js. Their source is stringified into the served HTML via Function.prototype.toString() so the browser executes the same code the tests cover — single source of truth, no double maintenance.

Image / MP4 carousel exports for 小红书 / 微博 / 公众号 头图 are NOT in Phase 1.4 text-only. Those land in a future Phase once renderStill per-card thumbnails are available (they require a backend Remotion endpoint that doesn't exist yet).

What Stage is NOT:

• Not a full Remotion preview yet. MVP shows deck structure (cards + JSON); cloud-rendered theme thumbnails arrive in Phase 1.3 via renderStill.
• Not a substitute for the full render's pixels — themes are server-side compositions. Stage previews the deck text, not the final video frames.

Edit-with-AI loop (the actual iteration workflow)

Stage doesn't try to be Cursor — it's a visual feedback closer that hands prompts to whatever AI tool the user already has open (Claude Code, Cursor, ChatGPT, anything). Two affordances cover the whole edit loop:

Intent	UX	Output
Whole-card rewrite ("regen this card, keep the rest")	Hover the card → corner button Edit with AI	Modal with a prompt: file path + cards[N] JSON snippet + <your instruction> slot
Local phrase rewrite ("just this phrase is off")	Select text inside a card → floating Edit selection with AI button appears	Modal with a prompt: file path + the exact selected substring quoted + full card JSON for context

The user types the instruction (e.g. "shorten to 12 chars, more visceral"), clicks Copy prompt, pastes into their AI. The AI uses its native file-edit tools (Claude Code's Edit, Cursor's Apply, etc.) to rewrite the file. Stage's SSE watcher hot-reloads the preview within ~150 ms. Loop until satisfied.

Why this design and not an embedded chat / MCP server: see #3330 for the full design rationale (universal copy-paste vs. Claude Code-only MCP, cost vs. coverage tradeoff, future MCP upgrade path conditional on usage telemetry).

CLI Approximation Route (full mp4 fallback)

If the user must have an mp4 from the CLI alone (no web app, no contributor Remotion access), fall back to voxflow present or voxflow picstory — they cover the same article-to-video shape but with their own visual schemes, not the exact 13 Slice themes.

voxflow present --text "paste article or summary" --style editorial --output slice-approx.mp4
voxflow picstory --topic "topic" --style sketchnote --scenes 4 --output slice-sketch.mp4

Closest CLI scheme per Slice theme:

Slice theme	Closest CLI route
paper-slide	voxflow picstory --style sketchnote
editorial-mag	voxflow present --style editorial
bold-poster	voxflow present --style brutalist (closest weight)
notion-card	voxflow present --style minimal
brutalist	voxflow present --style brutalist
glass-dark	voxflow present --style noir or --style aurora
editorial-stencil	voxflow present --style editorial (no letterbox / dual-tone equivalent)
broadsheet	voxflow present --style editorial (no FT salmon palette)
blueprint	voxflow picstory --style chalkboard (closest grid/diagram feel)
daisy-pastel	voxflow picstory --style sketchnote (no pastel illustration equivalent)
showa-catalog	voxflow picstory --style vintage_newspaper (no city-pop equivalent)
photo-feature	voxflow picstory --style photo (photo-feature needs imageUrl per card — see deck-schema)
atmospheric	voxflow present --style noir

Always tell the user: "This is a Slice-adjacent draft. The exact 13-theme renderer lives on voxflow.studio/apps/slice."

Local Remotion Route (contributors only)

Skip if video-present/src/compositions/PaperSlide is not in your checkout — it's private code; npm / skills users don't have it.

From the contributor checkout root:

cd video-present
node scripts/paper-slide-experiments.mjs

Render a subset:

cd video-present
PAPER_SLIDE_EXPERIMENT_FILTER=research-reading node scripts/paper-slide-experiments.mjs

Verify outputs:

ffprobe -v error -select_streams v:0 \
  -show_entries stream=width,height,duration \
  -of default=nw=1 out/paper-slide-experiments/research-reading.mp4

ffmpeg -y -hide_banner -loglevel error -ss 9 \
  -i out/paper-slide-experiments/research-reading.mp4 \
  -frames:v 1 -q:v 2 out/paper-slide-experiments/research-reading-body.jpg

Expected: 1080×1920, 20-35 seconds, no black flashes, no caption overflow, figure not clipped.

Deck Writing Rules (apply across all 13 themes)

• Title card: hook, contrast, or promise. Avoid abstract labels like "Introduction".
• Body card: one idea only. Caption usually under 16 Chinese chars or 7 English words.
• Narration: conversational, 25-60 Chinese chars per body card.
• Scene keywords (prefer when they fit): problem-framing, evidence-board, customer-pain, timeline-review, owner-deadline, risk-guardrail, cashflow-ledger, team-alignment, before-after, learning-loop, decision-fork, growth-system.
• Figure / icon keywords (visual accents): thinking, running, climbing, stuck, celebrating, briefcase, users, target, clock, flame, lightbulb, chart-bar.
• Vary adjacent visuals. Don't use thinking on every card.
• Theme is independent of deck content — the same deck JSON renders in any of the 13 themes; pick the theme based on platform / mood, not content. Exception: photo-feature and atmospheric use each card's imageUrl as a backdrop and degrade to an SVG stub when missing — see references/deck-schema.md.