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

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:

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:

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.