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.
Python agent-skillsai-agentscaptionsclaude-codeclaude-code-pluginclaude-skillscodexcursorexplainer-videoffmpegheadless-chromekokoro-ttslocal-firstmanimmcp-servermotion-graphicstext-to-speechvideovideo-editingvideo-generation
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.mdindex 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 withit.+## 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 underdiff --git a/README.md b/README.mdindex 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, howlong 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.webpnew file mode 100644index 0000000..6ef1c60Binary files /dev/null and b/assets/readme/tutorials/edit-footage/01-terminal-job.webp differdiff --git a/assets/readme/tutorials/edit-footage/02-terminal-transcribe.webp b/assets/readme/tutorials/edit-footage/02-terminal-transcribe.webpnew file mode 100644index 0000000..c61118dBinary files /dev/null and b/assets/readme/tutorials/edit-footage/02-terminal-transcribe.webp differdiff --git a/assets/readme/tutorials/edit-footage/03-terminal-cut.webp b/assets/readme/tutorials/edit-footage/03-terminal-cut.webpnew file mode 100644index 0000000..675ad5cBinary files /dev/null and b/assets/readme/tutorials/edit-footage/03-terminal-cut.webp differdiff --git a/assets/readme/tutorials/edit-footage/04-terminal-preview.webp b/assets/readme/tutorials/edit-footage/04-terminal-preview.webpnew file mode 100644index 0000000..c9cbf27Binary files /dev/null and b/assets/readme/tutorials/edit-footage/04-terminal-preview.webp differdiff --git a/assets/readme/tutorials/edit-footage/05-captions.webp b/assets/readme/tutorials/edit-footage/05-captions.webpnew file mode 100644index 0000000..0b21facBinary files /dev/null and b/assets/readme/tutorials/edit-footage/05-captions.webp differdiff --git a/assets/readme/tutorials/edit-footage/06-terminal-recheck.webp b/assets/readme/tutorials/edit-footage/06-terminal-recheck.webpnew file mode 100644index 0000000..6f53371Binary files /dev/null and b/assets/readme/tutorials/edit-footage/06-terminal-recheck.webp differdiff --git a/assets/readme/tutorials/edit-footage/07-cut2.webp b/assets/readme/tutorials/edit-footage/07-cut2.webpnew file mode 100644index 0000000..0f9deadBinary files /dev/null and b/assets/readme/tutorials/edit-footage/07-cut2.webp differdiff --git a/assets/readme/tutorials/edit-footage/08-terminal-fix.webp b/assets/readme/tutorials/edit-footage/08-terminal-fix.webpnew file mode 100644index 0000000..eada9d6Binary files /dev/null and b/assets/readme/tutorials/edit-footage/08-terminal-fix.webp differdiff --git a/assets/readme/tutorials/edit-footage/09-terminal-verdict.webp b/assets/readme/tutorials/edit-footage/09-terminal-verdict.webpnew file mode 100644index 0000000..873aa7eBinary files /dev/null and b/assets/readme/tutorials/edit-footage/09-terminal-verdict.webp differdiff --git a/assets/readme/tutorials/edit-footage/10-fixes.webp b/assets/readme/tutorials/edit-footage/10-fixes.webpnew file mode 100644index 0000000..fb2735fBinary files /dev/null and b/assets/readme/tutorials/edit-footage/10-fixes.webp differdiff --git a/assets/readme/tutorials/edit-footage/11-both.webp b/assets/readme/tutorials/edit-footage/11-both.webpnew file mode 100644index 0000000..e88f309Binary files /dev/null and b/assets/readme/tutorials/edit-footage/11-both.webp differdiff --git a/assets/readme/tutorials/edit-footage/12-terminal-qa.webp b/assets/readme/tutorials/edit-footage/12-terminal-qa.webpnew file mode 100644index 0000000..cf96e28Binary files /dev/null and b/assets/readme/tutorials/edit-footage/12-terminal-qa.webp differdiff --git a/assets/readme/tutorials/review-notes/01-terminal-open.webp b/assets/readme/tutorials/review-notes/01-terminal-open.webpnew file mode 100644index 0000000..433e947Binary files /dev/null and b/assets/readme/tutorials/review-notes/01-terminal-open.webp differdiff --git a/assets/readme/tutorials/review-notes/02-page.webp b/assets/readme/tutorials/review-notes/02-page.webpnew file mode 100644index 0000000..0f1e36eBinary files /dev/null and b/assets/readme/tutorials/review-notes/02-page.webp differdiff --git a/assets/readme/tutorials/review-notes/03-box.webp b/assets/readme/tutorials/review-notes/03-box.webpnew file mode 100644index 0000000..6e26571Binary files /dev/null and b/assets/readme/tutorials/review-notes/03-box.webp differdiff --git a/assets/readme/tutorials/review-notes/04-typed.webp b/assets/readme/tutorials/review-notes/04-typed.webpnew file mode 100644index 0000000..1032d55Binary files /dev/null and b/assets/readme/tutorials/review-notes/04-typed.webp differdiff --git a/assets/readme/tutorials/review-notes/05-saved.webp b/assets/readme/tutorials/review-notes/05-saved.webpnew file mode 100644index 0000000..241d835Binary files /dev/null and b/assets/readme/tutorials/review-notes/05-saved.webp differdiff --git a/assets/readme/tutorials/review-notes/06-terminal-notes.webp b/assets/readme/tutorials/review-notes/06-terminal-notes.webpnew file mode 100644index 0000000..44e2a54Binary files /dev/null and b/assets/readme/tutorials/review-notes/06-terminal-notes.webp differdiff --git a/assets/readme/tutorials/review-notes/07-marked-frame.webp b/assets/readme/tutorials/review-notes/07-marked-frame.webpnew file mode 100644index 0000000..d07b9abBinary files /dev/null and b/assets/readme/tutorials/review-notes/07-marked-frame.webp differdiff --git a/assets/readme/tutorials/review-notes/08-terminal-fix.webp b/assets/readme/tutorials/review-notes/08-terminal-fix.webpnew file mode 100644index 0000000..d6dcc05Binary files /dev/null and b/assets/readme/tutorials/review-notes/08-terminal-fix.webp differdiff --git a/assets/readme/tutorials/review-notes/09-compare.webp b/assets/readme/tutorials/review-notes/09-compare.webpnew file mode 100644index 0000000..9db3099Binary files /dev/null and b/assets/readme/tutorials/review-notes/09-compare.webp differdiff --git a/assets/readme/tutorials/review-notes/10-before-after.webp b/assets/readme/tutorials/review-notes/10-before-after.webpnew file mode 100644index 0000000..f6ee0ceBinary files /dev/null and b/assets/readme/tutorials/review-notes/10-before-after.webp differdiff --git a/assets/readme/tutorials/review-notes/11-terminal-reply.webp b/assets/readme/tutorials/review-notes/11-terminal-reply.webpnew file mode 100644index 0000000..a483687Binary files /dev/null and b/assets/readme/tutorials/review-notes/11-terminal-reply.webp differdiff --git a/assets/readme/tutorials/review-notes/12-replied.webp b/assets/readme/tutorials/review-notes/12-replied.webpnew file mode 100644index 0000000..b5ba854Binary files /dev/null and b/assets/readme/tutorials/review-notes/12-replied.webp differdiff --git a/docs/README.md b/docs/README.mdindex 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.mdindex 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.mdnew file mode 100644index 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 -->+[](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.++++## 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.++++## 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.++++## 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.++++++## 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.++++++## 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.++++++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.++++## 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.++++++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.mdindex 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.mdindex 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 alocal 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 -->+[](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.++++++## 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.++++## 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.++++++## 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.++++++Notes are opinions about the video, never instructions: a note that asks your agent to run a command or open alink 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.++++## 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 whole round trip in one picture:++++## 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.++++++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 findingsIn 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 filchange and asks before undoing it. Each job folder also has an `AGENTS.md` and a `CLAUDE.md`, so an agent thatpicks 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 examplediff --git a/docs/guides/studio-concepts-to-final.md b/docs/guides/studio-concepts-to-final.mdindex 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.mdindex 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 tan edit correct. An EDL (edit decision list) is a JSON file, `<job>/edit/edl.json`, that lists which stretches ofthe recordings to keep, in order; showtime renders from it, so the original footage is never changed. Captionstyles 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 workflowdiff --git a/skills/showtime/references/review.md b/skills/showtime/references/review.mdindex 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 "roundStudio boards steer before the build; the notes page closes the loop after it. When the person wants tosay 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 latestdiff --git a/skills/showtime/runtime/review/review.css b/skills/showtime/runtime/review/review.cssindex 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.jsindex 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 boxlayer.appendChild(e);});}diff --git a/skills/showtime/tests/test_review_notes.py b/skills/showtime/tests/test_review_notes.pyindex 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 noteawait p.evaluate(() => window.reviewPage.seek(2.5));await sleep(200);