@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/gemini-tts/references/prompting-guide.md

@@ -0,0 +1,169 @@
+# Gemini TTS Prompting Guide
+
+Advanced prompt engineering for controlling style, emotion, accent, and pacing in Gemini TTS output.
+
+## Prompt Structure
+
+A robust TTS prompt has these elements (in order of importance):
+
+1. **Director's Notes** (most impactful) — Style, pacing, accent instructions
+2. **Transcript** — The actual words to speak, with audio tags
+3. **Audio Profile** (optional) — Character persona definition
+4. **Scene** (optional) — Environmental context for the performance
+
+## Director's Notes
+
+The single most important section. Define only what matters — over-specifying limits the model's natural expressiveness.
+
+### Style
+
+Sets the emotional quality. Be descriptive:
+
+```
+Style: Infectious enthusiasm. The listener should feel like they're part of something exciting.
+```
+
+Works better than just "energetic". You can layer characteristics:
+
+```
+Style:
+* The "Vocal Smile": You must hear the grin in the audio.
+* Dynamics: High projection without shouting. Punchy consonants.
+```
+
+### Pacing
+
+Controls speed and rhythm:
+
+```
+Pacing: Moderate overall. Build energy gradually. Slow down for emphasis on key product names.
+```
+
+Advanced pacing:
+
+```
+Pacing: The "Drift" — incredibly slow and liquid. Words bleed into each other. Zero urgency.
+```
+
+### Accent
+
+Be specific — "British accent" is too vague:
+
+```
+Accent: Southern California, casual and warm.
+Accent: British English as heard in Croydon, London.
+Accent: Neutral American English, clear and professional.
+```
+
+## Audio Tags
+
+Inline modifiers placed in `[brackets]` within the transcript.
+
+### Emotion Tags
+
+```
+[excited] This is amazing!
+[whispers] Can you keep a secret?
+[serious] This is critically important.
+[sarcastic] Oh, what a surprise.
+[panicked] We need to fix this now!
+```
+
+### Pacing Tags
+
+```
+[very fast] Quick rapid-fire delivery here.
+[very slow] Each word gets its own moment.
+[one word at a time] Every. Single. Word. Matters.
+```
+
+### Interjection Tags
+
+```
+[laughs] That's hilarious.
+[sighs] I guess we have to do this.
+[gasp] I can't believe it!
+[cough] Excuse me.
+[yawn] So... what's on the agenda?
+```
+
+### Pause Tags
+
+```
+[short pause] — Brief breath pause (~0.5s)
+[pause] — Medium pause (~1s)
+```
+
+### Creative Tags
+
+The model interprets creative descriptions too:
+
+```
+[like a cartoon dog] Hey there!
+[like dracula] Welcome to my castle.
+[whispering conspiratorially] Don't tell anyone, but...
+```
+
+## Combining Tags with Director's Notes
+
+Tags override Director's Notes locally. Use Director's Notes for the baseline, tags for moments:
+
+```
+### DIRECTOR'S NOTES
+Style: Calm, measured, professional narrator.
+Pacing: Moderate and steady.
+
+### TRANSCRIPT
+The market was stable. Predictable. [excited] And then everything changed overnight!
+[returning to calm] But let's start from the beginning.
+```
+
+## Voice + Style Matching
+
+Choose a voice that naturally complements your style direction:
+
+| Desired Feel | Recommended Voices | Style Notes |
+|-------------|-------------------|-------------|
+| Professional narration | Kore, Charon, Alnilam | Firm, clear, authoritative |
+| Warm & friendly | Sulafat, Achird, Aoede | Conversational, approachable |
+| Energetic & upbeat | Puck, Fenrir, Laomedeia | High energy, enthusiastic |
+| Calm & gentle | Achernar, Vindemiatrix | Soft, soothing |
+| Mature & authoritative | Gacrux, Rasalgethi | Gravitas, trustworthy |
+| Youthful & casual | Leda, Zubenelgenubi | Relaxed, modern |
+
+Mismatching voice and style (e.g., asking Gacrux to sound like a teenager) produces unpredictable results.
+
+## Full Prompt Example
+
+```
+# AUDIO PROFILE: Narrator
+## "Product Launch Voiceover"
+
+## THE SCENE: Professional Recording Studio
+A polished, warm recording booth. The narrator delivers a product launch
+voiceover — confident, inspiring, and measured.
+
+### DIRECTOR'S NOTES
+Style: Warm, confident, and inspiring. Premium product launch feel.
+The voice should feel like a trusted guide revealing something exciting.
+Pacing: Moderate overall. Build energy toward the middle, settle into
+warmth at the end. Allow natural breathing pauses.
+Accent: Neutral American English, clear and professional.
+
+### TRANSCRIPT
+[short pause] Every creative idea deserves to be seen.
+
+But between imagination and reality... there's always a gap.
+
+[with growing confidence] Introducing WeShop AI.
+Powered by the most advanced AI models,
+turning every creative vision into reality — [excited] instantly.
+```
+
+## Tips
+
+- Keep transcripts under 600 tokens for best quality within a single generation
+- For multi-segment consistency, use `scripts/generate-tts.mjs --segments` which handles single-request generation + splitting automatically
+- English audio tags work best even in non-English transcripts
+- The model reads Director's Notes silently — they won't be spoken aloud (usually)
+- If the model reads your instructions aloud, add a clear preamble: "Generate speech for the following transcript only. Do not read the director's notes aloud."

package/skills/gen/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: 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>. Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
+license: Apache-2.0
+source: "ssrajadh/paperview"
+---
+
+# /ppv:gen — paper or codebase → narrated explainer video
+
+## Running it in AICUT
+
+AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
+sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
+`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
+and replaceable in Studio.
+
+```sh
+npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
+npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
+npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
+npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
+npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
+```
+
+Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
+
+Where the words below name another program's part, it becomes this:
+
+| elsewhere | in AICUT |
+|---|---|
+| composition, timeline, project file | `film.html`; tracks and clips inside it |
+| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
+| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
+| a still, a screengrab | `aicut look <t>` |
+| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
+| a dev server, a preview window | `aicut open` and the Studio address it prints |
+
+Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
+binding; look at the frames `look` writes before saying a film is done.
+
+
+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:
+```bash
+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:
+```bash
+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):
+```
+```bash
+~/.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:
+```
+```bash
+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
+equations). Then go straight to §4 and author the plan grounded in the code you actually read — the
+same faithfulness bar applies (don't describe functions/behavior the code doesn't have).
+**Read past the README, and paste real source.** Open the real entry points and core modules — a
+`code` scene's snippet must be source you actually read (the panel shows its `filename`, so it has
+to be real), not reconstructed from memory. The same goes for the claims in `mermaid`/`bullets`/
+`statement` scenes, which have no filename bar to anchor them: describe only structure you actually
+traced. If you only skimmed the README, keep claims high-level rather than inventing internals.
+```
+
+## 3b. Extract the paper's real equations (arXiv) — don't typeset math from memory
+Reconstructing equations from your own recall of the paper is the validated #1 faithfulness risk.
+When the source is an arXiv paper — an id/URL, or a PDF that prints `arXiv:NNNN.NNNNN` on page 1 —
+pull the **actual** LaTeX instead:
+```bash
+~/.paperview/venv/bin/ppv math "<source path or arXiv id/URL>" --out "$WORK"
+```
+```
+Read `$WORK/math.json`: it lists the paper's real display equations as KaTeX-ready `tex` (custom
+macros already expanded), each with the preceding sentence as `context` to help you place it. **Copy
+these `tex` strings verbatim into your `equation` scenes** rather than writing the math yourself. If
+`math.json` carries a `note` (no arXiv id, or not on arXiv), transcribe equations carefully from the
+PDF/figures instead — and prefer fewer, high-confidence equations over guessed ones.
+```
+
+## 4. Author the scene plan → `$WORK/plan.json`
+Run `~/.paperview/venv/bin/ppv components` for the component list + props, and
+`~/.paperview/venv/bin/ppv schema` for the full plan contract (meta fields, valid `aspect`/`voice`).
+Write a JSON object: `{ "meta": {title, aspect, voice, theme}, "scenes": [ {narration, component, props}, … ] }`.
+
+**Always set `meta.theme`** — don't leave it to the default. You've read the paper, so pick the
+backdrop that fits its field and tone (this is the auto-selection; the user shouldn't have to ask):
+- `midnight` (deep navy/blue) — default mood; core ML, theory, NLP, general CS.
+- `slate` (cool neutral gray-blue) — systems, infrastructure, security, networking, databases, hardware.
+- `dusk` (warm plum→amber) — vision, graphics, generative media, HCI, biology, or anything where a
+  softer/editorial feel suits the subject.
+Pick the closest fit; when genuinely unsure, use `midnight`. A user-specified look (or `--theme`)
+always wins.
+**`id` is optional — ppv auto-assigns it by order, so you can omit it** (or use readable names; they're
+renumbered).
+
+Guidance for a good plan:
+- **Narrative arc:** open with `title`; motivate the problem; explain the core idea/method; show
+  the architecture/key `figure`(s) by filename; typeset the key `equation`(s) in real LaTeX;
+  cover results with `stats`; close with `outro`.
+- **Narration** is spoken verbatim: 1–3 plain sentences per scene, **grounded in the paper's text**
+  (no invented numbers/claims).
+- **Don't overstate — calibrate claims to what the paper actually shows.** This is the #1 faithfulness
+  slip on unfamiliar papers (validated by external judges): the model nudges claims slightly too
+  strong. Avoid unearned superlatives — don't say **"state of the art"** unless the paper does;
+  attribute comparative results to the **specific baselines/benchmarks evaluated** ("outperforms the
+  prior methods on TriGap and UCIT", not "the best, period"). Don't assert a result is "proven" or
+  "largest/exactly" beyond the evidence. Prefer the paper's own hedging. When unsure, state the
+  narrower, supportable version.
+- **Write for TTS** — it reads text literally and has no math sense:
+  - Spell out symbols/operators: "d sub k", "square root", "less than or equal to".
+  - **Spell single-letter variables as their letter name**, or TTS voices them as a sound, not a
+    letter (e.g. matrix "a" → says "uh", not "ay"). Use: a→"ay", e→"ee", i→"eye", o→"oh", q→"cue",
+    k→"kay", x→"eks", w→"double-u", y→"why", h→"aitch" (others mostly read fine). E.g.
+    *"the query vector cue and the key vector kay"*. `ppv validate` warns on lone letters (except
+    a/A/I, which collide with articles — handle those yourself).
+  - **`narration` is spoken-only — it is NOT what's shown on screen.** On-screen text comes from the
+    component props (`title`, `text`, `tex`, `items`, …), which are independent fields. So spell
+    acronyms/units/symbols out phonetically in `narration` for the voice (*"Ay through Eff"*, *"five
+    kilograms"*) while the prop keeps the clean display form (*"A–F"*, *"5 kg"*) — you get correct
+    audio AND correct visuals, no tradeoff. (Caveat: with `meta.captions` on, narration also becomes
+    the subtitle text, so there keep it readable.)
+- **Visuals:** pick the component that best fits each beat — don't force a template. Use `figure`
+  only with real extracted filenames; use `equation` for math (LaTeX in `tex`, no `$` — prefer the
+  verbatim strings from `$WORK/math.json`, step 3b); use `mermaid` for an architecture / data-flow /
+  pipeline / sequence diagram when there's no real figure to show (the go-to for codebases and for
+  method overviews — keep it to ~3-10 nodes); use `code` for real source snippets (and `code` with
+  `diff: true` for a before/after change); use `comparison`/`stats`/`bullets` to keep it varied.
+  Respect the user's focus and length.
+- **Cite every reproduced figure.** When you use `figure`, set its `caption` to a source
+  attribution (e.g. *"Figure 2 — Vaswani et al., 2017"*). Papers' figures are copyrighted, so
+  they're always embedded **with credit**, never anonymously.
+- Each scene needs `narration`, a valid `component`, and that component's required props.
+
+## 4b. Validate the plan (cheap — do this before spending TTS/render time)
+```bash
+~/.paperview/venv/bin/ppv validate "$WORK/plan.json" --assets "$WORK/assets"
+```
+```
+Fixes the slow failures up front: invalid components/props (errors, exit 2) and **warnings** for
+TTS-hostile symbols in narration (raw `≤ → √ ⟹` etc. — spell them out) and `figure` srcs that don't
+exist. Fix anything it flags, then proceed.
+```
+
+## 5. Synthesize narration
+```bash
+~/.paperview/venv/bin/ppv tts "$WORK/plan.json" --out "$WORK"
+```
+```
+(`ppv tts --list-voices` lists the presets if the user asked for a specific voice.)
+```
+
+## 6. Cheap visual check before the full render — don't skip this
+A full render takes minutes; a still takes seconds, and clipped/overflowing scenes don't show up
+until you look. **Default to previewing with `--all` before every real render** — skipping it is
+how layout bugs ship. Spot-check dense scenes (equations, long text, figures) for overflow/clipping
+first:
+```bash
+~/.paperview/venv/bin/ppv preview "$WORK/plan.json" --workdir "$WORK" --scene 7   # -> $WORK/preview_scene7.png
+~/.paperview/venv/bin/ppv preview "$WORK/plan.json" --workdir "$WORK" --all       # -> $WORK/preview/scene<id>.png (one per scene)
+```
+```
+`ppv preview` prints each PNG's exact path as it writes it — **Read those paths** with the Read tool
+(note: a single `--scene` lands at `$WORK/preview_scene<n>.png`, but `--all` writes into the
+`$WORK/preview/` subdirectory). Fix any clipped/overflowing scenes in the plan before rendering.
+(Stills need only the figures in `$WORK/assets`; no TTS required.)
+```
+
+## 7. Render
+**Run the render in the background — do not block on it in the foreground.** A foreground command is
+killed at the ~10-minute tool limit, but a full render routinely runs longer: measured at ~4–5× the
+video length on a RAM-limited box, so even a ~2-minute video approaches the cap and a 3-minute one
+blows past it (the render itself is fine — it's the foreground wait that gets killed mid-render).
+So start it with your tool's **background execution**, tell the user it's rendering with a rough ETA
+(≈5× the narration length on modest hardware, less on a fast machine), poll until it finishes, then
+report (§8):
+```bash
+~/.paperview/venv/bin/ppv render "$WORK/plan.json" --workdir "$WORK" --out "$WORK/$SLUG.mp4" --progress
+```
+```
+Name the MP4 with the run's `$SLUG` (§2), not a generic `explainer.mp4`, so the file is
+self-describing. Defaults to **1080p @ 30fps**. Resolution is the big speed/size lever — `--resolution 810p` (or `540p`)
+renders **much** faster and smaller, and `--draft` (810p @ 24fps) is the fast-iteration preset; use it
+for previews and re-render at 1080p only for the final.
+`--crf N` (higher = smaller file) trims size without dropping resolution. `--captions` burns the
+narration in as subtitles (default off; use it when the user asks for captions/subtitles or an
+accessible cut). The backdrop palette normally comes from `meta.theme` (you set it in §4); `--theme midnight|slate|dusk`
+is only an override for when the user explicitly asks for a different look mid-render. Concurrency is
+auto-detected from cores + free RAM. `--progress` (above) surfaces Remotion's progress bar while the
+job runs in the background.
+```
+
+## 8. Report
+Give the user the result as a **clickable link** so they don't have to hunt the filesystem —
+present the MP4 as a markdown link, e.g. `[▶ play attention-is-all-you-need.mp4](file:///home/.../attention-is-all-you-need.mp4)`
+(absolute `file://` path, named with the run's `$SLUG`). `ppv render` also prints the path as a
+clickable terminal hyperlink (some terminals — GNOME Terminal, VS Code — need Ctrl/⌘-click to follow it).
+**Don't auto-open it** (a player stealing focus minutes later is disruptive) — let the user click
+when ready. Also report the **render time**, scene count, and a one-line honest note on where it
+might be weak (e.g. figures that couldn't be extracted). Offer to tweak the plan and re-render.
+
+## Source
+
+Rewritten for AICUT from [`ssrajadh/paperview`](https://github.com/ssrajadh/paperview)
+(Apache-2.0), adapters/claude-code/skills/gen/SKILL.md. The method is that skill's own; the way it runs is AICUT's.
+
+The repository holds 2 skills; this is the one its entry stands for.