/gen

description: "Generate a narrated, animated explainer video from a research paper (PDF) or a codebase/repo. Usage: /ppv:gen <pdf path, arxiv-style request, OR a codebase path/topic, plus optional steering: length, focus, aspect, voice>."
disable-model-invocation: true

/ppv:gen — paper or codebase → narrated explainer video

The user's full request is: **$ARGUMENTS**

You are the *planner/composer*. You parse the request, read the source (a research paper **or** a codebase), author a **scene plan**, and drive the deterministic `ppv` CLI (parse → TTS → render). The CLI does the mechanical work; your job is the script and the visual choices.

`ppv` lives at `~/.paperview/venv/bin/ppv`. **Pre-flight: if that binary doesn't exist, the toolchain isn't installed — tell the user to run `/ppv:setup` first, then stop.** Don't attempt to parse / tts / render without it (you'll just get `No such file or directory`).

1. Parse the request, then echo it back

From `$ARGUMENTS` extract: the **source** — a **PDF** (a local path, or an **arXiv id / URL** like `2310.06825` or `arxiv.org/abs/2310.06825`, which is downloaded for you — see §3), a **text/Markdown** file, or a **codebase** (a local repo/directory, a set of source files, a **remote git URL** like `https://github.com/owner/repo`, or a "explain project X" topic) — resolve `~`, relative paths; if missing or ambiguous, **ask — don't guess**. A codebase takes a different path through the steps below (no `ppv parse`, no figures — see §3). Then any steering:

• **length / duration** — a target time (e.g. *"2 minutes"*, *"~5 min"*) → target scene count at

~1 scene per 12–15s (default 10–12 scenes ≈ 3 min) **and** a per-scene narration word budget (~2.5 words/sec, so a 14s scene ≈ 35 words). Size narration to hit the target; TTS finalizes it.

• **depth / audience** — *intro / general* vs *expert*, *intuition-heavy* vs *math-heavy*. This sets

the narration register and the component mix: a general-audience cut leans on `statement`/`bullets`/ `figure` and explains terms; an expert cut spends more on `equation`/`comparison` and assumes vocabulary. Keep claims calibrated either way (§4). For papers/repos with an algorithm or key source snippet, use `code` — paste a real, focused snippet (~6-16 lines), set `lang`, and use `highlightLines` so the narration can walk through specific lines.

• **focus** — a sub-topic to emphasize (spend more scenes there, trim the rest).
• **aspect** (`16:9` default / `9:16` / `1:1`), **provider/voice** (default Kokoro, voice `af_heart`;

run `ppv tts --list-voices` for the voices each provider offers), **captions** (on/off — burned-in subtitles, default off; set `meta.captions` or pass `--captions`).

Briefly state your interpretation (*"paper = X.pdf · ~2 min (8 scenes) · expert · 16:9 — generating now"*) before the long steps.

2. Set up a run directory — named for the topic, not a timestamp

Derive a short **kebab-case slug** from the source's topic (the paper title or the codebase/project name, e.g. `attention-is-all-you-need`, `redis-event-loop`) — keep it lowercase, ascii, `< ~40` chars. Use that one slug for **both** the run directory and the final video filename so runs are self-describing instead of bare numbers:

SLUG=attention-is-all-you-need   # <- your topic slug
WORK=~/.paperview/runs/$SLUG; [ -e "$WORK" ] && WORK="$WORK-$(date +%y%m%d-%H%M%S)"  # avoid clobber
mkdir -p "$WORK"

Reuse `$SLUG` when naming the MP4 in §7 (`$WORK/$SLUG.mp4`). If you can't infer a topic yet, pick the best guess from the request/filename now — a readable name beats a timestamp.

3. Parse the source

**arXiv id / URL?** `ppv parse` needs a local file, so download the PDF into the run dir first, then parse that (the same way a codebase URL is cloned, below). Extract the id (`NNNN.NNNNN`) from the id or any `arxiv.org/abs|pdf|…` URL:

ARXIV=2310.06825    # <- the id you extracted
curl -fsSL "https://arxiv.org/pdf/$ARXIV" -o "$WORK/paper.pdf"   # arXiv serves the PDF here

Then parse `"$WORK/paper.pdf"` as a normal PDF below, **and** run §3b's `ppv math` on the same id for verbatim equations. (If the download fails — withdrawn/again-only paper — tell the user and ask for a local PDF.)

**Paper / document source** (PDF, Markdown, text):

~/.paperview/venv/bin/ppv parse "<source>" --out "$WORK"   # PDF, Markdown, or text

`ppv parse` handles each type natively — **for a Markdown/text source, never convert it to a PDF first** (lossy round-trip); `ppv parse` reads it directly. Then **read `$WORK/parse.json`** (the text) and **view every figure** in `$WORK/assets/` with the Read tool — you must know what each figure actually depicts before you reference it. (A text source with no images yields no figures — that's fine; lean on `equation`/`bullets`/`statement`/`comparison` instead.)

**Codebase source** (a local repo/directory, a set of files, or a **remote git URL**): **skip `ppv parse` entirely** — there's no document to extract. If the source is a remote git URL (e.g. `https://github.com/owner/repo`, a `*.git` URL, or `git@…`), **shallow-clone it into the run dir first** and treat that clone as the codebase:

git clone --depth 1 "<url>" "$WORK/repo"   # add `--branch <ref>` if the user named a branch/tag

(If the URL points at a subpath — `…/tree/main/pkg/x` — clone the repo *root*, then focus on that subdir. If the clone fails, e.g. a private repo, tell the user and ask them to clone it locally and pass the path.) Then **read the code directly with your own tools**: start at the entry points and README, map the architecture (modules, data flow, key abstractions), then open the few functions/types that carry the core idea. There are no extracted figures, so the visual load falls on `mermaid` (architecture/flow/sequence diagrams), `code` (real snippets — paste actual source, set `lang`, use `highlightLines` or `diff` mode), `bullets`, and `comparison`. Skip §3b (no equatio