# showtime

Adopt this skill: https://proskills.md/skills/other/faviovazquez-showtime-skills-showtime

Page: https://proskills.md/skills/other/faviovazquez-showtime-skills-showtime
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/showtime/SKILL.md
size: 8003
upstream: https://github.com/faviovazquez/showtime/blob/main/skills/showtime/SKILL.md

```text
---
name: showtime
description: "Use when the user wants a video made, edited or finished: a launch or promo video, product demo, explainer, trailer or teaser, tutorial or walkthrough, a screen recording turned into a demo, social short, reel, TikTok or YouTube Short, photo slideshow, animated chart or data story, motion graphics or animation, an animated logo intro, outro or sting, lower thirds, an audiogram, music video; captions or subtitles for a video; a voice-over or narration; music or sound effects for a video; a video thumbnail or poster frame; footage edits such as cutting the ums, removing silences, tightening a talking head, podcast or interview clips; reframing to vertical; re-voicing or subtitling a video in another language; turning a repo, website, pull request or changelog into a video; or when they type /showtime. Not for editing still images, writing a caption for a photo post, or code unrelated to a video."
compatibility: Any Agent Skills client with a shell, on macOS, Linux or Windows. Needs Python 3.8+ (or uv) and Node.js 20+; a one-time `showtime setup` downloads the local tools and models into ~/.showtime (or $SHOWTIME_HOME) and needs the network for that step.
---

# showtime

You direct; showtime does the work on this machine: HTML/canvas scenes rendered frame-exactly,
local voices, music, sound effects, transcript-driven footage edits, captions, QA and exports.

**Running it.** Paths are relative to the folder holding this SKILL.md, `<folder>` (Claude Code:
`${CLAUDE_SKILL_DIR}`; if that reads `${...}`, use the folder you read this from), never the plugin root (no `bin/`).
`showtime` means `showtime` on PATH, else `"<folder>/bin/showtime" <cmd>` (no exec bit: prefix
`sh`; Windows: `& "<folder>\bin\showtime.cmd"` in PowerShell, no `&` in cmd). Host kills long commands: `--background`, then
`showtime status <id> --wait 240`. Never call a bare `ffmpeg`.

**`<job>`** is the folder `showtime job init` prints (`showtime-out/<slug>-<timestamp>/`) or its name
(`launch` = the newest `launch-*`). Renders never overwrite (`final-2.mp4`); commands given `<job>`
use its latest file and say which.

## Modes

- **Quick (default).** Open with one line of assumptions ("Quick mode: 20 s, 16:9, upbeat; no
  voice-over. Quality mode (default): full review; say 'lean' for a cheaper draft pass.") and start
  working; do not wait for a reply. Ask (1-2 questions, each with a recommended answer) only when
  the request is ambiguous: nothing to work from, or two readings that make different videos. Wait
  for a yes only before a destructive step (dropping recorded content, touching their files) or an
  expensive one (a large install, a render over ~10 min).
- **Review: quality (default) or lean.** Quality reviews every finished video. Lean
  (`--mode lean`) only when the user says lean, cheap, quick/rough draft or don't review: critic
  only when publish-bound.
- **Studio (opt-in)** when the user says studio, brainstorm, show me options or concepts first,
  storyboard it first, or wants control. Offer it once, in the opening line, for high-stakes work
  with an open direction. Then follow `references/studio.md`.
- Switching, questions, the delivery card: `references/modes.md`.

## Pipeline

Log each stage boundary: `showtime job note <job> --stage <name> --verified ... --assumed ... --next ...`.

0. **Start.** `showtime job init <slug> --request "<verbatim>"` (`--platform reels|youtube|...` when
   named; qa checks it) checks setup. NOT READY: `showtime setup --estimate`, give size
   and time, then `showtime setup`; skipping it is the user's call, never a bare-ffmpeg
   stand-in (`references/onboarding.md`). *Done when:* it says ready.
1. **Understand.** Gather the inputs: repo, URL, footage, brief.
   Inspect before asking; with no path given, look in the working folder (one candidate: use
   it and say so). Launch/promo: `showtime brand capture <repo|url> --job <job>` first; else a
   kit only if the look must match.
   *Done when:* you can write the one-sentence contract (`references/story.md`) and SHOWTIME.md
   lists the assumptions.
2. **Plan.** Story, tone, structure, voice script, storyboard with a duration per scene. For
   voice-led videos run `showtime voice script <script> --fit <seconds>` first: the real line lengths
   (`timeline.json` slots) set the scene lengths, and in a project
   `showtime retime <project> --from-voice <project>/voice/timeline.json` applies them.
   *Done when:* durations sum to the target and every claim traces to a source.
3. **First look.** Project: `showtime new <template> <job>/project --duration <len>` (the whole
   timeline scales; later: `showtime retime`), then `showtime check <project>` and
   `showtime look <project>`. Footage (EDL in `<job>/edit/`): `showtime edit render <job> --preview`,
   then `showtime edit view <job>`. Fix what the images show. Quick mode: show the user and keep
   going; studio: the animatic is the gate.
   *Done when:* check reports 0 errors and every WARN is read (footage: `edit check` passes and you
   read every view PNG).
4. **Build.** Project: compose the hook complete at t=0 (`"poster": 0`), then
   `showtime render <project> --job <job>` (`final.mp4`, `poster.jpg`; a later poster is baked into
   frame 0 only when it matches the opening).
   Footage: `showtime edit render <job> -o <job>/final.mp4`; poster via
   `showtime deliver poster <job> --at <t> --bake` (the baked file becomes the latest final and
   ships). Say the time for anything over 30 s.
   *Done when:* the render finished cleanly.
5. **Verify.** `showtime qa <job>` in the same turn, then `showtime look <job>`, then the critic
   round qa names (`showtime review-pack`, `references/review.md`).
   *Done when:* qa says PASS or WARN, you quoted the verdict with LUFS and true peak, FAILs are fixed,
   no "review pending".
6. **Deliver.** `share.txt` (`references/platforms.md`), credits when qa asks,
   `showtime deliver exports` on request. End with the delivery card: paths, assumptions, cheap vs
   costly changes, three next options. *Done when:* the card is sent and the job note says deliver.

## Situation → workflow

`showtime guide <topic>` prints a topic's Essentials and sections, `<topic> <section>` one section,
`--find <words>` searches all.

| The user wants | `showtime guide` |
|---|---|
| a video like one they give | `reference` |
| a launch or promo from a repo, URL or site folder | `launch-video` |
| an explainer or how-it-works film | `explainer` |
| a repo or codebase explained | `repo-explainer` |
| a paper or PDF explained | `paper-explainer` |
| a tutorial, walkthrough, screen-recorded demo | `tutorial` |
| a reel, TikTok, Short, vertical clip, audiogram, or any vertical explainer | `social-short` |
| numbers or a chart that moves (a CSV: `showtime data import`) | `data-story` |
| their footage cut, captioned, reframed, cleaned (even a reel) | `footage-edit` |
| picture cut to a song | `music-video` |
| a PR, release or changelog | `changelog-video` |
| a trailer, teaser | `trailer` |
| photos or screenshots with music | `slideshow` |
| narration over existing video | `voiceover-only` |
| the same video, another language | `localize` |
| math: equations, proofs, graphs, grid transforms | `manim` |
| a logo sting, lower third, title or motion graphic | `components`, then `render` (`--alpha` for editors) |
| a thumbnail or poster | `platforms` §4 (`showtime deliver thumb`) |

## References (read when)

| Topic | Read when |
|---|---|
| `story`, `tones`, `reference` | before writing any plan |
| `render`, `stage-api`, `adopt` | building, rendering, adopting video code |
| `components`, `film-api` | choosing DOM components or drawing a canvas film |
| `voice`, `audio` | narration, music, effects, mixing |
| `editing`, `captions` | real footage and captions |
| `capture`, `brand-kit` | material from a repo, site, PDF or brand |
| `qa`, `review` | verifying and critiquing |
| `looking` | before open
```

## File: README.md
upstream: https://github.com/faviovazquez/showtime/blob/main/README.md

````text
<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/readme/hero-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="assets/readme/hero-light.svg">
    <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%">
  </picture>
</p>

https://github.com/user-attachments/assets/638bfa30-522f-4e7c-ab9e-e77f364e7dc9

<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>
<!-- /HERO -->

<p align="center">
  <a href="LICENSE"><img alt="license: MIT" src="assets/readme/badges/license.svg" height="24"></a>
  <img alt="runs on your machine" src="assets/readme/badges/local.svg" height="24">
  <img alt="API keys: none" src="assets/readme/badges/keys.svg" height="24">
  <a href="#works-with"><img alt="tested with Claude Code, Codex, Cursor, Devin and OpenCode" src="assets/readme/badges/agents.svg" height="24"></a>
  <a href="CHANGELOG.md"><img alt="status: 0.4, early" src="assets/readme/badges/status.svg" height="24"></a>
  <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>
  <a href="#requirements"><img alt="still to run: Windows 10/11 desktop" src="assets/readme/badges/windows.svg" height="24"></a>
</p>

<h3 align="center">A local video studio for your coding agent.<br>Describe a video. Your agent directs. Your machine renders.</h3>

<p align="center">
Motion graphics, voice-over, music, sound design, captions, footage editing and platform exports,
with no cloud AI services, no API keys and no uploads. Works in Claude Code, Codex, Cursor, Devin,
OpenCode and any agent that supports <a href="https://agentskills.io">Agent Skills</a>.
</p>

<p align="center">
  <a href="#quick-start"><b>Quick start</b></a> ·
  <a href="#x-ray"><b>X-ray</b></a> ·
  <a href="#works-with"><b>Works with</b></a> ·
  <a href="#now-showing"><b>Gallery</b></a> ·
  <a href="#how-it-works"><b>How it works</b></a> ·
  <a href="#meet-the-crew"><b>The crew</b></a> ·
  <a href="#studio-mode"><b>Studio</b></a> ·
  <a href="#what-you-get"><b>Formats</b></a> ·
  <a href="docs/README.md"><b>Docs</b></a> ·
  <a href="https://faviovazquez.github.io/showtime/"><b>Site</b></a> ·
  <a href="#requirements"><b>Requirements</b></a>
</p>

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="assets/readme/divider-dark.svg">
  <img alt="" src="assets/readme/divider-light.svg" width="100%">
</picture>

## Quick start

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:

```text
/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:**

```text
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">
    <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%">
  </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's new in 0.4.5** (the list is [below](#new-in-045), and [What's new](docs/whats-new.md) has a short
paragraph for each):

- **X-ray from data and from a recording.** `showtime xray import` turns event times measured in a data stream into a
  film; `xray analyze` takes a WA
````
