@mineo71/showtime 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.4.0 — 2026-10-13
+
+- Narration: `show.say` on any step is spoken by a TTS engine (`audio.voice`: the macOS/Linux
+  system voice, OpenAI, ElevenLabs or any command). The video holds the frame until a line ends.
+  Lines are cached; editing them needs no new take.
+- `audio.music`: a looped music bed that ducks under the voice. `audio.sounds`: click and
+  keystroke sounds (takes now log keystrokes; older takes spread them over each `type` step).
+- Subtitles from the narration: an `.srt` next to the video, or burned in (`audio.subtitles`).
+- `--aspect 9:16 | 1:1` on `render`, `make` and `frames`: cropped cuts with a camera that follows
+  the action, from the same take. Stills of a crop go to `frames-9x16/` or `frames-1x1/`.
+- `--format gif | webp` (or an `-o` with that extension) and `--width`; `--no-audio`. Silent
+  outputs skip narration (no voice needed) unless subtitles are burned in.
+- `render --json` adds `subtitles`; the brand file accepts `audio`.
+- `lint`: `narration-stretch` flags lines that hold the frame for long.
+
 ## 0.3.0 — 2026-10-13
 
 - `showtime frames` also renders a contact sheet (`frames/sheet.png`) of every step.

package/README.md

@@ -8,7 +8,8 @@
 
 Your AI agent (Claude Code or Codex) writes a short JSON script. showTime clicks through your web app, films it and edits it
 the way a motion designer would (auto-zoom, a smooth cursor, click ripples, spotlights, captions,
-sped-up loading) and hands you a polished 1080p MP4.<br />
+sped-up loading, narration) and hands you a polished video: a 1080p MP4, a 9:16 cut for social or
+a GIF for your README.<br />
 No timeline editor. No re-take when a caption changes.
 
 [![tests](https://img.shields.io/github/actions/workflow/status/mineo71/showTime/ci.yml?branch=main&style=flat-square&label=tests)](https://github.com/mineo71/showTime/actions/workflows/ci.yml)
@@ -26,7 +27,7 @@ No timeline editor. No re-take when a caption changes.
 <div align="center">
   <a href="docs/media/demo.mp4"><img src="docs/media/hero.webp" width="860" alt="A demo of a fictional invoicing app, filmed and edited by showTime: the camera zooms on a chart, a cursor fills in a new invoice, a spotlight lands on the total, and the sent invoice appears in the table" /></a>
   <br />
-  <sub>Made by <a href="examples/fennel/demo.json">a 39-line script</a>, a <a href="examples/fennel/showtime.config.json">brand file</a> and one command, with no manual editing. <a href="docs/media/demo.mp4">▶ Full-quality MP4</a></sub>
+  <sub>Made by <a href="examples/fennel/demo.json">a 39-line script</a>, a <a href="examples/fennel/showtime.config.json">brand file</a> and one command, with no manual editing. <a href="docs/media/demo.mp4">▶ Full-quality MP4, with sound</a></sub>
 </div>
 
 ---
@@ -124,6 +125,27 @@ again.
       <sub>Title card with your logo, a browser frame with your URL, a gradient backdrop, rounded corners and a shadow. Each of them is a <code>style</code> or <code>meta</code> field.</sub>
     </td>
   </tr>
+  <tr>
+    <td valign="top">
+<pre lang="json">
+"show": { "say": "Send it before lunch." }
+
+"audio": {
+  "voice": { "engine": "openai", "name": "nova" },
+  "music": { "file": "bed.mp3" },
+  "sounds": true,
+  "subtitles": "burn"
+}
+</pre>
+      <b>🎙️ Narration, music and clicks</b><br />
+      <sub>Give a step a line and a voice reads it: the built-in voice of macOS or Linux, OpenAI, ElevenLabs or any TTS command. The video holds the frame until the line ends, music ducks under the voice, and subtitles come as an <code>.srt</code> or burned in.</sub>
+    </td>
+    <td valign="top">
+      <img src="docs/media/formats.jpg" alt="The same moment in 16:9, 9:16 and 1:1" /><br />
+      <b>📱 Every format from one take</b><br />
+      <sub><code>--aspect 9:16</code> or <code>1:1</code> crops the window and a follow camera keeps the action in view. <code>--format gif</code> or <code>webp</code> for READMEs and docs. Nothing is re-recorded.</sub>
+    </td>
+  </tr>
   <tr>
     <td valign="top">
       <img src="docs/media/outro.jpg" alt="Outro card with logo, title and URL" /><br />
@@ -206,16 +228,19 @@ flowchart LR
   R --> E["events.json<br/>targets · clicks · idle"]
   S --> T["timeline.json<br/>camera · cursor · captions · speed"]
   E --> T
+  T --> A["mix.wav<br/>voice · music · clicks"]
   T --> M["Remotion"]
+  A --> M
   V --> M
-  M --> O["demo.mp4"]
+  M --> O["demo.mp4 · 9:16 · GIF"]
 ```
 
 The core idea is to **separate capture from direction**. `record` drives a real Chromium through
 the script and writes two things: a clean video with no cursor, and an event log of where every
 target was, when each click landed and when the page sat idle. A pure function,
 `buildTimeline(script, events)`, turns that log into speed segments, camera keyframes, cursor
-paths, captions and spotlights. Remotion renders the result frame by frame.
+paths, captions and spotlights, and holds the frame wherever a narration line needs more time.
+The soundtrack is mixed from the same timeline, and Remotion renders the result frame by frame.
 
 So presentation is cheap to change and recording stays honest: the app really is clicked, typed
 into and waited on, and everything cinematic is computed afterwards.
@@ -279,6 +304,7 @@ Targets are Playwright selectors: `role=button[name='Save']`, `text=Save`, `#id`
 | `spotlight` | boolean        | dim everything except the target |
 | `hold`      | ms             | extra real time after the step (changes the take) |
 | `speed`     | 0.25–16        | playback speed for this step |
+| `say`       | string         | narration spoken from the start of the step; the next narrated step waits for it |
 
 </details>
 
@@ -319,6 +345,37 @@ Targets are Playwright selectors: `role=button[name='Save']`, `text=Save`, `#id`
 
 </details>
 
+<details>
+<summary><b>Sound</b> (<code>audio</code>)</summary>
+
+```json
+"audio": {
+  "voice": { "engine": "system", "name": "Samantha", "speed": 1 },
+  "music": { "file": "music/bed.mp3", "volume": 0.25 },
+  "sounds": true,
+  "subtitles": "file"
+}
+```
+
+| field                | default    | |
+|----------------------|------------|-|
+| `voice.engine`       | `system`   | `system` (macOS `say`, Linux `espeak-ng`), `openai`, `elevenlabs`, or `command` |
+| `voice.name`         | engine default | voice name (`system`, `openai`), or voice id (`elevenlabs`, required) |
+| `voice.speed`        | `1`        | 0.5–2 |
+| `voice.model`        | engine default | `gpt-4o-mini-tts` (OpenAI), `eleven_multilingual_v2` (ElevenLabs) |
+| `voice.instructions` | none       | OpenAI only: how to speak ("warm, confident") |
+| `voice.command`      | none       | `command` only: a shell command that reads the text on stdin and writes audio to `{out}` (inserted already quoted, so write it bare; also in `$SHOWTIME_OUT`), e.g. `piper -m en_US.onnx -f {out}` |
+| `music`              | none       | `{ file, volume? }`: a bed under the whole video, looped and ducked under the voice |
+| `sounds`             | `false`    | click and keystroke sounds |
+| `subtitles`          | `file`     | `file`: an `.srt` next to the video; `burn`: also on the video (captions move up); `off` |
+
+`openai` and `elevenlabs` read `OPENAI_API_KEY` / `ELEVENLABS_API_KEY` from the environment
+(`OPENAI_BASE_URL` points at any OpenAI-compatible server). Each line is synthesized once and
+cached; edits to `say` or `audio` only need `render`. Silent outputs (GIF, WebP, `--no-audio`) skip
+the narration and its pauses, unless subtitles are burned in.
+
+</details>
+
 <details>
 <summary><b>Cards</b> (<code>meta</code>)</summary>
 
@@ -350,8 +407,8 @@ command in the script's folder (120 s timeout); `request` is an HTTP call that m
 <details>
 <summary><b>Brand file</b> (<code>showtime.config.json</code>)</summary>
 
-Put it next to your scripts or in any folder above them; the nearest one applies. Its `style` and
-`meta` are defaults, and a script's own fields win key by key.
+Put it next to your scripts or in any folder above them; the nearest one applies. Its `style`,
+`meta` and `audio` are defaults, and a script's own fields win key by key.
 
 ```json
 {
@@ -367,16 +424,17 @@ Put it next to your scripts or in any folder above them; the nearest one applies
 | command | what it does |
 |---|---|
 | `showtime setup [--agent claude\|codex\|all] [--no-browsers]` | download the browsers, link the skill |
-| `showtime make <script> [-o out.mp4]` | check → record → render |
+| `showtime make <script> [render options]` | check → record → render |
 | `showtime check <script> [--json] [--headed]` | rehearse; a screenshot per step; the first failure with an ARIA snapshot |
 | `showtime record <script> [--headed] [--keep-frames]` | record a take into `.showtime/<name>/take` |
-| `showtime render <script> [-o out.mp4]` | render from the last take, without re-recording |
-| `showtime frames <script>` | QA stills (intro, one per step, outro) and a contact sheet of them |
+| `showtime render <script> [-o out] [--aspect 16:9\|9:16\|1:1] [--format mp4\|gif\|webp] [--width px] [--no-audio]` | render from the last take, without re-recording |
+| `showtime frames <script> [--aspect …]` | QA stills (intro, one per step, outro) and a contact sheet of them |
 | `showtime lint <script>` | warnings about captions, pauses and length; timing checks need a take |
 | `showtime schema` | print the script's JSON Schema |
 
 Every command takes `--json` and then prints exactly one JSON document. The video lands next to
-the script (`demo/pitch.json` → `demo/pitch.mp4`). Working files live in
+the script (`demo/pitch.json` → `demo/pitch.mp4`, `demo/pitch-9x16.mp4`, `demo/pitch.gif`), with
+`demo/pitch.srt` when it is narrated. Working files live in
 `.showtime/<name>/`, which is worth adding to your `.gitignore`.
 
 ## Tips for a great demo
@@ -390,14 +448,19 @@ the script (`demo/pitch.json` → `demo/pitch.mp4`). Working files live in
   for anything personal, and `hooks` to reset the data between `check` and `record`.
 - **Pin the world.** Mock slow or random APIs with `app.mock` and pin the date with `app.clock`,
   so every take looks the same.
+- **Narrate the why, not the clicks.** One short sentence per moment. If `showtime lint` says a
+  line holds the frame for seconds, shorten it or give the step more to show.
 
 ## FAQ
 
 **Which apps does it work with?** Any web app Chromium can open: a localhost dev server, staging
 or production. Logged-in flows work through `app.storageState`.
 
-**Does showTime call an AI model?** No. showTime is deterministic and needs no API keys. The AI
-part (writing, fixing and reviewing the script) happens in your agent, guided by the skill.
+**Does showTime call an AI model?** Not for directing: the AI part (writing, fixing and reviewing
+the script) happens in your agent, guided by the skill. Narration is text-to-speech. The built-in
+voice of macOS or Linux needs no key and nothing leaves your machine; with `openai` or
+`elevenlabs`, only the narration text is sent to that provider, with your key from the
+environment.
 
 **Why not just screen-record?** You can, once. A screen recording can't be re-edited when the copy
 changes, the cursor is wherever your hand was, and the spinner plays at full length. With
@@ -408,8 +471,9 @@ needs Playwright and ffmpeg. Windows is untested.
 
 ## Roadmap
 
-- 🎙️ Narration: text-to-speech per scene, with steps stretched to fit the audio, and burnt-in subtitles.
-- 📱 Vertical 9:16 and square 1:1 cuts with a follow-cam, from the same take.
+- 🧑‍🎨 `showtime studio`: a local page with a live player and a timeline to drag captions, zooms and
+  speed, saving back to the JSON.
+- 🎥 `showtime record-human <url>`: click through the app yourself and get a script back.
 - 🎞️ Deterministic frame-by-frame capture in virtual time, for a perfect 60 fps.
 - 🧩 An MCP server for Claude Desktop, and a desktop studio for timeline tweaks.
 - 📲 Mobile (iOS Simulator) and desktop-app drivers that produce the same `events.json`.

package/docs/script.schema.json

@@ -360,6 +360,11 @@
                     "type": "number",
                     "minimum": 0.25,
                     "maximum": 16
+                  },
+                  "say": {
+                    "description": "Narration spoken from the start of this step; the video waits for it before the next narrated step",
+                    "type": "string",
+                    "minLength": 1
                   }
                 },
                 "additionalProperties": false
@@ -420,6 +425,11 @@
                     "type": "number",
                     "minimum": 0.25,
                     "maximum": 16
+                  },
+                  "say": {
+                    "description": "Narration spoken from the start of this step; the video waits for it before the next narrated step",
+                    "type": "string",
+                    "minLength": 1
                   }
                 },
                 "additionalProperties": false
@@ -504,6 +514,11 @@
                     "type": "number",
                     "minimum": 0.25,
                     "maximum": 16
+                  },
+                  "say": {
+                    "description": "Narration spoken from the start of this step; the video waits for it before the next narrated step",
+                    "type": "string",
+                    "minLength": 1
                   }
                 },
                 "additionalProperties": false
@@ -564,6 +579,11 @@
                     "type": "number",
                     "minimum": 0.25,
                     "maximum": 16
+                  },
+                  "say": {
+                    "description": "Narration spoken from the start of this step; the video waits for it before the next narrated step",
+                    "type": "string",
+                    "minLength": 1
                   }
                 },
                 "additionalProperties": false
@@ -624,6 +644,11 @@
                     "type": "number",
                     "minimum": 0.25,
                     "maximum": 16
+                  },
+                  "say": {
+                    "description": "Narration spoken from the start of this step; the video waits for it before the next narrated step",
+                    "type": "string",
+                    "minLength": 1
                   }
                 },
                 "additionalProperties": false
@@ -687,6 +712,11 @@
                     "type": "number",
                     "minimum": 0.25,
                     "maximum": 16
+                  },
+                  "say": {
+                    "description": "Narration spoken from the start of this step; the video waits for it before the next narrated step",
+                    "type": "string",
+                    "minLength": 1
                   }
                 },
                 "additionalProperties": false
@@ -753,6 +783,11 @@
                     "type": "number",
                     "minimum": 0.25,
                     "maximum": 16
+                  },
+                  "say": {
+                    "description": "Narration spoken from the start of this step; the video waits for it before the next narrated step",
+                    "type": "string",
+                    "minLength": 1
                   }
                 },
                 "additionalProperties": false
@@ -817,6 +852,11 @@
                     "type": "number",
                     "minimum": 0.25,
                     "maximum": 16
+                  },
+                  "say": {
+                    "description": "Narration spoken from the start of this step; the video waits for it before the next narrated step",
+                    "type": "string",
+                    "minLength": 1
                   }
                 },
                 "additionalProperties": false
@@ -876,6 +916,11 @@
                     "type": "number",
                     "minimum": 0.25,
                     "maximum": 16
+                  },
+                  "say": {
+                    "description": "Narration spoken from the start of this step; the video waits for it before the next narrated step",
+                    "type": "string",
+                    "minLength": 1
                   }
                 },
                 "additionalProperties": false
@@ -952,6 +997,94 @@
       },
       "additionalProperties": false
     },
+    "audio": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "voice": {
+          "description": "Text-to-speech for show.say",
+          "default": {},
+          "type": "object",
+          "properties": {
+            "engine": {
+              "default": "system",
+              "description": "system: macOS say / Linux espeak-ng; openai and elevenlabs read OPENAI_API_KEY / ELEVENLABS_API_KEY",
+              "type": "string",
+              "enum": [
+                "system",
+                "openai",
+                "elevenlabs",
+                "command"
+              ]
+            },
+            "name": {
+              "description": "Voice name (system, openai) or voice id (elevenlabs)",
+              "type": "string",
+              "minLength": 1
+            },
+            "speed": {
+              "default": 1,
+              "type": "number",
+              "minimum": 0.5,
+              "maximum": 2
+            },
+            "model": {
+              "description": "openai: gpt-4o-mini-tts by default; elevenlabs: eleven_multilingual_v2",
+              "type": "string",
+              "minLength": 1
+            },
+            "instructions": {
+              "description": "openai only: how to speak, e.g. \"warm and confident\"",
+              "type": "string",
+              "minLength": 1
+            },
+            "command": {
+              "description": "command engine: shell command that reads the text on stdin and writes audio to {out}",
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "additionalProperties": false
+        },
+        "music": {
+          "description": "Music bed under the whole video; ducks while the voice speaks",
+          "type": "object",
+          "properties": {
+            "file": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Audio file, relative to the file that names it"
+            },
+            "volume": {
+              "default": 0.25,
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1
+            }
+          },
+          "required": [
+            "file"
+          ],
+          "additionalProperties": false
+        },
+        "sounds": {
+          "default": false,
+          "description": "Click and keystroke sounds",
+          "type": "boolean"
+        },
+        "subtitles": {
+          "default": "file",
+          "description": "Narration subtitles: an .srt next to the video (file), also drawn on the video (burn), or none",
+          "type": "string",
+          "enum": [
+            "off",
+            "file",
+            "burn"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
     "scenes": {
       "minItems": 1,
       "type": "array",
@@ -1015,6 +1148,11 @@
                           "type": "number",
                           "minimum": 0.25,
                           "maximum": 16
+                        },
+                        "say": {
+                          "description": "Narration spoken from the start of this step; the video waits for it before the next narrated step",
+                          "type": "string",
+                          "minLength": 1
                         }
                       },
                       "additionalProperties": false
@@ -1075,6 +1213,11 @@
                           "type": "number",
                           "minimum": 0.25,
                           "maximum": 16
+                        },
+                        "say": {
+                          "description": "Narration spoken from the start of this step; the video waits for it before the next narrated step",
+                          "type": "string",
+                          "minLength": 1
                         }
                       },
                       "additionalProperties": false
@@ -1159,6 +1302,11 @@
                           "type": "number",
                           "minimum": 0.25,
                           "maximum": 16
+                        },
+                        "say": {
+                          "description": "Narration spoken from the start of this step; the video waits for it before the next narrated step",
+                          "type": "string",
+                          "minLength": 1
                         }
                       },
                       "additionalProperties": false
@@ -1219,6 +1367,11 @@
                           "type": "number",
                           "minimum": 0.25,
                           "maximum": 16
+                        },
+                        "say": {
+                          "description": "Narration spoken from the start of this step; the video waits for it before the next narrated step",
+                          "type": "string",
+                          "minLength": 1
                         }
                       },
                       "additionalProperties": false
@@ -1279,6 +1432,11 @@
                           "type": "number",
                           "minimum": 0.25,
                           "maximum": 16
+                        },
+                        "say": {
+                          "description": "Narration spoken from the start of this step; the video waits for it before the next narrated step",
+                          "type": "string",
+                          "minLength": 1
                         }
                       },
                       "additionalProperties": false
@@ -1342,6 +1500,11 @@
                           "type": "number",
                           "minimum": 0.25,
                           "maximum": 16
+                        },
+                        "say": {
+                          "description": "Narration spoken from the start of this step; the video waits for it before the next narrated step",
+                          "type": "string",
+                          "minLength": 1
                         }
                       },
                       "additionalProperties": false
@@ -1408,6 +1571,11 @@
                           "type": "number",
                           "minimum": 0.25,
                           "maximum": 16
+                        },
+                        "say": {
+                          "description": "Narration spoken from the start of this step; the video waits for it before the next narrated step",
+                          "type": "string",
+                          "minLength": 1
                         }
                       },
                       "additionalProperties": false
@@ -1472,6 +1640,11 @@
                           "type": "number",
                           "minimum": 0.25,
                           "maximum": 16
+                        },
+                        "say": {
+                          "description": "Narration spoken from the start of this step; the video waits for it before the next narrated step",
+                          "type": "string",
+                          "minLength": 1
                         }
                       },
                       "additionalProperties": false
@@ -1531,6 +1704,11 @@
                           "type": "number",
                           "minimum": 0.25,
                           "maximum": 16
+                        },
+                        "say": {
+                          "description": "Narration spoken from the start of this step; the video waits for it before the next narrated step",
+                          "type": "string",
+                          "minLength": 1
                         }
                       },
                       "additionalProperties": false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mineo71/showtime",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Product demos, directed by AI: Claude writes a JSON script, showTime records your web app and renders a polished MP4",
   "keywords": [
     "demo",

package/skill/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: showtime
-description: Use when the user wants a product demo video, walkthrough, screencast or feature recording of a web app (for a pitch, talk, README or social post). Write a showTime JSON script, rehearse it, record it and render a polished MP4 with auto-zoom, smooth cursor, captions and sped-up loading via the `showtime` CLI.
+description: Use when the user wants a product demo video, walkthrough, screencast or feature recording of a web app (for a pitch, talk, README or social post). Write a showTime JSON script, rehearse it, record it and render a polished MP4 (or a 9:16 cut, GIF or WebP) with auto-zoom, smooth cursor, captions, narration and sped-up loading via the `showtime` CLI.
 ---
 
 # showTime — scripted demo videos
 
 `showtime` turns a JSON script into a polished 1080p MP4. You are the director: you write the
 script; the CLI clicks through the app, records it and edits it (zoom, cursor, ripples,
-spotlights, captions, speed-ups, intro card).
+spotlights, captions, speed-ups, intro card, narration, music, subtitles). One take renders as
+16:9, 9:16 or 1:1, as MP4, GIF or WebP.
 
 ## Setup
 
@@ -36,12 +37,14 @@ showtime setup    # downloads the browsers it records with
 5. **Lint:** `showtime lint demo/pitch.json` and fix every warning (long captions, pauses that
    should be waits, zoom or spotlight on steps without a target).
 6. **Record:** `showtime record demo/pitch.json` (runs in real time).
-7. **Render:** `showtime render demo/pitch.json` → `demo/pitch.mp4`.
+7. **Render:** `showtime render demo/pitch.json` → `demo/pitch.mp4`. For social posts add
+   `--aspect 9:16` (→ `demo/pitch-9x16.mp4`); for a README or docs `--format gif` or `--format webp`
+   (`--width` sets the size). Each is a render of the same take, never a new recording.
 8. **QA:** `showtime frames demo/pitch.json`, then Read the contact sheet it prints first
    (`sheet.png`: every step in one image); open single stills only to look closer. Check that zoom
    lands on the right control, captions are legible, and pacing feels right. Run `showtime lint`
    again: with a take it also flags captions on screen too briefly to read.
-9. **Iterate:** edits to `show`, `style` or `meta` only need `render`. Edits to actions (`do`,
+9. **Iterate:** edits to `show` (including `say`), `style`, `meta` or `audio` only need `render`. Edits to actions (`do`,
    targets, text, `hold`, `app`) need `record` again — `render` refuses a stale take.
 
 `showtime make <script>` runs check → record → render in one go. Every command takes `--json`
@@ -55,6 +58,29 @@ with `run_in_background: true` and wait for the completion notification. In Code
 agents, give the command a timeout of at least 10 minutes.
 A `record` that fails or is stopped halfway leaves the previous take in place.
 
+## Narration and sound
+
+Give a step `"say": "…"` and a voice reads it from the start of that step. The video holds the
+frame until the line ends before the next narrated step begins, so a line may cover several quick
+steps. Write one short sentence per moment about the benefit, not the clicks. `showtime lint`
+(with a take) flags lines that hold the frame for seconds (`narration-stretch`): shorten them.
+
+```
+"audio": { "voice": { "engine": "system" }, "sounds": true, "subtitles": "burn" }
+```
+
+- `voice.engine`: `system` (macOS `say`, Linux `espeak-ng`; free and offline) is the default.
+  Use `openai` or `elevenlabs` only when the user asks for a better voice and the key is in the
+  environment (`OPENAI_API_KEY` / `ELEVENLABS_API_KEY`); never write keys into the script. Those
+  engines send the narration text to the provider. `command` runs any TTS that reads stdin and
+  writes `{out}` (inserted already quoted: write it bare, e.g. `piper -m en_US.onnx -f {out}`).
+- `music: { file, volume? }` adds a looped bed that ducks under the voice; only use files the user
+  provides.
+- `subtitles`: `file` (default) writes `<video>.srt`; `burn` also draws them (good for 9:16, which
+  is often watched muted); `off`.
+- `--no-audio` renders without the soundtrack. GIF, WebP and `--no-audio` leave narration out
+  (no voice needed, no pauses for it) unless subtitles are burned in.
+
 ## Side effects
 
 `check` performs every action for real (it is a full run, just fast), and `record` repeats them.
@@ -105,7 +131,10 @@ ask the user for one rather than guessing.
   `press {key}` · `hover {target}` · `select {target, value}` · `scroll {target} | {by}` ·
   `wait {for} | {ms}` · `pause {ms}`
 - **`show` (per step):** `zoom` (number, or `false`), `caption`, `spotlight`, `hold` (ms, real time),
-  `speed`.
+  `speed`, `say` (narration).
+- **`audio`:** `voice` (`{ engine: system | openai | elevenlabs | command, name?, speed?, model?,
+  instructions?, command? }`), `music` (`{ file, volume? }`), `sounds` (clicks and keystrokes),
+  `subtitles` (`file` | `burn` | `off`).
 - **`style`:** `background` (any CSS background), `chrome` (`browser` window frame | `none`), `address`
   (address-bar text), `padding`, `radius`, `shadow`, `font`, `accent`, `autoZoom`, `autoSpeed`, `maxZoom`.
 - **`app`:** `url`, `viewport`, `deviceScaleFactor`, `storageState` (Playwright storage-state JSON,
@@ -116,8 +145,10 @@ ask the user for one rather than guessing.
 - **`meta`:** `title`, `subtitle` (intro card), `logo` (SVG/PNG/JPEG/WebP), `outro`
   (`{ title, subtitle?, url? }`, closing card).
 - **`hooks`:** `before` / `after` lists of `{ run }` or `{ request }`.
-- **Brand file:** `showtime.config.json` in the script's folder or above holds default `style` and
-  `meta` (logo, outro) for every script; the script's own fields win.
+- **Brand file:** `showtime.config.json` in the script's folder or above holds default `style`,
+  `meta` (logo, outro) and `audio` for every script; the script's own fields win.
+- **Render options** (`render`, `make`): `-o <file>`, `--aspect 16:9|9:16|1:1`,
+  `--format mp4|gif|webp`, `--width <px>`, `--no-audio`. `frames --aspect` reviews a crop.
 - Output lands next to the script; working files in `.showtime/<script-name>/`.
 
 ## Direction tips
@@ -134,3 +165,5 @@ ask the user for one rather than guessing.
 - End pitch demos with `meta.outro`: the product name and the URL to visit. Put brand colours, logo
   and outro in `showtime.config.json` when a project has several demos.
 - Keep the default 1440×900 viewport at `deviceScaleFactor` 2 for crisp 16:9 zooms.
+- For a 9:16 cut, review it with `showtime frames <script> --aspect 9:16`: the camera follows each
+  target, so check that every step's target is the thing worth showing.

package/src/audio/decode.ts

@@ -0,0 +1,19 @@
+import { run, runBuffer } from '../ffmpeg';
+import { RATE } from './wav';
+
+const LOUDNORM = (lufs: number) => `loudnorm=I=${lufs}:TP=-1.5:LRA=11`;
+
+/** A synthesized line as a loudness-normalised mono 48 kHz 16-bit WAV. */
+export async function normalizeVoice(src: string, dest: string): Promise<void> {
+  await run('ffmpeg', ['-v', 'error', '-y', '-i', src, '-af', LOUDNORM(-16), '-ac', '1', '-ar', String(RATE), '-c:a', 'pcm_s16le', '-f', 'wav', dest]);
+}
+
+/** Any audio file ffmpeg reads, as float channels at 48 kHz (optionally loudness-normalised). */
+export async function decodeAudio(file: string, o: { channels: 1 | 2; lufs?: number }): Promise<Float32Array[]> {
+  const af = o.lufs === undefined ? [] : ['-af', LOUDNORM(o.lufs)];
+  const raw = await runBuffer('ffmpeg', ['-v', 'error', '-i', file, ...af, '-ac', String(o.channels), '-ar', String(RATE), '-f', 'f32le', '-']);
+  const n = Math.floor(raw.length / 4 / o.channels);
+  const channels = Array.from({ length: o.channels }, () => new Float32Array(n));
+  for (let i = 0; i < n; i++) for (let c = 0; c < o.channels; c++) channels[c][i] = raw.readFloatLE((i * o.channels + c) * 4);
+  return channels;
+}