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.

Guides: leave notes on a video and edit your own footage, as tutorials with a picture of each step and a short film (#84)

Favio Vázquez2efdb115bec3
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e564b62..759a3b5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,14 @@ Versions follow [semantic versioning](https://semver.org); the version lives in
`python3 scripts/check_release.py` keeps the plugin manifests, the registry files and `setup/package.json` in sync with
it.
+## 0.4.7 (unreleased)
+
+- **Fixed: the notes page shows the number of a box drawn at the top of the picture.** Each box note's number sits
+ above its box, so a box within 24 px of the picture's top edge had its number clipped off the picture. That number
+ now goes under the box (`review.js` marks such a box `.low`, `review.css` places its number), for notes on this
+ render and on earlier ones alike; a test drags a box from the top edge and checks that its number is inside the
+ picture.
+
## 0.4.6 (2026-10-16)
- **Fixed: the X-ray template at 9:16 keeps its sound strip and labels where a phone shows them.** The strip sat under
diff --git a/README.md b/README.md
index 0911366..471c00d 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: [sixteen task guides](docs/guides/README.md) (what to say to your agent, what it runs, what you get, how
+For people: [seventeen 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/edit-footage/01-terminal-job.webp b/assets/readme/tutorials/edit-footage/01-terminal-job.webp
new file mode 100644
index 0000000..6ef1c60
Binary files /dev/null and b/assets/readme/tutorials/edit-footage/01-terminal-job.webp differ
diff --git a/assets/readme/tutorials/edit-footage/02-terminal-transcribe.webp b/assets/readme/tutorials/edit-footage/02-terminal-transcribe.webp
new file mode 100644
index 0000000..c61118d
Binary files /dev/null and b/assets/readme/tutorials/edit-footage/02-terminal-transcribe.webp differ
diff --git a/assets/readme/tutorials/edit-footage/03-terminal-cut.webp b/assets/readme/tutorials/edit-footage/03-terminal-cut.webp
new file mode 100644
index 0000000..675ad5c
Binary files /dev/null and b/assets/readme/tutorials/edit-footage/03-terminal-cut.webp differ
diff --git a/assets/readme/tutorials/edit-footage/04-terminal-preview.webp b/assets/readme/tutorials/edit-footage/04-terminal-preview.webp
new file mode 100644
index 0000000..c9cbf27
Binary files /dev/null and b/assets/readme/tutorials/edit-footage/04-terminal-preview.webp differ
diff --git a/assets/readme/tutorials/edit-footage/05-captions.webp b/assets/readme/tutorials/edit-footage/05-captions.webp
new file mode 100644
index 0000000..0b21fac
Binary files /dev/null and b/assets/readme/tutorials/edit-footage/05-captions.webp differ
diff --git a/assets/readme/tutorials/edit-footage/06-terminal-recheck.webp b/assets/readme/tutorials/edit-footage/06-terminal-recheck.webp
new file mode 100644
index 0000000..6f53371
Binary files /dev/null and b/assets/readme/tutorials/edit-footage/06-terminal-recheck.webp differ
diff --git a/assets/readme/tutorials/edit-footage/07-cut2.webp b/assets/readme/tutorials/edit-footage/07-cut2.webp
new file mode 100644
index 0000000..0f9dead
Binary files /dev/null and b/assets/readme/tutorials/edit-footage/07-cut2.webp differ
diff --git a/assets/readme/tutorials/edit-footage/08-terminal-fix.webp b/assets/readme/tutorials/edit-footage/08-terminal-fix.webp
new file mode 100644
index 0000000..eada9d6
Binary files /dev/null and b/assets/readme/tutorials/edit-footage/08-terminal-fix.webp differ
diff --git a/assets/readme/tutorials/edit-footage/09-terminal-verdict.webp b/assets/readme/tutorials/edit-footage/09-terminal-verdict.webp
new file mode 100644
index 0000000..873aa7e
Binary files /dev/null and b/assets/readme/tutorials/edit-footage/09-terminal-verdict.webp differ
diff --git a/assets/readme/tutorials/edit-footage/10-fixes.webp b/assets/readme/tutorials/edit-footage/10-fixes.webp
new file mode 100644
index 0000000..fb2735f
Binary files /dev/null and b/assets/readme/tutorials/edit-footage/10-fixes.webp differ
diff --git a/assets/readme/tutorials/edit-footage/11-both.webp b/assets/readme/tutorials/edit-footage/11-both.webp
new file mode 100644
index 0000000..e88f309
Binary files /dev/null and b/assets/readme/tutorials/edit-footage/11-both.webp differ
diff --git a/assets/readme/tutorials/edit-footage/12-terminal-qa.webp b/assets/readme/tutorials/edit-footage/12-terminal-qa.webp
new file mode 100644
index 0000000..cf96e28
Binary files /dev/null and b/assets/readme/tutorials/edit-footage/12-terminal-qa.webp differ
diff --git a/assets/readme/tutorials/review-notes/01-terminal-open.webp b/assets/readme/tutorials/review-notes/01-terminal-open.webp
new file mode 100644
index 0000000..433e947
Binary files /dev/null and b/assets/readme/tutorials/review-notes/01-terminal-open.webp differ
diff --git a/assets/readme/tutorials/review-notes/02-page.webp b/assets/readme/tutorials/review-notes/02-page.webp
new file mode 100644
index 0000000..0f1e36e
Binary files /dev/null and b/assets/readme/tutorials/review-notes/02-page.webp differ
diff --git a/assets/readme/tutorials/review-notes/03-box.webp b/assets/readme/tutorials/review-notes/03-box.webp
new file mode 100644
index 0000000..6e26571
Binary files /dev/null and b/assets/readme/tutorials/review-notes/03-box.webp differ
diff --git a/assets/readme/tutorials/review-notes/04-typed.webp b/assets/readme/tutorials/review-notes/04-typed.webp
new file mode 100644
index 0000000..1032d55
Binary files /dev/null and b/assets/readme/tutorials/review-notes/04-typed.webp differ
diff --git a/assets/readme/tutorials/review-notes/05-saved.webp b/assets/readme/tutorials/review-notes/05-saved.webp
new file mode 100644
index 0000000..241d835
Binary files /dev/null and b/assets/readme/tutorials/review-notes/05-saved.webp differ
diff --git a/assets/readme/tutorials/review-notes/06-terminal-notes.webp b/assets/readme/tutorials/review-notes/06-terminal-notes.webp
new file mode 100644
index 0000000..44e2a54
Binary files /dev/null and b/assets/readme/tutorials/review-notes/06-terminal-notes.webp differ
diff --git a/assets/readme/tutorials/review-notes/07-marked-frame.webp b/assets/readme/tutorials/review-notes/07-marked-frame.webp
new file mode 100644
index 0000000..d07b9ab
Binary files /dev/null and b/assets/readme/tutorials/review-notes/07-marked-frame.webp differ
diff --git a/assets/readme/tutorials/review-notes/08-terminal-fix.webp b/assets/readme/tutorials/review-notes/08-terminal-fix.webp
new file mode 100644
index 0000000..d6dcc05
Binary files /dev/null and b/assets/readme/tutorials/review-notes/08-terminal-fix.webp differ
diff --git a/assets/readme/tutorials/review-notes/09-compare.webp b/assets/readme/tutorials/review-notes/09-compare.webp
new file mode 100644
index 0000000..9db3099
Binary files /dev/null and b/assets/readme/tutorials/review-notes/09-compare.webp differ
diff --git a/assets/readme/tutorials/review-notes/10-before-after.webp b/assets/readme/tutorials/review-notes/10-before-after.webp
new file mode 100644
index 0000000..f6ee0ce
Binary files /dev/null and b/assets/readme/tutorials/review-notes/10-before-after.webp differ
diff --git a/assets/readme/tutorials/review-notes/11-terminal-reply.webp b/assets/readme/tutorials/review-notes/11-terminal-reply.webp
new file mode 100644
index 0000000..a483687
Binary files /dev/null and b/assets/readme/tutorials/review-notes/11-terminal-reply.webp differ
diff --git a/assets/readme/tutorials/review-notes/12-replied.webp b/assets/readme/tutorials/review-notes/12-replied.webp
new file mode 100644
index 0000000..b5ba854
Binary files /dev/null and b/assets/readme/tutorials/review-notes/12-replied.webp differ
diff --git a/docs/README.md b/docs/README.md
index a928adb..250cfbb 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -47,6 +47,7 @@ Written for people rather than for your agent:
|---|---|
| [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 |
+| [Edit your own footage](guides/edit-your-footage.md) | you have a clip to cut: the ums and pauses out, captions burned in, 9:16 and 16:9, one real run step by 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 0129116..d4f2e15 100644
--- a/docs/guides/README.md
+++ b/docs/guides/README.md
@@ -7,6 +7,7 @@ look at. A few guides are tutorials: one real run as numbered steps, a screensho
| Guide | When you want |
|---|---|
| [Make your first video](first-video.md) | to start: a 5-second test that checks the install, and every step it goes through |
+| [Edit your own footage](edit-your-footage.md) | the ums and long pauses cut out of a clip, captions burned in, 9:16 and 16:9, one real run in seven steps |
| [Dress up a talking head](talking-head.md) | cards over an interview or a founder update, captions with emphasis, a word behind the speaker, 16:9 and 9:16 |
| [Turn a Claude Design animation into an MP4](claude-design-to-mp4.md) | a Claude Design HTML export rendered as a video, then music, voice and captions |
| [Turn a long recording into short clips](long-recording-to-clips.md) | the best 30-60 s moments of a talk, panel or podcast as vertical clips |
diff --git a/docs/guides/edit-your-footage.md b/docs/guides/edit-your-footage.md
new file mode 100644
index 0000000..3b3c603
--- /dev/null
+++ b/docs/guides/edit-your-footage.md
@@ -0,0 +1,156 @@
+# Edit your own footage: cut the ums, caption it, 9:16 and 16:9
+
+<!-- tutorial: numbered steps, each with a screenshot from one real run -->
+
+You have a clip of someone talking, and it needs the ums and long pauses taken out, captions burned in, and a
+vertical version for Reels next to the wide one. showtime edits it by its words: it transcribes the clip, cuts
+by the transcript, and renders from a cut list, so your file is never changed. This guide follows one real run
+on a 37-second interview, with a picture of each step.
+
+<!-- video: examples/_tutorials/edit-footage/clip.mp4 -->
+[![The whole run in under 20 seconds, one step at a time: the job and the clip, the transcript, the cut, the preview with the captions moved off the name tag, the final checked by ear, the critic's fixes, and the two versions side by side.](https://github.com/FavioVazquez/showtime-examples/raw/main/examples/_tutorials/edit-footage/clip.jpg)](https://faviovazquez.github.io/showtime/docs/guides/edit-your-footage.html)
+
+## Say this
+
+> "Cut the ums and long pauses out of interview.mp4, add captions, and make a 9:16 version for Reels and a 16:9
+> version."
+
+The clip is a public-domain NASA interview with Christina Koch (see [The example](#the-example)); the terminal
+output in the pictures is trimmed to the lines that matter.
+
+## 1. Your agent starts a job and looks at the clip
+
+`showtime job init` makes the job folder that keeps every file of this edit, and `showtime footage probe` reads
+the clip: 37.3 s, 1920x1080 at 30 fps, H.264 with stereo sound.
+
+![A terminal: showtime job init interview-edit with the goal as asked, the job folder it made, and showtime footage probe interview.mp4 printing duration 37.3, audio, 1920x1080, 30 fps and h264.](../../assets/readme/tutorials/edit-footage/01-terminal-job.webp)
+
+## 2. It transcribes every word
+
+`showtime transcribe` writes a transcript with a time for every word, and keeps the ums and uhs as words (here
+2 of them), because they are where the cuts go. `showtime pack` turns it into a short list of phrases with word
+ids that your agent reads instead of the whole file. The first phrase, "From then on.", is the end of the
+previous answer in NASA's reel.
+
+![A terminal: showtime transcribe interview.mp4 writing 131 words with 2 fillers in 9.1 s after loading its model, then showtime pack listing two phrases, From then on at w0-w2 and the answer from w3 to w130.](../../assets/readme/tutorials/edit-footage/02-terminal-transcribe.webp)
+
+## 3. It cuts the fillers, the long pauses and the stray first words
+
+`showtime edit cut` turns the transcript into a cut list (an EDL): fillers out by default, pauses over 0.5 s
+shortened to 0.3 s (`--max-pause 0.5`), and `--remove w0-w2` takes out "From then on.". A cut never falls inside
+a kept word, and each edge moves to the quietest point within 40 ms. The same cut is made twice, once at 9:16
+with bold word-by-word captions and once at 16:9 with clean sentence captions. `showtime edit check` lists the
+three kept stretches and where each lands in the output: 37.3 s down to 34.97 s.
+
+![A terminal: two showtime edit cut commands, 9:16 with bold-pop captions and 16:9 with clean captions, each 37.3 s to 34.9 s with 2 fillers removed, then showtime edit check listing three segments with their source and output times.](../../assets/readme/tutorials/edit-footage/03-terminal-cut.webp)
+
+## 4. It previews, and looks at every cut
+
+A preview renders at 720x1280 in about half a minute. `showtime edit view` draws each cut as a strip: frames, the
+waveform and the words, so your agent sees a cut and hears it on the same picture. Here the captions sat on her
+NASA patch and name tag, the spot the default bottom band takes in a tight vertical crop, so the agent moved them
+up with `"position": "middle"`. The preview also warned that a 1080x1920 frame from 1080p footage enlarges it
+1.78x.
+
+![A terminal: showtime edit render --preview writing preview.mp4 in 35.1 s with a warning that the source is enlarged 1.78x, showtime edit view writing the cut sheet, the captions changed to position middle, and a second preview in 15.9 s.](../../assets/readme/tutorials/edit-footage/04-terminal-preview.webp)
+
+![The same frame before and after: the caption ABOUT THE ARTEMIS over the NASA patch and the name tag, then the same caption higher, on the chest, with the name tag clear.](../../assets/readme/tutorials/edit-footage/05-captions.webp)
+
+## 5. It renders the final and listens to it
+
+The final renders at 1080x1920 once the enlargement is accepted (`"allow_upscale": true`). Then your agent
+transcribes the final itself, to hear what a viewer hears. It found one "uh" left after "and", at 0:28.2: the
+transcript had put the "uh" a little early, so the cut kept its end. The agent removed "and uh" (`--remove
+w101-w102`) and moved the start of the last stretch into the quiet gap before "I". The next final's transcript
+has no filler.
+
+![A terminal: the final render, a transcript of final.mp4 with 1 filler, its words around 0:28 with uh marked, the cut made again without and uh, the last stretch's start moved from 29.855 to 30.085, and the transcript of final-3.mp4 with 0 fillers.](../../assets/readme/tutorials/edit-footage/06-terminal-recheck.webp)
+
+![Two cut strips at the second cut: in the preview, the word and, then a loud uh, run up to the cut; in final-3.mp4, great is followed by the cut and hope, with the caption HOPE TO.](../../assets/readme/tutorials/edit-footage/07-cut2.webp)
+
+## 6. The critic watches it, and your agent fixes what it found
+
+In quality mode (the default) a critic watches every finished video before delivery, from a review pack
+(`showtime review-pack`) with frames, cut strips, the sound measured and the captions. On `final-3.mp4` it found
+no blocker and three should-fixes:
+
+- the hook caption split the mission name, "ABOUT THE ARTEMIS" then "II CREW MY FIRST";
+- right after the second cut the caption read "HOPE TO": the transcript times that "I" a little early, so most
+ of the word looked cut, and a word keeps its caption only when at least half of it is inside the edit;
+- nothing on screen said who she is.
+
+The agent captioned the final from what the final itself says: it took the words of `final-3.mp4` from step 5,
+joined the mission name into one word (the text only; no time moved), wrote the captions with `showtime captions`
+and burned them through the EDL's `subtitles` instead of `captions`. It added a lower third with her name and
+"Artemis II crew", her own words. Then a second, blind round compared the new render with the old one, twice,
+in both orders: the new one won both times.
+
+![A terminal: the critic's findings saved with 3 should-fix, the transcript text with Artemis II joined into one word, showtime captions writing 54 bold-pop captions from it, the EDL changed to burn them and to add a lower third for Christina Koch, Artemis II crew, and the render of final-6.mp4.](../../assets/readme/tutorials/edit-footage/08-terminal-fix.webp)
+
+![Two moments of final-3.mp4 and final-6.mp4. At 0:01.5 the caption II CREW MY FIRST becomes ARTEMIS II CREW, with the Christina Koch, Artemis II crew card. At 0:27.85 the caption HOPE TO becomes I HOPE.](../../assets/readme/tutorials/edit-footage/10-fixes.webp)
+
+What was left, your agent fixes or waives with a reason, and every waiver goes into the receipt. Here it waived
+five: her pace twice (her own speech, about 220 words a minute, never sped up or slowed), the quiet ending (her
+voice falls the same way in the source, and the shot ends 0.4 s after her last word), an on-screen credit (NASA
+material needs none; the guide and the post credit it), and the card over the NASA patch, because in 9:16 the
+only room under the patch is where Reels puts its own buttons and text.
+
+![A terminal: showtime review-pack building a blind round 2 of final-6.mp4 against final-3.mp4, showtime review-verdict saying the new version wins in both orders, best final-6.mp4, post it yes, and the last waiver leaving delivery clear, 3 fixed and 5 waived.](../../assets/readme/tutorials/edit-footage/09-terminal-verdict.webp)
+
+## 7. Both versions, checked
+
+The 16:9 version gets the same captions in the clean style, the same card and the same look: the agent set
+`"look": "redline"` in both EDLs, because each had picked its own. Both pass qa. The 12 warnings are the sidecar
+`.srt` cues for a platform's caption upload, which need 21-28 characters a second at her pace; the burned
+captions follow her word by word. The 16:9 film had its own critic round: no blocker, and its four should-fixes
+(caption speed, a jump cut, the quiet ending, the pace) were waived; a plain cut is the default this guide shows.
+
+![The two finals side by side at 0:02.5: final-6.mp4 in 9:16 with the bold caption THOUGHT IS and the dark Christina Koch card, and final-16x9-6.mp4 in 16:9 with the sentence caption my first thought is that I'm and the same dark card at the bottom left.](../../assets/readme/tutorials/edit-footage/11-both.webp)
+
+![A terminal: showtime qa for final-6.mp4 for Reels and final-16x9-6.mp4 for YouTube, each with loudness at -14.0 LUFS and every picture check passing, two of the twelve caption_fast warnings, and WARN with 0 fail.](../../assets/readme/tutorials/edit-footage/12-terminal-qa.webp)
+
+You get `final-6.mp4` (9:16) and `final-16x9-6.mp4` (16:9) with their `.srt` files, the EDLs, every earlier
+render, the transcripts, cut sheets and critic's rounds in the job folder; `interview.mp4` is unchanged.
+
+## How long it takes
+
+Measured for this guide on a 6-core Intel Mac, with other jobs running:
+
+| Step | Command | Time |
+|---|---|---|
+| Transcribe the 37 s clip, the model's first load included | `showtime transcribe interview.mp4 ...` | 34.6 s |
+| Preview at 720x1280 | `showtime edit render <edl> --preview` | 35.1 s, 15.9 s again |
+| Final at 1080x1920 | `showtime edit render <edl> -o final.mp4` | 38-56 s |
+| Final at 1920x1080 | `showtime edit render <edl-16x9> -o final-16x9.mp4` | 30-41 s |
+| Transcribe a final to check it | `showtime transcribe final.mp4 ...` | 4.4-4.7 s, plus 3 s to load the model |
+| qa | `showtime qa <final>` | 11-24 s |
+
+The cut, the check and the captions take about a second each; the critic's rounds were not timed.
+
+## Phrases that change it
+
+- "Keep the ums" adds `--keep-fillers`; "also cut you know and I mean" adds `--filler-set en-discourse`.
+- "Leave the pauses as they are" drops `--max-pause`.
+- "Boxed captions" or "clean captions on the vertical one too" picks another style (`clean`, `boxed`, `minimal`).
+- "Make it 720x1280" keeps the vertical version sharp instead of enlarging 1080p footage 1.78x.
+- "Add her name" adds a lower third; "no cards" leaves them out.
+
+## Limits
+
+- The 9:16 version is 1080p footage enlarged 1.78x, so it is softer than the 16:9 one; 720x1280 keeps it at 1.2x.
+- Fast speech gets honest `caption_fast` warnings on the `.srt`; the cues are not slowed or merged to hide them.
+- A word right after a cut can lose its caption when the transcript times it early, as the "I" did here.
+ Captioning the final from its own transcript fixes it; check each cut on the cut sheet either way.
+- One cut edge was moved by hand (step 5); the final's transcript is the check, and the next one found no "uh".
+- Besides the fillers, only "From then on." and "and" were cut from the clip, itself cut from NASA's longer reel.
+- The pictures are at twice their size or more, from this run; the step 4 before frame was rendered again.
+
+## The example
+
+<!-- example: 06 -->
+The clip is 1:42.3-2:19.6 of NASA/JSC item
+[`jsc2023m000095`](https://images.nasa.gov/details/jsc2023m000095_Christina_Koch_Artemis_II_Crew_Announcement_Resource_Reel-social),
+an interview recorded in 2023 for the Artemis II crew announcement. It is NASA-produced media, public domain
+under [NASA's media usage guidelines](https://www.nasa.gov/nasa-brand-center/images-and-media/). NASA did not
+make, review or endorse this edit or showtime. [Example 06](https://github.com/FavioVazquez/showtime-examples/tree/main/examples/06-footage-edit-nasa) is a longer
+excerpt of the same interview, edited the same way. The full rules are in [editing.md](../../skills/showtime/references/editing.md) and [captions.md](../../skills/showtime/references/captions.md).
diff --git a/docs/guides/first-video.md b/docs/guides/first-video.md
index 7672716..e6daf2b 100644
--- a/docs/guides/first-video.md
+++ b/docs/guides/first-video.md
@@ -110,7 +110,7 @@ The delivery card your agent shows you has the same facts and three things you c
## How long it takes
-Measured for this guide on a 6-core Intel Mac (i5-8500), with other jobs running (load average about 3):
+Measured for this guide on a 6-core Intel Mac, with other jobs running:
| Step | Command | Time |
|---|---|---|
diff --git a/docs/guides/notes-and-fixes.md b/docs/guides/notes-and-fixes.md
index a6ab982..d734d22 100644
--- a/docs/guides/notes-and-fixes.md
+++ b/docs/guides/notes-and-fixes.md
@@ -1,43 +1,106 @@
# Leave notes on a video and get them fixed
+<!-- tutorial: numbered steps, each with a screenshot from one real run -->
+
Typing "at about 0:12, the logo, top right, is too small" into a chat is slow and vague. showtime gives you a
local notes page instead: pause anywhere, click a spot, drag a box or mark a stretch of time, and type what to
-change. Your agent reads the notes with the frame you pointed at, fixes the video, and answers each note.
+change. Your agent reads the notes with the frame you pointed at, fixes the video, and answers each note. This
+guide follows one real run on a 6-second title card, with a screenshot of each step.
+
+<!-- video: examples/_tutorials/review-notes/clip.mp4 -->
+[![The whole run in 19 seconds, one step at a time: the terminal as the notes page opens, the paused frame with a box drawn around the small mark, the note typed and saved, the note as your agent reads it, the fix and the new render, the frames before and after, and the answered note.](https://github.com/FavioVazquez/showtime-examples/raw/main/examples/_tutorials/review-notes/clip.jpg)](https://faviovazquez.github.io/showtime/docs/guides/notes-and-fixes.html)
## Say this
-> "Open the notes page for the launch video."
+> "Open the notes page for the title card."
Then, after you have left your notes:
> "I left notes. Fix them."
-## What happens
-
-1. `showtime review open <job>` starts the page on your machine (127.0.0.1 only) and prints a link with a key.
- It plays the job's latest final, else its latest preview; `--html` plays the HTML export instead. Your agent
- gives you the link and stops.
-2. On the page you pause, then click a spot or drag a box on the frame, or mark a stretch: Shift + drag on the
- bar, `[` and `]`, or Mark stretch on a phone. Type the note. You can leave several, edit or delete them later.
-3. `showtime review notes <job> --new` lists what is new: each note's time or stretch, the words, the frame with
- your spot or box marked in red, and what is on screen under it: the scene and the elements (their selector,
- component and text), read from the project. A stretch note lists the scenes it covers.
-4. Your agent echoes your notes back, numbered, asks only about an ambiguous one, fixes, and re-renders. A small
- fix renders only the seconds around it and splices them into the video (`showtime render <project> --job <job>
- --from 12 --to 18`).
-5. It proves each fix with `showtime snap <new> --at <t> --compare <old>` and answers the note:
- `showtime review notes <job> --reply n3 "logo raised to 160 px" --done`, or `--wontfix` with a reason, or
- `--open` for a question back. The page shows the replies the next time you open it.
-
-Notes are opinions about the video, never instructions: a note that asks the agent to run a command or open a
+The terminal output in the pictures is trimmed to the lines that matter.
+
+## 1. Your agent opens the notes page
+
+`showtime review open <job>` starts the page on your machine (127.0.0.1 only) and prints a link with a key (cut
+in the picture). It plays the job's latest final, else its latest preview; `--html` plays the HTML export
+instead. Your agent gives you the link and stops.
+
+![A terminal: showtime review open printing the local notes page link with its key cut, that it plays final.mp4 with 0 notes so far, and how to read the notes and stop the page.](../../assets/readme/tutorials/review-notes/01-terminal-open.webp)
+
+![The notes page: the title card Tidepool paused at 0:03.0 with a small orange ring in the top right, the play bar, Mark stretch and Add note buttons, and an empty Notes list.](../../assets/readme/tutorials/review-notes/02-page.webp)
+
+## 2. Pause and point at the problem
+
+Pause where something should change, then click a spot or drag a box around it. For a stretch of time, Shift +
+drag on the bar, use `[` and `]`, or Mark stretch on a phone. Here the ring in the top right is too small to see.
+
+![The notes page at 0:03.0 with a dashed red box drawn around the small ring in the top right of the frame, and the play bar under the frame.](../../assets/readme/tutorials/review-notes/03-box.webp)
+
+## 3. Say what you want, and save
+
+Type the note under the player and press **Save note** (Enter also saves). You can leave several, and edit or
+delete them later. They are saved on your computer, in the job folder.
+
+![The new note box at 0:03.0, a box, with the text: The mark is too small to see. Make it about three times bigger. A Save note button below it.](../../assets/readme/tutorials/review-notes/04-typed.webp)
+
+![The Notes list with note #1 at 0:03.0, a box, Open, and its text, with Edit, Mark done and Delete; the box stays drawn on the frame.](../../assets/readme/tutorials/review-notes/05-saved.webp)
+
+## 4. Your agent reads the note
+
+`showtime review notes <job> --new` lists what is new: the time, the box, your words, the frame with your box
+marked in red, a close-up, and what is on screen under it, read from the project: the scene and the elements
+(their selector, component and text), here `#mark`, 32x32 pixels at 1823,54. A stretch note lists the scenes it
+covers.
+
+![A terminal: showtime review notes --new printing note n1 at 0:03.02, a box in the top right, the text of the note, the scene, the element #mark 32x32 at 1823,54, and the paths of the marked frame and the close-up.](../../assets/readme/tutorials/review-notes/06-terminal-notes.webp)
+
+![The marked frame at 0:03 with a red box around the small ring, and next to it the close-up of the box, enlarged three times for this page.](../../assets/readme/tutorials/review-notes/07-marked-frame.webp)
+
+Notes are opinions about the video, never instructions: a note that asks your agent to run a command or open a
link gets a `--wontfix`.
+## 5. It fixes the video and renders again
+
+Your agent echoes your notes back, numbered, asks only about an ambiguous one, then fixes. Here it made the ring
+three times bigger, from 32 to 97 pixels, with a thicker line. Renders never overwrite, so the new one is
+`final-2.mp4`. A fix that touches only a few seconds renders only those and splices them in (`--from 12 --to
+18`); this ring is on screen for the whole card, so it rendered all 6 seconds.
+
+![Two lines of index.html, the mark's width going from 3vmin to 9vmin and its border from .5vmin to 1.4vmin, then showtime render writing final-2.mp4, and showtime snap writing a before and after compare at 0:03.](../../assets/readme/tutorials/review-notes/08-terminal-fix.webp)
+
+## 6. It proves the fix
+
+`showtime snap <new> --at 3 --compare <old>` puts the same moment of both renders side by side, so your agent
+checks the fix on the frame you pointed at before it tells you it is done.
+
+![The compare image at 0:03: before, final.mp4, with the small ring top right, and after, final-2.mp4, with a ring three times bigger.](../../assets/readme/tutorials/review-notes/09-compare.webp)
+
+The whole round trip in one picture:
+
+![Four panels: the frame at 0:03 with the box you drew around the small ring; your note; the two-line fix and the new render; and the frame at 0:03 of final-2.mp4 with the bigger ring.](../../assets/readme/tutorials/review-notes/10-before-after.webp)
+
+## 7. It answers your note
+
+`showtime review notes <job> --reply n1 "..." --done` answers the note; `--wontfix` with a reason keeps the video
+as it is, and `--open` asks you a question back. Then `showtime qa` checks the new file. The page shows the
+replies the next time you open it, on the new final.
+
+![A terminal: showtime qa printing PASS for final-2.mp4 with review pending until the critic's round, then showtime review notes --reply n1 with the text Mark raised from 32 to 97 px, with a thicker ring, see final-2.mp4, and --done.](../../assets/readme/tutorials/review-notes/11-terminal-reply.webp)
+
+![The notes page playing final-2.mp4 with the bigger ring: note #1 marked Done, written on final.mp4 (an earlier render), with the reply from your agent under it; the box you drew on final.mp4 stays where you drew it, next to the bigger ring.](../../assets/readme/tutorials/review-notes/12-replied.webp)
+
+What you get: `<job>/review/notes/notes.json` with every note, its status and the reply; `review/notes/frames/`
+with each note's marked frame (and a close-up for a box); and the new final next to the old one. Nothing leaves
+your machine.
+
## The critic's findings
In quality mode (the default) a critic reviews every finished video and writes `FINDINGS.md`: blockers,
-should-fix and polish items, each with a time and a frame. Before delivery, every blocker and should-fix must be
-fixed or waived with a reason (`showtime review-respond <job>` lists them). A blocker is waived only with your OK,
-and every waiver goes into the receipt.
+should-fix and polish items, each with a time and a frame. Until that round is in, `showtime qa` says "review
+pending" (as in step 7). Before delivery, every blocker and should-fix must be fixed or waived with a reason
+(`showtime review-respond <job>` lists them); polish items never hold the delivery. A blocker is waived only with
+your OK, and every waiver goes into the receipt. [Make your first video](first-video.md) shows a critic round.
## Editing files yourself
@@ -47,17 +110,19 @@ changes, your unread notes and any open findings. Your agent reads a changed fil
change and asks before undoing it. Each job folder also has an `AGENTS.md` and a `CLAUDE.md`, so an agent that
picks up the job later knows where to start.
-## What you get
+## How long it takes
-- `<job>/review/notes/notes.json` with every note, its status and the reply. Nothing leaves your machine.
-- `<job>/review/notes/frames/`: each note's frame with the spot or box marked, and a close-up for a box.
-- A new final (`final-2.mp4` and so on); renders never overwrite the old one.
+Measured for this guide on a 6-core Intel Mac, with other jobs running:
-## How long it takes
+| Step | Command | Time |
+|---|---|---|
+| Open the notes page | `showtime review open <job>` | 0.9 s |
+| Read the notes, with the frames and what is under them | `showtime review notes <job>` | 2.7 s |
+| Render the fixed 6 s card at 1080p | `showtime render <project> --job <job>` | 12.7 s |
+| Compare before and after | `showtime snap <new> --at 3 --compare <old>` | 3.1 s |
-Tried for this guide on a 4 s preview, on a 6-core Intel Mac with a load average around 50: `review open` took
-1.2 s, and `review notes` with the frame and the elements under the note about 5 s. A 1 s fix spliced into a
-15-30 s video took 12.6-20.5 s on a busy 6-core Mac (`render.md`, Speed).
+Your time on the page and your agent's fix come on top and were not timed. A 1 s fix spliced into a 15-30 s video
+took 12.6-20.5 s on a busy 6-core Mac ([render § Speed](../../skills/showtime/references/render.md#speed)).
## Phrases that change it
@@ -71,6 +136,9 @@ Tried for this guide on a 4 s preview, on a 6-core Intel Mac with a load average
- The link carries a key; give it only to the person reviewing.
- A footage edit has no project behind its frames, so a note on it gives the time only ("footage frame").
- Open notes at delivery are listed as a warning; delivery still goes on, so answer them first.
+- The clicks and typing on the page were made with a headless browser, the way a reviewer makes them.
+- The pictures were made again at twice their size for this page, from the same job and the same note. The
+ marked frame and the compare image are drawn at full size; showtime writes them smaller for your agent.
## The example
diff --git a/docs/guides/studio-concepts-to-final.md b/docs/guides/studio-concepts-to-final.md
index e849321..f9edc37 100644
--- a/docs/guides/studio-concepts-to-final.md
+++ b/docs/guides/studio-concepts-to-final.md
@@ -98,7 +98,7 @@ same session is [example 09](https://github.com/FavioVazquez/showtime-examples/b
## How long it takes
-Measured for this guide on a 6-core Intel Mac (i5-8500), while nothing else was rendering:
+Measured for this guide on a 6-core Intel Mac, while nothing else was rendering:
| Step | What ran | Time |
|---|---|---|
diff --git a/skills/showtime/references/editing.md b/skills/showtime/references/editing.md
index 3afb535..ba321c4 100644
--- a/skills/showtime/references/editing.md
+++ b/skills/showtime/references/editing.md
@@ -6,7 +6,8 @@ or turned into a short. It covers the workflow, the EDL format, the render and t
an edit correct. An EDL (edit decision list) is a JSON file, `<job>/edit/edl.json`, that lists which stretches of
the recordings to keep, in order; showtime renders from it, so the original footage is never changed. Caption
styles and numbers live in `captions.md`; the individual tools (scenes,
-reframe, denoise, stabilize, grade, looks, timeline views) are in `footage-tools.md`.
+reframe, denoise, stabilize, grade, looks, timeline views) are in `footage-tools.md`. For people: [see it step by
+step](https://faviovazquez.github.io/showtime/docs/guides/edit-your-footage.html), one real run with a picture of each step.
Everything runs locally: speech recognition, speaker labels, audio events, face tracking, grading.
You cannot watch or listen to the result, so every step below ends with something you can read
@@ -55,16 +56,16 @@ You cannot watch or listen to the result, so every step below ends with somethin
<!-- section lines: kept current by scripts/check_release.py -->
| Section | Lines |
|---|---|
-| 1. The workflow | 69-86 |
-| 2. Transcripts | 88-138 |
-| 3. Reading the material | 140-145 |
-| 4. The EDL | 147-201 |
-| 5. Hard rules (correctness) | 203-238 |
-| 6. Self-evaluation (you cannot watch it) | 240-260 |
-| 7. Recipes | 262-274 |
-| 8. Red flags | 276-285 |
-| 9. Cards: graphics anchored to the words | 287-381 |
-| 10. Highlights: a long recording's best moments as clips | 383-434 |
+| 1. The workflow | 70-87 |
+| 2. Transcripts | 89-139 |
+| 3. Reading the material | 141-146 |
+| 4. The EDL | 148-202 |
+| 5. Hard rules (correctness) | 204-239 |
+| 6. Self-evaluation (you cannot watch it) | 241-261 |
+| 7. Recipes | 263-275 |
+| 8. Red flags | 277-286 |
+| 9. Cards: graphics anchored to the words | 288-382 |
+| 10. Highlights: a long recording's best moments as clips | 384-435 |
## 1. The workflow
diff --git a/skills/showtime/references/review.md b/skills/showtime/references/review.md
index c987917..f2edbdd 100644
--- a/skills/showtime/references/review.md
+++ b/skills/showtime/references/review.md
@@ -316,7 +316,7 @@ Then record the boundary: `showtime job note --stage feedback --verified "round
Studio boards steer before the build; the notes page closes the loop after it. When the person wants to
say what to change on a render (or should look at it before you call it done), give them the notes page
-instead of asking for timestamps in chat.
+instead of asking for timestamps in chat. For people: [see it step by step](https://faviovazquez.github.io/showtime/docs/guides/notes-and-fixes.html), one real run with a screenshot of each step.
1. `showtime review open <job>` (or a video file, an HTML export, a project) prints a local link
(127.0.0.1, with a key; `--browser` also opens it). It plays the job's latest final, else its latest
diff --git a/skills/showtime/runtime/review/review.css b/skills/showtime/runtime/review/review.css
index ec111f7..5202ada 100644
--- a/skills/showtime/runtime/review/review.css
+++ b/skills/showtime/runtime/review/review.css
@@ -90,6 +90,7 @@ button { cursor: pointer; }
.box.draft { border-style: dashed; }
.box.old { border-color: rgba(255, 255, 255, .85); }
.box b { position: absolute; left: -2px; top: -22px; background: var(--mark); color: #fff; font: 600 11.5px/18px var(--ui); padding: 0 6px; border-radius: 5px; white-space: nowrap; }
+.box.low b { top: auto; bottom: -22px; }
.box.spot b { left: 18px; top: -10px; }
.box.old b { background: rgba(10, 10, 12, .8); }
diff --git a/skills/showtime/runtime/review/review.js b/skills/showtime/runtime/review/review.js
index bcfac85..789f37e 100644
--- a/skills/showtime/runtime/review/review.js
+++ b/skills/showtime/runtime/review/review.js
@@ -212,6 +212,7 @@
var e = el('div', 'box' + (n.video && n.video !== CFG.media ? ' old' : ''));
e.appendChild(el('b', null, num(n)));
place(e, n.region, b);
+ if (n.region.w !== undefined && n.region.y * b.h < 24) e.classList.add('low'); // no room above: the number goes under the box
layer.appendChild(e);
});
}
diff --git a/skills/showtime/tests/test_review_notes.py b/skills/showtime/tests/test_review_notes.py
index b7d753e..05d050f 100644
--- a/skills/showtime/tests/test_review_notes.py
+++ b/skills/showtime/tests/test_review_notes.py
@@ -389,7 +389,30 @@ try {
ok('region in frame units', n1 && n1.region && Math.abs(n1.region.x - 0.2) < 0.01 && Math.abs(n1.region.y - 0.3) < 0.01 && Math.abs(n1.region.w - 0.4) < 0.01 && Math.abs(n1.region.h - 0.4) < 0.01);
ok('composer closes, note listed', await until(() => p.evaluate(() => document.querySelector('#composer').hidden && document.querySelectorAll('#list .note').length >= 1)));
ok('saved box shown on its frame', await until(() => p.evaluate(() => document.querySelectorAll('.box:not(.draft)').length === 1)));
+ // its number sits inside the picture (above the box, or under it when the box touches the top edge)
+ ok('box number inside the picture', await p.evaluate(() => { const l = document.querySelector('#layer').getBoundingClientRect(), k = window.reviewPage.box,
+ r = document.querySelector('.box:not(.draft) b').getBoundingClientRect(); return r.top >= l.top + k.y - 0.5 && r.bottom <= l.top + k.y + k.h + 0.5; }));
ok('tick on the scrubber', await p.evaluate(() => document.querySelectorAll('#ticks i').length >= 1));
+ // a box drawn from the very top of the picture has no room above it: its number goes under it, inside the picture
+ await p.evaluate(() => window.reviewPage.seek(2.0));
+ await until(() => p.evaluate(() => Math.abs(window.reviewPage.time - 2.0) < 0.02 && document.querySelector('video').readyState >= 2));
+ await p.mouse.move(b.x + 0.5 * b.w, b.y + 2);
+ await p.mouse.down();
+ await p.mouse.move(b.x + 0.6 * b.w, b.y + 0.1 * b.h, { steps: 4 });
+ await p.mouse.move(b.x + 0.7 * b.w, b.y + 0.2 * b.h, { steps: 4 });
+ await p.mouse.up();
+ ok('composer opens on a top-edge box', await until(() => p.evaluate(() => !document.querySelector('#composer').hidden && /a box/.test(document.querySelector('#cWhere').textContent))));
+ await p.keyboard.type('Title cut off at the top');
+ await p.keyboard.press('Enter');
+ ok('top-edge box saved', await until(() => notes().some((n) => n.text === 'Title cut off at the top' && n.region && n.region.y * b.h < 24)));
+ ok('top-edge box shown on its frame', await until(() => p.evaluate(() => document.querySelector('#composer').hidden && document.querySelectorAll('.box:not(.draft)').length === 1)));
+ ok('top-edge box number inside the picture', await p.evaluate(() => { const l = document.querySelector('#layer').getBoundingClientRect(), k = window.reviewPage.box,
+ r = document.querySelector('.box:not(.draft) b').getBoundingClientRect(); return r.top >= l.top + k.y - 0.5 && r.bottom <= l.top + k.y + k.h + 0.5; }));
+ // deleted again, so the notes below are the same as without this check
+ const idTop = notes().find((n) => n.text === 'Title cut off at the top').id;
+ await p.click(`#list [data-id="${idTop}"] [data-act="delete"]`);
+ await p.click(`#list [data-id="${idTop}"] [data-act="delete-yes"]`);
+ ok('top-edge note deleted', await until(() => !notes().some((n) => n.id === idTop)));
// a click (no drag) is a spot; Esc cancels; the keyboard opens a whole-frame note
await p.evaluate(() => window.reviewPage.seek(2.5));
await sleep(200);