Skip to content
Back to search

showtime

MarketplaceWorks with Claude CodeGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/FavioVazquez/showtime with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/FavioVazquez/showtime'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/faviovazquez--showtime/badge.svg)](/listings/faviovazquez--showtime)

HTML

<a href="/listings/faviovazquez--showtime"><img src="/api/listings/faviovazquez--showtime/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

New here? [Make your first video](docs/guides/first-video.md): a 5-second test that checks the install and shows every step a bigger video goes through.

**1. Install the two prerequisites** (details in [Requirements](#requirements)): [uv](https://docs.astral.sh/uv/) and [Node.js](https://nodejs.org) 24 or 22 LTS (20 or newer works). Restart your coding agent afterwards so it sees them.

**2. Add showtime to your agent.** In Claude Code:

/plugin marketplace add FavioVazquez/showtime
/plugin install showtime@showtime

Using Codex, Cursor, Devin, OpenCode or another agent? [Works with](#works-with) has the exact install for each, and `npx skills add FavioVazquez/showtime` covers any agent that supports Agent Skills.

**3. Ask for a video:**

Make a 20-second launch video for this repo, with a voice-over and upbeat music.

The first time, your agent checks what is missing, tells you the download size and time (about 0.5 to 0.75 GB to download and 1.4 to 1.8 GB in `~/.showtime` once installed, depending on your system, usually 2 to 6 minutes; outside that folder only uv's and npm's download caches change) and runs setup once you say yes. If your agent's sandbox blocks the download, run setup once in a terminal ([Troubleshooting](docs/troubleshooting.md#setup-never-ran-or-the-sandbox-blocked-it)). Bigger pieces (the transcription model, Manim, music tracks) come the first time a video needs them, announced with their size. After that, a request in Claude Code looks like this:

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="assets/readme/terminal-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="assets/readme/terminal-light.svg"> </picture> <br><sub>An illustration of a session in Claude Code; other agents show the same steps in their own style. The card's figures are example 01's; render time depends on your machine.</sub> </p>

Your agent states its assumptions in one line (it asks only when a request is genuinely open), shows you a first look (stills or a fast draft) before the full-quality render, then checks the result with `showtime qa`. Every request gets its own folder, `showtime-out/<name>-<timestamp>/`, with `final.mp4`, `poster.jpg`, `share.txt`, `exports/` and `work/`. Nothing is ever overwritten. Questions about cost, GPUs, disk, languages or what leaves your machine: the [FAQ](docs/faq.md). Something went wrong: [Troubleshooting](docs/troubleshooting.md). A word you don't know: the [glossary](docs/glossary.md).

> [!TIP] > Two separate settings. **Quick or studio** decides how much your agent asks before building: quick (the > default) states its assumptions and starts; studio (say **"show me options first"**) shows a concept, a look, a > music bed and a storyboard on a local board first. **Quality or lean** decides how much it checks afterwards: > quality (the default) has a critic review every finished video; lean skips the critic unless the video is going > to be published. Say **"no crew"** to keep the whole job in one session.

**What's new in 0.4.6** (the list is [below](#new-in-046), and [What's new](docs/whats-new.md) has a short paragraph for each):

- **`check` reads the text a page draws on its own canvas.** Text outside the phone's safe box, text too small to read and text over other text are found between its samples and on any canvas, not only the film API's. - **X-ray on a phone and in sync.** At 9:16 the sound strip and the part labels sit where a phone shows them, a new 16:9 project passes its own check, and with `"xray".offset_frames` the strip and the piano, drums and guitar follow the recording's clock. - **Fixes.** `export html --interactive` packs a page's own fonts, `xray verify` reads the marker on a draft render, installed files match the repository byte for byte, and `setup --home` brings its own ffmpeg.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 24 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "showtime",
  3. "owner": {
  4. "name": "Favio Vazquez"
  5. },
  6. "metadata": {
  7. "description": "showtime: a local video studio for your coding agent",
  8. "version": "0.4.6"
  9. },
  10. "plugins": [
  11. {
  12. "name": "showtime",
  13. "source": "./",
  14. "description": "A local video studio for your coding agent. Describe a video. Your agent directs. Your machine renders. Motion graphics, voice-over, music, footage editing, captions and platform-ready exports, with no cloud AI services or API keys.",
  15. "version": "0.4.6",
  16. "author": {
  17. "name": "Favio Vazquez"
  18. },
  19. "license": "MIT",
  20. "keywords": ["video", "motion-graphics", "tts", "music", "captions", "ffmpeg"],
  21. "category": "media"
  22. }
  23. ]
  24. }
README.md · README · 1,754 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/hero-dark.svg">
  4. <source media="(prefers-color-scheme: light)" srcset="assets/readme/hero-light.svg">
  5. <img alt="showtime: velvet curtains open on a lit stage. A local video studio for your coding agent. Describe a video. Your agent directs. Your machine renders." src="assets/readme/hero-light.svg" width="100%">
  6. </picture>
  7. </p>
  8. https://github.com/user-attachments/assets/638bfa30-522f-4e7c-ab9e-e77f364e7dc9
  9. <p align="center"><sub>The 0.4.1 showreel: 55 seconds, rendered by showtime 0.4.1 in 2 min 23 s on a 64-core CPU with no GPU; seven real showtime films, then the features behind them (<a href="https://github.com/FavioVazquez/showtime-examples/blob/main/examples/_showreel041/README.md">about the film</a>).</sub><br><sub><a href="https://github.com/FavioVazquez/showtime-examples/releases/download/examples-media-v1/_showreel041--showreel-16x9.mp4"><b>Download the showreel</b></a> (full quality, 107 MB). Music: “Supernova” by Scott Buckley, <a href="https://creativecommons.org/licenses/by/4.0/">CC BY 4.0</a>. Footage: NASA (public domain); photo: “Godafoss 3” by Tord Dellsen, CC0 (<a href="https://github.com/FavioVazquez/showtime-examples/blob/main/examples/_showreel041/credits.txt">credits</a>).</sub></p>
  10. <!-- /HERO -->
  11. <p align="center">
  12. <a href="LICENSE"><img alt="license: MIT" src="assets/readme/badges/license.svg" height="24"></a>
  13. <img alt="runs on your machine" src="assets/readme/badges/local.svg" height="24">
  14. <img alt="API keys: none" src="assets/readme/badges/keys.svg" height="24">
  15. <a href="#works-with"><img alt="tested with Claude Code, Codex, Cursor, Devin and OpenCode" src="assets/readme/badges/agents.svg" height="24"></a>
  16. <a href="CHANGELOG.md"><img alt="status: 0.4, early" src="assets/readme/badges/status.svg" height="24"></a>
  17. <a href="#requirements"><img alt="tested: Intel Mac, Apple Silicon, Linux x64, Linux arm64, Windows x64, Windows 11 on Arm" src="assets/readme/badges/tested.svg" height="24"></a>
  18. <a href="#requirements"><img alt="still to run: Windows 10/11 desktop" src="assets/readme/badges/windows.svg" height="24"></a>
  19. </p>
  20. <h3 align="center">A local video studio for your coding agent.<br>Describe a video. Your agent directs. Your machine renders.</h3>
  21. <p align="center">
  22. Motion graphics, voice-over, music, sound design, captions, footage editing and platform exports,
  23. with no cloud AI services, no API keys and no uploads. Works in Claude Code, Codex, Cursor, Devin,
  24. OpenCode and any agent that supports <a href="https://agentskills.io">Agent Skills</a>.
  25. </p>
  26. <p align="center">
  27. <a href="#quick-start"><b>Quick start</b></a> ·
  28. <a href="#x-ray"><b>X-ray</b></a> ·
  29. <a href="#works-with"><b>Works with</b></a> ·
  30. <a href="#now-showing"><b>Gallery</b></a> ·
  31. <a href="#how-it-works"><b>How it works</b></a> ·
  32. <a href="#meet-the-crew"><b>The crew</b></a> ·
  33. <a href="#studio-mode"><b>Studio</b></a> ·
  34. <a href="#what-you-get"><b>Formats</b></a> ·
  35. <a href="docs/README.md"><b>Docs</b></a> ·
  36. <a href="https://faviovazquez.github.io/showtime/"><b>Site</b></a> ·
  37. <a href="#requirements"><b>Requirements</b></a>
  38. </p>
  39. <picture>
  40. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/divider-dark.svg">
  41. <img alt="" src="assets/readme/divider-light.svg" width="100%">
  42. </picture>
  43. ## Quick start
  44. New here? [Make your first video](docs/guides/first-video.md): a 5-second test that checks the install and shows
  45. every step a bigger video goes through.
  46. **1. Install the two prerequisites** (details in [Requirements](#requirements)):
  47. [uv](https://docs.astral.sh/uv/) and [Node.js](https://nodejs.org) 24 or 22 LTS (20 or newer works).
  48. Restart your coding agent afterwards so it sees them.
  49. **2. Add showtime to your agent.** In Claude Code:
  50. ```text
  51. /plugin marketplace add FavioVazquez/showtime
  52. /plugin install showtime@showtime
  53. ```
  54. Using Codex, Cursor, Devin, OpenCode or another agent? [Works with](#works-with) has the exact
  55. install for each, and `npx skills add FavioVazquez/showtime` covers any agent that supports Agent Skills.
  56. **3. Ask for a video:**
  57. ```text
  58. Make a 20-second launch video for this repo, with a voice-over and upbeat music.
  59. ```
  60. The first time, your agent checks what is missing, tells you the download size and time (about
  61. 0.5 to 0.75 GB to download and 1.4 to 1.8 GB in `~/.showtime` once installed, depending on your system,
  62. usually 2 to 6 minutes; outside that folder only uv's and npm's download caches change) and runs setup once
  63. you say yes. If your agent's sandbox blocks the download, run setup once in a terminal
  64. ([Troubleshooting](docs/troubleshooting.md#setup-never-ran-or-the-sandbox-blocked-it)). Bigger pieces (the
  65. transcription model, Manim, music tracks) come the first time a video needs them, announced with their size. After
  66. that, a request in Claude Code looks like this:
  67. <p align="center">
  68. <picture>
  69. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/terminal-dark.svg">
  70. <source media="(prefers-color-scheme: light)" srcset="assets/readme/terminal-light.svg">
  71. <img alt="A Claude Code session: the request is typed, Claude states its assumptions (quick mode, 20 s, 16:9, English voice, upbeat bed, only claims the README makes), shows a first look, renders on this machine, and showtime prints its completion card: final.mp4 is ready, 20.0 s, 1920x1080, 17.0 MB, qa PASS, the output path and the next step." src="assets/readme/terminal-light.svg" width="100%">
  72. </picture>
  73. <br><sub>An illustration of a session in Claude Code; other agents show the same steps in their own style. The card's figures are example 01's; render time depends on your machine.</sub>
  74. </p>
  75. Your agent states its assumptions in one line (it asks only when a request is genuinely open), shows you a
  76. first look (stills or a fast draft) before the full-quality render, then checks the result with
  77. `showtime qa`. Every request gets its own folder, `showtime-out/<name>-<timestamp>/`, with `final.mp4`,
  78. `poster.jpg`, `share.txt`, `exports/` and `work/`. Nothing is ever overwritten. Questions about cost, GPUs, disk,
  79. languages or what leaves your machine: the [FAQ](docs/faq.md). Something went wrong:
  80. [Troubleshooting](docs/troubleshooting.md). A word you don't know: the [glossary](docs/glossary.md).
  81. > [!TIP]
  82. > Two separate settings. **Quick or studio** decides how much your agent asks before building: quick (the
  83. > default) states its assumptions and starts; studio (say **"show me options first"**) shows a concept, a look, a
  84. > music bed and a storyboard on a local board first. **Quality or lean** decides how much it checks afterwards:
  85. > quality (the default) has a critic review every finished video; lean skips the critic unless the video is going
  86. > to be published. Say **"no crew"** to keep the whole job in one session.
  87. **What's new in 0.4.6** (the list is [below](#new-in-046), and [What's new](docs/whats-new.md) has a short
  88. paragraph for each):
  89. - **`check` reads the text a page draws on its own canvas.** Text outside the phone's safe box, text too small to read
  90. and text over other text are found between its samples and on any canvas, not only the film API's.
  91. - **X-ray on a phone and in sync.** At 9:16 the sound strip and the part labels sit where a phone shows them, a new
  92. 16:9 project passes its own check, and with `"xray".offset_frames` the strip and the piano, drums and guitar follow
  93. the recording's clock.
  94. - **Fixes.** `export html --interactive` packs a page's own fonts, `xray verify` reads the marker on a draft render,
  95. installed files match the repository byte for byte, and `setup --home` brings its own ffmpeg.
  96. **What's new in 0.4.5** (the list is [below](#new-in-045), and [What's new](docs/whats-new.md) has a short
  97. paragraph for each):
  98. - **X-ray from data and from a recording.** `showtime xray import` turns event times measured in a data stream into a
  99. film; `xray analyze` takes a WAV with no picture.
  100. - **A live page that says what it knows.** How the events were measured, your own steps, and what sharing the page
  101. shares.
  102. - **A shorter skill router.** Six families instead of one row per feature, with a routing eval for contributors.
  103. - **Safer and smoother.** `footage trim -o` writes the file you name, the embed takes only safe addresses, and living
  104. diagrams type properly on a phone.
  105. **What's new in 0.4.4** (the list is [below](#new-in-044), and [What's new](docs/whats-new.md) has a short
  106. paragraph for each):
  107. - **X-ray.** Film a real thing doing its thing and showtime draws its inside on the frames its own sound says; a score,
  108. a guitar tab or a drum sheet from the sound; a receipt that reads the finished film back.
  109. - **A live page you play.** Pads that play the real clip with its sound, your keyboard typing on the typewriter, drag to
  110. scrub, `#hit4` links, the request that made it, and an embed.
  111. - **Living diagrams you touch.** Type on a typewriter, follow a key press to the screen, drag the heat pump's weather.
  112. **What's new in 0.4.3** (the list is [below](#new-in-043), and [What's new](docs/whats-new.md) has a short
  113. paragraph for each):
  114. - **Living diagrams.** `showtime new diagram` explains a system over time as an isometric figure that builds
  115. itself: parts arrive in the order that explains them, and flows, packets and labels move through them.
  116. - **Live figures.** `showtime export html <project> --interactive` turns the same scene into one offline page
  117. people poke: hover a part, pick a step, turn a knob, and the numbers answer
  118. ([try one](https://github.com/FavioVazquez/showtime-examples/blob/main/examples/_diagram/README.md)).
  119. - **A recap of your agent's session.** `showtime recap --latest` turns a Claude Code session into a 30-60 s
  120. narrated film of what the agent did, built only from allow-listed facts, never the transcript's text.
  121. - **A failing test as a bug-report video.** `showtime repro` turns a Playwright trace into a narrated film of the
  122. steps and the failure, with a Markdown summary for the issue; typed values are never shown.
  123. - **Steadier renders, quieter cuts.** Every render worker now captures from a page set up like the first one; recap
  124. and repro pick their music per session or test, and generated videos no longer put a sound on every cut.
  125. On the [behaviour scoreboard](#behaviour-scoreboard), 14 one-sentence requests were run 3 times each (42 runs). The
  126. same model did the right thing 35 times with showtime and 25 times without. The cases check that it starts on
  127. video requests and stays out of others, that it is honest about missing inputs and unsupported claims, and that it
  128. keeps to the plan and the delivery card. Anyone can rerun it.
  129. <picture>
  130. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/divider-dark.svg">
  131. <img alt="" src="assets/readme/divider-light.svg" width="100%">
  132. </picture>
  133. ## X-ray
  134. Film a real thing doing its thing, a typewriter typing or a music box playing, and showtime draws its inside moving
  135. on the exact frames the clip's own sound says: on the object as the camera moves, or beside it, as a dark radiograph
  136. or a light blueprint. Instruments get their music written out from the sound too (a score, a guitar tab, a drum
  137. sheet), and every film ends with a receipt that proves it.
  138. <p align="center"><a href="https://faviovazquez.github.io/showtime/xray/"><img alt="A typewriter filmed on a desk, its typebars, ribbon and escapement drawn in glowing lines on the machine itself as it types, with the receipt: 19 of 19 events on their frame, audio 0.0 ms from the original." src="assets/readme/xray/xray-hero.jpg" width="100%"></a></p>
  139. <p align="center"><sub>An Underwood 315 typing, seen through. Clip: Erik Pålsson / Sounds of Changes, <a href="https://creativecommons.org/licenses/by/3.0/">CC BY 3.0</a>.</sub></p>
  140. Say "X-ray this clip of my typewriter" to your agent, or run the three steps yourself:
  141. ```text
  142. showtime xray analyze clip.mp4 --job xray-typewriter # every event in the sound, with its frame
  143. showtime new xray xray-typewriter/project --mechanism typewriter --theme dark
  144. showtime xray verify xray-typewriter # after the render: reads the film back
  145. ```
  146. ```text
  147. 19 of 19 events on their frame · audio 0.0 ms from the original
  148. ```
  149. The mechanisms come from a library that grows with every verified X-ray, and anyone can add one. The
  150. **[X-ray gallery](https://faviovazquez.github.io/showtime/xray/)** plays every verified film with its receipt and the
  151. commands that made it, and shows how to post yours; the [X-ray guide](docs/guides/xray.md) walks through filming,
  152. mechanisms, music and drums, and what the receipt checks.
  153. <picture>
  154. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/divider-dark.svg">
  155. <img alt="" src="assets/readme/divider-light.svg" width="100%">
  156. </picture>
  157. ## Works with
  158. showtime is a skill, a command line and an MCP server, so it runs in any coding agent that reads
  159. [Agent Skills](https://agentskills.io) and can run shell commands. MCP adds typed tools on top, and
  160. the ten [crew](#meet-the-crew) agents are an optional speed-up for hosts that have custom sub-agents.
  161. **Tested with.** A real run passed: the agent installed showtime from this repository and made a
  162. 5-second test video ("make a 5-second test video that says hello", empty folder), ending in a `final.mp4`
  163. whose `showtime qa` verdict had no FAIL.
  164. | Agent | Install route | Crew agents | Tested with |
  165. |---|---|---|---|
  166. | [Claude Code](#claude-code) | plugin | yes | the primary host |
  167. | [OpenAI Codex](#other-agents) | plugin | with `showtime install` | CLI 0.158.0, plugin route |
  168. | [Cursor](#other-agents) | plugin (reads `.claude-plugin/`) | yes | CLI 2026.09.28 |
  169. | [Devin](#other-agents) | plugin (reads `.claude-plugin/`) | yes (local only) | CLI 3000.11.3 |
  170. | [OpenCode](#other-agents) | `showtime install` | yes | 1.18.33, a free model |
  171. **Should work with** any agent that supports [Agent Skills](https://agentskills.io): GitHub Copilot
  172. (CLI and VS Code), Gemini CLI, Antigravity, Cline, Kilo Code, Kiro, Zed, Goose, Amp, Factory Droid and Qwen
  173. Code. The files each one reads are packaged and were checked with the agent's own tools where possible, but
  174. no real video has been made in them yet. If you try one, an [issue](https://github.com/FavioVazquez/showtime/issues)
  175. with what happened helps everyone. Exact steps for every agent, and what the tests covered:
  176. [docs/agents.md](docs/agents.md).
  177. ### Claude Code
  178. ```text
  179. /plugin marketplace add FavioVazquez/showtime
  180. /plugin install showtime@showtime
  181. ```
  182. Everything is included: the skill, the ten crew agents, the MCP server and the plugin settings (`/config`).
  183. ### Any agent that supports Agent Skills
  184. ```bash
  185. npx skills add FavioVazquez/showtime
  186. ```
  187. This installs the skill for the agents you pick. Then run setup once from the installed skill folder
  188. (`<skills folder>/showtime/bin/showtime setup`), and add the MCP server if you want it ([below](#mcp-only)).
  189. ### Other agents
  190. Agents often run in a sandbox that blocks a large download, so run setup yourself once, in a normal terminal
  191. (it prints the size first and resumes if interrupted):
  192. ```bash
  193. git clone --depth 1 https://github.com/FavioVazquez/showtime ~/showtime
  194. ~/showtime/skills/showtime/bin/showtime setup # Windows: ~\showtime\skills\showtime\bin\showtime.cmd setup
  195. ~/showtime/skills/showtime/bin/showtime doctor # every line PASS (SKIP is fine)
  196. ```
  197. Setup also writes the stable command `~/.showtime/bin/showtime` (Windows: `showtime.cmd`), which keeps working
  198. when a plugin update moves the skill folder. In the commands below, `showtime` means that command.
  199. `showtime install --agent <name>` links the skill where the agent looks, writes the ten crew agents in the
  200. agent's own format and adds a `showtime` MCP server entry; it merges config files (one backup, never a
  201. replacement), and `--print`, `--project` and `--uninstall` are there too.
  202. <details>
  203. <summary><b>OpenAI Codex</b> · tested</summary>
  204. ```bash
  205. codex plugin marketplace add FavioVazquez/showtime
  206. codex plugin add showtime@showtime
  207. showtime install --agent codex --no-skill --no-mcp # optional: the ten crew agents (~/.codex/agents)
  208. ```
  209. Codex reads the root `plugin.json` and `mcp.json`; the skill appears as `showtime:showtime`. In its default
  210. sandbox, allow network access and write access to `~/.showtime` (the exact `config.toml` lines are in
  211. [docs/agents.md](docs/agents.md#openai-codex)). Headless: `codex exec --skip-git-repo-check "make a 5-second test video that says hello"`.
  212. </details>
  213. <details>
  214. <summary><b>Cursor</b> · tested</summary>
  215. ```bash
  216. git clone --depth 1 https://github.com/FavioVazquez/showtime ~/.cursor/plugins/local/showtime # then restart Cursor
  217. agent --plugin-dir ~/.cursor/plugins/local/showtime # the CLI
  218. ```
  219. Cursor reads `.claude-plugin/plugin.json`: the skill, the crew and the MCP server all load. Without the
  220. plugin: `showtime install --agent cursor`.
  221. </details>
  222. <details>
  223. <summary><b>Devin</b> · tested</summary>
  224. ```bash
  225. devin plugins install FavioVazquez/showtime # add --local to keep it off your Devin Cloud plugins
  226. devin plugins info showtime # skill, 10 agents, MCP server "showtime"
  227. ```
  228. Devin reads `.claude-plugin/`. The crew works in the CLI and Devin Desktop, not in Devin Cloud.
  229. </details>
  230. <details>
  231. <summary><b>OpenCode</b> · tested</summary>
  232. ```bash
  233. showtime install --agent opencode
  234. ```
  235. The skill goes to `~/.agents/skills/showtime`, the crew to `~/.config/opencode/agents` and the MCP server to
  236. `~/.config/opencode/opencode.json`. Check with `opencode agent list` and `opencode mcp list`.
  237. </details>
  238. <details>
  239. <summary><b>GitHub Copilot</b> (CLI and VS Code) · should work</summary>
  240. ```bash
  241. copilot plugin marketplace add FavioVazquez/showtime
  242. copilot plugin install showtime@showtime
  243. ```
  244. VS Code: run **Chat: Install Plugin From Source** with `https://github.com/FavioVazquez/showtime`. Without the
  245. plugin: `showtime install --agent copilot`.
  246. </details>
  247. <details>
  248. <summary><b>Gemini CLI</b> · should work</summary>
  249. ```bash
  250. showtime install --agent gemini
  251. ```
  252. Adds the skill, the crew in Gemini's format and the MCP server. The repository is also a Gemini extension
  253. (`gemini extensions install https://github.com/FavioVazquez/showtime`), which brings the skill and the MCP
  254. server without the crew.
  255. </details>
  256. <details>
  257. <summary><b>Antigravity</b> · should work</summary>
  258. ```bash
  259. git clone --depth 1 https://github.com/FavioVazquez/showtime ~/showtime
  260. agy plugin install ~/showtime # skill, crew and MCP server
  261. ```
  262. Or, without the plugin: `showtime install --agent antigravity`.
  263. </details>
  264. <details>
  265. <summary><b>Cline, Kilo Code, Kiro, Zed, Goose, Amp, Qwen Code</b> · should work</summary>
  266. ```bash
  267. showtime install --agent cline # skill + MCP server (no crew: Cline's sub-agents cannot use MCP)
  268. showtime install --agent kilo # skill; add the MCP server in Kilo's settings with the command it prints
  269. showtime install --agent kiro # skill, crew and MCP server
  270. showtime install --agent zed # skill; it prints the context_servers entry to paste into settings.json
  271. showtime install --agent goose # skill; it prints the extension block for config.yaml
  272. showtime install --agent amp # or: amp mcp add showtime -- ~/.showtime/bin/showtime mcp
  273. showtime install --agent qwen # Qwen reads skills only from ~/.qwen/skills
  274. ```
  275. In the Cline VS Code extension, add the MCP server under **MCP Servers > Configure MCP Servers** (the command
  276. prints the entry), or let Cline follow [`llms-install.md`](llms-install.md).
  277. </details>
  278. <details>
  279. <summary><b>Factory Droid</b> · should work</summary>
  280. ```bash
  281. droid plugin marketplace add FavioVazquez/showtime
  282. droid plugin install showtime@showtime
  283. ```
  284. Factory translates the `.claude-plugin/` layout. Without the plugin: `showtime install --agent factory`.
  285. </details>
  286. <a id="mcp-only"></a>
  287. ### MCP only
  288. Any client that starts local (stdio) servers can use showtime's MCP server on its own, without the skill. After
  289. setup:
  290. ```json
  291. {
  292. "mcpServers": {
  293. "showtime": { "command": "/home/<you>/.showtime/bin/showtime", "args": ["mcp"] }
  294. }
  295. }
  296. ```
  297. (Use the full path to that file in your home folder; on Windows it is `showtime.cmd` in `%USERPROFILE%\.showtime\bin`, written out in full.) Two more routes need no clone at all:
  298. ```json
  299. { "command": "npx", "args": ["-y", "@faviovazquez/showtime-mcp"] }
  300. ```
  301. is the same server from npm ([@faviovazquez/showtime-mcp](https://www.npmjs.com/package/@faviovazquez/showtime-mcp),
  302. also listed in the [MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.FavioVazquez/showtime)
  303. as `io.github.FavioVazquez/showtime` and on [Smithery](https://smithery.ai/servers/favio-vazquezp/showtime)), and
  304. [`showtime-0.4.6.mcpb`](https://github.com/FavioVazquez/showtime/releases/download/v0.4.6/showtime-0.4.6.mcpb) from
  305. the v0.4.6 release opens in Claude Desktop with a double click. Setup still runs once on your machine: the
  306. models and tools never travel inside a package. Long tools answer with a task id after about 20 seconds when a
  307. client stops calls early; the `status` tool reports progress and the result. Besides the tools that mirror the commands,
  308. `guide` reads a reference by the piece and `receipt` writes a job's receipt (tokens and cost are "not reported by this
  309. agent" through MCP). Ten core tools are listed by default (`doctor`, `status`, `guide`, `new_project`, `render`,
  310. `check`, `qa`, `export_html`, `deliver_exports`, `receipt`), which keeps the list short. Add
  311. `"env": { "SHOWTIME_MCP_TOOLS": "all" }` to the server entry to list the voice, music, sound-effect, transcription,
  312. stills and studio-board tools too; the `.mcpb` sets it for you. Some features have no MCP tool yet and run from the
  313. command line: `adopt`, `footage cutout`, `edit cards`, `edit moments`, `edit clips`, `pr-video`, `review open` and
  314. `review notes`, and `export html`'s link-preview flags (showtime.json `"share"` works through `export_html`).
  315. <picture>
  316. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/divider-dark.svg">
  317. <img alt="" src="assets/readme/divider-light.svg" width="100%">
  318. </picture>
  319. <a id="now-showing"></a>
  320. <p align="center">
  321. <picture>
  322. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/marquee-dark.svg">
  323. <source media="(prefers-color-scheme: light)" srcset="assets/readme/marquee-light.svg">
  324. <img alt="Now showing: 35 videos, every frame rendered by showtime." src="assets/readme/marquee-light.svg" width="100%">
  325. </picture>
  326. </p>
  327. ## Now showing
  328. <p align="center"><a href="https://faviovazquez.github.io/showtime/gallery.html"><img alt="The 0.2.0 launch film: the camera flies through the o of &quot;road&quot;, with the Iceland example seen through it." src="assets/readme/launch/launch-film-poster.jpg" width="100%"></a></p>
  329. <p align="center"><sub>▶ <a href="https://github.com/FavioVazquez/showtime-examples/releases/download/examples-media-v1/_launch--launch-16x9.mp4"><b>Watch the 0.2.0 launch film</b></a> (40 s, MP4; made with showtime, every frame from a real example, <a href="https://github.com/FavioVazquez/showtime-examples/blob/main/examples/_launch/README.md">about the film</a>). Every example plays in the <a href="https://faviovazquez.github.io/showtime/gallery.html">gallery on the showtime site</a>.</sub><br><sub>Music: “With These Hands” by Scott Buckley, <a href="https://creativecommons.org/licenses/by/4.0/">CC BY 4.0</a> (<a href="https://github.com/FavioVazquez/showtime-examples/blob/main/examples/_launch/credits.txt">credits</a>).</sub></p>
  330. Every example was made by an agent acting as a user, and ships with its project sources and a README
  331. that tells the story: the request, the assumptions, the commands, what the critic found and what
  332. changed. Click a preview to open the example. Each one has a card with its prompt and links in
  333. [`examples/`](https://github.com/FavioVazquez/showtime-examples/blob/main/examples/README.md). Previews are silent; the videos have sound.
  334. #### Data and reports
  335. <table>
  336. <tr>
  337. <td width="33%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/07-data-story"><img src="assets/readme/gallery/07-data-story.webp" width="260" alt="Warming stripes turn into a bar chart of global temperature since 1880."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/07-data-story">Data story</a></b> · 30 s<br><sub>146 years of NASA temperature from a CSV. Every number on screen comes from the data.</sub></td>
  338. <td width="33%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/12-energy-report"><img src="assets/readme/gallery/12-energy-report.webp" width="260" alt="A ranked bar chart of US electricity sources moving through the years."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/12-energy-report">Energy report</a></b> · 60 s, narrated<br><sub>How the US power mix changed, from EIA data. Also an <a href="https://github.com/FavioVazquez/showtime-examples/blob/main/examples/12-energy-report/us-power-mix.html">HTML video</a>.</sub></td>
  339. <td width="33%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/14-usgs-kilauea-pdf"><img src="assets/readme/gallery/14-usgs-kilauea-pdf.webp" width="260" alt="Aerial footage of the Kilauea Fissure 8 lava fountain with a caption card."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/14-usgs-kilauea-pdf">PDF to summary</a></b> · 75 s, English + Spanish<br><sub>A two-page USGS PDF on Kīlauea 2018, with the agency's own footage, stabilized.</sub></td>
  340. </tr>
  341. </table>
  342. #### Explainers
  343. <table>
  344. <tr>
  345. <td width="50%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/02-explainer-heat-pump"><img src="assets/readme/gallery/02-explainer-heat-pump.webp" width="400" alt="An animated refrigerant cycle: evaporator, compressor, condenser and expansion valve."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/02-explainer-heat-pump">How a heat pump heats a home</a></b> · 45 s<br><sub>A procedural canvas film, narration fitted to the length, a synthesized score. Also an <a href="https://github.com/FavioVazquez/showtime-examples/blob/main/examples/02-explainer-heat-pump/heat-pump.html">HTML video</a>.</sub></td>
  346. <td width="50%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/03-explainer-heat-pump-es"><img src="assets/readme/gallery/03-explainer-heat-pump-es.webp" width="400" alt="The same heat pump film with Spanish labels: condensador, gas caliente."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/03-explainer-heat-pump-es">The same film, in Spanish</a></b> · 51 s<br><sub>Spanish voice and on-screen text, every cut moved to the new narration. Also an <a href="https://github.com/FavioVazquez/showtime-examples/blob/main/examples/03-explainer-heat-pump-es/bomba-de-calor.html">HTML video</a>.</sub></td>
  347. </tr>
  348. <tr>
  349. <td width="50%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/13-wikipedia-waggle-dance"><img src="assets/readme/gallery/13-wikipedia-waggle-dance.webp" width="400" alt="A diagram of the waggle dance: the angle to the sun outside becomes the angle to vertical on the comb."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/13-wikipedia-waggle-dance">A Wikipedia article, explained</a></b> · 60 s, English + French<br><sub>The honey bee waggle dance, with real research footage. Also as HTML videos. (CC BY-SA, like its source.)</sub></td>
  350. <td width="50%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/22-manim-circle-area"><img src="assets/readme/gallery/22-manim-circle-area.webp" width="400" alt="A circle made of rings unrolls into a triangle, a Manim animation."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/22-manim-circle-area">Why a circle's area is πr²</a></b> · 70 s + Shorts cut<br><sub>A narrated Manim proof with real animated equations.</sub></td>
  351. </tr>
  352. <tr>
  353. <td width="50%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/25-nobel-physics-ice-telescope"><img src="assets/readme/gallery/25-nobel-physics-ice-telescope.webp" width="400" alt="A pause-and-think card: what are the odds a neutrino hits anything in a kilometre of ice? Three choices and a countdown."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/25-nobel-physics-ice-telescope">An explainer that stops and asks</a></b> · 2:38, narrated<br><sub>The 2026 Nobel Prize in Physics: three questions that stop the <a href="https://github.com/FavioVazquez/showtime-examples/blob/main/examples/25-nobel-physics-ice-telescope/interactive/index.html">HTML video</a> until you answer.</sub></td>
  354. <td width="50%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/26-nobel-chemistry-en-es"><img src="assets/readme/gallery/26-nobel-chemistry-en-es.webp" width="400" alt="A flask of orange and teal dots tips toward orange under a catalyst stamp: 48 to 22, tipped."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/26-nobel-chemistry-en-es">Nobel Chemistry, in English and Spanish</a></b> · 2:30 + 2:34<br><sub>A lab-notebook explainer of the 2026 Nobel Prize in Chemistry, then every word of it in Spanish.</sub></td>
  355. </tr>
  356. </table>
  357. #### Product and brand
  358. <table>
  359. <tr>
  360. <td width="50%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/01-launch-tidepool"><img src="assets/readme/gallery/01-launch-tidepool.webp" width="400" alt="Hook cards: No account. No server. No loading spinner."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/01-launch-tidepool">Launch video</a></b> · 20 s<br><sub>A (fictional) notes app: hook cards, its landing page, a scripted recording of the real app.</sub></td>
  361. <td width="50%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/10-launch-showtime"><img src="assets/readme/gallery/10-launch-showtime.webp" width="400" alt="A grid of example videos playing side by side."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/10-launch-showtime">showtime's own launch video</a></b> · 30 s + square cut<br><sub>Real renders, real terminal output, narration made on the rendering machine.</sub></td>
  362. </tr>
  363. <tr>
  364. <td width="50%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/17-product-promo-teapot"><img src="assets/readme/gallery/17-product-promo-teapot.webp" width="400" alt="A silver teapot on black with rising steam."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/17-product-promo-teapot">Product promo, 1:1</a></b> · 20 s + 6 s bumper<br><sub>A museum's CC0 photos of a Christopher Dresser teapot, only facts from the record. Also an <a href="https://github.com/FavioVazquez/showtime-examples/blob/main/examples/17-product-promo-teapot/dresser-teapot.html">HTML video</a>.</sub></td>
  365. <td width="50%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/20-curtain-call-pack"><img src="assets/readme/gallery/20-curtain-call-pack.webp" width="400" alt="Red velvet curtains part on a spotlit stage: the showtime logo sting."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/20-curtain-call-pack">Brand motion pack</a></b> · sting, lower thirds, stingers<br><sub>A 3D logo sting in three layouts, lower thirds with alpha for an editor, made in studio mode. Also as <a href="https://github.com/FavioVazquez/showtime-examples/blob/main/examples/20-curtain-call-pack/html/curtain-call-sting-player.html">HTML</a>.</sub></td>
  366. </tr>
  367. <tr>
  368. <td width="50%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/28-claude-design-to-mp4"><img src="assets/readme/gallery/28-claude-design-to-mp4.webp" width="400" alt="An amber counter at 1,234 over four growing bars, a design adopted from Claude Design."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/28-claude-design-to-mp4">Claude Design to MP4</a></b> · 12 s + a 20 s loop<br><sub>Two exported designs adopted as they are, sharp at 1080p, each on a music bed that ends on a phrase.</sub></td>
  369. </tr>
  370. </table>
  371. #### Footage and audio
  372. <table>
  373. <tr>
  374. <td width="50%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/06-footage-edit-nasa"><img src="assets/readme/gallery/06-footage-edit-nasa.webp" width="400" alt="A vertical interview with an astronaut and bold word-by-word captions."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/06-footage-edit-nasa">Interview, tightened</a></b> · 72 s, 9:16 + 16:9<br><sub>A public-domain NASA interview cut by transcript, face-tracked to vertical, graded and captioned.</sub></td>
  375. <td width="50%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/16-podcast-audiogram"><img src="assets/readme/gallery/16-podcast-audiogram.webp" width="400" alt="A vertical podcast audiogram with the speaker's name, a waveform and captions."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/16-podcast-audiogram">Podcast audiogram</a></b> · 45 s, 9:16<br><sub>A NASA podcast clip for Reels, TikTok and Shorts, with speaker names and captions.</sub></td>
  376. </tr>
  377. <tr>
  378. <td width="50%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/23-talking-head-cards-nasa"><img src="assets/readme/gallery/23-talking-head-cards-nasa.webp" width="400" alt="A NASA scientist on the right, a side panel on the left: From 22,000 miles up, Half of Earth in one view."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/23-talking-head-cards-nasa">Talking head, dressed</a></b> · 55 s, 16:9 + 9:16<br><sub>Cards that appear as the words are said: name tag, list, data callout, side panel, pull-quote, caption emphasis.</sub></td>
  379. <td width="50%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/24-highlights-apollo17-panel"><img src="assets/readme/gallery/24-highlights-apollo17-panel.webp" width="400" alt="A vertical clip of an Artemis flight controller, with bold captions: a spaceship."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/24-highlights-apollo17-panel">A long panel, its best moments</a></b> · 3 clips, 9:16<br><sub>A 58-minute NASA panel ranked by <code>edit moments</code>; three vertical clips with captions, each through qa.</sub></td>
  380. </tr>
  381. </table>
  382. #### Tutorials
  383. <table>
  384. <tr>
  385. <td width="33%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/04-tutorial-tidepool"><img src="assets/readme/gallery/04-tutorial-tidepool.webp" width="260" alt="A notes app with a search palette open and a step card: Find it with search."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/04-tutorial-tidepool">Recorded tutorial</a></b> · 50 s<br><sub>Recorded from a running app; each click lands on the word that names it.</sub></td>
  386. <td width="33%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/11-tutorial-series-tidepool"><img src="assets/readme/gallery/11-tutorial-series-tidepool.webp" width="260" alt="A drawn notes app with a Markdown checklist being typed."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/11-tutorial-series-tidepool">Tutorial series</a></b> · 2 × 90 s<br><sub>Two canvas episodes sharing one kit. Also as <a href="https://github.com/FavioVazquez/showtime-examples/blob/main/examples/11-tutorial-series-tidepool/episode-01/final.html">HTML videos</a>.</sub></td>
  387. <td width="33%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/21-tutorial-studio-board"><img src="assets/readme/gallery/21-tutorial-studio-board.webp" width="260" alt="The showtime studio board comparing two concepts side by side."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/21-tutorial-studio-board">Tutorial of a real app</a></b> · 75 s + Shorts cut<br><sub>How to use the showtime studio board, recorded from the real board.</sub></td>
  388. </tr>
  389. </table>
  390. #### Social
  391. <table>
  392. <tr>
  393. <td width="50%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/05-short-vertical"><img src="assets/readme/gallery/05-short-vertical.webp" width="400" alt="A vertical short with a keycap overlay and the caption: as you type."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/05-short-vertical">Vertical short</a></b> · 15 s, 9:16<br><sub>Three shortcuts: a hook in the first second, karaoke captions, effects on every cut.</sub></td>
  394. <td width="50%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/19-travel-slideshow-iceland"><img src="assets/readme/gallery/19-travel-slideshow-iceland.webp" width="400" alt="An Iceland waterfall with a small map of the ring road."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/19-travel-slideshow-iceland">Travel slideshow</a></b> · 45 s + 9:16<br><sub>Eight CC0 photos cut to the music, with a live map inset. The vertical is a re-layout, not a crop.</sub></td>
  395. </tr>
  396. </table>
  397. #### Trailers and montage
  398. <table>
  399. <tr>
  400. <td width="33%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/08-beat-montage"><img src="assets/readme/gallery/08-beat-montage.webp" width="260" alt="Space photos cut on the beat: the Eagle Nebula."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/08-beat-montage">Beat-synced montage</a></b> · 20 s<br><sub>Public-domain NASA photos cut on the beat of a library track; its CC-BY credit written automatically.</sub></td>
  401. <td width="33%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/09-studio-trailer"><img src="assets/readme/gallery/09-studio-trailer.webp" width="260" alt="A cinematic tilted close-up of a notes app interface."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/09-studio-trailer">Studio-mode trailer</a></b> · 20 s<br><sub>Four concepts on a local board, picks and notes, a storyboard and an animatic, then the final.</sub></td>
  402. <td width="33%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/18-book-trailer-war-of-the-worlds"><img src="assets/readme/gallery/18-book-trailer-war-of-the-worlds.webp" width="260" alt="An engraved illustration of a Martian from The War of the Worlds."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/18-book-trailer-war-of-the-worlds">Book trailer</a></b> · 30 s + 15 s vertical teaser<br><sub>The War of the Worlds, from public-domain illustrations and lines from the novel.</sub></td>
  403. </tr>
  404. </table>
  405. #### Looks and motion
  406. <table>
  407. <tr>
  408. <td width="50%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/30-showreel-four-shapes"><img src="assets/readme/gallery/30-showreel-four-shapes.webp" width="400" alt="The flash word TYPE. smeared by the shutter blur as it whips in, on a cyan ground."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/30-showreel-four-shapes">The showreel template in four shapes</a></b> · 4 × 15 s<br><sub><code>showtime new showreel</code> as it ships, rendered in four shapes with no edits.</sub></td>
  409. <td width="50%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/32-twelve-looks"><img src="assets/readme/gallery/32-twelve-looks.webp" width="400" alt="The same launch film in two look signatures: nocturne&#x27;s ink blue, then paperback&#x27;s warm paper, a label naming each."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/32-twelve-looks">Twelve looks, one project</a></b> · 24 s loop<br><sub>One <code>dom</code> project in all twelve look signatures, the look changing every 2 s.</sub></td>
  410. </tr>
  411. <tr>
  412. <td width="50%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/_looks"><img src="assets/readme/gallery/_looks.webp" width="400" alt="Metaballs gathering into one coral blob next to the word Metaballs."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/_looks">Seven looks, no GPU</a></b> · 18 s demo<br><sub>The seven WebGL looks, one scene each, drawn in showtime's own WebGL on the CPU.</sub></td>
  413. <td width="50%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/_blur"><img src="assets/readme/gallery/_blur.webp" width="400" alt="A card reading PUNCH. lands on a lime ground after a scale punch."></a><br><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/_blur">Shutter blur on fast moves</a></b> · 7.5 s demo<br><sub><code>data-st-blur</code> on the word that moves: smeared while it is fast, sharp when it lands.</sub></td>
  414. </tr>
  415. </table>
  416. #### For developers
  417. <table>
  418. <tr>
  419. <td width="50%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/15-oss-release-black"><img src="assets/readme/gallery/15-oss-release-black.webp" width="400" alt="A code diff: redundant parentheses on the left of an assignment are removed."></a></td>
  420. <td width="50%" valign="top"><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/15-oss-release-black">Open-source release video</a></b> · 35 s, no voice<br><sub>What changes in people's code with Black 26.1.0's 2026 stable style: real before-and-after diffs, the install line and the changelog. Point showtime at a repo, a pull request or a changelog and it makes the same kind of video. (An unofficial summary, made as an example.)</sub></td>
  421. </tr>
  422. <tr>
  423. <td width="50%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/29-pr-video-showtime"><img src="assets/readme/gallery/29-pr-video-showtime.webp" width="400" alt="68 files changed, +1138 -159: a file tree with green and red bars, from showtime&#x27;s pull request #7."></a></td>
  424. <td width="50%" valign="top"><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/29-pr-video-showtime">A pull request becomes a video</a></b> · 40 s, one command<br><sub><code>showtime pr-video 7</code> on showtime's own pull request: the PR's title and words, the files it changed with their +/- counts, a real hunk and its URL, secrets masked, a copy under GitHub's 10 MB attachment limit and the Markdown to paste.</sub></td>
  425. </tr>
  426. <tr>
  427. <td width="50%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/_recap"><img src="assets/readme/gallery/_recap.webp" width="400" alt="Red to green, from a Claude Code session: one red test run, then two green ones, and 12/12 test files passed."></a></td>
  428. <td width="50%" valign="top"><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/_recap">A recap of an agent's session</a></b> · 37 s, narrated<br><sub><code>showtime recap</code> on showtime's test session: 17 minutes of an agent fixing a parser test as the numbers, a minute-by-minute timeline, the edit, the tests red to green and the commit, built from allow-listed facts only.</sub></td>
  429. </tr>
  430. <tr>
  431. <td width="50%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/_repro"><img src="assets/readme/gallery/_repro.webp" width="400" alt="A failing Playwright step: the page says Welcome back, Ada; expected &quot;Welcome, Ada!&quot;, received &quot;Welcome back, Ada&quot;, and the console error."></a></td>
  432. <td width="50%" valign="top"><b><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/_repro">A failing test as a bug-report video</a></b> · 34 s, narrated<br><sub><code>showtime repro</code> on a Playwright trace: each step on the trace's screenshots, the failure slowed down with expected and received, the typed values covered, and <code>repro.md</code> for the issue.</sub></td>
  433. </tr>
  434. </table>
  435. Two more kinds of developer video have a workflow but no example in this gallery yet: a **repo explainer** (what the
  436. code does, a map of it, one request traced through real files and lines, every claim tied to a file and a commit) and
  437. a **paper explainer** (claims tied to pages, figures shown only when their license allows, Manim for the math). Say
  438. "explain this repo" or give your agent a paper's PDF or arXiv link. For a pull request, `showtime pr-video <N>` reads
  439. it (with gh, or from GitHub's API for a public one) and renders a video under 10 MB to drag into its description
  440. ([example 29](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/29-pr-video-showtime)). For release notes and pull requests with no agent at all,
  441. `showtime release-video` and the [GitHub Action](docs/github-action.md) make a short film in CI.
  442. <p align="center"><sub>All 22 examples, with their projects and full-quality videos, live in <a href="https://github.com/FavioVazquez/showtime-examples"><b>showtime-examples</b></a>.</sub></p>
  443. > [!NOTE]
  444. > The **HTML videos** are single files you can open in any browser, offline: the same frames as the
  445. > MP4, a player with chapters, keyboard shortcuts, links to a moment or to a part that loops, questions
  446. > that pause the video until the viewer answers, and no network requests. Make one from any project with
  447. > `showtime export html`. On GitHub, download the file to play it. A living diagram also exports as a live figure
  448. > (`--interactive`): no player, a board people hover, step through and tune, in one offline file.
  449. <details>
  450. <summary><b>The 35 prompts behind the examples</b>: copy one into your agent</summary>
  451. | # | Prompt |
  452. |---|---|
  453. | [01](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/01-launch-tidepool) | Make a 20-second launch video for Tidepool from its landing page and the real app UI, with music and subtle sound effects, no voice-over. |
  454. | [02](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/02-explainer-heat-pump) | Make a 45-second explainer video with voiceover about how a heat pump heats a home in winter. |
  455. | [03](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/03-explainer-heat-pump-es) | Now make the Spanish version of the heat pump explainer. |
  456. | [04](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/04-tutorial-tidepool) | Make a 40-60 second tutorial showing how to create a note, tag it and find it with search in Tidepool. |
  457. | [05](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/05-short-vertical) | Make a 15-second vertical short for Reels: 3 keyboard shortcuts that make Tidepool fast. |
  458. | [06](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/06-footage-edit-nasa) | Cut the ums and long pauses out of this interview clip, add captions, and make a vertical 9:16 version for Reels plus a 16:9 version. |
  459. | [07](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/07-data-story) | Make a 30-second data story from this CSV. |
  460. | [08](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/08-beat-montage) | Make a 20-second beat-synced montage of space photos. |
  461. | [09](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/09-studio-trailer) | Let's brainstorm a trailer for Tidepool first. Show me options. |
  462. | [10](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/10-launch-showtime) | Make a 30-second launch video for showtime itself. Show real things: real renders, real terminal commands, the studio board. Plus a square cut-down. |
  463. | [11](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/11-tutorial-series-tidepool) | Build a two-episode tutorial series for Tidepool as canvas films: "Capture a note in seconds" and "Find anything with search and tags". |
  464. | [12](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/12-energy-report) | Make a one-minute narrated video from the EIA's electricity generation data showing how the US power mix changed: coal, gas, wind and solar. |
  465. | [13](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/13-wikipedia-waggle-dance) | Turn the Wikipedia article on the waggle dance into a 60-second animated explainer, and make a French version too. |
  466. | [14](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/14-usgs-kilauea-pdf) | Here's a USGS PDF about the 2018 Kīlauea eruption. Make a 75-second narrated summary video, and a Spanish version with subtitles. |
  467. | [15](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/15-oss-release-black) | Make a 35-second what's-new video for Black 26.1.0: show what the 2026 stable style actually changes in people's code. |
  468. | [16](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/16-podcast-audiogram) | Cut a 40-second vertical audiogram from this NASA podcast episode for Reels, TikTok and Shorts, with captions and the speakers' names. |
  469. | [17](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/17-product-promo-teapot) | Make a 20-second square product promo from these museum photos of Christopher Dresser's teapot: sleek, but only facts from the museum record. Plus a 6-second bumper. |
  470. | [18](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/18-book-trailer-war-of-the-worlds) | Make a 30-second cinematic book trailer for The War of the Worlds using public-domain illustrations and lines from the novel, plus a vertical 15-second teaser. |
  471. | [19](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/19-travel-slideshow-iceland) | Make a 45-second travel slideshow of an Iceland ring-road trip from these CC0 photos, cut to the music, with a little map showing where each place is. Also a vertical version for Reels. |
  472. | [20](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/20-curtain-call-pack) | Using our brand, give me a motion pack: a 3D logo sting in wide, square and vertical, four lower thirds my editor can drop into Premiere, and a couple of branded transitions. Show me concepts first. |
  473. | [21](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/21-tutorial-studio-board) | Record a 75-second narrated tutorial showing how to use the showtime studio board: open it, compare concepts, react, pick one, and send feedback. And a vertical cut for Shorts. |
  474. | [22](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/22-manim-circle-area) | Make a narrated 70-second math explainer showing why the area of a circle is pi r squared, with real animated equations. |
  475. | [23](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/23-talking-head-cards-nasa) | Dress up this NASA interview with Sarah Jones about the GOLD mission: name tag, a data callout, a pull-quote, a list or chapter, a side panel and captions with emphasis; a 16:9 and a 9:16 cut. |
  476. | [24](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/24-highlights-apollo17-panel) | Find the best 30-60 s moments of this 58-minute NASA panel (Apollo 17 legends and Artemis leaders) and make three vertical clips with captions |
  477. | [25](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/25-nobel-physics-ice-telescope) | Physics 2026 explainer for nobel-2026-lab: a telescope made of ice, ~2 min, three stop-and-ask questions, interactive export, 60 s vertical cut; publish today |
  478. | [26](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/26-nobel-chemistry-en-es) | Full Chemistry 2026 explainer (~2:10, 16:9) for the nobel-2026-lab: Frank's recipe, Kagan's bend, Soai's copier, the 2003 staircase, the coin flip, our mirror-race toy, caveats, medicines. NOT socratic: no questions to the viewer. American voice (af_bella; not the British female). Paperback lab-notebook look, CC0 bed, showtime credited (corner mark, end card, closing line). Must look great; post soon. |
  479. | [28](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/28-claude-design-to-mp4) | Make 'Showtime Test (12s, 16 9)-html.zip' an MP4, with a music bed. |
  480. | [29](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/29-pr-video-showtime) | Turn showtime's pull request #7 into a short video I can paste into its description. |
  481. | [30](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/30-showreel-four-shapes) | Render the showreel template as it ships, with no edits, at 16:9, 9:16, 1:1 and 4:5. |
  482. | [32](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/32-twelve-looks) | Show one project in each of the twelve look signatures: a contact sheet of all twelve, and a 24-second loop that changes look every 2 seconds. |
  483. | [_looks](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/_looks) | Show the seven WebGL looks in one short page, one scene each, rendered without a GPU. |
  484. | [_blur](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/_blur) | Show the shutter blur on four snaps: a whip, a slam, a scale punch, and the same whip without and with it. |
  485. | [_diagram](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/_diagram) | Show what happens when you press Enter in a coding agent, as a diagram that builds itself, and a live version people can poke. |
  486. | [_recap](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/_recap) | Make a short video of what my agent did in this Claude Code session. |
  487. | [_repro](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/_repro) | Turn this failing Playwright test into a video I can attach to the bug report. |
  488. </details>
  489. <picture>
  490. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/divider-dark.svg">
  491. <img alt="" src="assets/readme/divider-light.svg" width="100%">
  492. </picture>
  493. ## How it works
  494. <p align="center"><picture>
  495. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/diagrams/pipeline-dark.svg">
  496. <img alt="How showtime works. One sentence in your coding agent; your agent directs (assumptions, script, scenes, mix); a first look, and your notes loop back; the render runs on your machine (frames, voice, music, encode); showtime qa checks loudness, frames, captions and platform specs; out come an MP4 and an HTML video with poster, exports, captions and credits." src="assets/readme/diagrams/pipeline-light.svg" width="100%">
  497. </picture></p>
  498. Motion graphics are written as HTML, CSS and canvas and rendered frame-exactly in headless Chrome: every
  499. frame is a pure function of time, so a render, its preview and its HTML video show the same picture.
  500. Math scenes use Manim, and real footage is cut by transcript with ffmpeg.
  501. ### What runs where
  502. <p align="center"><picture>
  503. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/diagrams/runs-where-dark.svg">
  504. <img alt="What runs where. In your coding agent, your agent is the director: it reads your request and sources, states assumptions, writes the script, picks templates, scenes and sound, shows a first look, briefs the crew and checks the result. On your machine, in ~/.showtime, is the studio: headless Chrome, ffmpeg, Kokoro, Piper and Supertonic voices, local transcripts, a composer with 18 styles and 56 effect types, 1,334 sounds and 297 music tracks, Manim, and showtime qa. The web only when you ask: archive search and site capture fetch pages; nothing of yours is sent. No cloud AI service, no API keys, no uploads." src="assets/readme/diagrams/runs-where-light.svg" width="100%">
  505. </picture></p>
  506. showtime adds no cloud service of its own: no API keys, no accounts, nothing you make is uploaded.
  507. Every model and tool is downloaded once into `~/.showtime`, the small ones at setup and the bigger ones the
  508. first time a video needs them. After that it goes online only when you ask for something from the web: public-archive media search (Openverse, Wikimedia Commons, NASA) and website
  509. capture fetch pages and files, and send nothing of yours.
  510. ### Quiet, checked and on the record
  511. Every job follows the same order: check the project, render once, then fix only the seconds that changed. Output
  512. stays short and images stay out of your agent's context, so a video costs fewer tokens without skipping a check.
  513. Here is how (most of it came in 0.3.0, after the 0.2.0 benchmark showed where an agent's budget went):
  514. - **Check first, then one render.** `showtime check` (with the phone check and the look-repeat warning) runs before
  515. the full render, and a fix re-renders only the seconds that changed (`render --from S --to S`).
  516. - **Faster fixes (0.4.1).** The encoder runs while the frames are captured and an unchanged soundtrack is reused: on a
  517. busy 6-core Intel Mac a 1 s fix spliced into a 15-30 s video went from 31-54 s to 13-21 s, and whole renders from
  518. 54-115 s to 56-81 s (best of 2, other jobs running).
  519. - **One picture per look.** `showtime look` makes a single 1280 px composite of the key frames plus a brief for a
  520. disposable reviewer that answers in text; your agent never has to open the image itself. About 12 images per job
  521. is the budget ([looking guide](skills/showtime/references/looking.md)).
  522. - **Short output.** Without a terminal, `check`, `qa`, `doctor` and `render` print the verdict, the findings with
  523. their fixes and the paths; the full report is in a file. `--verbose` prints everything.
  524. - **References by the piece.** Every guide opens with its rules, and `showtime guide <topic> [section]` prints just
  525. that part.
  526. - **A receipt.** Each job ends with `receipt.md` and `receipt.json`: the request as typed, assumptions, review rounds,
  527. full and partial renders, images made for looking, wall time, and tokens and cost when your agent's session log is
  528. named. Anything unknown says "not reported by this agent"; nothing is estimated. Claude Code costs are labelled
  529. API-equivalent, since a plan does not pay per video ([format](skills/showtime/references/receipt.md)).
  530. Every finished video gets the full review by default (quality mode: looks, qa and a critic round before delivery).
  531. Say "lean" (or run `showtime config mode lean`) for a cheaper draft pass without the critic, and "show me options
  532. first" for the full studio.
  533. ## Benchmark
  534. A small benchmark: one-sentence video tasks, one run each, scored by automatic checks, an AI judge that must prove it
  535. looked at every frame, and a blind vote by me. Round 4 compared showtime 0.3.0 **in lean mode** (the lighter review
  536. setting, which was the default when the round ran) with 0.2.0 in its default mode, plain Claude Code on Opus 5.5 and,
  537. for the launch video, an open-source tool built only for launch videos.
  538. In my blind vote, 0.3.0 was preferred to 0.2.0 on 4 of 6 tasks and to plain Claude Code on 7 of 8, and its launch
  539. video beat the launch-only tool for the first time in four rounds. The AI judge preferred 0.2.0's polish on most
  540. tasks; that is why 0.3.0 ships with the full review (a critic round on every video) as the default, and that default
  541. was not part of the round. I'm showtime's author, so treat these as anecdotes, not a result. Every number, limit and
  542. loss is in the [benchmark report](https://faviovazquez.github.io/showtime/benchmark/), with each earlier version a
  543. click away; the method and the code to rerun it are in [`benchmarks/`](benchmarks/).
  544. ### Behaviour scoreboard
  545. A cheaper check anyone can rerun with one command: 14 one-sentence requests run through `claude plugin eval`, each
  546. with showtime and with no plugin at all (same model). Does the skill fire on video requests and stay out of
  547. unrelated ones, does it report a missing file or an unsupported claim instead of inventing around it, and does it
  548. keep its contract? Regex and tool-call checks first, a model grader only where a pattern cannot decide; tokens and
  549. cost per run, and every failure in plain words, are in [SCOREBOARD.md](benchmarks/plugin-eval/SCOREBOARD.md).
  550. <!-- scoreboard:start -->
  551. | Behaviour | Cases | With showtime | Without (same model, no plugin) |
  552. |---|---|---|---|
  553. | Skill fires on a video request | 12 | 36/36 (100%) | - |
  554. | Stays out of unrelated requests | 2 | 6/6 (100%) | 6/6 (100%) |
  555. | Honest about inputs and limits | 7 | 18/21 (86%) | 10/21 (48%) |
  556. | Keeps the contract (questions, card, plan shape) | 7 | 16/21 (76%) | 11/21 (52%) |
  557. | All cases | 14 | 35/42 (83%) | 25/42 (60%) |
  558. `claude plugin eval`, 2026-10-05, showtime 0.4.0, agent claude-opus-5-5, judge sonnet, 3 runs per case per arm; median tokens per run 65.3k with showtime, 34.7k without; the whole run cost $36.00 at list price. Every case, every failure and how to rerun it: [SCOREBOARD.md](benchmarks/plugin-eval/SCOREBOARD.md).
  559. <!-- scoreboard:end -->
  560. <picture>
  561. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/divider-dark.svg">
  562. <img alt="" src="assets/readme/divider-light.svg" width="100%">
  563. </picture>
  564. ## Meet the crew
  565. Your agent is the director. It can hand parts of the job to **ten specialist sub-agents** that ship with
  566. the plugin. Every finished video gets a critic by default (quality mode); say "lean" to skip it (a video you
  567. will publish still gets one). A researcher joins when the video states facts or you will publish it, a sound designer when you will
  568. publish it and it has music or effects, and scene builders when it is long. The rest come with studio mode, or when you say **"full crew"**. Each member gets a written brief, works only in its own folder, never asks you anything,
  569. never uploads, and reports back with a short status.
  570. <p align="center"><a href="https://faviovazquez.github.io/showtime/crew.html#film"><img alt="The crew film: the critic's catch in example 13, the old caption struck through with a BLOCKER note." src="assets/readme/crew/crew-film-poster.jpg" width="100%"></a></p>
  571. <p align="center"><sub>▶ <a href="https://faviovazquez.github.io/showtime/crew.html#film"><b>Watch the crew at work</b></a> (45 s, plays on the showtime site; made with showtime, <a href="https://github.com/FavioVazquez/showtime-examples/blob/main/examples/_crew/README.md">about the film</a>, <a href="https://github.com/FavioVazquez/showtime-examples/releases/download/examples-media-v1/_crew--crew-16x9.mp4">download</a>).</sub><br><sub>Music: “Artemis” by Scott Buckley, <a href="https://creativecommons.org/licenses/by/4.0/">CC BY 4.0</a>. Bee footage: Su et al. 2008, CC BY 3.0 (<a href="https://github.com/FavioVazquez/showtime-examples/blob/main/examples/_crew/credits.txt">credits</a>).</sub></p>
  572. <p align="center"><picture>
  573. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/crew/cast-dark.svg">
  574. <img alt="The crew as a cast of ten illustrated cards, all optional: creative director (pitches three concepts and a wildcard, then signs off the storyboard); brand designer (pulls a brand kit from your repo or site, or proposes one); scriptwriter (every word, each fact tied to a source); storyboard artist (turns the concept into shots, timings and an animatic); motion designer (one scene in its own sandbox, several in parallel); sound designer (bed, effects, sound logo, a metered mix); voice director (picks the voice, fixes pronunciation, adds languages); editor (cuts real footage by transcript); researcher (checks every claim and every asset's license); critic (watches the draft like a stranger)." src="assets/readme/crew/cast-light.svg" width="100%">
  575. </picture></p>
  576. ### Who hands what to whom
  577. <p align="center"><picture>
  578. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/diagrams/crew-handoff-dark.svg">
  579. <img alt="How the crew hands work around. The director, your agent in your session, writes a TASK.md brief for each member and merges each RESULT.md. I, pitch, in parallel: creative director (concepts and a wildcard), scriptwriter (facts, claims, hooks), brand designer (a brand kit); you pick a concept. II, plan: scriptwriter (the script), storyboard artist (storyboard and animatic), researcher (checks every claim), creative director (signs off); you sign off. III, build, in parallel: motion designers (one per scene), sound designer (bed, effects, mix), voice director (the voice-over). IV, review: the critic writes findings with frames; fixes go back to the same member. V, deliver: showtime qa, then the MP4 and HTML video. Footage jobs: editor, sound designer, researcher, critic. Members never talk to each other or to you." src="assets/readme/diagrams/crew-handoff-light.svg" width="100%">
  580. </picture></p>
  581. **Let your agent cast it** (the usual way). Studio mode brings in the company; for a quick video, your agent
  582. adds the critic on its own, the researcher when the video states facts or you will publish it, and the sound
  583. designer when you will publish it and it has music or effects. Say
  584. **"full crew"** to get every member the job can use without the pitch step, or **"no crew"** to keep
  585. everything in one session. The words that set each mode:
  586. | You say | Mode | Crew |
  587. |---|---|---|
  588. | (nothing special) | quick, quality review | critic; researcher for facts or publish-bound; sound designer for publish-bound with music or effects; motion designers at 6+ scenes |
  589. | "lean", "quick draft", "don't review" | quick, lean | none; a critic only when publish-bound |
  590. | "full crew", "use the whole crew" | quick, full crew | every member the job can use, critic twice |
  591. | "studio", "show me concepts first", "storyboard it first" | studio | pitch, storyboard gate, full crew |
  592. | "no crew" | any | done inline |
  593. ```text
  594. Let's make a launch trailer for this repo. Show me options first.
  595. ```
  596. **Or call one member yourself**, by name (Claude Code syntax; in other agents, ask it to "spawn the researcher agent"):
  597. ```text
  598. @agent-showtime:researcher check the claims in narration.md against the README
  599. @agent-showtime:critic showtime-out/<job>/review/round-1/CRITIC.md
  600. ```
  601. The agents live in [`agents/`](agents/); their briefs, in
  602. [`skills/showtime/references/crew/`](skills/showtime/references/crew/), work on any agent host, and the
  603. [crew guide](skills/showtime/references/crew.md) has the dispatch rules.
  604. A fix is judged by preference, not by a score. After a fix, `showtime review-pack --against best`
  605. sets the new render beside the best one so far as a blind pair, and two fresh critics judge it, one in each order.
  606. `showtime review-verdict` applies the rule: the new render wins only when it is preferred both times; a tie or a split
  607. keeps the older one. There are up to three rounds. Before the job is marked delivered, every blocker and should-fix the
  608. critics raised is fixed or waived with a one-line reason (`showtime review-respond`), and the receipt lists each waiver
  609. ([review guide](skills/showtime/references/review.md)).
  610. <picture>
  611. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/divider-dark.svg">
  612. <img alt="" src="assets/readme/divider-light.svg" width="100%">
  613. </picture>
  614. ## Studio mode
  615. Quick mode is the default: one request in, a video out. Studio is opt-in ("show me options first").
  616. ```mermaid
  617. flowchart LR
  618. R["Your request"] --> Q{"Options first?"}
  619. Q -->|"no, the default"| QM["Quick mode"]
  620. Q -->|"yes, studio"| SM["Studio mode"]
  621. QM --> P{"Facts, or will you publish it?"}
  622. P -->|"yes"| RS["A researcher joins"]
  623. P -->|"no"| D["Checked by showtime qa"]
  624. RS --> D
  625. SM --> CR["The crew joins"]
  626. CR --> D
  627. D --> RC["A critic reviews it (say lean to skip)"]
  628. classDef st fill:#15100E,stroke:#E9B949,color:#F5EBDC
  629. classDef hot fill:#B3121F,stroke:#E9B949,color:#FFF7EC
  630. class R,Q,QM,SM,P,RS,CR,RC st
  631. class D hot
  632. ```
  633. Quick mode is one sentence in and a video out; studio mode opens a local board first, then builds.
  634. In studio you talk about facts and goals in chat; everything about look, sound and timing is shown on a
  635. board, a local page served on `127.0.0.1` with a token, with lettered options, one recommendation and
  636. buttons you click.
  637. <p align="center"><picture>
  638. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/diagrams/studio-dark.svg">
  639. <img alt="Studio mode, on a local board at 127.0.0.1 with a token. 1 concepts: three and a wildcard, with style frames. 2 look and sound, optional: three looks, three music beds, voices. 3 storyboard: every shot with time, picture, text and voice-over. 4 animatic: a draft with the bed, notes by timecode. 5 build and review: the final, checked with showtime qa. Picks and comments come back as data and are logged." src="assets/readme/diagrams/studio-light.svg" width="100%">
  640. </picture></p>
  641. See [example 09](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/09-studio-trailer) and [example 21](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/21-tutorial-studio-board), which is
  642. a tutorial of the board itself.
  643. <picture>
  644. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/divider-dark.svg">
  645. <img alt="" src="assets/readme/divider-light.svg" width="100%">
  646. </picture>
  647. ## What you get
  648. <p align="center"><picture>
  649. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/diagrams/formats-dark.svg">
  650. <img alt="Output formats. One request, every shape: 16:9 for YouTube, X and LinkedIn; 1:1 for square feeds; 9:16 for Reels, TikTok and Shorts, laid out again or face-tracked rather than just cropped. What a job can hand you: final.mp4 (H.264 and AAC, mastered to -14 LUFS), the HTML video, WebP and GIF loops, poster.jpg and thumbnails, SRT and VTT captions, WebM and ProRes with alpha, share.txt with post copy and credits.txt." src="assets/readme/diagrams/formats-light.svg" width="100%">
  651. </picture></p>
  652. ### HTML videos
  653. `showtime export html` writes one file that plays offline in any browser, with the same frames as the
  654. render. Press <kbd>?</kbd> in the player for the key map. A link can open a moment (`#t=18`) or loop a part
  655. (`#t=10-20`; <kbd>Shift</kbd> + drag on the scrubber picks one), and questions listed in showtime.json pause the
  656. video until the viewer answers ([guide](skills/showtime/references/html-export.md)).
  657. <p align="center"><picture>
  658. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/diagrams/html-anatomy-dark.svg">
  659. <img alt="Anatomy of an HTML video: the real player of example 02, heat-pump.html, paused at 0:18 with its chapter menu open (Hook, Heat in cold air, The loop, Evaporator, Compressor, Condenser, Expansion valve, Payoff, End card). 1 one file of about 1 MB with frames, audio and player inside. 2 deep links such as #t=18 or #chapter=4. 3 chapters on the scrubber, in a menu and on keys 1 to 9. 4 keyboard control. 5 zero network requests." src="assets/readme/diagrams/html-anatomy-light.svg" width="100%">
  660. </picture></p>
  661. <details>
  662. <summary><b>The player's keys</b></summary>
  663. | Keys | Action |
  664. |---|---|
  665. | <kbd>Space</kbd> or <kbd>K</kbd> | play / pause |
  666. | <kbd>←</kbd> / <kbd>→</kbd> | back / forward 1 s |
  667. | <kbd>,</kbd> / <kbd>.</kbd> | one frame back / forward |
  668. | <kbd>J</kbd> / <kbd>L</kbd> | back / forward 5 s |
  669. | <kbd>1</kbd> to <kbd>9</kbd> | jump to a chapter |
  670. | <kbd>[</kbd> / <kbd>]</kbd> | previous / next chapter |
  671. | <kbd>M</kbd> | mute |
  672. | <kbd>F</kbd> | fullscreen |
  673. | <kbd>C</kbd> | copy a link to this moment (`#t=`), or to the picked range (`#t=a-b`) |
  674. | <kbd>Shift</kbd> + drag on the scrubber | pick a range to loop and link (<kbd>Shift</kbd> + click: from the playhead); <kbd>Esc</kbd> clears it |
  675. | <kbd>A</kbd>-<kbd>C</kbd> or <kbd>1</kbd>-<kbd>3</kbd>, <kbd>Enter</kbd> | while a question is asked: answer it, then continue |
  676. </details>
  677. ## What is in the box
  678. <table>
  679. <tr>
  680. <td width="33%" valign="top"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/readme/icons/voice-dark.svg"><img src="assets/readme/icons/voice-light.svg" width="44" alt=""></picture><br><b>Voice-over</b><br><sub>Kokoro, Piper and Supertonic voices, English, Spanish and 30+ more languages, with exact word timings for captions and kinetic type.</sub></td>
  681. <td width="33%" valign="top"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/readme/icons/music-dark.svg"><img src="assets/readme/icons/music-light.svg" width="44" alt=""></picture><br><b>Music and sound</b><br><sub>297 produced tracks (Scott Buckley, Kevin MacLeod, a dozen more composers, public-domain recordings) with the credit written for you, a composer that hits exact lengths, 56 synthesized effect types, 1,334 permissively licensed sounds, beat grids, ducking, mastering.</sub></td>
  682. <td width="33%" valign="top"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/readme/icons/captions-dark.svg"><img src="assets/readme/icons/captions-light.svg" width="44" alt=""></picture><br><b>Captions</b><br><sub>Five styles, burned in or as SRT/VTT, placed inside each platform's safe zone; karaoke from the voice's word times.</sub></td>
  683. </tr>
  684. <tr>
  685. <td width="33%" valign="top"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/readme/icons/footage-dark.svg"><img src="assets/readme/icons/footage-light.svg" width="44" alt=""></picture><br><b>Footage editing</b><br><sub>Word-level local transcripts that keep the ums; cut fillers and pauses by editing text; speakers, scenes, face-tracked 9:16, stabilize, denoise, grade.</sub></td>
  686. <td width="33%" valign="top"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/readme/icons/manim-dark.svg"><img src="assets/readme/icons/manim-light.svg" width="44" alt=""></picture><br><b>Math with Manim</b><br><sub>Equations, proofs, graphs and grid transforms, timed to the narration, as an optional extra.</sub></td>
  687. <td width="33%" valign="top"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/readme/icons/studio-dark.svg"><img src="assets/readme/icons/studio-light.svg" width="44" alt=""></picture><br><b>Studio boards</b><br><sub>Concepts, style frames, music beds, a storyboard and an animatic on local pages you click through; picks are logged.</sub></td>
  688. </tr>
  689. <tr>
  690. <td width="33%" valign="top"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/readme/icons/crew-dark.svg"><img src="assets/readme/icons/crew-light.svg" width="44" alt=""></picture><br><b>A crew of ten</b><br><sub>Optional specialist sub-agents from creative director to critic; your agent stays the director and the only one who talks to you.</sub></td>
  691. <td width="33%" valign="top"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/readme/icons/html-dark.svg"><img src="assets/readme/icons/html-light.svg" width="44" alt=""></picture><br><b>HTML videos</b><br><sub>One self-contained file per video: chapters, keyboard control, links to a moment or a looping part, questions that wait for the viewer's answer, zero network requests.</sub></td>
  692. <td width="33%" valign="top"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/readme/icons/qa-dark.svg"><img src="assets/readme/icons/qa-light.svg" width="44" alt=""></picture><br><b>QA before done</b><br><sub>Pre-render checks and a phone check, then <code>showtime qa</code> on the final: loudness, black or frozen frames, captions, platform specs, and a hearing pass (a voice buried under the music, long quiet stretches, jumps in level at a cut, sound cut off at the end).</sub></td>
  693. </tr>
  694. <tr>
  695. <td width="33%" valign="top"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/readme/icons/studio-dark.svg"><img src="assets/readme/icons/studio-light.svg" width="44" alt=""></picture><br><b>Looks and motion blur</b><br><sub>Seven WebGL looks (fluted glass, tilt-shift, liquid metal, mesh gradient, god rays, marble, metaballs) and a shutter blur on fast moves, all rendered without a GPU (<a href="https://github.com/FavioVazquez/showtime-examples/blob/main/examples/_looks/README.md">demo</a>).</sub></td>
  696. <td width="33%" valign="top"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/readme/icons/captions-dark.svg"><img src="assets/readme/icons/captions-light.svg" width="44" alt=""></picture><br><b>Talking heads</b><br><sub>Cards that appear as the words are said (name tag, list, data callout, pull-quote, side panel), caption emphasis, and a big word behind the speaker, cut out on the CPU.</sub></td>
  697. <td width="33%" valign="top"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/readme/icons/footage-dark.svg"><img src="assets/readme/icons/footage-light.svg" width="44" alt=""></picture><br><b>Long recordings to clips</b><br><sub>A podcast, talk or panel ranked for its best moments on your machine, then the ones you pick as captioned vertical clips, each checked by qa.</sub></td>
  698. </tr>
  699. </table>
  700. Also: 30 motion components (seven of them WebGL looks), 26 transitions (15 CSS, 11 WebGL) and 6 themes, 12 look signatures that new
  701. dom, launch, short and data projects start in (a palette, a type pair and a motion feel, picked away from your
  702. recent videos; `showtime signature`), a showreel template for a dense 15-second reel, living diagrams (a system as an isometric figure that builds itself,
  703. also exported as a live figure people poke), website capture
  704. (screenshots, copy, brand colours and fonts), scripted app recordings with smooth auto-zoom, cursor and keycaps, PDF import, CSV and JSON to charts, a brand kit, posters baked into frame
  705. 0, exports for YouTube, X, LinkedIn, Reels, TikTok, Shorts and square feeds, README loops (animated WebP
  706. and GIF, like the previews on this page), credits written automatically when an asset needs
  707. attribution, a look history so videos do not repeat, style references, adopting video code you already wrote or a
  708. Claude Design export (`showtime adopt`), and a receipt for every job.
  709. <details>
  710. <summary><b>Every command</b></summary>
  711. `showtime --help` lists them grouped, with examples; `showtime <command> --help` has the details.
  712. | Group | Commands |
  713. |---|---|
  714. | Make | `new` (templates: data, diagram, dom, film, launch, series, short, showreel, tutorial, manim), `adopt`, `release-video`, `pr-video`, `recap`, `repro`, `retime`, `data`, `preview`, `render`, `export`, `check`, `snap`, `look`, `score`, `motion`, `code`, `server`, `manim` |
  715. | Audio | `audio compose`, `sfx`, `lib`, `beats`, `fit`, `mix`, `meter`, `master` |
  716. | Voice | `voice say`, `voice script` (narration with word timings, fitted to a length) |
  717. | Footage | `transcribe`, `pack`, `edit` (`cut`, `check`, `render`, `view`, `cards`, `moments`, `clips`), `captions`, `footage` (`scenes`, `reframe`, `cutout`, `denoise`, `stabilize`, `grade` and more), `autozoom` |
  718. | Capture and assets | `site`, `demo`, `doc`, `assets` (`font --css <Google Fonts link>` copies a stylesheet's fonts with their licences) |
  719. | Studio | `studio`, `brand` (`init`, `capture`, `apply`, `skip`) |
  720. | Job and QA | `status`, `qa`, `review-pack`, `review-findings`, `review-verdict`, `review-respond`, `review` (`open`, `notes`: notes on the finished video), `receipt`, `history`, `reference`, `job`, `clean` |
  721. | Deliver | `deliver` (posters, platform exports, thumbnails, README loops) |
  722. | Setup | `setup`, `doctor`, `config`, `install`, `report`, `paths`, `version`, `mcp`, `guide`, `help` |
  723. | More | `series` (a tutorial series sharing one kit), `signature` (the look signatures: `list`, `apply`) |
  724. ```bash
  725. showtime new dom my-video --duration 20 # a project from a template
  726. showtime voice script my-video/narration.md -o my-video/voice --fit 18 # local narration, fitted to 18 s
  727. showtime retime my-video --from-voice my-video/voice/timeline.json # scenes follow the narration
  728. showtime data import signups.csv my-video --x month --y signups --scene bars # a CSV becomes a chart
  729. showtime preview my-video # live player with scrubber and audio
  730. showtime render my-video --preview # fast draft
  731. showtime render my-video -o final.mp4 # full quality
  732. showtime qa final.mp4 # PASS/WARN/FAIL: loudness, black/frozen frames, captions, platform
  733. showtime deliver exports final.mp4 --targets youtube,reels,square
  734. showtime export html my-video # a single-file interactive HTML video
  735. showtime look my-video # one composite of the key frames, for a quick visual check
  736. showtime reference clip.mp4 --job my-job # a video's pace, shots and type scale, as a brief (never its content)
  737. showtime adopt my-page/ # a page that already has seek(t) gets check, sound, qa and export
  738. showtime adopt design-html.zip # a Claude Design animation's HTML export to a 1080p video, its fonts local
  739. showtime release-video notes.md -o my-video # release notes to a ready-to-render project, no agent needed
  740. showtime pr-video 123 # a pull request to a video under 10 MB for its description
  741. showtime recap --latest # this folder's newest Claude Code session as a short film: script.md first, then --yes
  742. showtime repro -- npx playwright test tests/login.spec.ts # a failing test as a bug-report video: script.md first, then --yes
  743. showtime new diagram how-it-works --example enter # a living diagram: a system that builds and explains itself
  744. showtime export html how-it-works --interactive # the same scene as a live figure people poke, one offline file
  745. showtime review open my-job # a local page to leave notes on frames or stretches of the finished video
  746. showtime edit cards suggest edit/transcripts/talk.json # moments in a talking head for cards (name tag, quote, list)
  747. showtime footage cutout talk.mp4 # the speaker cut out on the CPU: a video with alpha, a matte, a sheet
  748. showtime edit moments my-job # a long recording's best moments for short clips, ranked locally
  749. showtime edit clips my-job --pick m1,m3 # the picked moments as finished 9:16 clips, each through qa
  750. showtime assets font --css "https://fonts.googleapis.com/css2?family=Anton" --copy-to my-video/fonts
  751. ```
  752. </details>
  753. <details>
  754. <summary><b>The audio toolkit</b></summary>
  755. Everything is local and license-gated: no sample leaves your machine, and an asset that needs
  756. attribution writes itself into `credits.txt`. Catalog tracks are downloaded from their creators on first use
  757. (with the size announced) and never re-hosted here.
  758. | Command | What it does |
  759. |---|---|
  760. | `audio compose` | procedural music to an exact length in 18 styles, with stems, MIDI and a beat map; restrained beds for explainers and data, livelier styles on request |
  761. | `audio sfx` | 56 synthesized effect types (whooshes, hits, UI clicks, risers), with the hit time printed |
  762. | `audio music` | the produced-music catalog: 297 tracks, each measured for quality and tagged by mood, energy and tempo; `audio music pick --for launch --dur 45` chooses one, and the credit lands in `credits.txt` and the post copy by itself |
  763. | `audio lib` | the local library, 1,334 sounds: CC0 effects and ambiences, CC-BY music beds credited automatically, and beds rendered on your machine; `audio packs` adds 35 more sound packs (34 CC0, 1 CC BY) on demand |
  764. | `audio beats` | beats, downbeats, onsets, energy, sections and key, so cuts land on the music |
  765. | `audio fit` | loops or trims music to a length on bar lines |
  766. | `audio mix` | one mix file: ducking under the voice, effects aligned to hits, loudness |
  767. | `audio meter`, `audio master` | LUFS, true peak and loudness range; mastering to -14 LUFS / -1 dBTP by default |
  768. </details>
  769. <details>
  770. <summary><b>Math with Manim</b></summary>
  771. `showtime manim new|render|check|cues` makes equations, proofs, graphs and grid transforms with Manim
  772. Community (the `manim` extra; LaTeX is needed only for equations), and times them to the narration.
  773. [Example 22](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/22-manim-circle-area) cuts a circle into rings, unrolls them into a triangle and
  774. lands on
  775. $$A = \tfrac{1}{2} \cdot 2\pi r \cdot r = \pi r^2$$
  776. with a vertical cut for Shorts from the same scenes. An optional OpenGL engine (the `manimgl` extra) runs
  777. scene files written for it. `showtime manim check` also renders a draft and runs qa's black-frame and frozen-frame
  778. detectors on it, so a near-black scene or a barely visible change is reported before the full render.
  779. </details>
  780. <picture>
  781. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/divider-dark.svg">
  782. <img alt="" src="assets/readme/divider-light.svg" width="100%">
  783. </picture>
  784. ## New in 0.4.6
  785. [What's new](docs/whats-new.md) has a short paragraph for each.
  786. **`check`**
  787. - **Canvas text outside the safe box.** At 9:16, every step of the dense timeline compares each text a page draws on
  788. its own canvas with the safe box (x 64-916, y 220-1440 at 1080x1920): one `safe_zone` warning per text, with its span.
  789. - **Canvas text size.** Raw `fillText`/`strokeText` now feeds the `tiny_text` rule and the phone check, as DOM text and
  790. `F.text` already did.
  791. - **Text over text.** Every text a canvas paints and the DOM's are compared on the whole timeline: a pair that overlaps
  792. on two steps in a row is a `text_overlap` warning with when it starts and ends. Text layered on purpose can say so
  793. (`F.text(..., {layer: true})`, `F.layer`, `ST.layer`).
  794. - **A probe that did not run is a warning** (`cut_probe_failed`, `webgpu_probe_failed`), so such a check never reads as
  795. clean and `check --strict` fails on it.
  796. **X-ray**
  797. - **9:16.** The sound strip sits above the counters inside the safe box, and the part labels are 44 px in a column at
  798. the safe box's edge, with the drawing between the columns. The 9:16 layout change leaves 16:9, 4:5 and 1:1 as
  799. they were. A project made with 0.4.5 keeps its copy of the template; `showtime new xray` gets the new layout.
  800. - **16:9.** A new project passes its own check, and the strip's label is 26 px and fits a long mechanism word.
  801. - **`"xray".offset_frames`.** The sound strip, `track_until` and the piano, drums and guitar follow the recording's
  802. clock (`k.rt`, `k.frameAt(t)` in the drawing kit).
  803. - **`xray verify`** reads the sync marker on a `--preview` or `--scale` render; the receipt says what "the original" is
  804. for a film made from a rendering of data.
  805. - **`export html --interactive`** packs a page's own fonts, and `export html` run from inside a job writes into that job
  806. ([xray](skills/showtime/references/workflows/xray.md)).
  807. **Fixes**
  808. - **Files as installed.** The repository stores every file exactly as it is installed (`.gitattributes` `* -text`,
  809. Windows launchers with CRLF), checked by `scripts/check_release.py`.
  810. - **`setup --home X`** installs ffmpeg into X when a default install exists.
  811. - **Living diagrams.** Space or Enter on a focused control no longer also fires the scene's key.
  812. - **The embed element** takes a `file:` address only on a page opened from disk.
  813. - **`showtime assets icon`** suggests the right name at once for a misspelled one.
  814. <picture>
  815. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/divider-dark.svg">
  816. <img alt="" src="assets/readme/divider-light.svg" width="100%">
  817. </picture>
  818. ## New in 0.4.5
  819. [What's new](docs/whats-new.md) has a short paragraph for each.
  820. **X-ray**
  821. - **From data.** `showtime xray import <events.csv|json> --job <job> --time-map SLOW,T0` writes `xray.json` from event
  822. times measured in data (peaks of a signal, a sensor log): film time is (t_data - T0) x SLOW and each event lands on
  823. its frame. `--source` names the sound the film plays, so `xray verify` can check it.
  824. - **From a recording with no picture.** `xray analyze` takes a WAV (events on a frame grid of `--fps`, default 30) and
  825. `xray notes` takes one too, always at 30 fps; the page draws the picture side.
  826. - **The live page.** It states how the events were measured, lists your own steps when `"xray".made.commands` has them,
  827. and the page, the gallery and the guide say what sharing a page shares
  828. ([guide](docs/guides/xray.md), [xray](skills/showtime/references/workflows/xray.md)).
  829. **The skill and the tools**
  830. - **Routing by family.** SKILL.md sends a request to one of six families at 1,200 words or fewer; flags live in the
  831. guides and `--help`. A routing eval (`benchmarks/routing-eval/`) and a release check keep a case for every new
  832. workflow guide.
  833. - **`footage trim -o <file>`** writes that file. An existing file is refused unless `--overwrite`.
  834. - **The embed element** loads only a relative, http(s) or `file:` address.
  835. - **Living diagrams on a phone.** The Type field takes a paste, an input-method composition and Android Backspace, and
  836. no longer zooms the page on iOS.
  837. <picture>
  838. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/divider-dark.svg">
  839. <img alt="" src="assets/readme/divider-light.svg" width="100%">
  840. </picture>
  841. ## New in 0.4.4
  842. [What's new](docs/whats-new.md) has a short paragraph for each.
  843. **X-ray**
  844. - **`showtime xray`.** `analyze` finds every event (a keystroke, a pluck, a hit) in a clip's sound with its frame;
  845. `showtime new xray --mechanism <object>` draws the inside moving on those frames, on the object (`through`), beside
  846. it (`split`) or as an isometric diagram (`diagram`), as a dark radiograph or a light blueprint, 16:9 or 9:16; the
  847. library has a typewriter, a music box, a switch, a piano, a guitar and a drum kit. `notes` writes a score, a guitar
  848. tab or a drum sheet from the sound; `verify` reads the finished film back and `qa` fails a missing or extra event or
  849. audio more than 20 ms off. The receipt and the clip's credit go on the end card
  850. ([guide](docs/guides/xray.md), [xray](skills/showtime/references/workflows/xray.md)).
  851. - **The live page.** `showtime export html <xray project> --interactive` writes one offline page: pads play the next
  852. event of their kind with the clip's sound, your keyboard types on the typewriter, drag scrubs, `#hit4` and `#t2.5`
  853. link to a moment, `--prompt` puts the request that made it on the page next to the commands, and
  854. `<showtime-xray src="you-live.html">` or an iframe embeds it.
  855. - **The gallery.** The [X-ray page](https://faviovazquez.github.io/showtime/xray/) plays ten films with their
  856. receipts and plays each one live in place.
  857. **Living diagrams**
  858. - **You touch them.** A scene can take typing (`interactive.type`), a click on a part (`parts[].press`) and a drag that
  859. turns a knob (`parts[].drag`). `--example typewriter` and `--example computer` are new, and the heat pump's outdoor
  860. unit drags to set the weather ([guide](docs/guides/living-diagram.md)).
  861. <picture>
  862. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/divider-dark.svg">
  863. <img alt="" src="assets/readme/divider-light.svg" width="100%">
  864. </picture>
  865. ## New in 0.4.3
  866. [What's new](docs/whats-new.md) has a short paragraph for each.
  867. <table>
  868. <tr>
  869. <td width="33%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/_diagram"><img src="assets/readme/gallery/_diagram.webp" width="260" alt="The Enter loop at work: your machine with the terminal, Claude Code, Bash and a permission check, a request flying up to a glass cube labelled cloud."></a><br><b>Living diagrams and live figures</b></td>
  870. <td width="33%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/_recap"><img src="assets/readme/gallery/_recap.webp" width="260" alt="Red to green, from a Claude Code session: one red test run, then two green ones, and 12/12 test files passed."></a><br><b>A recap of your agent's session</b></td>
  871. <td width="33%" valign="top"><a href="https://github.com/FavioVazquez/showtime-examples/tree/main/examples/_repro"><img src="assets/readme/gallery/_repro.webp" width="260" alt="A failing Playwright step: the page says Welcome back, Ada; expected &quot;Welcome, Ada!&quot;, received &quot;Welcome back, Ada&quot;, and the console error."></a><br><b>A failing test as a video</b></td>
  872. </tr>
  873. </table>
  874. **Explain a system**
  875. - **Living diagrams.** `showtime new diagram` draws a system as an isometric figure that builds itself over time:
  876. parts arrive in the order that explains them, pipes and links join them, flows, packets and state changes move
  877. through them, labels land when their part matters, and the camera chooses what to look at. Light, dark or white;
  878. `--example enter` (a coding agent's loop), `--example market` and `--example econ-lab` start from finished scenes.
  879. `showtime check` reports a label that collides or never shows whole
  880. ([diagram](skills/showtime/references/workflows/diagram.md), issue #51).
  881. - **Live figures.** `showtime export html <project> --interactive` writes the same scene as one offline file,
  882. `<slug>-figure.html`: no play button, the board is live from the first frame. Hover a part to light it and read
  883. its value, pick a step to run it as an experiment on the board, turn a knob and the levels and numbers answer at
  884. once; untouched, a short tour plays. Keys, deep links to a state (`#step=cost&rule=3`), reduced motion, a phone
  885. layout and no network requests. `showtime check` walks every step, knob value and hovered part for cut or
  886. overlapping text and broken readouts ([html-export § Live figure](skills/showtime/references/html-export.md#live-figure),
  887. [the demo, live on the site](https://faviovazquez.github.io/showtime/examples/_diagram.html)).
  888. **From your agent's work**
  889. - **`showtime recap`.** A Claude Code session becomes a 30-60 s narrated film of what the agent did: the time, turns
  890. and tool calls, a timeline of the files it read and edited and the commands and tests it ran, the tests red to
  891. green and the diff from git. It reads the session log on your machine through an allow-list of facts
  892. (repository-relative paths, program names from a fixed list, test counts, git stats), never the transcript's own
  893. text; a filter drops anything that still looks like a key, a path, a URL or an e-mail address, and nothing renders
  894. until you have read `script.md` ([recap](skills/showtime/references/workflows/recap.md)).
  895. - **`showtime repro`.** A failing Playwright test (its `trace.zip`, or the test command) becomes a narrated
  896. bug-report video: each step on the trace's screenshots with a cursor and the target boxed, then the failure slowed
  897. down with expected and received, plus `repro.md` to paste into the issue. Typed values are never shown or spoken
  898. (their fields are covered); paths are shortened to the file name, URLs lose their query strings, and secrets are
  899. masked ([repro](skills/showtime/references/workflows/repro.md)).
  900. **Render, sound and the site**
  901. - **Every render worker captures from a page set up like the first one.** Under load, a worker whose page opened
  902. while one of its modules got no reply could render bare frames. Each page's setup is now compared with the first
  903. page's, and a page that differs is opened again; if the first page was the broken one, the render stops with an
  904. error instead of shipping its frames (issue #52).
  905. - **Music per video, and quiet cuts.** Recap and repro pick their bed from the music catalog (or a composed style
  906. offline) per session or test, so two films do not sound the same; a rerun keeps its bed, `--music` pins one, and a
  907. CC BY track's credit is written for you. A catalog track is downloaded once from its creator's site and cached;
  908. nothing is sent, and `--music <style>` or `SHOWTIME_OFFLINE=1` keeps the whole film local. Recap, repro,
  909. `release-video` and `pr-video` no longer put a sound on every cut (`--cut-sounds` adds a soft swoosh back), and the
  910. transition sounds are softer everywhere.
  911. - **How showtime is built.** A new page on the site, [how showtime is built](https://faviovazquez.github.io/showtime/harness/),
  912. is the crew's operating manual: who does what, and how a task becomes a merged pull request or a film (issue #53).
  913. The site and the repository share one link-preview image (issue #54).
  914. <picture>
  915. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/divider-dark.svg">
  916. <img alt="" src="assets/readme/divider-light.svg" width="100%">
  917. </picture>
  918. ## New in 0.4.2
  919. [What's new](docs/whats-new.md) has a short paragraph for each group of them.
  920. **Render**
  921. - **Chapter mode.** `showtime render --chapters` plans the pieces from your chapters (or the film's acts),
  922. `--chapter N --job J` renders one, and `--join --job J` joins them and builds the soundtrack once for the whole
  923. video, so there are none of the loudness steps (2.6 and 0.7 dB) that joining separately mastered sections gave.
  924. Every seam is checked against a master before the file is named `final.mp4`, and after a whole render or a
  925. join a later fix to one chapter re-renders exactly its frames. On one machine a whole render is faster: use
  926. chapters for a second machine (not measured), a later fix of one chapter, or a long film ([render § Speed](skills/showtime/references/render.md#speed), issue #22).
  927. - **A browser window resized late no longer ruins a render.** With 3 workers, 7 of 40 renders on a 6-core Intel Mac with a
  928. GPU had a wrong-sized capture lane under heavy load, and 0 of 30 do after the fix; the same fix makes `--scale 2` real
  929. on a Mac. A page with the wrong size is set again and `render.log` says so
  930. ([render](skills/showtime/references/render.md), issue #49).
  931. - **A frame that never comes no longer stalls a render** (when the browser reports its processes' work; otherwise
  932. the 10-minute cap stays): the frame is drawn again in a new browser, or the check ends with an error (issue #24).
  933. A WebGL canvas that loses its context on the GPU renders again without the GPU (`--gpu off`) instead of shipping
  934. white.
  935. - **More browsers without a GPU.** Without a GPU, `--workers auto` uses CPU threads - 2 from 8 threads up (at most 8,
  936. within the frame, memory and `SHOWTIME_MAX_WORKERS` limits): on an 8-thread machine it picks 6 browsers instead of
  937. 3; with a GPU nothing changes (issue #41, [FAQ](docs/faq.md#do-i-need-a-gpu)).
  938. **Footage and voice**
  939. - **`edit render` keeps the sound in sync** on showtime's own renders: a range could come out with its sound up to
  940. 21 ms early (issue #38).
  941. - **Narration that fits.** `showtime voice script narration.md -o voice --fit 15 --estimate` says up front whether
  942. the narration can fit before it synthesizes a single line.
  943. - **Your own local voice engine.** Extra engines load by name, and `doctor` no longer fails on Kokoro when you chose
  944. another ([voice](skills/showtime/references/voice.md), issue #8).
  945. **Help**
  946. - **A first-video guide, troubleshooting by symptom and a glossary**; `showtime doctor` ends with a link to the
  947. troubleshooting page when a check fails, and the site's docs start on "Start here"
  948. ([your first video](docs/guides/first-video.md), [troubleshooting](docs/troubleshooting.md),
  949. [glossary](docs/glossary.md)).
  950. <picture>
  951. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/divider-dark.svg">
  952. <img alt="" src="assets/readme/divider-light.svg" width="100%">
  953. </picture>
  954. ## New in 0.4.1
  955. [What's new](docs/whats-new.md) has one sentence and a picture for each.
  956. **Look and motion**
  957. - **Seven WebGL looks, no GPU needed**: fluted glass, tilt-shift, liquid metal, mesh gradient, god rays, marble and
  958. metaballs. Each adds less than 50 ms to a 1080p frame at its default size (one browser on a 64-core machine
  959. without a GPU), renders the same frames with any number of browsers, and has a designed fallback where WebGL is
  960. missing ([components § 7](skills/showtime/references/components.md), [the demo](https://github.com/FavioVazquez/showtime-examples/blob/main/examples/_looks/README.md)).
  961. - **Shutter blur.** `data-st-blur` smears an element the way a camera shutter would, only on the frames it moves fast;
  962. it lands sharp ([stage-api](skills/showtime/references/stage-api.md), [the demo](https://github.com/FavioVazquez/showtime-examples/blob/main/examples/_blur/README.md), the flash
  963. words of [example 30](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/30-showreel-four-shapes)).
  964. **Footage**
  965. - **Cards over a talking head**: a name tag, a list that builds as it is said, a data callout, a pull-quote, a side
  966. panel, anchored to the words so a re-cut moves them, and caption emphasis on key terms
  967. ([example 23](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/23-talking-head-cards-nasa)).
  968. - **A word behind the speaker.** `showtime footage cutout` cuts a person out on the CPU (MODNet, Apache-2.0), and the
  969. EDL card `behind` puts a big word between the background and the speaker.
  970. - **A long recording to its best clips.** `showtime edit moments` ranks whole-sentence moments by local signals (a
  971. hook, a complete thought, energy, laughter and applause, one topic) and `showtime edit clips` renders the picked
  972. ones as face-tracked 9:16 clips with captions, each through qa: a 58-minute panel took about 7 minutes end to end
  973. on a 64-core machine ([example 24](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/24-highlights-apollo17-panel)).
  974. **New ways in, and sharing**
  975. - **Claude Design to MP4.** `showtime adopt <export.zip>`: the artboard fills a 1080p frame with sharp text, its
  976. Google Fonts are copied in with their licences, and a looping design renders exactly one loop
  977. ([adopt](skills/showtime/references/adopt.md), [example 28](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/28-claude-design-to-mp4)).
  978. - **Link previews.** `showtime export html --share-url <address>` (or `"share"` in showtime.json) adds the tags that
  979. show a title, a description and the poster when the link is pasted; `--folder` exports are ready for GitHub Pages
  980. ([example 25](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/25-nobel-physics-ice-telescope)'s HTML video).
  981. **Review and resume**
  982. - **Notes on a stretch of time** (Shift + drag on the notes page's scrubber), and `showtime review notes` names the
  983. scene and the elements under each note.
  984. - **Since you last looked.** `showtime status <job>` lists the files you edited by hand, your unread notes and open
  985. findings, so your agent keeps your changes.
  986. - **The voice-over is heard back**: showtime transcribes it on your machine and flags a name, an acronym or a number
  987. said wrong, with the fix to try; qa and the critic see it too. It runs when the local recognizer is installed: it
  988. arrives with the first transcription, or `showtime setup --fetch parakeet-tdt-0.6b-v3-int8`.
  989. - **check catches more**: a fading text is judged at its clearest frame, `caption_zone` warns about anything where
  990. the captions go, a WebGPU page is tried again without WebGPU, and each look's cost is estimated.
  991. **Faster**
  992. - The encoder runs while the frames are captured, a finished browser takes over half of the largest part left, and
  993. an unchanged soundtrack is reused: on a busy 6-core Intel Mac a 1 s fix went from 31-54 s to 13-21 s.
  994. - Without a GPU, the number of browsers follows the cores (CPU threads - 2 from 8 threads up, at most 8, and 3
  995. below that, at most CPU threads - 2), and waits stretch on a slow page instead of failing: on a 64-core Linux
  996. machine with no GPU a 30 s launch film went from 42.0 s to 17.6 s and a 15 s DOM page from 31.8 s to 16.4 s.
  997. [Do I need a GPU?](docs/faq.md#do-i-need-a-gpu)
  998. The full list is in the [changelog](CHANGELOG.md).
  999. <picture>
  1000. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/divider-dark.svg">
  1001. <img alt="" src="assets/readme/divider-light.svg" width="100%">
  1002. </picture>
  1003. ## New in 0.4.0
  1004. **Videos that ask, and notes on the finished video**
  1005. - **Videos that stop and ask.** List questions in showtime.json and the HTML export pauses on that frame, asks, marks
  1006. the answer, replies and plays on; the MP4 gets a "pause and think" beat with a countdown and the answer. A question
  1007. can sit on a narration line, so a re-voice moves it with the line ([guide](skills/showtime/references/html-export.md),
  1008. [example 25](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/25-nobel-physics-ice-telescope)).
  1009. - **Notes on the finished video.** `showtime review open <job>` serves a local page that plays the latest render:
  1010. pause, click a spot or drag a box on the frame, type a note. Your agent reads them with `showtime review notes`,
  1011. fixes, and replies on the same note.
  1012. - **Range links** in the HTML player: `video.html#t=10-20` plays that part on a loop.
  1013. **New ways in**
  1014. - **`showtime pr-video <N | URL>`**: a pull request becomes a short video for its own description in one command,
  1015. with a copy under GitHub's 10 MB attachment limit. A public PR works without a GitHub login, and values that look
  1016. like secrets never reach the video ([example 29](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/29-pr-video-showtime)).
  1017. - **A storyboard from another skill becomes a project**: `showtime new <template> <dir> --from-storyboard FILE`
  1018. reads a Markdown table (Shot | Length | Visual | Narration, in any order, English or Chinese headers;
  1019. [examples 25 and 26](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/26-nobel-chemistry-en-es)).
  1020. - **Go all out: the showreel tone.** A "showreel" or "go all out" brief turns it on: 12-14 shots in 15 s, no
  1021. technique twice, flash words allowed, the name landing late and short; `qa` judges density, the ending and repeats.
  1022. The `showreel` template renders at 16:9, 9:16, 1:1 and 4:5 with no edits ([example 30](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/30-showreel-four-shapes)).
  1023. **A stricter quality gate**
  1024. - **The critic watches as a first-time viewer** before it reads the brief: for each part, does a newcomer know why it
  1025. is there? Explainers default to a cold open with the stakes, a roadmap, bridges and a close that answers the opening.
  1026. - **Findings gate delivery.** A job is not marked delivered while a critic's Blocker or Should-fix is neither fixed
  1027. nor waived (`showtime review-respond --fixed | --waive`), and every waiver keeps its reason in the receipt.
  1028. - **A hearing pass** next to the visual critic: music over the voice, a rushed or cut-off line, a long silence, a
  1029. late or loud effect, a jump in level at a cut, music that stops dead.
  1030. - **One delivery card** with a mandatory `Look:` line saying what was opened, at what size, and what was seen.
  1031. **Better-looking by default**
  1032. - **Twelve look signatures.** `showtime new` dresses the page templates in one of twelve curated looks (palette at
  1033. the contrast rules, a type pair, a motion feel), picked away from your recent videos (`--look <id>` to choose;
  1034. [example 32](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/32-twelve-looks) shows one project in all twelve).
  1035. - **No blank or late first frames** after a cut or in a `<video>`: every video is drawn on a canvas in renders, and
  1036. `check` warns `late_first_frame`.
  1037. **Proof**
  1038. - **A behaviour scoreboard anyone can rerun** ([above](#behaviour-scoreboard)): 35/42 with showtime, 25/42 without.
  1039. - **A blind rematch** on the round-1 showreel prompt ([round notes](benchmarks/rounds/r5-allout.md)): showtime 0.4.0
  1040. lost round 5; after the density fix its two takes ranked first and second in round 6, ahead of the plain take that
  1041. had won round 1. One voter (me, showtime's author), partly blind: an anecdote, not a result.
  1042. Limits: the hearing pass and the checks measure the file; whether a video is good is still the critic's and your
  1043. call. The full list is in the [changelog](CHANGELOG.md).
  1044. <picture>
  1045. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/divider-dark.svg">
  1046. <img alt="" src="assets/readme/divider-light.svg" width="100%">
  1047. </picture>
  1048. ## New in 0.3.0
  1049. **Quieter runs, full review by default**
  1050. - **Lean mode, when you ask for it.** The full review stays the default; say "lean" (or run
  1051. `showtime config mode lean`) for a lighter pass without the critic round. In both modes `showtime look` makes one
  1052. composite image that a disposable reviewer reads (your agent does not), `render` says when a project was not
  1053. checked first and names the cheaper `--from/--to` fix after a second full render, and `check`, `qa`, `doctor` and
  1054. `render` print a short summary by default (`--verbose` for everything). Every reference opens with its rules
  1055. (`showtime guide <topic>` prints them). No check was removed. In benchmark round 4, lean runs read a median of 4.5
  1056. images into the agent's context and made a median of one full render per job.
  1057. - **`showtime job init` checks your setup** and prints `setup: ready` or the failures with their fixes, so it is the
  1058. one command to start with.
  1059. **Better videos**
  1060. - **Variety guard.** Each finished job's look (template, theme, palette, type pair, transitions, camera moves, music,
  1061. structure, tone) goes into a local history that never leaves your machine (`showtime history off` turns it off).
  1062. `showtime check` warns `look_repeat` when a project repeats one of the last five, with two concrete alternatives.
  1063. - **Style references.** `showtime reference <video>` writes a brief with the video's cut rhythm, shot lengths, how
  1064. scenes change, palette, camera moves, rough type scale and loudness curve, and a contact sheet. The storyboard
  1065. borrows the grammar, never the words, logos or shots; the credit "Style reference: ..." is written for you, and
  1066. `showtime qa` fails a render that copies the reference's pictures ([guide](skills/showtime/references/reference.md)).
  1067. - **Phone check.** `showtime check` ends with `phone check: PASS` or `FAIL` with timestamps: each text held long
  1068. enough to read (per language), a minimum type size at phone width (16:9 5 pt, 1:1 10, 4:5 11, 9:16 15) and nothing
  1069. under a platform's buttons or at the edge. In `qa`, a failure is a warning, never a FAIL.
  1070. - **Brand first for launches.** `showtime brand capture <repo|url> --job <job>` takes the product's palette with
  1071. roles, fonts, logo, wordmark, real copy (with file and line) and real UI before the storyboard, and `showtime new
  1072. launch` applies it. A launch job with no kit says why (`showtime brand skip`), and `check` warns when it does not.
  1073. - **Pairwise review.** See [the crew](#meet-the-crew): a new version ships only if the critic prefers it in both orders.
  1074. - **Fixes where agents tripped:** a clip's frames no longer depend on the order the frames were asked for,
  1075. `retime --from-voice --total` works when every scene is narrated, Manim silent films and `--mix` paths work, `doctor`
  1076. warns when the `showtime` command on your path is not the agent's, and font errors name the exact missing
  1077. characters and the fix.
  1078. **New kinds of video**
  1079. - **Repo explainers and paper explainers** (workflows `repo-explainer` and `paper-explainer`), described
  1080. [above](#for-developers).
  1081. - **`showtime release-video`** turns release notes, a CHANGELOG section or a PR description into a ready-to-render
  1082. project with no agent: the notes' own words, reading-time holds, the people credited.
  1083. - **A GitHub Action** that renders a release or PR video on the runner, checks it, exports an HTML video and a copy
  1084. under 10 MB, and uploads them ([guide](docs/github-action.md)). It needs no API key unless you choose the mode that
  1085. runs your own agent.
  1086. - **`showtime adopt <folder | page | script>`** takes a video someone already wrote as a function of time (an HTML
  1087. page with `seek(t)`, a canvas `draw(t)`, a CSS-animated page, a Python frame function) and gives it showtime's checks,
  1088. sound, captions, qa, HTML export and review, without a rewrite. The originals are never changed
  1089. ([guide](skills/showtime/references/adopt.md)).
  1090. **Honesty**
  1091. - **Receipts.** Every job ends with `receipt.md`, `receipt.json` and a line in `share.txt` (see
  1092. [above](#quiet-checked-and-on-the-record)).
  1093. **In progress** (landing before the release):
  1094. - A fix to a few seconds (`render --from A --to B --job <job>`) splices into a complete new final: only those frames change, the audio is mastered again, and a span is never mistaken for the video.
  1095. - Every Manim template passes its own check, and a scene's first element is on screen at frame 0.
  1096. Limits: the phone check and the look history read the project files and cannot judge whether a video is good; a
  1097. model reviewer's preference is steadier than its score but is still an opinion; tokens and cost appear only for
  1098. agents that expose their session log (Claude Code and Codex, as numbers only), and everything else says "not reported
  1099. by this agent". The full list is in the [changelog](CHANGELOG.md).
  1100. <picture>
  1101. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/divider-dark.svg">
  1102. <img alt="" src="assets/readme/divider-light.svg" width="100%">
  1103. </picture>
  1104. ## New in 0.2.0
  1105. - **Works in your coding agent.** One repository for every agent: Claude Code, Codex, Cursor, Devin and OpenCode
  1106. are tested, and Copilot, Gemini CLI, Antigravity, Cline, Kilo Code, Kiro, Zed, Goose, Amp, Factory Droid and
  1107. Qwen Code are packaged ([Works with](#works-with)). `showtime install --agent <name>` puts the skill, the crew
  1108. and the MCP server where an agent looks. A stable `~/.showtime/bin/showtime` command survives plugin updates,
  1109. long commands can run in the background (`--background`, `showtime status`), and `showtime doctor` knows the
  1110. sandboxes of the common agents and says which setting to change.
  1111. - **A lighter first run.** The default download is about 770 MB on Linux x64 (about 560 to 610 MB on macOS and
  1112. Windows) instead of 2.9 GB. `showtime setup --plan` lists every component with its size and when it is
  1113. fetched, and `showtime setup --full` installs everything up front. Nothing was removed: a piece that left the
  1114. default install (the transcription model, Manim, the audio library beyond its 41 MB starter, browser and icon
  1115. extras) is fetched the first time a video needs it, announced with its size. Homes made by 0.1 keep working;
  1116. `setup --prune` clears what is no longer used.
  1117. - **A real music catalog.** 297 produced tracks (Scott Buckley, Kevin MacLeod, a dozen more composers and
  1118. public-domain recordings),
  1119. each downloaded and measured for hiss, clipping, mono, dead gaps and loudness swings, tagged by mood, energy,
  1120. tempo and use, and picked with `showtime audio music pick`. Tracks are fetched from their creators on first use
  1121. and never re-hosted. Every render that uses one writes the credit into `credits.txt` and the post copy by
  1122. itself, and prints a note. 35 more sound packs (34 CC0) install when a search needs them.
  1123. - **Platforms.** Apple Silicon and Linux arm64 now run end to end in CI, Windows 11 on Arm runs with an x64
  1124. Python under Windows' emulation ([Requirements](#requirements)), and `scripts/e2e.py` repeats the whole
  1125. path on any machine.
  1126. - **A safer preview server.** `showtime preview` and `showtime server` answer only requests that carry a
  1127. random per-session key from the printed link; before, any web page open in your browser could read a
  1128. project's files over `127.0.0.1`.
  1129. - **Footage edits that hear the ums.** The default transcription is now Parakeet-TDT 0.6B v3 (25 languages
  1130. including English and Spanish; fetched on first use, about 490 MB; Whisper stays for other languages and with
  1131. `--model`). It keeps "um" and "uh" as words, and a scan after it hears the hesitations no word covers. On a public,
  1132. human-labelled podcast set (20 episodes, 495 labelled fillers) it found 81% of them at 83% precision against the
  1133. labels, where 0.1.0's default found 11% at 78%; on the benchmark interview it cuts all five known "uh" (the
  1134. benchmark's scorer credits 4 of 5; 0.1.0's default commands cut none). Cuts get 20 ms crossfades. Speech under
  1135. music is heard better because showtime transcribes its own dry narration stem, and separates the voice only when
  1136. the music is loud: word errors at equal loudness fell from 19.7% to 7.3% on a small test set. These are local
  1137. evaluations on a few sets, not a guarantee for your footage; label-based precision understates it, since the
  1138. labels miss some real fillers. CrisperWhisper is available as an opt-in model under its non-commercial licence
  1139. (not on Intel Macs).
  1140. - **Launch videos by default.** Ask for a launch, promo or release video and the default is a calm short film of
  1141. four to six scenes: a big still hook, one smooth fly-through into the product, the same window carried across the
  1142. cuts, and a produced track whose swell lands on the end card. The camera only moves when it has a reason; the
  1143. motion comes from the product itself. Terminals and code shrink to fit every size, and `showtime check` stops a
  1144. render when text would be cut off.
  1145. The full list is in the [changelog](CHANGELOG.md).
  1146. <picture>
  1147. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/divider-dark.svg">
  1148. <img alt="" src="assets/readme/divider-light.svg" width="100%">
  1149. </picture>
  1150. ## Requirements
  1151. **No GPU needed.** Without one, the browser draws every frame on the CPU, WebGL included; how long that takes, and
  1152. other common questions, are in the [FAQ](docs/faq.md).
  1153. showtime is built for macOS (Apple Silicon and Intel), Windows 10/11 and Linux (x86_64 and arm64). What has
  1154. actually been run, and where ("end to end" means setup, doctor, a voiced render with qa, HTML export,
  1155. transcription, captions and the MCP server):
  1156. - **Intel Mac** (a physical machine): end to end, plus the fast test suite.
  1157. - **Apple Silicon**: end to end on GitHub's `macos-14` (M1) runners, plus the fast suite. A run on a physical
  1158. Apple Silicon Mac is still welcome.
  1159. - **Linux x86_64**: end to end on Ubuntu 24.04 (AWS), plus the fast suite.
  1160. - **Linux arm64**: end to end on GitHub's `ubuntu-24.04-arm` runners.
  1161. - **Windows Server 2025 x64**: end to end as a standard user (AWS) and on GitHub's `windows-2025` runners.
  1162. - **Windows 11 on Arm**: end to end on GitHub's `windows-11-arm` runners, plus the fast suite. showtime's
  1163. Python and ffmpeg run as x64 under Windows' emulation there (some packages have no Windows arm64 build, and the
  1164. native arm64 ffmpeg build did not start on the runner), so it is slower than on x64.
  1165. - **Windows 10/11 x64 desktop as a standard user**: not yet run on a real machine. If you have one,
  1166. `scripts/e2e-windows.ps1` runs everything and zips the result to attach to an
  1167. [issue](https://github.com/FavioVazquez/showtime/issues).
  1168. CI runs the fast test suite on Linux, Windows and Apple Silicon for every change, and on an Intel Mac
  1169. nightly. Expect rough edges on anything marked not yet run, and please open an issue when something breaks.
  1170. | | macOS 14+ | Windows 10/11 (x64) | Linux (glibc 2.28+: Ubuntu 20.04+, Debian 10+) |
  1171. |---|---|---|---|
  1172. | Status | Intel: tested<br>Apple Silicon: tested (CI, end to end) | Server 2025 x64: tested<br>11 on Arm: run in CI, rerun pending<br>10/11 x64 desktop: not yet run | x86_64: tested<br>arm64: tested (CI, end to end) |
  1173. | [uv](https://docs.astral.sh/uv/getting-started/installation/) | install script | install script or winget | install script |
  1174. | [Node.js](https://nodejs.org) 24 or 22 LTS (20+) | installer | installer or winget | fnm or NodeSource |
  1175. Chrome, Edge or Chromium is found automatically; if none is installed, setup downloads Chrome's headless
  1176. shell (100 to 120 MB to download). Disk: the default install downloads about 0.73 GB on Linux x64 (0.67 GB on Linux
  1177. arm64) and 0.53 to 0.59 GB on macOS and Windows, and once unpacked it takes about 1.4 GB on macOS and Windows and 1.7
  1178. to 1.8 GB on Linux (Python packages 0.65 to 0.9 GB, Node packages 0.34 GB, ffmpeg 0.13 to 0.33 GB, models 0.22 GB),
  1179. with a browser already installed; the headless shell adds 0.2 to 0.3 GB, and a system ffmpeg 6.0 or newer saves
  1180. the ffmpeg part. `showtime setup --estimate` prints yours, `showtime setup --plan` lists every download. What a video needs only sometimes arrives the first time it is used, with its size
  1181. announced: the transcription model (Parakeet, about 490 MB, once),
  1182. Manim (60 MB), the audio library's starter part (41 MB), a music track or a sound pack (each a few MB to a few
  1183. dozen). `showtime setup --full` fetches all of it now, for a machine that will be offline (about 5.1 to 5.7 GB,
  1184. mostly the 1.6 GB Whisper large-v3-turbo model and 0.9 GB of the music catalog; Scott Buckley asks for no bulk
  1185. downloads, so his tracks still download one at a time, the first time a video uses them).
  1186. <details>
  1187. <summary><b>Install commands for uv and Node.js</b></summary>
  1188. macOS and Linux:
  1189. ```bash
  1190. curl -LsSf https://astral.sh/uv/install.sh | sh
  1191. # Node.js: the installer from nodejs.org (macOS), or on Linux fnm (distribution packages are often older than 20):
  1192. curl -fsSL https://fnm.vercel.app/install | bash && fnm install 22
  1193. ```
  1194. Windows (PowerShell):
  1195. ```powershell
  1196. winget install --id=astral-sh.uv -e # or: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  1197. winget install OpenJS.NodeJS.LTS --source winget # or the installer from nodejs.org
  1198. ```
  1199. On Linux, if the browser does not start, install Chromium's system libraries once (after setup):
  1200. `sudo "$(command -v node)" ~/.showtime/node/node_modules/playwright/cli.js install-deps chromium`.
  1201. [NodeSource](https://github.com/nodesource/distributions) packages work too.
  1202. </details>
  1203. ffmpeg is downloaded as a static build, so a system ffmpeg is not needed. Installing uv or Node.js
  1204. updates `PATH` for new terminals only: **restart your coding agent afterwards** (showtime also looks in the
  1205. installers' default folders if the new `PATH` has not reached it yet).
  1206. <details>
  1207. <summary><b>Setup from a terminal, and what it installs</b></summary>
  1208. The first time showtime is used, your agent tells you the size and time and runs the setup once you agree. The first time a video
  1209. needs a bigger piece (library sounds, a music track, the transcription model, Manim), showtime fetches just that piece and prints its
  1210. size first; `showtime setup --full` fetches everything up front. To run setup yourself, use a clone (both share `~/.showtime`).
  1211. macOS and Linux (bash, zsh):
  1212. ```bash
  1213. git clone https://github.com/FavioVazquez/showtime
  1214. showtime/skills/showtime/bin/showtime setup
  1215. showtime/skills/showtime/bin/showtime doctor
  1216. showtime/skills/showtime/bin/showtime setup --plan # what setup and first use download, with sizes
  1217. showtime/skills/showtime/bin/showtime audio lib fetch # optional: the whole sound library now (about 249 MB)
  1218. ```
  1219. Windows PowerShell (`showtime.cmd` also works from cmd; `showtime.ps1` is there too):
  1220. ```powershell
  1221. git clone https://github.com/FavioVazquez/showtime
  1222. & .\showtime\skills\showtime\bin\showtime.cmd setup
  1223. & .\showtime\skills\showtime\bin\showtime.cmd doctor
  1224. & .\showtime\skills\showtime\bin\showtime.cmd setup --plan
  1225. & .\showtime\skills\showtime\bin\showtime.cmd audio lib fetch # optional: the whole sound library now
  1226. ```
  1227. Setup also writes `~/.showtime/bin/showtime` (Windows: `showtime.cmd`), a command that keeps working when a
  1228. plugin update moves the skill folder, and prints how to put it on your `PATH` (it never changes `PATH` itself). On
  1229. Windows that is one PowerShell line adding `%USERPROFILE%\.showtime\bin` to your user `PATH`: run it once, then
  1230. open a new terminal (or restart your agent) to type just `showtime`.
  1231. Without it, `skills/showtime/bin/showtime` is the entry point (the skill's folder, not the plugin's top folder). On
  1232. Windows that runs `showtime.cmd` (from cmd or PowerShell); call `showtime.ps1` directly only where the PowerShell
  1233. execution policy allows scripts.
  1234. | In `~/.showtime` (move it with `SHOWTIME_HOME`) | Contents |
  1235. |---|---|
  1236. | `bin/` | static `ffmpeg` / `ffprobe` for your OS and CPU |
  1237. | `venv/` | Python 3.12 environment with pinned packages |
  1238. | `node/` | pinned Node packages: Playwright, animation, charts, math, icons, fonts |
  1239. | `browsers/` | Chrome's headless shell, only when no Chrome/Edge/Chromium is installed |
  1240. | `models/` | the Kokoro voice, face detection and denoise models at setup; transcription models on the first transcription; the portrait-matting model on the first speaker cutout |
  1241. | `soundfonts/` | the FluidR3Mono General MIDI bank (MIT) and its license |
  1242. | `library/` | the audio library, fetched in parts: CC0 effects and ambiences, CC-BY music beds (credited automatically), plus effects and beds rendered locally; `showtime audio lib fetch --tier extended` adds about 200 MB more music |
  1243. | `music/` | produced-music catalog tracks, each fetched from its creator the first time a mix uses it |
  1244. Downloads resume after an interruption and are skipped when already present, so re-running setup is
  1245. always safe. Setup's downloads, the optional extras, the core audio library, the music catalog, the sound
  1246. packs and the models fetched on first use (the English aligner, Piper voices, the speaker cutout) are pinned by URL, size and
  1247. SHA-256. Two are not pinned
  1248. yet: the extended audio-library tier records each file's SHA-256 on its first download and verifies
  1249. every re-download against it (trust on first use), and the background-removal engine used outside
  1250. macOS (rembg, a pinned package version) fetches its model with its own downloader. Features that need
  1251. an optional extra say so and print the exact command; nothing is installed behind your back.
  1252. ```bash
  1253. showtime setup --list # tiers, extras and their sizes
  1254. showtime setup --plan # every component: size, source, when it is fetched (--platform X for another OS)
  1255. showtime setup --estimate # what this run would download, and how long it takes
  1256. showtime setup --full # everything now, nothing fetched later (offline machines; --seed DIR reuses files)
  1257. showtime setup --prune # remove files from older versions that nothing uses any more
  1258. showtime setup --with asr-turbo,diarize # add extras (keeps what is already installed)
  1259. showtime setup --tier full # core + the common extras
  1260. ```
  1261. | Extra | What it adds |
  1262. |---|---|
  1263. | `asr-turbo` | Whisper large-v3-turbo, transcripts for languages outside Parakeet's 25 |
  1264. | `parakeet` | Parakeet-TDT 0.6B v2, English only; fetched on first use when asked for |
  1265. | `diarize` | speaker labels for interviews and podcasts |
  1266. | `events` | audio event tags (laughter, applause, music) |
  1267. | `supertonic` | Supertonic 3 voices (Spanish and 30 more languages) |
  1268. | `sf-generaluser` | the GeneralUser GS SoundFont, a richer General MIDI bank (its own free license) |
  1269. | `sf-musescore` | the MuseScore General orchestral SoundFont |
  1270. | `deepfilter` | DeepFilterNet3 speech denoiser |
  1271. | `rife` | RIFE frame interpolation (GPU, Vulkan) |
  1272. | `chromium` | Playwright's Chromium even when Chrome is installed |
  1273. | `manim` | Manim Community for math and diagram animation, `showtime manim` (needs cairo/pango on macOS/Linux; LaTeX only for equations) |
  1274. | `manimgl` | ManimGL 1.7.2, an optional OpenGL engine for scene files written for it (own venv; needs OpenGL 3.3; a Linux server without a display also needs `xvfb`) |
  1275. | `musicgen` | MusicGen draft music; its weights are **non-commercial**, so outputs are labelled |
  1276. Parakeet-TDT 0.6B v3 (the default verbatim transcription, 25 languages) and the UVR MDX-Net vocal separator
  1277. (speech under loud music) are not extras: they are fetched the first time a transcription needs them, or now
  1278. with `showtime setup --full`.
  1279. </details>
  1280. <details>
  1281. <summary><b>What showtime runs and downloads</b>: every download, and what goes over the network</summary>
  1282. **What runs.** Installing the plugin downloads this repository and nothing else. It adds the `showtime`
  1283. skill (Claude runs `skills/showtime/bin/showtime`, a Python and Node command line, in your terminal), a
  1284. local MCP server (`node skills/showtime/mcp/server.mjs` over stdio; it makes no network calls of its own), a
  1285. progress monitor while the skill is in use (`node skills/showtime/mcp/progress-monitor.mjs`, which reads
  1286. `~/.showtime/logs/progress.jsonl`), and ten optional sub-agents. No hooks. Setup runs only after Claude has
  1287. told you the size and time and you agree, or when you run it yourself. Files go to `~/.showtime` (or
  1288. `SHOWTIME_HOME`, or the plugin's `home` setting) and each video to `showtime-out/<slug>-<timestamp>/` in
  1289. your project.
  1290. **Setup downloads** (the default `core` tier, about 2.9 GB). Every model and ffmpeg file is checked against
  1291. a size and SHA-256 pinned in `skills/showtime/setup/manifest.json`:
  1292. | What | From | Size |
  1293. |---|---|---|
  1294. | ffmpeg 9.0.2 and ffprobe, static builds (GPL), skipped when a capable ffmpeg is already installed | macOS Intel: evermeet.cx (fallback ffmpeg.martin-riedl.de); Apple Silicon: ffmpeg.martin-riedl.de; Windows: gyan.dev builds from github.com/GyanD/codexffmpeg (fallback github.com/BtbN/FFmpeg-Builds); Linux: github.com/BtbN/FFmpeg-Builds (x64 fallback ffmpeg.martin-riedl.de) | 52 to 194 MB, one build |
  1295. | Python packages, in a Python 3.12 environment (uv downloads Python 3.12 if you do not have it) | PyPI through uv; versions pinned in `setup/requirements.txt` | about 1.5 GB installed |
  1296. | Node packages: Playwright, anime.js, D3, three.js, KaTeX, Shiki, Lottie, icon sets and 16 Fontsource font packages | registry.npmjs.org, `npm ci` from `setup/package-lock.json` (integrity hashes, no install scripts) | about 250 MB installed |
  1297. | Kokoro 82M text-to-speech, two model files and the voices (Apache-2.0) | huggingface.co/onnx-community, github.com/thewh1teagle/kokoro-onnx | 679 MB |
  1298. | Whisper small.en transcription (MIT) | huggingface.co/Systran | 486 MB |
  1299. | Silero VAD (MIT), the YuNet face detector (MIT), arnndn denoise models, the FluidR3Mono SoundFont (MIT) | github.com/k2-fsa/sherpa-onnx, github.com/opencv/opencv_zoo, raw.githubusercontent.com (richardpl/arnndn-models, musescore/MuseScore), pinned to a release or commit | 27 MB |
  1300. | Chromium, only when no Chrome, Edge or Chromium is installed (or with `--with chromium`) | Playwright's download server, through `playwright install` | not in the 2.9 GB |
  1301. On macOS, setup removes the download quarantine flag from the ffmpeg binaries (`xattr -d
  1302. com.apple.quarantine`) so Gatekeeper does not block them.
  1303. **Downloaded later, only when a feature needs it.** The command or Claude says so first.
  1304. - The audio library, `showtime audio lib fetch`: the core set is 87 files (about 250 MB, CC0 and CC BY 4.0)
  1305. from kenney.nl, opengameart.org, incompetech.com and archive.org, pinned by SHA-256. `--tier extended`
  1306. adds 218 files (about 1 GB) from incompetech.com, archive.org and opengameart.org; those are not pinned
  1307. yet, so each file's SHA-256 is recorded at its first download and checked on every re-download.
  1308. - The English word aligner, wav2vec2 (95 MB, Hugging Face, pinned), the first time narration is aligned;
  1309. a Piper voice (67 to 116 MB, github.com/k2-fsa/sherpa-onnx releases, pinned) when you choose one.
  1310. - Another Whisper model (Hugging Face, 150 MB to 3 GB, not pinned) when you transcribe with `--model`, or
  1311. speech that is not English (`small`, about 480 MB).
  1312. - Outside macOS, background removal installs the rembg package from PyPI, and rembg downloads its own
  1313. model (about 170 MB) the first time.
  1314. - Optional extras, only with `showtime setup --with <name>` (the list and sizes: `showtime setup --list`):
  1315. larger Whisper and Parakeet transcription, speaker labels, audio event tags, Supertonic voices,
  1316. DeepFilterNet, RIFE, two more SoundFonts and Manim/ManimGL (from Hugging Face, GitHub releases, OSU OSL
  1317. and PyPI, pinned by SHA-256 except the Python packages), and MusicGen (PyPI, PyTorch's package index on
  1318. Linux, and Meta's non-commercial weights from Hugging Face).
  1319. `SHOWTIME_OFFLINE=1` stops the web asset lookups and the voice-model downloads.
  1320. **What goes over the network.** showtime adds no cloud service: no accounts, no telemetry (Hugging Face's
  1321. is switched off too) and no uploads. Every request it makes is a download. Rendering is offline: the
  1322. headless browser that draws the frames blocks every request that is not local, and an HTML video carries a
  1323. content security policy that allows no network access. The web is used only when you ask for something
  1324. from it:
  1325. - web assets: fonts (api.fontsource.org, cdn.jsdelivr.net), icons and emoji (cdn.jsdelivr.net,
  1326. raw.githubusercontent.com), and openly licensed photos and video (Openverse, Wikimedia Commons, NASA,
  1327. the Cleveland Museum of Art, the Met, the Art Institute of Chicago, or a URL you give);
  1328. - a web page you name, loaded in a local browser to capture it (`showtime site capture <url>`, `showtime
  1329. demo record --url`, `showtime brand init --url`), with cookie banners declined and trackers blocked;
  1330. - the optional researcher sub-agent, which checks facts with Claude Code's web tools.
  1331. Those requests carry the search words or the URL and a `showtime/<version>` user agent; your files and
  1332. videos are never sent. The studio board and the preview server listen on 127.0.0.1 only, and the board's
  1333. link carries a random key.
  1334. </details>
  1335. <details>
  1336. <summary><b>Troubleshooting</b></summary>
  1337. | Symptom | Try |
  1338. |---|---|
  1339. | Anything looks wrong with the install | `showtime doctor`: real checks with a one-line fix for each problem (`--json` for scripts) |
  1340. | A command says setup has not been run | `showtime setup`; it prints the size and time first |
  1341. | A feature asks for an extra | run the `showtime setup --with <name>` it prints (or set `SHOWTIME_AUTO_INSTALL=1`) |
  1342. | An error needs more detail | re-run with `--debug` for the full traceback; the last one is also saved in `~/.showtime/logs/last-error.log` |
  1343. | You want to report a bug | `showtime doctor --report <job folder>` writes a redacted `bug-report.md` there; read it, then share it if you like. showtime never uploads anything |
  1344. | Linux: the browser does not start | install Chromium's system libraries once: `sudo "$(command -v node)" ~/.showtime/node/node_modules/playwright/cli.js install-deps chromium` |
  1345. | `uv`/`node` not found right after installing them | restart your coding agent (or open a new terminal) so it sees the new `PATH` |
  1346. | Your agent's sandbox blocks the download or `~/.showtime` | `showtime doctor` names the setting to change for that agent; or run `showtime setup` yourself once in a normal terminal; or `SHOWTIME_HOME=.showtime showtime setup` to install inside the project |
  1347. | Your agent looks for `bin/showtime` and cannot find it | the entry point is `~/.showtime/bin/showtime` (written by setup) or `<skill folder>/bin/showtime`; the plugin's top folder has no `bin/` |
  1348. | `showtime doctor` takes minutes right after a restart | normal on the first run: the OS (macOS especially) checks the native libraries as they load for the first time. doctor says so and shows what it is checking; later runs take seconds |
  1349. | Claude Code says the showtime MCP server timed out | usually the first start after a reboot, while the OS checks the Node.js binary; run `/mcp` and reconnect, or start Claude Code with `MCP_TIMEOUT=60000`. The `showtime` skill works without it |
  1350. | Setup was interrupted | run it again; downloads resume and finished items are skipped |
  1351. | Files look corrupt | `showtime setup --verify` re-hashes everything; `--force` reinstalls |
  1352. | You want your own binaries | set `SHOWTIME_FFMPEG`, `SHOWTIME_CHROME`, `SHOWTIME_NODE` or `SHOWTIME_PYTHON` |
  1353. | Output colours or progress bars clutter logs | `NO_COLOR=1`; progress is plain lines automatically when not in a terminal |
  1354. Platform notes (by design; see the status above): Apple Silicon runs everything natively and renders
  1355. WebGL through Metal; Intel Macs get the last x86_64 builds of ONNX Runtime and numba automatically; on
  1356. Windows, drive letters, spaces and parentheses in paths are handled everywhere, including inside ffmpeg
  1357. filters; Linux machines without a GPU render WebGL through SwiftShader. Hardware encoders and macOS-only
  1358. features are used only when present, with portable fallbacks.
  1359. </details>
  1360. <details>
  1361. <summary><b>Use showtime from other tools (MCP)</b></summary>
  1362. showtime ships an MCP server (`skills/showtime/mcp/server.mjs`, Node only, no extra install) with a
  1363. small set of coarse tools: `doctor`, `new_project`, `render`, `check`, `qa`, `export_html`, `deliver_exports`,
  1364. `receipt`, `guide` and `status` by default, and with `SHOWTIME_MCP_TOOLS=all` also `snap`, `voice_say`,
  1365. `voice_script`, `transcribe`, `audio_compose`, `audio_sfx`, `audio_mix`, `audio_search`, `studio_open` and
  1366. `studio_feedback` (the Claude Desktop bundle lists them all). Each runs the matching `showtime`
  1367. command on your machine and answers with a short summary and the paths it wrote; a tool that runs longer than about
  1368. 20 seconds answers with a task id, and `status` reports progress and the result. The plugins register it for you.
  1369. For Claude Desktop or any other MCP client, run `~/.showtime/bin/showtime mcp` (see [MCP only](#mcp-only) for the
  1370. snippet and the npm and `.mcpb` routes); the snippet for each client is in
  1371. [references/mcp.md](skills/showtime/references/mcp.md), next to the plugin settings (default voice and
  1372. language, a CPU limit) and the render progress monitor.
  1373. </details>
  1374. ## Docs
  1375. <p align="center"><picture>
  1376. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/diagrams/docs-map-dark.svg">
  1377. <img alt="The documentation map: eighteen workflows (launch video, explainer, tutorial, social short, data story, footage edit, trailer, slideshow, changelog video, music video, voice-over only, localize, repo explainer, paper explainer, repro, diagram, recap, x-ray), then five acts and a finale of guides, from onboarding to qa and review." src="assets/readme/diagrams/docs-map-light.svg" width="100%">
  1378. </picture></p>
  1379. For people: [seventeen task guides](docs/guides/README.md) (what to say to your agent, what it runs, what you get, how
  1380. long it takes), [What's new](docs/whats-new.md) (each release in one sentence a feature) and the [FAQ](docs/faq.md)
  1381. (GPUs, cost, agents, privacy, licences, disk, time, platforms, languages).
  1382. The [documentation map](docs/README.md) is the way in: every guide, grouped by what you are making, from
  1383. workflows (launch, explainer, tutorial, social, data, footage, trailer, diagram, recap, repro, X-ray) to story and craft, sound and
  1384. voice, rendering, and QA. The glossary is in [CONTEXT.md](CONTEXT.md), and what showtime deliberately
  1385. does not do, and why, is in [.out-of-scope/](.out-of-scope/README.md).
  1386. Installing in a particular agent: [docs/agents.md](docs/agents.md) has the exact steps for each, and what each
  1387. test covered. The same guides are also a searchable site, with the gallery playing every example:
  1388. **[faviovazquez.github.io/showtime](https://faviovazquez.github.io/showtime/)**.
  1389. ## License and credits
  1390. showtime's own code is MIT licensed ([LICENSE](LICENSE)). Setup downloads third-party tools and models
  1391. under their own licenses, recorded per item in `skills/showtime/setup/manifest.json`. Notable ones: the
  1392. static ffmpeg builds are GPL; Kokoro is Apache-2.0; Whisper models are MIT; Parakeet (NVIDIA) and TitaNet
  1393. are CC-BY-4.0; the vocal separator UVR-MDX-NET-Voc_FT is MIT, by the Ultimate Vocal Remover project (UVR)
  1394. and its developers; MODNet (the speaker cutout behind a big word, `footage cutout`) is Apache-2.0, code and
  1395. weights, by Zhanghan Ke and co-authors; CrisperWhisper 2.0 weights (opt-in only, `--model crisper`) are non-commercial and
  1396. ask for your acceptance first; Supertonic weights are OpenRAIL-M; FluidR3Mono and MuseScore General are MIT; GeneralUser GS
  1397. (optional) has its own free license; MusicGen weights (optional) are CC-BY-NC-4.0, non-commercial. The
  1398. brand (Curtain Call) is described in [assets/brand/](assets/brand/BRAND.md). The produced-music catalog is
  1399. by Scott Buckley and Kevin MacLeod (CC BY 4.0) plus CC0 and public-domain recordings; the tracks stay on their
  1400. creators' sites, are fetched on first use, and every render that uses one writes its credit into `credits.txt`
  1401. and the post copy (a track that needs a credit and has none stops the mix). Each example credits its
  1402. sources in its own folder, and example 13 is CC BY-SA 4.0, like the article it adapts. The videos you
  1403. make are yours; when a render uses an asset that needs attribution, showtime writes `credits.txt` next
  1404. to it.
  1405. ## Contributing
  1406. See [CONTRIBUTING.md](CONTRIBUTING.md) and the glossary in [CONTEXT.md](CONTEXT.md).
  1407. ```bash
  1408. python3 skills/showtime/tests/run_all.py --fast # what CI runs on every pull request (py on Windows)
  1409. python3 skills/showtime/tests/run_all.py --changed # only the tests your change can affect
  1410. python3 scripts/check_release.py --check # release hygiene
  1411. ```
  1412. <p align="center"><sub>Status: 0.4, early. Commands and file formats may still change before 1.0 (see <a href="CHANGELOG.md">CHANGELOG.md</a>).</sub></p>
skills/showtime/lib/st/platform.py · Bundled script · 618 lines · 1 finding marked
  1. """Operating-system and architecture helpers for showtime.
  2. Stdlib only and Python 3.8+ compatible: the launcher, the installer and the
  3. doctor import this module before the showtime virtualenv exists.
  4. Everything that differs between macOS, Windows and Linux lives here:
  5. platform keys, executable suffixes, browser discovery, opening files,
  6. Chrome GPU flag sets and ffmpeg filter-argument escaping.
  7. """
  8. from __future__ import annotations
  9. import json
  10. import os
  11. import re
  12. import shutil
  13. import subprocess
  14. import sys
  15. import sysconfig
  16. from pathlib import Path, PurePath, PureWindowsPath
  17. from typing import Any, Dict, Iterable, List, Optional, Union
  18. PathLike = Union[str, "os.PathLike[str]"]
  19. IS_WINDOWS = os.name == "nt"
  20. IS_MAC = sys.platform == "darwin"
  21. IS_LINUX = sys.platform.startswith("linux")
  22. # --------------------------------------------------------------------------
  23. # OS / architecture
  24. # --------------------------------------------------------------------------
  25. def os_name() -> str:
  26. """Return 'mac', 'windows' or 'linux' (other Unixes report 'linux')."""
  27. if IS_MAC:
  28. return "mac"
  29. if IS_WINDOWS:
  30. return "windows"
  31. return "linux"
  32. def _machine() -> str:
  33. # sysconfig/platform.machine() would do; avoid importing the stdlib
  34. # `platform` module under a name clash when this file is run oddly.
  35. m = ""
  36. try:
  37. m = os.uname().machine # type: ignore[attr-defined]
  38. except AttributeError:
  39. m = os.environ.get("PROCESSOR_ARCHITEW6432") or os.environ.get("PROCESSOR_ARCHITECTURE", "")
  40. return (m or sysconfig.get_platform().split("-")[-1]).lower()
  41. def _mac_is_translated() -> bool:
  42. """True when this (x86_64) process runs under Rosetta on Apple Silicon."""
  43. if not IS_MAC:
  44. return False
  45. try:
  46. out = subprocess.run(["sysctl", "-n", "sysctl.proc_translated"],
  47. capture_output=True, text=True, timeout=5)
  48. return out.stdout.strip() == "1"
  49. except (OSError, subprocess.SubprocessError):
  50. return False
  51. _WIN_ARM64: Optional[bool] = None
  52. def _win_native_arm64() -> bool:
  53. """True on Windows on Arm, also when this process is x64 code run by Windows' emulation.
  54. An emulated x64 process sees PROCESSOR_ARCHITECTURE=AMD64, so the environment cannot tell;
  55. IsWow64Process2 (Windows 10 1709+) reports the machine's native architecture.
  56. """
  57. global _WIN_ARM64
  58. if not IS_WINDOWS:
  59. return False
  60. if _WIN_ARM64 is None:
  61. _WIN_ARM64 = False
  62. try:
  63. import ctypes
  64. from ctypes import wintypes
  65. k32 = ctypes.WinDLL("kernel32", use_last_error=True)
  66. fn = getattr(k32, "IsWow64Process2", None)
  67. if fn is not None:
  68. k32.GetCurrentProcess.restype = wintypes.HANDLE
  69. fn.argtypes = [wintypes.HANDLE, ctypes.POINTER(ctypes.c_ushort), ctypes.POINTER(ctypes.c_ushort)]
  70. fn.restype = wintypes.BOOL
  71. proc, native = ctypes.c_ushort(0), ctypes.c_ushort(0)
  72. if fn(k32.GetCurrentProcess(), ctypes.byref(proc), ctypes.byref(native)):
  73. _WIN_ARM64 = native.value == 0xAA64 # IMAGE_FILE_MACHINE_ARM64
  74. except Exception: # noqa: BLE001
  75. _WIN_ARM64 = False
  76. return _WIN_ARM64
  77. def arch() -> str:
  78. """Hardware architecture: 'arm64' or 'x64' (others returned verbatim).
  79. On an Apple Silicon Mac this reports 'arm64' even when the current
  80. Python runs under Rosetta, so native binaries get installed. On Windows
  81. on Arm it reports 'arm64' even when the current Python is x64 code run by
  82. Windows' emulation (showtime's own venv is x64 there; see binary_key()).
  83. """
  84. m = _machine()
  85. if m in ("arm64", "aarch64", "armv8l", "arm64e"):
  86. return "arm64"
  87. if m in ("x86_64", "amd64", "x64", "i686-64"):
  88. if _mac_is_translated() or _win_native_arm64():
  89. return "arm64"
  90. return "x64"
  91. return m
  92. def platform_key() -> str:
  93. """'mac-arm64', 'mac-x64', 'win-x64', 'win-arm64', 'linux-x64', 'linux-arm64'."""
  94. o = {"mac": "mac", "windows": "win", "linux": "linux"}[os_name()]
  95. return "%s-%s" % (o, arch())
  96. # Where a download has no build for this platform, use another platform's: Windows 11 on Arm runs
  97. # x64 programs through its built-in emulation (tools without an arm64 build such as deep-filter;
  98. # its native ffmpeg is used when the manifest lists one).
  99. BINARY_FALLBACK = {"win-arm64": "win-x64"}
  100. def binary_key(key: Optional[str] = None) -> str:
  101. """The platform key whose prebuilt binaries (ffmpeg, tools, Python wheels) this machine uses."""
  102. key = key or platform_key()
  103. return BINARY_FALLBACK.get(key, key)
  104. def pick_for_platform(table: Dict[str, Any], key: Optional[str] = None) -> Any:
  105. """table[key], else the entry for binary_key(key) (None when neither exists)."""
  106. key = key or platform_key()
  107. got = table.get(key)
  108. if got is None and binary_key(key) != key:
  109. got = table.get(binary_key(key))
  110. return got
  111. def exe(name: str) -> str:
  112. """Append '.exe' on Windows (idempotent)."""
  113. if IS_WINDOWS and not name.lower().endswith(".exe"):
  114. return name + ".exe"
  115. return name
  116. def venv_python(venv_dir: PathLike) -> Path:
  117. """Path of the interpreter inside a virtualenv on this OS."""
  118. v = Path(venv_dir)
  119. if IS_WINDOWS:
  120. return v / "Scripts" / "python.exe"
  121. return v / "bin" / "python"
  122. def venv_bin(venv_dir: PathLike) -> Path:
  123. v = Path(venv_dir)
  124. return v / ("Scripts" if IS_WINDOWS else "bin")
  125. def which(name: str, extra_dirs: Iterable[PathLike] = ()) -> Optional[str]:
  126. """shutil.which that first looks in `extra_dirs` (handles .exe/.cmd)."""
  127. for d in extra_dirs:
  128. d = Path(d)
  129. for cand in (d / name, d / exe(name)):
  130. if cand.is_file() and os.access(str(cand), os.X_OK):
  131. return str(cand)
  132. return shutil.which(name)
  133. def user_home() -> Path:
  134. return Path(os.path.expanduser("~"))
  135. def _version_key(name: str) -> tuple:
  136. return tuple(int(x) for x in re.findall(r"\d+", name)[:3])
  137. def default_tool_dirs(name: str) -> List[Path]:
  138. """Folders the official installers put `uv` / `node` in, for when they are not on PATH yet.
  139. Installing uv or Node.js updates PATH for new terminals only: an app that was already open
  140. (Claude Code, an editor) keeps the old PATH until it restarts. Looking in the default install
  141. folders makes a fresh install work at once. Existing folders only, most likely first."""
  142. h = user_home()
  143. env = os.environ
  144. local = Path(env["LOCALAPPDATA"]) if env.get("LOCALAPPDATA") else h / "AppData" / "Local"
  145. roaming = Path(env["APPDATA"]) if env.get("APPDATA") else h / "AppData" / "Roaming"
  146. cands: List[Path] = []
  147. if name == "uv":
  148. # the uv installer (XDG_BIN_HOME, then ~/.local/bin; ~/.cargo/bin for older installs), winget
  149. if env.get("XDG_BIN_HOME"):
  150. cands.append(Path(env["XDG_BIN_HOME"]))
  151. cands += [h / ".local" / "bin", h / ".cargo" / "bin"]
  152. if os_name() == "windows":
  153. cands.append(local / "Microsoft" / "WinGet" / "Links")
  154. else:
  155. cands += [Path("/opt/homebrew/bin"), Path("/usr/local/bin")]
  156. elif name == "node":
  157. if os_name() == "windows":
  158. for var in ("ProgramFiles", "ProgramW6432"):
  159. if env.get(var):
  160. cands.append(Path(env[var]) / "nodejs")
  161. if env.get("NVM_SYMLINK"):
  162. cands.append(Path(env["NVM_SYMLINK"]))
  163. cands += [local / "Volta" / "bin", roaming / "fnm" / "aliases" / "default"]
  164. else:
  165. cands += [Path("/opt/homebrew/bin"), Path("/usr/local/bin"), Path("/usr/bin"),
  166. h / ".volta" / "bin",
  167. h / ".local" / "share" / "fnm" / "aliases" / "default" / "bin",
  168. h / "Library" / "Application Support" / "fnm" / "aliases" / "default" / "bin",
  169. h / ".fnm" / "aliases" / "default" / "bin"]
  170. # nvm: the newest installed version
  171. nvm = Path(env.get("NVM_DIR") or (h / ".nvm")) / "versions" / "node"
  172. try:
  173. vers = sorted((d for d in nvm.iterdir() if d.is_dir()), key=lambda d: _version_key(d.name), reverse=True)
  174. cands += [d / "bin" for d in vers[:1]]
  175. except OSError:
  176. pass
  177. out: List[Path] = []
  178. for d in cands:
  179. f = d / exe(name)
  180. if d not in out and f.is_file() and (os_name() == "windows" or os.access(str(f), os.X_OK)):
  181. out.append(d)
  182. return out
  183. def find_tool(name: str, path: Optional[str] = None) -> Optional[str]:
  184. """`uv` / `node` on PATH (or `path`), else in its default install folder."""
  185. found = shutil.which(name, path=path)
  186. if found:
  187. return found
  188. dirs = default_tool_dirs(name)
  189. return str(dirs[0] / exe(name)) if dirs else None
  190. # --------------------------------------------------------------------------
  191. # Browsers (Chrome / Edge / Chromium) discovery
  192. # --------------------------------------------------------------------------
  193. def _mac_app_candidates() -> List[tuple]:
  194. apps = [
  195. ("chrome", "Google Chrome.app/Contents/MacOS/Google Chrome"),
  196. ("chrome", "Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta"),
  197. ("chrome", "Google Chrome Dev.app/Contents/MacOS/Google Chrome Dev"),
  198. ("chrome", "Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary"),
  199. ("chrome-for-testing", "Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing"),
  200. ("edge", "Microsoft Edge.app/Contents/MacOS/Microsoft Edge"),
  201. ("chromium", "Chromium.app/Contents/MacOS/Chromium"),
  202. ]
  203. roots = [Path("/Applications"), user_home() / "Applications"]
  204. return [(kind, root / rel) for kind, rel in apps for root in roots]
  205. def _win_candidates() -> List[tuple]:
  206. roots = []
  207. for var in ("PROGRAMFILES", "PROGRAMFILES(X86)", "LOCALAPPDATA", "PROGRAMW6432"):
  208. v = os.environ.get(var)
  209. if v:
  210. roots.append(Path(v))
  211. rels = [
  212. ("chrome", "Google/Chrome/Application/chrome.exe"),
  213. ("chrome", "Google/Chrome Beta/Application/chrome.exe"),
  214. ("chrome", "Google/Chrome SxS/Application/chrome.exe"),
  215. ("edge", "Microsoft/Edge/Application/msedge.exe"),
  216. ("chromium", "Chromium/Application/chrome.exe"),
  217. ]
  218. return [(kind, root / rel) for kind, rel in rels for root in roots]
  219. def _linux_candidates() -> List[tuple]:
  220. out = []
  221. for kind, name in (("chrome", "google-chrome-stable"), ("chrome", "google-chrome"),
  222. ("chromium", "chromium"), ("chromium", "chromium-browser"),
  223. ("edge", "microsoft-edge-stable"), ("edge", "microsoft-edge")):
  224. p = shutil.which(name)
  225. if p:
  226. out.append((kind, Path(p)))
  227. for kind, p in (("chrome", "/opt/google/chrome/chrome"),
  228. ("edge", "/opt/microsoft/msedge/msedge"),
  229. ("chromium", "/usr/lib/chromium/chromium"),
  230. ("chromium", "/snap/bin/chromium")):
  231. out.append((kind, Path(p)))
  232. return out
  233. def playwright_chromium(browsers_dir: Optional[PathLike] = None) -> Optional[Path]:
  234. """Newest Chromium installed by `playwright install chromium` in browsers_dir."""
  235. base = Path(browsers_dir) if browsers_dir else None
  236. if base is None:
  237. env = os.environ.get("PLAYWRIGHT_BROWSERS_PATH")
  238. if env and env != "0":
  239. base = Path(env)
  240. if base is None or not base.is_dir():
  241. return None
  242. patterns = [
  243. "chromium-*/chrome-mac*/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing",
  244. "chromium-*/chrome-mac*/Chromium.app/Contents/MacOS/Chromium",
  245. "chromium-*/chrome-win*/chrome.exe",
  246. "chromium-*/chrome-linux*/chrome",
  247. ]
  248. found: List[Path] = []
  249. for pat in patterns:
  250. found.extend(base.glob(pat))
  251. def rev(p: Path) -> int:
  252. m = re.search(r"chromium-(\d+)", str(p))
  253. return int(m.group(1)) if m else 0
  254. found = [p for p in found if p.is_file()]
  255. return max(found, key=rev) if found else None
  256. def playwright_headless_shell(browsers_dir: Optional[PathLike] = None) -> Optional[Path]:
  257. """Newest Chrome Headless Shell in browsers_dir (installed by showtime setup when no Chrome is found)."""
  258. base = Path(browsers_dir) if browsers_dir else None
  259. if base is None:
  260. env = os.environ.get("PLAYWRIGHT_BROWSERS_PATH")
  261. if env and env != "0":
  262. base = Path(env)
  263. if base is None or not base.is_dir():
  264. return None
  265. found = [p for p in base.glob("chromium_headless_shell-*/chrome-headless-shell-*/chrome-headless-shell*")
  266. if p.is_file() and p.name in ("chrome-headless-shell", "chrome-headless-shell.exe")]
  267. def rev(p: Path) -> int:
  268. m = re.search(r"chromium_headless_shell-(\d+)", str(p))
  269. return int(m.group(1)) if m else 0
  270. return max(found, key=rev) if found else None
  271. def system_browsers_allowed() -> bool:
  272. """SHOWTIME_SYSTEM_BROWSER=0 ignores installed Chrome/Edge/Chromium (tests; a system browser that misbehaves)."""
  273. return os.environ.get("SHOWTIME_SYSTEM_BROWSER", "1").strip().lower() not in ("0", "false", "no", "off")
  274. def find_browsers(browsers_dir: Optional[PathLike] = None) -> List[Dict[str, str]]:
  275. """All usable Chromium-family browsers, best first.
  276. Order: $SHOWTIME_CHROME, then system Chrome, Edge, Chromium, then the
  277. Playwright-managed Chromium in `browsers_dir`, then the Chrome Headless Shell
  278. (headless only; what a default install gets when no browser is installed).
  279. """
  280. seen = set()
  281. result: List[Dict[str, str]] = []
  282. def add(kind: str, path: Union[str, Path], source: str) -> None:
  283. p = str(path)
  284. key = os.path.normcase(os.path.realpath(p))
  285. if key in seen or not os.path.isfile(p):
  286. return
  287. seen.add(key)
  288. result.append({"kind": kind, "path": p, "source": source})
  289. env = os.environ.get("SHOWTIME_CHROME") or os.environ.get("CHROME_PATH")
  290. if env:
  291. add("custom", env, "env")
  292. cands = {"mac": _mac_app_candidates, "windows": _win_candidates,
  293. "linux": _linux_candidates}[os_name()]() if system_browsers_allowed() else []
  294. for kind in ("chrome", "edge", "chromium", "chrome-for-testing"):
  295. for k, p in cands:
  296. if k == kind:
  297. add(kind, p, "system")
  298. pw = playwright_chromium(browsers_dir)
  299. if pw:
  300. add("playwright", pw, "playwright")
  301. shell = playwright_headless_shell(browsers_dir)
  302. if shell:
  303. add("headless-shell", shell, "showtime")
  304. return result
  305. def find_chrome(browsers_dir: Optional[PathLike] = None) -> Optional[Dict[str, str]]:
  306. """Best browser for rendering, or None."""
  307. b = find_browsers(browsers_dir)
  308. return b[0] if b else None
  309. # --------------------------------------------------------------------------
  310. # Chrome launch flags (single source of truth shared with scripts/lib/chrome.mjs)
  311. # --------------------------------------------------------------------------
  312. def _flags_file() -> Path:
  313. return Path(__file__).resolve().parents[2] / "scripts" / "lib" / "chrome-flags.json"
  314. def chrome_flags(gpu: str = "auto", os_key: Optional[str] = None) -> List[str]:
  315. """Launch flags for headless capture.
  316. gpu: 'auto' (per-OS hardware path), 'on' (same as auto), 'off'/'software'
  317. (SwiftShader, slower but closer to bit-exact across machines).
  318. """
  319. data = json.loads(_flags_file().read_text(encoding="utf-8"))
  320. o = os_key or os_name()
  321. flags = list(data["common"])
  322. mode = "software" if gpu in ("off", "software", "swiftshader") else "gpu"
  323. if mode == "gpu":
  324. flags += data["gpu"].get(o, [])
  325. else:
  326. flags += data["software"]
  327. return flags
  328. # --------------------------------------------------------------------------
  329. # Opening files / URLs for the user
  330. # --------------------------------------------------------------------------
  331. def open_path(target: Union[str, PathLike], browser: Optional[str] = None) -> bool:
  332. """Open a file, folder or URL with the desktop's default handler.
  333. If `browser` (an executable path) is given and target is a URL or HTML
  334. file, open it in that browser instead. Returns False if nothing worked.
  335. """
  336. t = str(target)
  337. is_url = bool(re.match(r"^[a-zA-Z][a-zA-Z0-9+.-]*://", t))
  338. try:
  339. if browser:
  340. subprocess.Popen([browser, t if is_url else Path(t).resolve().as_uri()],
  341. stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
  342. return True
  343. if IS_WINDOWS:
  344. os.startfile(t) # type: ignore[attr-defined]
  345. return True
  346. if IS_MAC:
  347. subprocess.Popen(["open", t], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
  348. return True
  349. opener = shutil.which("xdg-open") or shutil.which("gio")
  350. if opener:
  351. args = [opener, t] if opener.endswith("xdg-open") else [opener, "open", t]
  352. subprocess.Popen(args, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
  353. return True
  354. except OSError:
  355. pass
  356. import webbrowser
  357. return webbrowser.open(t if is_url else Path(t).resolve().as_uri())
  358. # --------------------------------------------------------------------------
  359. # ffmpeg filtergraph escaping
  360. # --------------------------------------------------------------------------
  361. _WIN_ABS = re.compile(r"^(?:[A-Za-z]:[\\/]|\\\\|//)")
  362. def _to_ffmpeg_path_string(p: Union[str, PurePath], absolute: bool) -> str:
  363. """Normalise to the forward-slash form ffmpeg accepts on every OS."""
  364. s = str(p)
  365. windows_style = (isinstance(p, PureWindowsPath) or bool(_WIN_ABS.match(s))
  366. or (IS_WINDOWS and "\\" in s))
  367. if absolute and not _WIN_ABS.match(s) and (IS_WINDOWS or not windows_style):
  368. # Only make real local paths absolute (pure Windows paths in unit
  369. # tests on POSIX are left alone).
  370. s = os.path.abspath(s)
  371. if windows_style or IS_WINDOWS:
  372. return PureWindowsPath(s).as_posix()
  373. return s
  374. def _av_escape(s: str, special: str) -> str:
  375. """Escape for libavutil's av_get_token(): backslash-escape `special`,
  376. backslash and quote; protect leading/trailing whitespace."""
  377. out = []
  378. for i, ch in enumerate(s):
  379. if ch in special or ch in "\\'":
  380. out.append("\\" + ch)
  381. elif ch in " \t\r\n" and (i == 0 or i == len(s) - 1):
  382. out.append("\\" + ch)
  383. else:
  384. out.append(ch)
  385. return "".join(out)
  386. def filter_value(value: str) -> str:
  387. """Escape an arbitrary option value for use inside a filtergraph string.
  388. Two escaping levels are applied: the filter's own option parser
  389. (special ':') and the filtergraph parser (special '[],;'). The result
  390. is meant for arg-list subprocess calls (no shell quoting needed), e.g.
  391. ["-vf", "subtitles=filename=" + filter_path(p)].
  392. """
  393. # '=' matters for positional values such as subtitles=<path>, where the
  394. # option parser first tries to read a key terminated by '=' or ':'.
  395. level1 = _av_escape(value, ":=")
  396. return _av_escape(level1, "[],;")
  397. def filter_path(p: Union[str, PurePath], absolute: bool = True) -> str:
  398. """Escape a file path for ffmpeg filter options (subtitles=, ass=,
  399. lut3d=, movie=, amovie=, drawtext fontfile=/textfile=, arnndn m=...).
  400. - Windows paths become forward-slash paths (``C:/Users/me/x.ass``); the
  401. drive colon is escaped so it is not read as an option separator.
  402. - Quotes, backslashes, ``: , ; [ ]`` and edge whitespace are escaped for
  403. both parsing levels.
  404. Pass the result as part of an argument list, never through a shell.
  405. """
  406. return filter_value(_to_ffmpeg_path_string(p, absolute))
  407. def concat_list_path(p: Union[str, PurePath]) -> str:
  408. """Quote a path for an ffmpeg concat-demuxer list file line: file '<here>'."""
  409. s = _to_ffmpeg_path_string(p, True)
  410. return "'" + s.replace("'", "'\\''") + "'"
  411. # --------------------------------------------------------------------------
  412. # Misc
  413. # --------------------------------------------------------------------------
  414. def cpu_count() -> int:
  415. try:
  416. return len(os.sched_getaffinity(0)) # type: ignore[attr-defined]
  417. except (AttributeError, OSError):
  418. return os.cpu_count() or 2
  419. # Windows: onnxruntime (voices, transcription, cutouts) needs the Microsoft Visual C++ 2015-2022 runtime.
  420. # Python ships vcruntime140*.dll next to python.exe, but not msvcp140.dll, so a machine without the
  421. # runtime fails with an unclear "DLL load failed while importing onnxruntime_pybind11_state".
  422. VC_REDIST_URL = "https://aka.ms/vs/17/release/vc_redist.x64.exe"
    • Note: Links to a Windows program from code, which is how droppers fetch their payload
    • Line 521 on GitHub
  423. VC_DLLS = ("msvcp140.dll", "vcruntime140.dll", "vcruntime140_1.dll")
  424. # the same probe as a snippet for another interpreter (the venv's Python can be x64 under an arm64 launcher)
  425. VC_CHECK_CODE = ("import ctypes, json\nbad = []\nfor d in %r:\n try: ctypes.WinDLL(d)\n"
  426. " except OSError: bad.append(d)\nprint(json.dumps(bad))" % (VC_DLLS,))
  427. def missing_vc_runtime(python: Optional[PathLike] = None) -> List[str]:
  428. """The Visual C++ runtime DLLs that do not load (Windows only; [] elsewhere or when the probe cannot run).
  429. With `python`, probes in that interpreter (the venv's), else in this process."""
  430. if not IS_WINDOWS:
  431. return []
  432. if python is None:
  433. import ctypes
  434. bad = []
  435. for d in VC_DLLS:
  436. try:
  437. ctypes.WinDLL(d) # type: ignore[attr-defined]
  438. except OSError:
  439. bad.append(d)
  440. return bad
  441. try:
  442. cp = subprocess.run([os.fspath(python), "-c", VC_CHECK_CODE], stdout=subprocess.PIPE, stderr=subprocess.PIPE,
  443. encoding="utf-8", errors="replace", timeout=60)
  444. return [str(x) for x in json.loads((cp.stdout or "").strip().splitlines()[-1])]
  445. except (OSError, ValueError, IndexError, subprocess.SubprocessError):
  446. return []
  447. def vc_runtime_fix(missing: Iterable[str] = ()) -> str:
  448. names = ", ".join(missing)
  449. return ("install the Microsoft Visual C++ 2015-2022 x64 runtime%s: %s (run it, then run the command again)"
  450. % ((" (missing %s)" % names) if names else "", VC_REDIST_URL))
  451. def explain_dll_error(message: str) -> Optional[str]:
  452. """A fix for Windows' "DLL load failed" import errors (onnxruntime, cv2, av ...), or None."""
  453. if not IS_WINDOWS or "DLL load failed" not in str(message):
  454. return None
  455. missing = missing_vc_runtime()
  456. if missing or "onnxruntime" in str(message):
  457. return vc_runtime_fix(missing)
  458. return None
  459. XVFB_FIX = ("install Xvfb (a virtual display): Debian/Ubuntu: sudo apt install xvfb; Fedora: sudo dnf install "
  460. "xorg-x11-server-Xvfb; Arch: sudo pacman -S xorg-server-xvfb")
  461. def gl_display_prefix(env: Optional[Dict[str, str]] = None, os_key: Optional[str] = None) -> tuple:
  462. """Command prefix that gives an OpenGL program (ManimGL) a display: (prefix, problem).
  463. macOS, Windows and Linux desktops need nothing. A Linux server without DISPLAY / WAYLAND_DISPLAY gets
  464. `xvfb-run` when it is installed; otherwise the prefix is empty and `problem` says how to fix it."""
  465. env = os.environ if env is None else env
  466. if (os_key or os_name()) != "linux" or env.get("DISPLAY") or env.get("WAYLAND_DISPLAY"):
  467. return [], None
  468. xr = shutil.which("xvfb-run", path=env.get("PATH"))
  469. if xr:
  470. return [xr, "-a", "-s", "-screen 0 1920x1080x24"], None
  471. return [], "no display on this Linux machine and no xvfb-run: " + XVFB_FIX
  472. def uptime_seconds() -> Optional[float]:
  473. """Seconds since the machine booted, or None when it cannot be read (never raises)."""
  474. try:
  475. if IS_LINUX:
  476. with open("/proc/uptime", "r") as f:
  477. return float(f.read().split()[0])
  478. if IS_WINDOWS:
  479. import ctypes
  480. fn = ctypes.windll.kernel32.GetTickCount64 # type: ignore[attr-defined]
  481. fn.restype = ctypes.c_ulonglong
  482. return fn() / 1000.0
  483. if IS_MAC:
  484. import time as _time
  485. out = subprocess.run(["sysctl", "-n", "kern.boottime"], stdout=subprocess.PIPE,
  486. stderr=subprocess.DEVNULL, encoding="utf-8", timeout=5).stdout
  487. m = re.search(r"sec\s*=\s*(\d+)", out or "")
  488. return (_time.time() - int(m.group(1))) if m else None
  489. except (OSError, ValueError, AttributeError, subprocess.SubprocessError):
  490. return None
  491. return None
  492. def summary() -> Dict[str, str]:
  493. return {
  494. "os": os_name(),
  495. "arch": arch(),
  496. "key": platform_key(),
  497. "python": sys.version.split()[0],
  498. "python_exe": sys.executable,
  499. "cpus": str(cpu_count()),
  500. }
  501. if __name__ == "__main__": # pragma: no cover - manual inspection helper
  502. print(json.dumps({"platform": summary(), "browsers": find_browsers()}, indent=2))

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.