showtime
Docs / docs/guides/notes-and-fixes.md

Leave notes on a video and get them fixed

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.

Say this#

"Open the notes page for the launch video."

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 link gets a --wontfix.

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.

Editing files yourself#

You can edit the project's files by hand while your agent is away. The next job command ends with one line, such as "since you last looked: index.html edited by hand, 2 unread notes", and showtime status <job> lists the changes, your unread notes and any open findings. Your agent reads a changed file before touching it, keeps your 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#

  • <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.

How long it takes#

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).

Phrases that change it#

  • "Open the web version for notes" adds --html.
  • "Leave it, I agree with the critic" or "waive S2, the brand sets that colour" waives a finding with your reason.
  • "Keep the page open longer" sets --idle (minutes; 240 by default).

Limits#

  • The page runs on your machine. Someone on another computer cannot reach it.
  • 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 example#

The full rules are in review.md, section 6.

View or edit this page on GitHub