@mineo71/showtime 0.2.1 → 0.4.0

package/docs/script.schema.json

@@ -18,6 +18,31 @@
         },
         "subtitle": {
           "type": "string"
+        },
+        "logo": {
+          "description": "SVG/PNG/JPEG/WebP shown on the intro and outro cards",
+          "type": "string",
+          "minLength": 1
+        },
+        "outro": {
+          "description": "Closing card after the video",
+          "type": "object",
+          "properties": {
+            "title": {
+              "type": "string",
+              "minLength": 1
+            },
+            "subtitle": {
+              "type": "string"
+            },
+            "url": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "title"
+          ],
+          "additionalProperties": false
         }
       },
       "additionalProperties": false
@@ -83,6 +108,71 @@
             "type": "string",
             "minLength": 1
           }
+        },
+        "mock": {
+          "default": [],
+          "description": "Answer matching network requests with canned responses; the first match wins",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "url": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Playwright URL glob of the requests to answer, e.g. **/api/reports*"
+              },
+              "method": {
+                "description": "Only answer this HTTP method; others go to the network",
+                "type": "string",
+                "minLength": 1
+              },
+              "status": {
+                "default": 200,
+                "type": "integer",
+                "minimum": 100,
+                "maximum": 599
+              },
+              "json": {
+                "description": "Response body, sent as application/json"
+              },
+              "body": {
+                "description": "Raw response body",
+                "type": "string"
+              },
+              "headers": {
+                "type": "object",
+                "propertyNames": {
+                  "type": "string"
+                },
+                "additionalProperties": {
+                  "type": "string"
+                }
+              },
+              "delayMs": {
+                "description": "Wait this long before answering",
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 30000
+              }
+            },
+            "required": [
+              "url"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "clock": {
+          "description": "Start the page clock at this ISO date-time; it then runs normally",
+          "type": "string"
+        },
+        "dialogs": {
+          "default": "accept",
+          "description": "How to answer alert/confirm/prompt dialogs",
+          "type": "string",
+          "enum": [
+            "accept",
+            "dismiss"
+          ]
         }
       },
       "required": [
@@ -90,6 +180,133 @@
       ],
       "additionalProperties": false
     },
+    "hooks": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "before": {
+          "default": [],
+          "description": "Run before every check and record, e.g. to reset demo data",
+          "type": "array",
+          "items": {
+            "anyOf": [
+              {
+                "type": "object",
+                "properties": {
+                  "run": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Shell command, run in the script folder"
+                  }
+                },
+                "required": [
+                  "run"
+                ],
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "request": {
+                    "type": "object",
+                    "properties": {
+                      "url": {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "method": {
+                        "default": "POST",
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "json": {},
+                      "headers": {
+                        "type": "object",
+                        "propertyNames": {
+                          "type": "string"
+                        },
+                        "additionalProperties": {
+                          "type": "string"
+                        }
+                      }
+                    },
+                    "required": [
+                      "url"
+                    ],
+                    "additionalProperties": false
+                  }
+                },
+                "required": [
+                  "request"
+                ],
+                "additionalProperties": false
+              }
+            ]
+          }
+        },
+        "after": {
+          "default": [],
+          "description": "Run after every check and record, even when it failed",
+          "type": "array",
+          "items": {
+            "anyOf": [
+              {
+                "type": "object",
+                "properties": {
+                  "run": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Shell command, run in the script folder"
+                  }
+                },
+                "required": [
+                  "run"
+                ],
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "request": {
+                    "type": "object",
+                    "properties": {
+                      "url": {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "method": {
+                        "default": "POST",
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "json": {},
+                      "headers": {
+                        "type": "object",
+                        "propertyNames": {
+                          "type": "string"
+                        },
+                        "additionalProperties": {
+                          "type": "string"
+                        }
+                      }
+                    },
+                    "required": [
+                      "url"
+                    ],
+                    "additionalProperties": false
+                  }
+                },
+                "required": [
+                  "request"
+                ],
+                "additionalProperties": false
+              }
+            ]
+          }
+        }
+      },
+      "additionalProperties": false
+    },
     "setup": {
       "default": [],
       "type": "array",
@@ -143,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
@@ -203,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
@@ -287,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
@@ -347,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
@@ -407,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
@@ -470,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
@@ -536,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
@@ -600,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
@@ -659,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
@@ -735,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",
@@ -798,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
@@ -858,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
@@ -942,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
@@ -1002,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
@@ -1062,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
@@ -1125,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
@@ -1191,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
@@ -1255,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
@@ -1314,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.2.1",
+  "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
 
@@ -33,14 +34,21 @@ showtime setup    # downloads the browsers it records with
 4. **Rehearse:** `showtime check demo/pitch.json`. On failure read the error, the ARIA snapshot it
    prints and `.showtime/<name>/check/failure.png`; fix the selector or add a `wait`, repeat until
    green.
-5. **Record:** `showtime record demo/pitch.json` (runs in real time).
-6. **Render:** `showtime render demo/pitch.json` → `demo/pitch.mp4`.
-7. **QA:** `showtime frames demo/pitch.json`, then Read the PNGs it lists. Check that zoom lands on
-   the right control, captions are legible and do not hide the action, and pacing feels right.
-8. **Iterate:** edits to `show`, `style` or `meta` only need `render`. Edits to actions (`do`,
+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`. 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` (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.
+`showtime make <script>` runs check → record → render in one go. Every command takes `--json`
+and then prints exactly one JSON document on stdout.
 
 ## Long-running commands
 
@@ -48,14 +56,45 @@ showtime setup    # downloads the browsers it records with
 Remotion. They routinely take several minutes. In Claude Code run them with `timeout: 600000`, or
 with `run_in_background: true` and wait for the completion notification. In Codex and other
 agents, give the command a timeout of at least 10 minutes.
-Never let a `record` be killed halfway: it replaces the previous take.
+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.
 Flows that create data ("New project", sign-up, checkout) can collide on the second run
-("name already exists"). Use a resettable demo account or seed data, make names unique, or undo
-the change in `setup`; after a green `check`, reset the data before `record`.
+("name already exists"). Add `hooks` that reset the data: `before` hooks run at the start of every
+`check` and `record`, `after` hooks when they end.
+
+```
+"hooks": { "before": [{ "run": "npm run db:reset" }] }
+```
+
+A hook is `{ "run": "<shell command, run in the script folder>" }` or
+`{ "request": { "url": "…", "method": "POST", "json": {…} } }`. If the project has no reset command,
+ask the user for one rather than guessing.
 
 ## Example
 
@@ -92,12 +131,24 @@ the change in `setup`; after a green `check`, reset the data before `record`.
   `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,
   path relative to the script), `colorScheme`, `locale`, `timezoneId`, `mask` (CSS selectors to blur —
-  plain CSS only, not `text=` / `role=`).
+  plain CSS only, not `text=` / `role=`), `mock` (`[{ url: "**/api/x*", json | body, status?,
+  method?, delayMs? }]`), `clock` (ISO date-time the page clock starts at; first matching mock wins), `dialogs` (`accept` | `dismiss`).
+  Relative `goto` URLs resolve against `app.url`.
+- **`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`,
+  `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
@@ -109,4 +160,10 @@ the change in `setup`; after a green `check`, reset the data before `record`.
 - Never `pause` to wait for loading — use `wait {for}`; auto-speed compresses the loader.
 - Use `setup` for cookie banners and onboarding, `app.storageState` to start logged in, `app.mask`
   to blur personal data.
+- Mock APIs that are slow, random or need real accounts (`app.mock`), and pin the date
+  (`app.clock`) so every take shows the same numbers and timestamps.
+- 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.