agentcut 0.2.3 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -64,7 +64,8 @@ projects/<slug>/
64
64
  5. **Sound** (`references/sound.md`): voice and music first, then SFX on picture cues. You cannot hear;
65
65
  never say a sound fits without `agentcut_listen_*` numbers, and write them in notes.md.
66
66
  6. **Review**: `agentcut_contact_sheet` across the whole video for each variant, and
67
- `agentcut_listen_critique` for the mix. Fix what they show.
67
+ `agentcut_listen_critique` for the mix. Fix what they show. `agentcut_preview_check` every heavy scene
68
+ so the preview plays smoothly (`references/performance.md`); never at the cost of render quality.
68
69
  7. **Hand off** in a few lines: what's where, what's easy to tweak by hand. Export only when the user
69
70
  asks (`agentcut_export`); report the paths and measured loudness.
70
71
 
@@ -137,10 +138,11 @@ scripts from the project folder (e.g. composing music or fetching CC0 sounds, se
137
138
  |---|---|
138
139
  | `agentcut_status` | first, and after every edit (build + validation) |
139
140
  | `agentcut_create_project` / `_open_project` | new video / switch project |
140
- | `agentcut_capture_frames` | look at specific frames (same renderer as export) |
141
+ | `agentcut_capture_frames` | look at specific frames (same renderer as export); `region` + `scale: 2` for a sharp crop |
141
142
  | `agentcut_contact_sheet` | stills sheet of the whole video before export |
142
143
  | `agentcut_media_info` | exact durations (frames) for clips |
143
144
  | `agentcut_transcribe` | word timings for voice / lyrics |
145
+ | `agentcut_preview_check` | does the live preview keep up? dropped frames per clip (see `references/performance.md`) |
144
146
  | `agentcut_import_reference` | Style Spy: a reference video plus sampled frames (see `references/style-spy.md`) |
145
147
  | `agentcut_voice_options` / `_generate_voice` | voice-overs with the user's own provider (see `references/sound.md`) |
146
148
  | `agentcut_components` | the component library: search, then `id` for props and a ready clip |
@@ -0,0 +1,81 @@
1
+ # Preview performance
2
+
3
+ The user watches the live preview, which draws every scene in their browser at playback speed. A scene
4
+ that takes too long per frame makes the preview skip frames (choppy) and can freeze the tab while you
5
+ capture frames. The export doesn't skip: it renders every frame at full quality. So:
6
+
7
+ **Never lower what the render shows to make the preview smoother.** No lower resolution, fewer
8
+ elements on screen, skipped frames, softer images or simpler motion. Every change below must render
9
+ the same frames as before (check with captures); when one can't, keep the look and tell the user that
10
+ part previews choppy but exports perfectly.
11
+
12
+ ## Measure
13
+
14
+ - `agentcut_preview_check` (from/to in frames) plays a range muted in the user's preview and returns
15
+ per visual clip: frames played and dropped, loading stalls, the longest freeze, the most DOM elements
16
+ the clip drew, and a verdict: `smooth`, `choppy` from 20 % dropped, `heavy` from 40 % (and at least 6
17
+ dropped frames); a freeze over a second or more than 0.5 s of stalls also counts as slow. It takes as
18
+ long as the range plays: check the clip you changed, not the whole video every time. One check at a
19
+ time; it stops if the user pauses or seeks.
20
+ - `slowClips` lists the likeliest cause first. `sharesDropsOnly` marks a clip (often text or captions)
21
+ that only sits on top of a slower one: fix the other one. `slowToMount` means the clip drops frames in
22
+ the second before it starts, while it mounts early: its setup work is heavy (see rule 4), even when it
23
+ plays fine afterwards.
24
+ - `agentcut_status` → `page.previewPerformance` has the latest check (`lastCheck`) and the user's own
25
+ playback (`playback`). `current: false` means it was measured on an older build.
26
+ - Run a check after building or changing a heavy scene (walls and grids, hundreds of elements, image
27
+ sequences, big blurs, generated images) and before you say you're done. A first run includes loading
28
+ (stalls); run it again to see steady playback. A machine's own jitter varies between runs: act on a
29
+ `choppy` only when a second run agrees.
30
+
31
+ ## Make it lighter (same pixels)
32
+
33
+ 1. **Image sequences that stall.** Swapping a different picture every few frames makes the browser fetch
34
+ and decode a full image each time. When a check shows stalls or drops on one, encode it into one video,
35
+ but only if it keeps the same picture and timing:
36
+ - Keep the images when the frames have transparency (H.264 has none, they'd render on black), or
37
+ small text and hard-edged colored UI (4:2:0 color softens it).
38
+ - The video must show each image on exactly the frames it shows now. Images held the same number of
39
+ frames each: `-framerate <fps / frames per image>`. Any other timing (eased, held, reversed): write
40
+ the images out in display order, one file per project frame, and encode at the project fps.
41
+ - Encode at the frames' own size (never smaller than they ever appear), visually lossless, BT.709:
42
+ ```
43
+ ffmpeg -framerate <rate> -start_number <first> -i f%03d.png \
44
+ -vf "pad=ceil(iw/2)*2:ceil(ih/2)*2,scale=out_color_matrix=bt709:out_range=tv,format=yuv420p" \
45
+ -c:v libx264 -crf 12 -preset slow -colorspace bt709 -color_primaries bt709 -color_trc bt709 \
46
+ -color_range tv -movflags +faststart out.mp4
47
+ ```
48
+ `pad` adds one pixel on the right or bottom when a side is odd (H.264 4:2:0 needs even sizes):
49
+ draw the video at its padded size inside a box of the frames' size with `overflow: hidden`.
50
+ - ffmpeg is on PATH or in `~/.agentcut/tools/ffmpeg/`; if there's none, ask the user.
51
+ - Play it with `<Video>` from `@remotion/media` (`trimBefore` in frames to start inside it). Many tiles
52
+ of the same footage: one video per distinct clip.
53
+ - Capture frames across the sequence before and after and compare; if colors or edges differ,
54
+ keep the images.
55
+ 2. **Repeated complex elements that never change** (a wall of the same static card): draw the piece
56
+ once to an image and show the copies as `<Img>`. Make it with `agentcut_capture_frames` at `scale: 2`
57
+ with `region` set to the piece's box in composition pixels, on a frame where it's fully drawn and
58
+ unobstructed; save it in `assets/` and show it at its 1x size. Keep the live version for every copy
59
+ that animates or changes, and for anything the camera zooms past 2x, so its text stays sharp (House
60
+ style).
61
+ 3. **Draw only what's visible.** An absolutely positioned element that is fully outside the frame or at
62
+ opacity 0 can `return null`. Not when it sits in a flex or grid layout (opacity 0 still takes its
63
+ space, so its siblings would move), not when it holds `<Audio>`/`<Video>` (the sound would stop), and
64
+ "outside" means after the camera's transforms and including its shadow and blur.
65
+ 4. **Compute once.** Canvases, data URLs, noise and layout math that don't depend on the frame go in
66
+ `useMemo` (or module scope), never in every render; nothing heavy in a component that mounts per tile.
67
+ Anything random must stay deterministic: `random("seed")` from `remotion`, never `Math.random()`,
68
+ which differs on every load and between the export's render tabs (it would flicker).
69
+ 5. **One filter on a wrapper** instead of the same `filter`/`blur` on dozens of children, only when the
70
+ children don't overlap or touch (a blur or drop-shadow of the group differs where they meet), then
71
+ compare captures. Big animated blurs are the most expensive thing to draw: keep their area as small as
72
+ the look allows.
73
+ 6. **Fewer DOM nodes for the same look.** A stack of plain divs for a skeleton UI can often be one
74
+ element with a `linear-gradient` background or an inline SVG that draws the same lines (check
75
+ `browser-export.md` for what the export draws). Never remove anything that shows.
76
+ 7. **WebGL and canvas scenes**: `usePreviewQuality()` lowers resolution and redraw rate in the preview
77
+ only (`browser-export.md`); captures and the export keep full quality.
78
+
79
+ After a change, capture the same frames as before (`agentcut_capture_frames`, the export's own
80
+ renderer) and compare: the frames must look the same. Then run `agentcut_preview_check` again and report
81
+ the before/after drop rates.