Skip to content

A local video studio for your coding agent. Describe a video in one sentence: your agent directs, your machine renders. Claude Code, Codex, Cursor, Devin and more. No API keys, no uploads.

Site and docs: the footer and reference tables no longer scroll sideways, and two step-by-step tutorials (#81)

Favio Vázquez2122ca44520b
diff --git a/README.md b/README.md
index f74d439..0911366 100644
--- a/README.md
+++ b/README.md
@@ -1710,7 +1710,7 @@ language, a CPU limit) and the render progress monitor.
<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%">
</picture></p>
-For people: [fifteen task guides](docs/guides/README.md) (what to say to your agent, what it runs, what you get, how
+For people: [sixteen task guides](docs/guides/README.md) (what to say to your agent, what it runs, what you get, how
long it takes), [What's new](docs/whats-new.md) (each release in one sentence a feature) and the [FAQ](docs/faq.md)
(GPUs, cost, agents, privacy, licences, disk, time, platforms, languages).
diff --git a/assets/readme/tutorials/first-video/01-terminal-job.webp b/assets/readme/tutorials/first-video/01-terminal-job.webp
new file mode 100644
index 0000000..497f435
Binary files /dev/null and b/assets/readme/tutorials/first-video/01-terminal-job.webp differ
diff --git a/assets/readme/tutorials/first-video/02-terminal-check.webp b/assets/readme/tutorials/first-video/02-terminal-check.webp
new file mode 100644
index 0000000..a1c06b4
Binary files /dev/null and b/assets/readme/tutorials/first-video/02-terminal-check.webp differ
diff --git a/assets/readme/tutorials/first-video/03-look.webp b/assets/readme/tutorials/first-video/03-look.webp
new file mode 100644
index 0000000..737233f
Binary files /dev/null and b/assets/readme/tutorials/first-video/03-look.webp differ
diff --git a/assets/readme/tutorials/first-video/04-terminal-render-qa.webp b/assets/readme/tutorials/first-video/04-terminal-render-qa.webp
new file mode 100644
index 0000000..5a4bd11
Binary files /dev/null and b/assets/readme/tutorials/first-video/04-terminal-render-qa.webp differ
diff --git a/assets/readme/tutorials/first-video/05-fix-and-pass.webp b/assets/readme/tutorials/first-video/05-fix-and-pass.webp
new file mode 100644
index 0000000..01743ad
Binary files /dev/null and b/assets/readme/tutorials/first-video/05-fix-and-pass.webp differ
diff --git a/assets/readme/tutorials/first-video/06-final.webp b/assets/readme/tutorials/first-video/06-final.webp
new file mode 100644
index 0000000..27e4bc3
Binary files /dev/null and b/assets/readme/tutorials/first-video/06-final.webp differ
diff --git a/assets/readme/tutorials/first-video/07-terminal-review-pack.webp b/assets/readme/tutorials/first-video/07-terminal-review-pack.webp
new file mode 100644
index 0000000..6123395
Binary files /dev/null and b/assets/readme/tutorials/first-video/07-terminal-review-pack.webp differ
diff --git a/assets/readme/tutorials/first-video/08-review-sheet.webp b/assets/readme/tutorials/first-video/08-review-sheet.webp
new file mode 100644
index 0000000..6a53a14
Binary files /dev/null and b/assets/readme/tutorials/first-video/08-review-sheet.webp differ
diff --git a/assets/readme/tutorials/first-video/09-findings.webp b/assets/readme/tutorials/first-video/09-findings.webp
new file mode 100644
index 0000000..9bbd3ac
Binary files /dev/null and b/assets/readme/tutorials/first-video/09-findings.webp differ
diff --git a/assets/readme/tutorials/first-video/10-terminal-waive.webp b/assets/readme/tutorials/first-video/10-terminal-waive.webp
new file mode 100644
index 0000000..9707879
Binary files /dev/null and b/assets/readme/tutorials/first-video/10-terminal-waive.webp differ
diff --git a/assets/readme/tutorials/first-video/11-receipt.webp b/assets/readme/tutorials/first-video/11-receipt.webp
new file mode 100644
index 0000000..b6bf058
Binary files /dev/null and b/assets/readme/tutorials/first-video/11-receipt.webp differ
diff --git a/assets/readme/tutorials/first-video/clip.webp b/assets/readme/tutorials/first-video/clip.webp
new file mode 100644
index 0000000..75acd1e
Binary files /dev/null and b/assets/readme/tutorials/first-video/clip.webp differ
diff --git a/assets/readme/tutorials/studio/01-terminal-board.webp b/assets/readme/tutorials/studio/01-terminal-board.webp
new file mode 100644
index 0000000..a96c4e7
Binary files /dev/null and b/assets/readme/tutorials/studio/01-terminal-board.webp differ
diff --git a/assets/readme/tutorials/studio/02-board.webp b/assets/readme/tutorials/studio/02-board.webp
new file mode 100644
index 0000000..120a7e7
Binary files /dev/null and b/assets/readme/tutorials/studio/02-board.webp differ
diff --git a/assets/readme/tutorials/studio/03-compare.webp b/assets/readme/tutorials/studio/03-compare.webp
new file mode 100644
index 0000000..d4906b3
Binary files /dev/null and b/assets/readme/tutorials/studio/03-compare.webp differ
diff --git a/assets/readme/tutorials/studio/04-comment.webp b/assets/readme/tutorials/studio/04-comment.webp
new file mode 100644
index 0000000..3c8b28f
Binary files /dev/null and b/assets/readme/tutorials/studio/04-comment.webp differ
diff --git a/assets/readme/tutorials/studio/05-feedback.webp b/assets/readme/tutorials/studio/05-feedback.webp
new file mode 100644
index 0000000..b7439a1
Binary files /dev/null and b/assets/readme/tutorials/studio/05-feedback.webp differ
diff --git a/assets/readme/tutorials/studio/06-terminal-digest.webp b/assets/readme/tutorials/studio/06-terminal-digest.webp
new file mode 100644
index 0000000..6f51d2e
Binary files /dev/null and b/assets/readme/tutorials/studio/06-terminal-digest.webp differ
diff --git a/assets/readme/tutorials/studio/07-storyboard.webp b/assets/readme/tutorials/studio/07-storyboard.webp
new file mode 100644
index 0000000..2bb6902
Binary files /dev/null and b/assets/readme/tutorials/studio/07-storyboard.webp differ
diff --git a/assets/readme/tutorials/studio/08-shot-note.webp b/assets/readme/tutorials/studio/08-shot-note.webp
new file mode 100644
index 0000000..909827f
Binary files /dev/null and b/assets/readme/tutorials/studio/08-shot-note.webp differ
diff --git a/assets/readme/tutorials/studio/09-approve.webp b/assets/readme/tutorials/studio/09-approve.webp
new file mode 100644
index 0000000..a0d60f9
Binary files /dev/null and b/assets/readme/tutorials/studio/09-approve.webp differ
diff --git a/assets/readme/tutorials/studio/10-terminal-storyboard.webp b/assets/readme/tutorials/studio/10-terminal-storyboard.webp
new file mode 100644
index 0000000..3d997d6
Binary files /dev/null and b/assets/readme/tutorials/studio/10-terminal-storyboard.webp differ
diff --git a/assets/readme/tutorials/studio/11-final.webp b/assets/readme/tutorials/studio/11-final.webp
new file mode 100644
index 0000000..c17ffb8
Binary files /dev/null and b/assets/readme/tutorials/studio/11-final.webp differ
diff --git a/assets/readme/tutorials/studio/clip.webp b/assets/readme/tutorials/studio/clip.webp
new file mode 100644
index 0000000..09bcfde
Binary files /dev/null and b/assets/readme/tutorials/studio/clip.webp differ
diff --git a/docs/README.md b/docs/README.md
index 217bef3..a928adb 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -46,6 +46,7 @@ Written for people rather than for your agent:
| Page | Read it when |
|---|---|
| [Your first video](guides/first-video.md) | you are new: a 5-second test video and what each step does |
+| [Studio, step by step](guides/studio-concepts-to-final.md) | you want options first: one real run from concepts to the final film, a screenshot at each step |
| [Task guides](guides/README.md) | you want a recipe: what to say, what your agent runs, what you get, how long it takes |
| [What's new](whats-new.md) | you want each release's new features, one sentence each |
| [Questions people ask](faq.md) | you want short answers: GPU, cost, agents, privacy, licences, disk, time, platforms, languages |
diff --git a/docs/guides/README.md b/docs/guides/README.md
index edf1a86..6305563 100644
--- a/docs/guides/README.md
+++ b/docs/guides/README.md
@@ -2,7 +2,7 @@
Task guides for people. Each one says what to tell your coding agent, the commands it runs, the files you get,
how long it took on a named machine, the phrases that change the result, the honest limits, and an example to
-look at. The references in `skills/showtime/references/` are written for your agent; these are written for you.
+look at. A few guides are tutorials: one real run as numbered steps, a screenshot at each and a short clip at the top, then the same closing sections. The references in `skills/showtime/references/` are written for your agent; these are written for you.
| Guide | When you want |
|---|---|
@@ -16,6 +16,7 @@ look at. The references in `skills/showtime/references/` are written for your ag
| [Make a short film of what your agent did](session-recap.md) | a 30-60 s recap of a Claude Code session for a PR, a standup or a post, from allow-listed facts only |
| [Turn a failing test into a bug-report video](bug-report-video.md) | a failing Playwright test as a narrated video and a summary to paste into the issue |
| [Make an X-ray of a real thing](xray.md) | a clip of a machine or an instrument with its inside drawn moving on the exact frames its sound says, its music as a score, tab or drum sheet, and a receipt that proves it |
+| [Studio: from concepts to the final film](studio-concepts-to-final.md) | open the studio board, compare concepts, leave notes, approve a storyboard and see the final, one real run in eight steps |
| [Make a living diagram, and a live figure](living-diagram.md) | how something works, as a figure that builds itself, and a live figure people hover, step through and tune |
| [Make an explainer that stops and asks](explainer-that-asks.md) | questions the web version stops on, links to a moment or a stretch, link previews |
| [Go all out: a showreel](go-all-out.md) | a hype reel with flash words, a shutter blur on snaps, and WebGL looks |
diff --git a/docs/guides/first-video.md b/docs/guides/first-video.md
index ac3ec75..926195f 100644
--- a/docs/guides/first-video.md
+++ b/docs/guides/first-video.md
@@ -1,8 +1,12 @@
# Make your first video
+<!-- tutorial: numbered steps, each with a screenshot from one real run -->
+
Start here if you have never used showtime. Ask for a 5-second test video: your agent installs what is missing, makes
-the video on your computer and checks it. You learn that the install works, and you see every step a bigger video
-goes through.
+the video on your computer, checks it and has it reviewed. You learn that the install works, and you see every step a
+bigger video goes through. This guide follows one real run, with a screenshot of each step.
+
+![The whole run in 23 seconds: the terminal as the job is made, the check and the first look, the first render and its qa warning, the fixed render, the finished 5-second video, the review sheet and the receipt.](../../assets/readme/tutorials/first-video/clip.webp)
## Say this
@@ -13,44 +17,107 @@ them with `uv --version` and `node --version`, and restart your coding agent. Ad
> "Make a 5-second test video that says hello."
-## What happens
-
-1. **One line of assumptions,** before anything runs: "Quick mode: 5 s, 16:9, no voice-over; full review, say 'lean'
- for a draft pass." It asks a question only when a request could mean two different videos.
-2. **Setup, the first time only.** `showtime job init` stops with "setup has not been run yet". Your agent tells you
- the download (about 0.5 to 0.75 GB, usually 2 to 6 minutes; `showtime setup --estimate` prints yours) and runs
- `showtime setup` once you say yes. A sandbox blocks it? See
- [Troubleshooting](../troubleshooting.md#setup-never-ran-or-the-sandbox-blocked-it).
-3. **A job folder.** `showtime job init hello` makes `showtime-out/hello-<date>-<time>/` for everything this request
- makes ([what is in it](../glossary.md#the-job-folder)).
-4. **A first look.** `showtime new dom <job>/project --duration 5` copies a starter page, fits it to 5 s and dresses
- it in a [look signature](../glossary.md#look-signature). Your agent writes "hello" into it, runs `showtime check`
- and `showtime look`, and shows you a still or a fast draft.
-5. **The render.** `showtime render <job>/project --job <job>` draws every frame in a headless browser on your
- computer. Nothing is uploaded.
-6. **The checks.** `showtime qa <job>` checks the file, the loudness, black or frozen stretches and the poster, and
- prints PASS, WARN or FAIL. In quality mode (the default) a [critic](../glossary.md#critic) then reviews the video;
- until it has, qa says "review pending".
-7. **The delivery card:** the files, the length, the loudness, the qa verdict, the review, what was assumed, and
- three things you could ask for next.
-
-## What you get
-
-- `final.mp4` (1920x1080, 30 fps) and `poster.jpg`. Open `final.mp4`: that is your first video.
-- `receipt.md`: the request as you typed it, the renders, the time, and the tokens and cost when your agent reports
- them. `share.txt` holds the receipt's one line.
-- `project/`: the page your agent wrote. Edit it and ask for a new render; renders never overwrite.
+Your agent writes one line of assumptions before anything runs ("Quick mode: 5 s, 16:9, no voice-over; full review,
+say 'lean' for a draft pass"). It asks a question only when a request could mean two different videos.
+
+## 1. Setup and a job folder
+
+The first time only, `showtime job init` stops with "setup has not been run yet". Your agent tells you the download
+(about 0.5 to 0.75 GB, usually 2 to 6 minutes; `showtime setup --estimate` prints yours) and runs `showtime setup` once
+you say yes. A sandbox blocks it? See [Troubleshooting](../troubleshooting.md#setup-never-ran-or-the-sandbox-blocked-it).
+
+Then the job: a folder, `showtime-out/hello-<date>-<time>/`, for everything this request makes
+([what is in it](../glossary.md#the-job-folder)). `showtime new dom` copies a starter page into it, fits it to 5 s and
+dresses it in a [look signature](../glossary.md#look-signature).
+
+The terminal output in the pictures is trimmed to the lines that matter.
+
+![A terminal: showtime doctor reporting ready, showtime job init hello printing the job folder, and showtime new dom copying the starter page and naming its look.](../../assets/readme/tutorials/first-video/01-terminal-job.webp)
+
+## 2. Your agent writes "hello" and checks the page
+
+Your agent writes the word into the page, `showtime check` tests it before any render (fonts, contrast, text layout,
+that nothing moves by chance), and `showtime look` makes one small image of the key frames.
+
+![A terminal: showtime check printing PASS for page, determinism, fonts, contrast, text layout and timeline plus the phone check, then showtime look naming a look image.](../../assets/readme/tutorials/first-video/02-terminal-check.webp)
+
+The look image is the first thing you can judge: three frames of the page, with nothing rendered yet.
+
+![The look image: three frames of the page, an empty cream background with a peach glow at 0:00, then the word hello over a short rust rule and the line "a five-second test, made on this computer" at 0:03 and 0:04.97.](../../assets/readme/tutorials/first-video/03-look.webp)
+
+## 3. The first render, and what qa says
+
+`showtime render` draws every frame in a headless browser on your computer. Nothing is uploaded. Then `showtime qa`
+checks the file itself: the codec, black or frozen stretches, the poster, the loudness, and what the project says to
+expect. Here it warns that the last 4.1 seconds are a still hold.
+
+![A terminal: showtime render capturing 150 frames and writing final.mp4, then showtime qa printing a WARN, final_hold, a still hold from 0.90 s (the last 4.1 s), with the frame and a fix: shorten the end hold or add subtle motion.](../../assets/readme/tutorials/first-video/04-terminal-render-qa.webp)
+
+## 4. Fix it and render again
+
+Renders never overwrite, so the fixed renders are `final-2.mp4` and `final-3.mp4`. Your agent made two changes:
+a slow drift on the glow so the end is not frozen, and a line in `showtime.json` that says this film is meant to be
+silent, so qa does not ask for music. The fixed file passes.
+
+![Two small code changes (expect audio false in showtime.json; a drift animation in index.html) above showtime qa printing PASS for final-3.mp4, 5.00 s at 1920x1080.](../../assets/readme/tutorials/first-video/05-fix-and-pass.webp)
+
+## 5. Open the video
+
+`final-3.mp4` (1920x1080, 30 fps) and its poster are in the job folder. Open the file: that is your first video. The
+frames below are from the run itself.
+
+![Four frames of the finished video: the word hello fading in at 0.4 s, at full strength at 0.9 s, with the rust rule and the line "a five-second test, made on this computer" at 1.6 s, and the same card at 4.9 s.](../../assets/readme/tutorials/first-video/06-final.webp)
+
+## 6. A critic reviews it
+
+In quality mode (the default) the finished video is reviewed before it counts as done. `showtime review-pack` makes
+a pack of contact sheets, key frames and the qa result, and a second agent, which sees only that pack, writes its
+findings.
+
+![A terminal: showtime review-pack printing round 1, the sheet, the scenes strip, five key frames, four context files and the path of the brief for the critic.](../../assets/readme/tutorials/first-video/07-terminal-review-pack.webp)
+
+![The review sheet: six frames of final-3.mp4, one per second, from 0.00 s to 4.97 s.](../../assets/readme/tutorials/first-video/08-review-sheet.webp)
+
+## 7. Read the findings and answer each one
+
+The verdict here was "ship after fixes": no blockers, four should-fix points and three polish notes. Every finding is
+fixed or waived with a reason. Blocker and should-fix findings hold the delivery until they are answered (until the
+critic's verdict is in, `showtime qa` and the delivery say "review pending"); polish notes never do. For this test
+card all seven were waived, and the reasons are in the receipt:
+
+- a one-frame pop at the start: the first frame is also the poster, on purpose;
+- a glow that stops short of the right and bottom edges: the strip is faint on a test card;
+- a small line of text: this card is not for a phone feed;
+- a 3.6 s still stretch: five seconds is the ask;
+- the three polish notes (timing of the fade, the three parts arriving one after another, no brand on the card): not
+ needed for a test.
+
+On a real video you would fix the should-fix points and render again; the [review and notes guide](notes-and-fixes.md)
+shows that.
+
+![The critic's findings: the verdict ship after fixes, no blockers, and four should-fix points with a time, a frame and a fix for each.](../../assets/readme/tutorials/first-video/09-findings.webp)
+
+![A terminal: showtime review-respond waiving the last polish note with a reason and listing the polish notes as waived, delivery clear with 0 fixed and 4 should-fix waived, then showtime receipt.](../../assets/readme/tutorials/first-video/10-terminal-waive.webp)
+
+## 8. The receipt
+
+`showtime receipt` writes `receipt.md`: the request as you typed it, the review rounds and what became of each
+finding, the renders, the time, and the tokens and cost when your agent reports them. `share.txt` holds one line of it.
+The delivery card your agent shows you has the same facts and three things you could ask for next.
+
+![The receipt: one review round, four should-fix findings waived and none open (it counts should-fix points only), three full renders, 31 seconds of render time in total.](../../assets/readme/tutorials/first-video/11-receipt.webp)
## How long it takes
-Measured for this guide on a 6-core Intel Mac with its GPU, while other jobs kept it busy (load average about 4):
+Measured for this guide on a 6-core Intel Mac (i5-8500), with other jobs running (load average about 3):
| Step | Command | Time |
|---|---|---|
-| Make the job and check setup | `showtime job init hello --request "..."` | 0.8 to 15 s (two runs) |
-| Copy and fit the starter page | `showtime new dom <job>/project --duration 5` | 3 s |
-| Render 5 s at 1080p (3 browsers) | `showtime render <job>/project --job <job>` | 78 s |
-| Check the file | `showtime qa <job>` | 10 s |
+| Make the job and check setup | `showtime job init hello --request "..."` | 6.7 s |
+| Copy and fit the starter page | `showtime new dom <job>/project --duration 5` | 0.8 s |
+| Check the page | `showtime check <job>/project` | 17.3 s |
+| Render 5 s at 1080p | `showtime render <job>/project --job <job>` | 6.5 s (3.9 s capture, 2.6 s encode) |
+| Check the file | `showtime qa <job>` | 1.2 to 2.5 s |
Setup comes first, the first time (usually 2 to 6 minutes). Your agent's writing and the critic's review come on
top and were not timed. More numbers: [render § Speed](../../skills/showtime/references/render.md#speed).
@@ -68,7 +135,9 @@ top and were not timed. More numbers: [render § Speed](../../skills/showtime/re
a brief, footage.
- Setup needs the network once. Bigger pieces (the transcription model, Manim, music tracks) download the first time
a video needs them, with their size shown first. The test video downloads nothing more.
-- Something failed? Ask your agent to run `showtime doctor`, then see [Troubleshooting](../troubleshooting.md).
+- The qa output in steps 3 and 4 was printed again on the saved files for the screenshots, after the silent-film line
+ was in `showtime.json`, so it shows the still-hold warning only. The findings in step 7 are shortened from the
+ critic's reply. Something failed? Ask your agent to run `showtime doctor`, then see [Troubleshooting](../troubleshooting.md).
## The example
diff --git a/docs/guides/studio-concepts-to-final.md b/docs/guides/studio-concepts-to-final.md
new file mode 100644
index 0000000..96b126e
--- /dev/null
+++ b/docs/guides/studio-concepts-to-final.md
@@ -0,0 +1,126 @@
+# Studio: from concepts to the final film
+
+<!-- tutorial: numbered steps, each with a screenshot from one real run -->
+
+Studio mode opens a local board where you choose a concept, compare it with the others, leave notes, approve a
+storyboard, and only then does the film get built. This guide walks through one real run, step by step, with a
+screenshot of each step. The video is a 20-second trailer for Tidepool, a fictional notes app that ships with showtime
+as sample material.
+
+![The whole run in 22 seconds: the board with four concepts, a wipe between two of them, a pick and a comment, the storyboard, the approval and the finished trailer.](../../assets/readme/tutorials/studio/clip.webp)
+
+## Say this
+
+> "Show me options first for a 20-second trailer that tells note-takers everything they write stays on their own
+> machine."
+
+"Options first" (or "studio") is the trigger. Without it, your agent goes straight to a draft.
+
+## 1. Your agent starts the session and builds the board
+
+It makes a job, attaches a studio session to it, writes the concepts into `studio/board.json`, and renders one to
+three style frames for each concept. Then it checks the board and opens it.
+
+![A terminal: showtime studio init, two showtime studio frame runs that render three frames each in under 3 seconds, showtime studio board printing "board OK: rev 1, 4 concepts", and showtime studio open printing a local link.](../../assets/readme/tutorials/studio/01-terminal-board.webp)
+
+The terminal output is trimmed to the lines that matter; `showtime studio frame` runs once per concept. The link is
+local (`127.0.0.1`) and carries a key. It opens nowhere else.
+
+## 2. Open the board
+
+Round 1 is the question "which direction feels like a Tidepool trailer?". There are three concepts and one wildcard.
+Each card has its frames, a one-line pitch, the hook of the first three seconds, a palette, type, music and the risk.
+One concept is marked **Recommended**, with the reason.
+
+![The studio board at round 1: the heading "Which direction feels like a Tidepool trailer?", and cards for C1 Low tide, C2 Macro (recommended) and C3 Keystrokes, each with a style frame.](../../assets/readme/tutorials/studio/02-board.webp)
+
+## 3. Compare two concepts
+
+The **Compare** tab puts any two concepts on one frame. Drag across it to wipe from one to the other.
+
+![The Compare tab: a frame split down the middle, C1 Low tide on the left with its wave line and C2 Macro on the right with the words "Sync: local only".](../../assets/readme/tutorials/studio/03-compare.webp)
+
+## 4. Pick, like and comment
+
+**Pick** chooses a concept. The heart likes one, and you can like a concept you did not pick, to say "keep this part".
+The speech-bubble button opens a comment. Here the reviewer picks C2, likes C1 and writes that the film should land on
+C1's sunrise.
+
+![A comment box on C2 Macro with the text: Frame 1 reads instantly. Land the name on the sunrise from C1.](../../assets/readme/tutorials/studio/04-comment.webp)
+
+Every click is saved on your computer in `studio/feedback.json`. Press **Feedback** to read what you left:
+
+![The Feedback panel listing the pick, the like and the comment, with a box to add a note and a Copy for your agent button.](../../assets/readme/tutorials/studio/05-feedback.webp)
+
+## 5. Your agent reads it and answers
+
+You tell your agent you are done. It runs `showtime studio feedback`, repeats what you said in a few lines, logs the
+decision in `decisions.md` (append-only) and brings out the next round. What you typed on the board is quoted as
+your opinion about the video; it is never run as an instruction.
+
+![A terminal: showtime studio feedback printing the pick C2 Macro, the like on C1 and the comment, then showtime studio decide appending D-002.](../../assets/readme/tutorials/studio/06-terminal-digest.webp)
+
+## 6. Check the storyboard
+
+Round 2 is the storyboard of the concept you picked: every shot with its time range, what is on screen, and a note on
+how it moves. The thumbnails are rendered from the draft project at those moments. Open the **Storyboard** tab, and
+use **Note** under a shot to say what to change.
+
+![The Storyboard tab: shot cards C2.1 to C2.5, with a sixth cut off at the right edge, each with a thumbnail, a time range such as 0:00.0 to 0:02.5, what is on screen and a Note button.](../../assets/readme/tutorials/studio/07-storyboard.webp)
+
+![A comment box on shot C2.1: Hold the first shot a beat longer.](../../assets/readme/tutorials/studio/08-shot-note.webp)
+
+The **Animatic** below the storyboard is a rough cut with the music, to judge pace before anything is rendered;
+`n` adds a note at the moment you are watching.
+
+## 7. Approve
+
+The **Decide** tab has the questions your agent still needs answered, two dials (energy and pace) and an **Approve**
+button for the concept you want built, with a box for final notes.
+
+![The Decide tab: Energy and Pace sliders, "C2 · Macro, ending on the sunrise" chosen in the Ready box, the note "Lock it. Cuts on the beat." and an Approve button.](../../assets/readme/tutorials/studio/09-approve.webp)
+
+Your agent reads the approval, logs it and builds the film. This is the last point to change your mind cheaply.
+
+![A terminal for steps 6 and 7: the storyboard thumbnails rendered, the board checked at rev 2, and showtime studio feedback printing APPROVED: C2 Macro, ending on the sunrise with the final note.](../../assets/readme/tutorials/studio/10-terminal-storyboard.webp)
+
+## 8. See the final
+
+`showtime render` draws every frame on your computer, and `showtime qa` checks the file. For this film the render took
+45 seconds for 20 seconds of 1080p.
+
+![Four frames of the finished trailer: the words "Sync: local only" in macro focus, a task being ticked, a note on local-first software, and the end card: Tidepool, Your notes, kept on your own machine.](../../assets/readme/tutorials/studio/11-final.webp)
+
+In quality mode (the default), a critic reviews the finished film and you can leave notes on it too:
+[Leave notes on a video and get them fixed](notes-and-fixes.md). The finished trailer from an earlier run of this
+same session is [example 09](https://github.com/FavioVazquez/showtime-examples/blob/main/examples/09-studio-trailer/README.md).
+
+## How long it takes
+
+Measured for this guide on a 6-core Intel Mac (i5-8500), while nothing else was rendering:
+
+| Step | What ran | Time |
+|---|---|---|
+| Style frames, one concept | `showtime studio frame ... --html` (3 frames) | 2.8 to 3.2 s (39 s the first time, while the browser started) |
+| Storyboard thumbnails | `showtime studio frame ... --project --at` (8 frames) | 9.6 s |
+| The final render | `showtime render <project> --job <job>` (20 s, 1080p) | 45 s |
+
+Your agent's writing of the concepts and your own time on the board come on top and were not timed.
+
+## Phrases that change it
+
+- "Show me options first", "studio", "I want control": opens the board.
+- "Only stop me for concepts": your agent fills the other stops with its recommended answer and logs them as assumed.
+- "Resume the studio": it reads `brief.md` and `decisions.md` and carries on; it never asks a settled question again.
+- "Export the board": `showtime studio export <job> --inline` makes one HTML file you can send.
+
+## Limits
+
+- The board is local. Anyone you send the link to cannot open it; export it if someone else must look.
+- The style frames show a direction, not the film. A concept can look right in frames and still be hard to animate.
+- Music beds and voice samples also go on the board; this run skipped them to stay short.
+- To keep the run short, the project that was rendered in step 8 is the finished project of example 09, copied to a plain
+ folder; the storyboard thumbnails and the final film come from it. The clicks on the board were made with a headless
+ browser, the way a reviewer would make them.
+- The commands behind each step: [Studio mode](../../skills/showtime/references/studio.md); the board file:
+ [Board format](../../skills/showtime/references/boards.md).
diff --git a/site/build.py b/site/build.py
index f74905e..040eda7 100644
--- a/site/build.py
+++ b/site/build.py
@@ -493,9 +493,27 @@ class Site:
body = re.sub(r"<blockquote>\s*<p>\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]\s*",
lambda m: '<blockquote class="alert"><p class="alert-title">%s</p><p>' % m.group(1).title(), body)
body = self.rewrite(body, src, page)
+ body = mark_url_links(body)
+ body = keep_flags_whole(body)
return body, title, heads
+def mark_url_links(body: str) -> str:
+ """A link whose text looks like an address (a source or a credit) gets class="url", so it may break anywhere and
+ never widens the page; links with words as their text keep wrapping at spaces, and a link that already has a
+ class attribute is left alone."""
+ return re.sub(r'<a(?![^>]*\sclass=) ([^>]*href="https?://[^"]*"[^>]*)>(https?://[^<]*)</a>', r'<a class="url" \1>\2</a>', body)
+
+
+def keep_flags_whole(body: str) -> str:
+ """In a table cell, a command-line flag (--check, -x) is wrapped in a nowrap span so a narrow column breaks the
+ line before it, never after its dashes; the copied text does not change."""
+ flag = re.compile(r'(?<![\w-])(--?[A-Za-z0-9][\w-]*)')
+ code = re.compile(r'<code>([^<]*)</code>')
+ cell = re.compile(r'<td\b[^>]*>.*?</td>', re.S)
+ return cell.sub(lambda c: code.sub(lambda m: '<code>%s</code>' % flag.sub(r'<span class="nb">\1</span>', m.group(1)), c.group(0)), body)
+
+
# ----------------------------------------------------------------------------------------------- the shell
ICON_SUN = ('<svg class="sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" aria-hidden="true">'
diff --git a/site/static/style.css b/site/static/style.css
index 45b768d..f99c8a9 100644
--- a/site/static/style.css
+++ b/site/static/style.css
@@ -257,8 +257,11 @@ p{margin:0}
.prose h2:hover .anchor,.prose h3:hover .anchor,.prose .anchor:focus{opacity:1}
.prose table{display:block;overflow-x:auto;border-collapse:collapse;font-size:.92rem;line-height:1.5;margin:1.6em 0;max-width:100%}
.prose th,.prose td{text-align:left;vertical-align:top;padding:10px 20px 10px 0;border-bottom:1px solid var(--line)}
-.prose th{font-weight:600;color:var(--ink);border-bottom-color:var(--line-2);white-space:nowrap}
-.prose td code{white-space:nowrap}
+.prose th{font-weight:600;color:var(--ink);border-bottom-color:var(--line-2)}
+.prose td code .nb{white-space:nowrap} /* a --flag never breaks after its dashes */
+.prose td code{overflow-wrap:break-word} /* wraps at spaces; a long unbroken token is the only thing that may push the table wider */
+.prose a.url{overflow-wrap:anywhere}
+.prose li,.prose p{overflow-wrap:break-word} /* a credit's file name or bare URL longer than the screen breaks instead of scrolling the page */
.prose td pre{white-space:pre-wrap;font-size:.72rem;padding:10px 12px;margin:10px 0 8px}
.prose td pre code{white-space:inherit}
/* the docs map's Overture (three steps, one with the install block): one step under another on a phone */
@@ -306,7 +309,7 @@ p{margin:0}
footer.site{border-top:1px solid var(--line);padding:40px 0 56px;color:var(--muted);font-size:.88rem}
footer.site .wrap{display:flex;flex-wrap:wrap;gap:12px 32px;align-items:baseline;justify-content:space-between;max-width:1360px}
-footer.site nav{display:flex;gap:20px}
+footer.site nav{display:flex;flex-wrap:wrap;gap:8px 20px}
footer.site a{color:var(--muted);text-decoration:none}
footer.site a:hover{color:var(--ink)}
footer.site .word{font-family:var(--serif);font-weight:900;color:var(--ink);font-size:1.05rem;font-variation-settings:"opsz" 144}
diff --git a/skills/showtime/references/studio.md b/skills/showtime/references/studio.md
index ea1c182..b338644 100644
--- a/skills/showtime/references/studio.md
+++ b/skills/showtime/references/studio.md
@@ -7,7 +7,7 @@ before asking the first studio question. The board format is in `boards.md`.
Quick mode stays the default: one request in, a video out. Studio is opt-in. In studio you **talk
about facts and goals, and show anything about look, sound or timing** as a board: a local page with
lettered options, one recommendation, and buttons the user clicks. Chat stays the source of truth;
-the board is a faster way to answer.
+the board is a faster way to answer. For people: [see it step by step](https://faviovazquez.github.io/showtime/docs/guides/studio-concepts-to-final.html), one real run with a screenshot of each step.
## Essentials
diff --git a/skills/showtime/tests/test_site_build.py b/skills/showtime/tests/test_site_build.py
index 1368d9d..b8de64c 100644
--- a/skills/showtime/tests/test_site_build.py
+++ b/skills/showtime/tests/test_site_build.py
@@ -208,6 +208,76 @@ class OneVersion(unittest.TestCase):
self.assertEqual(build.latest_release(limit=1, text=notes, version="0.4.1"), ("0.4.1", "One; and more."))
self.assertEqual(build.latest_release(text="# nothing\n", version="0.4.1"), ("0.4.1", "See what changed."))
+ def test_footer_nav_wraps_on_a_phone(self):
+ # the public build adds the examples-repo link to the footer nav; without flex-wrap the row grew 3 px past a
+ # 375 px screen (a sideways scroll on every page). The row must be allowed to wrap.
+ css = (REPO / "site" / "static" / "style.css").read_text(encoding="utf-8")
+ rule = re.search(r"footer\.site nav\{([^}]*)\}", css)
+ self.assertIsNotNone(rule)
+ self.assertIn("flex-wrap:wrap", rule.group(1))
+
+ def test_table_cells_wrap_at_spaces(self):
+ # a long command in a reference table (studio Commands) must wrap in its cell: with nowrap the table grew past
+ # its column (920 px in 704), the first column took 758 px and the rows stood 150 px tall
+ css = (REPO / "site" / "static" / "style.css").read_text(encoding="utf-8")
+ for sel in (r"\.prose th", r"\.prose td code"):
+ rule = re.search(sel + r"\{([^}]*)\}", css)
+ self.assertIsNotNone(rule, sel)
+ self.assertNotIn("nowrap", rule.group(1), sel)
+ # break at spaces first; a mid-word break is only for the one token that is longer than the cell
+ self.assertIn("overflow-wrap:break-word", re.search(r"\.prose td code\{([^}]*)\}", css).group(1))
+
+ def test_address_links_may_break_anywhere(self):
+ # sources and credits print their URLs as link text; those links wrap, links with words do not change
+ css = (REPO / "site" / "static" / "style.css").read_text(encoding="utf-8")
+ self.assertIn("overflow-wrap:anywhere", re.search(r"\.prose a\.url\{([^}]*)\}", css).group(1))
+ self.assertIn("overflow-wrap:break-word", re.search(r"\.prose li,\.prose p\{([^}]*)\}", css).group(1)) # bare URLs and file names in credits
+ url = "https://www.eia.gov/totalenergy/data/browser/index.php?tbl=T07.02A"
+ out = build.mark_url_links('<li><a href="%s">%s</a> and <a href="%s">the table</a> <a class="x" href="%s">%s</a></li>'
+ % (url, url, url, url, url))
+ self.assertEqual(out.count('class="url"'), 1)
+ self.assertIn('<a class="url" href="%s">%s</a>' % (url, url), out)
+ self.assertIn('<a href="%s">the table</a>' % url, out)
+ self.assertIn('<a class="x" href="%s">' % url, out)
+
+ def test_render_md_marks_address_links_and_keeps_flags_whole(self):
+ # through the real renderer, not the helpers: deleting the calls in render_md must fail here
+ site = build.Site(Path(tempfile.mkdtemp(prefix="st-md-")), [], "o/r", None, "main")
+ md = ("# T\n\nSource: <https://www.eia.gov/totalenergy/data/browser/index.php?tbl=T07.02A> and "
+ "[the table](https://www.eia.gov/totalenergy/).\n\n| Command | Use |\n|---|---|\n"
+ "| `showtime check --strict -x file` | checks |\n")
+ html, _t, _h = site.render_md(md, build.GUIDES / "x.md", "docs/guides/x.html")
+ self.assertEqual(html.count('class="url"'), 1)
+ self.assertIn('>the table</a>', html)
+ self.assertIn('<span class="nb">--strict</span>', html)
+ self.assertIn('<span class="nb">-x</span>', html)
+ self.assertIn("showtime check --strict -x file", re.sub(r"<[^>]+>", "", html))
+ self.assertNotIn("nb", build.keep_flags_whole("<p><code>--a</code></p>")) # only inside table cells
+
+ def test_tutorials_have_a_picture_for_every_step(self):
+ # a tutorial is a walk through one run: every numbered step has a picture with real alt text, no file is
+ # missing, the clip at the top stays small, and nothing on the page names a private folder
+ guides = [p for p in sorted((REPO / "docs" / "guides").glob("*.md")) if "<!-- tutorial:" in p.read_text(encoding="utf-8")]
+ self.assertTrue(guides)
+ for guide in guides:
+ text = guide.read_text(encoding="utf-8")
+ pics = re.findall(r"!\[([^\]]*)\]\(([^)]+)\)", text)
+ self.assertGreaterEqual(len(pics), 10, guide.name)
+ for alt, src in pics:
+ self.assertGreater(len(alt), 20, src)
+ self.assertTrue((guide.parent / src).is_file(), src)
+ clip = [src for _a, src in pics if src.endswith("clip.webp")]
+ self.assertEqual(len(clip), 1, guide.name)
+ self.assertLess((guide.parent / clip[0]).stat().st_size, 3 * 1024 * 1024)
+ for marker in ("/Users/", "/home/", "C:\\Users\\", "~/Projects"):
+ self.assertNotIn(marker, text, guide.name)
+ sections = re.split(r"^## ", text, flags=re.M)[1:]
+ steps = [sec for sec in sections if re.match(r"\d+\. ", sec)]
+ self.assertGreaterEqual(len(steps), 5, guide.name)
+ for sec in steps:
+ self.assertRegex(sec, r"!\[[^\]]{20,}\]\(", "%s: step '%s' has no picture" % (guide.name, sec.splitlines()[0]))
+ self.assertIn("(%s)" % guide.name, (guide.parent / "README.md").read_text(encoding="utf-8") if guide.name != "first-video.md" else "(first-video.md)")
+
def test_landing_anchors_are_of_open_sections(self):
# a heading is linked to the section it is in, never to one that closed before it
out = Path(tempfile.mkdtemp(prefix="st-anchor-"))
@@ -601,9 +671,19 @@ class Guides(unittest.TestCase):
for p in self.guides():
text = p.read_text(encoding="utf-8")
n = len(text.rstrip("\n").splitlines())
- self.assertTrue(50 <= n <= 90, "%s: %d lines (50-90)" % (p.name, n))
heads = re.findall(r"^## (.+)$", text, re.M)
- self.assertEqual([h for h in heads if h in GUIDE_SECTIONS], GUIDE_SECTIONS, p.name)
+ if "<!-- tutorial:" in text:
+ # a tutorial is a walk through one real run: numbered steps with a picture each, then the same closing sections
+ self.assertTrue(60 <= n <= 160, "%s: %d lines (60-160)" % (p.name, n))
+ steps = [h for h in heads if re.match(r"\d+\. ", h)]
+ self.assertGreaterEqual(len(steps), 5, p.name)
+ self.assertEqual([int(h.split(".")[0]) for h in steps], list(range(1, len(steps) + 1)), p.name)
+ self.assertEqual([h for h in heads if h in GUIDE_SECTIONS[3:6] or h == "Say this"],
+ ["Say this"] + GUIDE_SECTIONS[3:6], p.name)
+ self.assertGreaterEqual(len(re.findall(r"^!\[[^\]]{20,}\]\(", text, re.M)), len(steps), p.name)
+ else:
+ self.assertTrue(50 <= n <= 90, "%s: %d lines (50-90)" % (p.name, n))
+ self.assertEqual([h for h in heads if h in GUIDE_SECTIONS], GUIDE_SECTIONS, p.name)
self.assertRegex(text, r"(example|examples)/|<!-- example: \d\d -->", p.name)
@unittest.skipUnless(HAVE_EXAMPLES, NO_EXAMPLES)