agentcut 0.2.26 → 0.2.27
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.
- package/README.md +177 -177
- package/dist/studio/agents/claude.js +3 -2
- package/dist/studio/agents/claude.js.map +1 -1
- package/dist/studio/chat.js +1 -1
- package/dist/studio/chat.js.map +1 -1
- package/dist/studio/cli.js +24 -24
- package/dist/studio/download.d.ts +24 -0
- package/dist/studio/download.js +234 -0
- package/dist/studio/download.js.map +1 -0
- package/dist/studio/host.js +8 -0
- package/dist/studio/host.js.map +1 -1
- package/dist/studio/housekeeping.d.ts +2 -2
- package/dist/studio/housekeeping.js +18 -17
- package/dist/studio/housekeeping.js.map +1 -1
- package/dist/studio/release-cursor.js +21 -21
- package/dist/studio/release-video.js +10 -10
- package/dist/studio/tools.js +7 -0
- package/dist/studio/tools.js.map +1 -1
- package/package.json +56 -56
- package/template/AGENTS.md +14 -14
- package/template/components/README.md +70 -70
- package/template/components/before-after/BeforeAfter.tsx +89 -89
- package/template/components/catalog.ts +107 -107
- package/template/components/cinematic/Device3D.tsx +324 -324
- package/template/components/cinematic/devices3d/display-model.ts +184 -184
- package/template/components/cinematic/devices3d/iphone-model.ts +643 -643
- package/template/components/cinematic/devices3d/macbook-model.ts +608 -608
- package/template/components/cinematic/devices3d/models.ts +657 -657
- package/template/components/cinematic/devices3d/runtime.ts +267 -267
- package/template/components/cinematic/math.ts +100 -100
- package/template/components/color/grade-effect.ts +650 -650
- package/template/components/color/grade.ts +512 -512
- package/template/components/color/looks.ts +154 -154
- package/template/components/countdown/Countdown.tsx +166 -166
- package/template/components/dot-trace-title/DotTraceTitle.tsx +181 -181
- package/template/components/dot-trace-title/meta.json +51 -51
- package/template/components/generate/GenerateReveal.tsx +381 -381
- package/template/components/hook-card/HookCard.tsx +554 -554
- package/template/components/index.ts +199 -199
- package/template/components/lib.ts +191 -191
- package/template/components/line-diagram/LineDiagram.tsx +205 -205
- package/template/components/line-diagram/meta.json +215 -215
- package/template/components/list-card/ListCard.tsx +104 -104
- package/template/components/live-clip.ts +75 -75
- package/template/components/looks.tsx +1447 -1447
- package/template/components/loops/LoopCanvas.tsx +132 -132
- package/template/components/loops/engine.ts +184 -184
- package/template/components/loops/library.ts +667 -667
- package/template/components/loops/library2.ts +777 -777
- package/template/components/motion-loop/MotionLoop.tsx +37 -37
- package/template/components/motion-loop/meta.json +311 -311
- package/template/components/props.ts +73 -73
- package/template/components/quote-card/QuoteCard.tsx +71 -71
- package/template/components/style-layer.tsx +233 -233
- package/template/components/styles.ts +113 -113
- package/template/components/types.ts +66 -66
- package/template/components/word-pop/WordPop.tsx +59 -59
- package/template/components/word-stack/WordStack.tsx +122 -122
- package/template/presets/charcoal-sketch/PROMPT.md +48 -48
- package/template/presets/charcoal-sketch/scripts/duck_music.py +34 -34
- package/template/presets/punk-cut-paper/scenes/Motif.tsx +376 -376
- package/template/presets/punk-cut-paper/scenes/Photo.tsx +73 -73
- package/template/presets/punk-cut-paper/scenes/Ransom.tsx +119 -119
- package/template/runtime/composition.tsx +1189 -1189
- package/template/runtime/helpers.tsx +230 -230
- package/template/runtime/index.tsx +22 -22
- package/template/runtime/types.ts +315 -315
- package/template/skill/SKILL.md +186 -187
- package/template/skill/references/broll.md +44 -44
- package/template/skill/references/browser-export.md +61 -61
- package/template/skill/references/cinematic.md +206 -206
- package/template/skill/references/color.md +79 -79
- package/template/skill/references/craft.md +97 -97
- package/template/skill/references/editing-styles.md +57 -57
- package/template/skill/references/feature-launch.md +34 -34
- package/template/skill/references/footage.md +72 -72
- package/template/skill/references/format.md +142 -142
- package/template/skill/references/how-to.md +146 -146
- package/template/skill/references/launch-direction.md +89 -89
- package/template/skill/references/loops.md +151 -151
- package/template/skill/references/mcp-external.md +19 -19
- package/template/skill/references/performance.md +93 -93
- package/template/skill/references/person-cutout.md +19 -19
- package/template/skill/references/presets.md +60 -60
- package/template/skill/references/product-launch.md +134 -134
- package/template/skill/references/release-capture.md +53 -53
- package/template/skill/references/sound.md +167 -166
- package/template/skill/references/style-spy.md +160 -160
- package/template/skill/references/website-howto.md +45 -45
- package/template/starter/.studio/chat.json +1 -1
- package/template/starter/layers.json +46 -46
- package/template/starter/notes.md +4 -4
- package/template/starter/project.json +13 -13
- package/template/starter/scenes/Title.tsx +38 -38
|
@@ -1,206 +1,206 @@
|
|
|
1
|
-
# Cinematic Mode: product shots with a real camera
|
|
2
|
-
|
|
3
|
-
A **Cinematic** message hands you screenshots and/or screen recordings and a **direction** (mood, camera
|
|
4
|
-
energy, signature move, palette, type, transitions) rolled at random by the studio. Your job: a short,
|
|
5
|
-
premium product film in the spirit of Apple launch shots — screens tilted in 3D, lens blur,
|
|
6
|
-
UI pieces lifting off the glass, light sweeping across, a camera that always moves with intent.
|
|
7
|
-
|
|
8
|
-
Every take must look different (follow the direction you were given, don't fall back to your favourite
|
|
9
|
-
moves) and every take must look expensive (the quality gate below is not optional).
|
|
10
|
-
|
|
11
|
-
## The toolkit (`agentcut/components`)
|
|
12
|
-
|
|
13
|
-
```tsx
|
|
14
|
-
import { useCurrentFrame } from "remotion";
|
|
15
|
-
import { asset, type SceneProps } from "agentcut";
|
|
16
|
-
import { Backdrop, Device3D, Floor, Glare, Group, Lift, Plane, PlaneVideo, Screen, Stage, progress, useStage } from "agentcut/components";
|
|
17
|
-
```
|
|
18
|
-
|
|
19
|
-
It is a real 3D camera: each plane gets one `matrix3d()`, which the preview and the browser export both
|
|
20
|
-
draw (the export through WebGL). **Never** add CSS `perspective`, `preserve-3d` or your own 3D transforms
|
|
21
|
-
around it; place things with the toolkit's props.
|
|
22
|
-
|
|
23
|
-
**Draw order is JSX order, not depth.** Nothing sorts by z: write the Stage's children back to front
|
|
24
|
-
(backdrop and loops, floor, far planes, the device, lifts and titles in front). A `Device3D` is one
|
|
25
|
-
full-frame layer, so a Plane written after it covers it wherever they overlap, whatever their z.
|
|
26
|
-
|
|
27
|
-
**World units**: px at 1080 on the short side (`useStage().u` scales to the frame). `x` right, `y` down,
|
|
28
|
-
`z` toward the viewer; (0,0,0) is the frame center. `useStage()` → `{ width, height, u, vertical, worldWidth,
|
|
29
|
-
worldHeight }`: size screens from `worldWidth` so both variants frame well (`vertical` → smaller screens,
|
|
30
|
-
narrower moves).
|
|
31
|
-
|
|
32
|
-
- `<Stage camera={pose | keys} float motionBlur seed background>` — everything 3D goes inside. `camera` is
|
|
33
|
-
one pose or keyframes `{ at: frame, ...pose, ease }`; keys carry values forward, `ease` is the move
|
|
34
|
-
*into* that key: `linear`, `in`, `out`, `inOut` (default), `expo` (premium glide), `back` (small
|
|
35
|
-
overshoot), `whip` (slow–very fast–slow). Pose:
|
|
36
|
-
- `x, y, z`: the point the camera looks at. `zoom`: 1 = things at z 0 at their size, 2 = twice as close.
|
|
37
|
-
- `tilt` (> 0: the camera rises and looks down, so floors and laptop decks show their top), `turn`
|
|
38
|
-
(> 0: the camera orbits left, the right side recedes), `roll` (> 0 clockwise), all degrees. To lay a
|
|
39
|
-
flat screen back like a laptop on a desk, tilt the **Screen/Group** (`tilt 25–55`) and keep the camera
|
|
40
|
-
tilt small (5–20) with some `turn` and `roll`.
|
|
41
|
-
- `fov`: 15–25 flat telephoto (default 24, product look), 35 natural, 50–70 dramatic close-ups.
|
|
42
|
-
- `focus`: a world point `[x, y, z]` (put it ON the thing that matters) or px toward the camera from
|
|
43
|
-
the target. `aperture`: 0 none, 0.4 subtle, 1 strong, 2.5–4 macro (see Macro focus), 6+ a razor line. Focus and aperture animate: a rack
|
|
44
|
-
focus is two keys with different `focus` points.
|
|
45
|
-
- `shiftX`, `shiftY`: move the subject off-center (fractions of the frame) to leave room for a title.
|
|
46
|
-
- `float` 0–1: handheld drift (0.3–0.6 on holds keeps them alive). `motionBlur` 0–1: blur on fast moves.
|
|
47
|
-
- `<Screen kind src width ...placement>` — a screenshot (`src`), a screen recording (`video`, with
|
|
48
|
-
`videoProps` for `volume`, `loop`, `trimBefore`…) or `children` (live React UI) in a device. `kind`: `browser` (+ `url`), `iphone`, `ipad`,
|
|
49
|
-
`monitor`, `none`. `width` is the SCREEN width. Set `aspect` to the screenshot's width/height when it
|
|
50
|
-
differs from the device (or `imageAspect` + `scroll` 0→1 to scroll a tall page). `finish`: `black` /
|
|
51
|
-
`silver` (hardware), `light` / `dark` (browser). Extras: `shadow` (0.7), `reflection` (0–0.5 on dark
|
|
52
|
-
floors), `rim` (glass edge light), `glare` (0→1 sweep position), `dof={false}` to keep it sharp.
|
|
53
|
-
- `<Device3D model src size lifts ...placement>` — **real 3D hardware**, and the default for every phone,
|
|
54
|
-
laptop and desktop shot (three.js, drawn through the same camera, studio-lit with real reflections):
|
|
55
|
-
`model` `iphone` (iPhone 16 Pro Max model), `macbook` (keyboard, trackpad, opening lid: animate
|
|
56
|
-
`lidAngle` 0→110), `display` (Studio Display on its foot), `iphone-color` (a modern iPhone in colour: `finish` `graphite` (default), `lavender`, `mist-blue`,
|
|
57
|
-
`white`, `cosmic-orange`, or the brand's hex; pick a colour that suits the palette, show the back in
|
|
58
|
-
orbits and turn-arounds, and use several colours side by side for "for everyone" shots). `src` is the screenshot
|
|
59
|
-
on its screen (it covers the screen; a taller one shows its top, `scroll` 0→1 moves down it). `size` =
|
|
60
|
-
largest dimension in world px (defaults 760 / 1250 / 1150), `finish` `space-black` (MacBook default) `space-gray` `silver` `starlight`
|
|
61
|
-
`midnight` `black` (MacBook, display), `exposure`, `shadow`. `lifts`: pieces of the screenshot that rise
|
|
62
|
-
off the device's screen, `[{ box: [x, y, w, h] (fractions of the SCREENSHOT), z, scale, radius }]` —
|
|
63
|
-
they follow the screen's angle, even on an opening lid. Devices blur as a whole with the lens. Credit
|
|
64
|
-
the iPhone model in the hand-off: "iPhone 16 Pro Max model by MajdyModels, CC BY 4.0".
|
|
65
|
-
**Better laptop if the workspace has one:** check `library/models/` for a user-supplied GLB (e.g.
|
|
66
|
-
`macbook-pro-14.glb`, a Sketchfab "MacBook Pro 14-inch M5" under a licence that forbids bundling it).
|
|
67
|
-
If it's there, prefer `model="macbook-pro" modelSrc={asset("library:models/macbook-pro-14.glb")}` for
|
|
68
|
-
laptop shots: it's far more detailed than the built-in `macbook`. Its lid doesn't open (`lidAngle` is
|
|
69
|
-
ignored), so use the built-in `macbook` for lid-opening shots. Never copy such a model into a project's
|
|
70
|
-
assets or anywhere it would be shared. If it isn't there and the user wants the most realistic laptop,
|
|
71
|
-
tell them they can download it free (their own Sketchfab "Free Standard" licence, fine for their
|
|
72
|
-
videos) from https://sketchfab.com/3d-models/macbook-pro-14-inch-m5-652a992f4f244122ae251f9cbb81da1e
|
|
73
|
-
(the "glb · Original format" download) and save it as `library/models/macbook-pro-14.glb` in the
|
|
74
|
-
workspace. Use `modelSrc` only with `macbook-pro` (or `iphone` with a copy of the same GLB): the
|
|
75
|
-
built-in `macbook`, `display`, `iphone-color` and `iphone-classic` are drawn in code and can't take a GLB.
|
|
76
|
-
- **Never** use the flat `Screen` `iphone` / `ipad` / `monitor` frames when the shot shows the
|
|
77
|
-
device: they look like clip-art next to the 3D models. Flat `Screen` is for browser windows
|
|
78
|
-
(`kind="browser"`), frameless UI (`kind="none"`), giant readable close-ups where the hardware is off
|
|
79
|
-
frame, and tall pages you fly over with `scroll`.
|
|
80
|
-
- `<Lift src box kind width z scale ...>` — a region of a FLAT Screen rising out of it (for 3D devices use
|
|
81
|
-
`Device3D`'s `lifts`): put it in the same `<Group>` as its `<Screen>` with the same `kind`, `width`, `aspect`. `box` = `[x, y, w, h]` in
|
|
82
|
-
fractions of the screen picture. Animate `z` 0 → 40–140 and `scale` 1 → 1.03–1.15; it casts a real
|
|
83
|
-
shadow on the screen. With the camera looking down (tilt > 0) a lift also travels up the frame.
|
|
84
|
-
- `<Group ...placement>` moves/turns screens and their lifts together. `<Plane width height ...>` is the
|
|
85
|
-
raw surface: cards, text, logos, a second screenshot, anything in depth (`radius`, `background`,
|
|
86
|
-
`shadow`, `shadowDepth`, `reflection`, `rim`, `dof`, `blur` for extra softness in world px).
|
|
87
|
-
- A Plane with lens blur or a reflection draws its content more than once (blurred and mirrored copies
|
|
88
|
-
under the sharp one). Videos inside a Plane or as Screen `children` must be `<PlaneVideo>` (same props as
|
|
89
|
-
`@remotion/media`'s `<Video>`): only the sharp copy plays sound. Your own heavy content can check
|
|
90
|
-
`usePlaneLayer().copy` and draw less in the copies.
|
|
91
|
-
- **Backgrounds are motion loops first** (`references/loops.md`): `<LoopCanvas loop … />` as the
|
|
92
|
-
Stage's first child, or on a big Plane far behind (`z -600…-1200`) so it parallaxes with the camera.
|
|
93
|
-
Rotate loops and tones across shots; add a transparent shape loop as an accent. `<Backdrop>` is for
|
|
94
|
-
quiet shots where the background should disappear.
|
|
95
|
-
- `<GenerateReveal …>` as a flat Screen's children: the UI builds itself on the 3D screen like an agent is
|
|
96
|
-
generating it (see `references/loops.md` › Generated by an agent). A strong hook or reveal shot.
|
|
97
|
-
- `<Backdrop look>`: `studio` (dark, accent glow), `light` (Apple white), `aurora`, `spotlight`, `mesh`,
|
|
98
|
-
`solid`; `color`, `accent`, `accent2`, `glowX/Y` (animate slowly), `intensity`. First child of the Stage.
|
|
99
|
-
- `<Floor y size spacing color opacity glow near>`: a receding grid floor (reads best with tilt 15–35). It is
|
|
100
|
-
drawn in tiles, so the part that passes the lens drops out on its own.
|
|
101
|
-
- `<Glare progress angle width strength>` inside any Plane; `progress(frame, from, to, ease)` → 0…1.
|
|
102
|
-
- Placement (Screen, Plane, Group, Lift offsets): `x y z tilt turn roll scale`.
|
|
103
|
-
|
|
104
|
-
## Workflow
|
|
105
|
-
|
|
106
|
-
1. **Look at every file.** Open each screenshot (Read) and `agentcut_media_info` for size; for a
|
|
107
|
-
recording, capture or sample frames. Find 3–6 **hero regions** per screen (the number that matters,
|
|
108
|
-
the button, the chart, the card with the promise) and measure their `box` fractions from the image.
|
|
109
|
-
Write them in notes.md. Read the product's words: they become the titles.
|
|
110
|
-
2. **Shot list in notes.md** (show it to the user in 2–3 lines): 4–7 shots, 1.5–4 s each, for the
|
|
111
|
-
requested length. Each line: subject, camera move, signature effect, focus target, text, frames. Arc:
|
|
112
|
-
**reveal** (the whole product in a bold angle) → **details** (lifts, rack focus, push-ins on hero
|
|
113
|
-
regions, one per shot) → **payoff** (hero angle again, wider or rotated, then the name / CTA).
|
|
114
|
-
3. **Build one shot per scene file** (`scenes/Cine01Reveal.tsx` …), one clip each on a "Cinematic" track;
|
|
115
|
-
words, colors and key timings in `props` so the user can tune them. Titles: a library text component
|
|
116
|
-
on a track above, or HTML text on a `Plane` in the stage (text in depth, with blur, is a premium look).
|
|
117
|
-
4. **Music**: `agentcut_music_options` for the direction's mood, beats with `agentcut_analyze_audio`;
|
|
118
|
-
land cuts and lift peaks on beats, whips on a downbeat. One whoosh per whip, a soft tick per lift.
|
|
119
|
-
5. **Quality gate** (below), then hand off.
|
|
120
|
-
|
|
121
|
-
## Shot vocabulary (adapt the numbers, combine, invent)
|
|
122
|
-
|
|
123
|
-
| Move | Recipe |
|
|
124
|
-
|---|---|
|
|
125
|
-
| Tilt reveal | `<Group tilt={34}>` around the Screen; camera from `zoom 0.75 tilt 14 turn -26 roll 10` to `zoom 1.05 tilt 10 turn -16 roll 8`, `expo`, 70–110 f |
|
|
126
|
-
| Hero push | same angle, zoom +15–25 % over the shot, `inOut`, `float 0.4` |
|
|
127
|
-
| Rack focus | camera still or drifting; `focus` from region A to B over 20–30 f, `aperture 0.9–1.3` |
|
|
128
|
-
| Lift-out | `Device3D` `lifts` (or `Lift` on a flat Screen) z 0→80–140, scale →1.08, `back` or `expo`, focus moves to the lift |
|
|
129
|
-
| Macro focus | see "Macro focus" below: a flat screen seen at a grazing angle, one line sharp, everything else melted; slow drift only |
|
|
130
|
-
| Push to detail | zoom 1→2.2–3 on a hero region (`x, y` = its world center), aperture up as you go in |
|
|
131
|
-
| Fly-over | low `tilt 55–65`, camera `y` travels down the page, `fov 35`, long screenshot with `scroll` |
|
|
132
|
-
| Orbit | `Device3D` iPhone: camera `turn` −35 → +25, `tilt` 5–12, `fov 28–32`, a dark backdrop with a glow behind |
|
|
133
|
-
| Laptop opens | `Device3D macbook` with `lidAngle` 0→110 over 40–60 f (`expo`), camera `tilt 15–25` pushing in |
|
|
134
|
-
| Whip pan | hold, then `x` jumps to the next subject in 12–16 f with `whip`, `motionBlur 1`; cut or keep going |
|
|
135
|
-
| Drop-in | device (Screen or Device3D) starts `y −900 tilt 25`, lands with `back`; camera tiny shake via `float` |
|
|
136
|
-
| Exploded view | 3–5 Lifts at increasing z (40, 90, 140…) with small `turn`; camera turns 15° to show depth |
|
|
137
|
-
| Spotlight | `Backdrop spotlight` glow follows the hero (`glowX/Y`), aperture high, others fall into blur |
|
|
138
|
-
| Split screens | two Screens (desktop + phone) at different z; focus pulls from one to the other |
|
|
139
|
-
| Glass sweep | `glare` 0→1 over 40–60 f on a hold; `rim 0.6` |
|
|
140
|
-
| Dolly zoom | zoom up while fov goes down (or the reverse): the background perspective warps, subject holds |
|
|
141
|
-
| Title in depth | a Plane with the headline at z 150–300 in front of the screen, focus on it, screen soft behind |
|
|
142
|
-
|
|
143
|
-
## Brand colours and variety
|
|
144
|
-
|
|
145
|
-
Find the brand colours first (logo, UI, website) and build the palette from them
|
|
146
|
-
(`references/loops.md` › Brand palette). Every take must differ in loop choice, tone rotation, shapes
|
|
147
|
-
and type, not only in camera moves: write the rotation in the shot list, and check notes.md for what
|
|
148
|
-
the last take used.
|
|
149
|
-
|
|
150
|
-
## Macro focus (an occasional signature shot)
|
|
151
|
-
|
|
152
|
-
The extreme close-up where the camera skims the screen, one line of UI is crisp and everything in front
|
|
153
|
-
and behind melts into blur (the look of a macro lens). Use it **once or twice per film at most**, for a
|
|
154
|
-
detail worth savouring: a key number, a headline, a list. It is not the default framing.
|
|
155
|
-
|
|
156
|
-
- **Keep the screen flat** (no `tilt` on the Screen/Group) and get the angle from the **camera**:
|
|
157
|
-
`tilt 60–70`, `turn ±15–30`, `roll ±10–20`, `fov 30–36`, `zoom 2.5–3.2`, `aperture 2.5–4`
|
|
158
|
-
(6+ shrinks the sharp band to a line, only for a brief accent).
|
|
159
|
-
- **Focus on the surface:** `x, y` and `focus: [x, y, 0]` = the world point of the hero line on the flat
|
|
160
|
-
screen (measure it from the screenshot like a hero region). With a tilted screen a point `[x, y, 0]` is
|
|
161
|
-
off the surface and nothing comes out sharp.
|
|
162
|
-
- **The sharp area is a band, not a dot:** real depth of field is a slice across the surface at one
|
|
163
|
-
distance. Aim the band along the line of text you want (turn/roll set its direction). **Never** cut a
|
|
164
|
-
plane into tiles or stack copies to fake a focus point: the blurred tiles leave a visible grid.
|
|
165
|
-
- **Move slowly.** A macro shot is a slow, almost still drift: over 3–5 s, the camera's `x`/`y` travel at
|
|
166
|
-
most 60–120 world px and its angles at most 3–5°, with `inOut` or `linear` keys (no `expo`, `back`
|
|
167
|
-
or `whip`), `float 0.2–0.4`, no motion blur. Optionally a slow rack: `focus` slides 80–200 px along the
|
|
168
|
-
line over the whole shot. Fast moves at this magnification look like a glitch, not a lens.
|
|
169
|
-
- Cut into and out of it on a calm beat; the shots around it should be wider so the close-up lands.
|
|
170
|
-
|
|
171
|
-
## Taste rules
|
|
172
|
-
|
|
173
|
-
- **The hero is always sharp.** Put `focus` on it; blur is for what's around it. Never blur text the
|
|
174
|
-
viewer must read during a hold.
|
|
175
|
-
- One idea per shot, one signature effect per shot. Motion never stops: every hold drifts (`float`, slow
|
|
176
|
-
zoom), and moves start/stop with eased keys.
|
|
177
|
-
- Angles between 8° and 45°; mostly telephoto (fov 18–30). Extreme angles only on whips and reveals.
|
|
178
|
-
- Depth everywhere: something nearer than the screen (a lift, a title, a second device) and something
|
|
179
|
-
behind it (backdrop glow, floor). Flat-looking frames fail the gate.
|
|
180
|
-
- Never show the screen's edge cutting through the frame at an awkward 2–3 %: either full in frame with
|
|
181
|
-
air, or confidently cropped (≥ 15 % off frame).
|
|
182
|
-
- Text: 2–6 words per title, big, with contrast against the backdrop; on screen ≥ 1.2 s.
|
|
183
|
-
- Both variants: re-frame per variant with `useStage().vertical` (smaller widths, narrower x travel,
|
|
184
|
-
more vertical moves on mobile), never just let the wide shot crop.
|
|
185
|
-
- Contrast pairs that read premium: light UI on `studio`/`spotlight`; dark UI on `light` or `mesh`.
|
|
186
|
-
|
|
187
|
-
## Quality gate (before you say it's done)
|
|
188
|
-
|
|
189
|
-
For every shot: `agentcut_capture_frames` at the entrance, the middle and the exit, in wide AND mobile.
|
|
190
|
-
Open them and check:
|
|
191
|
-
1. The hero region is sharp and readable; the blur falls off naturally (no hard seams).
|
|
192
|
-
2. Nothing important is clipped; edges are either clean or boldly cropped.
|
|
193
|
-
3. There is depth (foreground + background), and the frame isn't empty or flat.
|
|
194
|
-
4. Titles are readable and don't collide with UI.
|
|
195
|
-
5. The move has a clear start and end (compare entrance vs exit).
|
|
196
|
-
Then `agentcut_contact_sheet` over the whole video (pacing, variety: no two consecutive shots with the
|
|
197
|
-
same angle and move) and `agentcut_preview_check` (each Plane with lens blur draws several copies; if a
|
|
198
|
-
shot is choppy, lower `aperture` on secondary planes or set `dof={false}` on them, never on the hero in
|
|
199
|
-
the export path). Fix what fails and re-capture. Write what you checked in notes.md.
|
|
200
|
-
|
|
201
|
-
## Takes
|
|
202
|
-
|
|
203
|
-
"Another take" asks for a new film from the same media with a new direction. Before changing anything,
|
|
204
|
-
copy project.json, layers.json and scenes/ to a new timestamped folder under `.studio/cinematic-takes/`
|
|
205
|
-
(never overwrite one). Then replace the Cinematic track and its scenes: new shot list, new moves, new
|
|
206
|
-
backdrop and type. Reusing the previous take's structure with new colors is a failure.
|
|
1
|
+
# Cinematic Mode: product shots with a real camera
|
|
2
|
+
|
|
3
|
+
A **Cinematic** message hands you screenshots and/or screen recordings and a **direction** (mood, camera
|
|
4
|
+
energy, signature move, palette, type, transitions) rolled at random by the studio. Your job: a short,
|
|
5
|
+
premium product film in the spirit of Apple launch shots — screens tilted in 3D, lens blur,
|
|
6
|
+
UI pieces lifting off the glass, light sweeping across, a camera that always moves with intent.
|
|
7
|
+
|
|
8
|
+
Every take must look different (follow the direction you were given, don't fall back to your favourite
|
|
9
|
+
moves) and every take must look expensive (the quality gate below is not optional).
|
|
10
|
+
|
|
11
|
+
## The toolkit (`agentcut/components`)
|
|
12
|
+
|
|
13
|
+
```tsx
|
|
14
|
+
import { useCurrentFrame } from "remotion";
|
|
15
|
+
import { asset, type SceneProps } from "agentcut";
|
|
16
|
+
import { Backdrop, Device3D, Floor, Glare, Group, Lift, Plane, PlaneVideo, Screen, Stage, progress, useStage } from "agentcut/components";
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
It is a real 3D camera: each plane gets one `matrix3d()`, which the preview and the browser export both
|
|
20
|
+
draw (the export through WebGL). **Never** add CSS `perspective`, `preserve-3d` or your own 3D transforms
|
|
21
|
+
around it; place things with the toolkit's props.
|
|
22
|
+
|
|
23
|
+
**Draw order is JSX order, not depth.** Nothing sorts by z: write the Stage's children back to front
|
|
24
|
+
(backdrop and loops, floor, far planes, the device, lifts and titles in front). A `Device3D` is one
|
|
25
|
+
full-frame layer, so a Plane written after it covers it wherever they overlap, whatever their z.
|
|
26
|
+
|
|
27
|
+
**World units**: px at 1080 on the short side (`useStage().u` scales to the frame). `x` right, `y` down,
|
|
28
|
+
`z` toward the viewer; (0,0,0) is the frame center. `useStage()` → `{ width, height, u, vertical, worldWidth,
|
|
29
|
+
worldHeight }`: size screens from `worldWidth` so both variants frame well (`vertical` → smaller screens,
|
|
30
|
+
narrower moves).
|
|
31
|
+
|
|
32
|
+
- `<Stage camera={pose | keys} float motionBlur seed background>` — everything 3D goes inside. `camera` is
|
|
33
|
+
one pose or keyframes `{ at: frame, ...pose, ease }`; keys carry values forward, `ease` is the move
|
|
34
|
+
*into* that key: `linear`, `in`, `out`, `inOut` (default), `expo` (premium glide), `back` (small
|
|
35
|
+
overshoot), `whip` (slow–very fast–slow). Pose:
|
|
36
|
+
- `x, y, z`: the point the camera looks at. `zoom`: 1 = things at z 0 at their size, 2 = twice as close.
|
|
37
|
+
- `tilt` (> 0: the camera rises and looks down, so floors and laptop decks show their top), `turn`
|
|
38
|
+
(> 0: the camera orbits left, the right side recedes), `roll` (> 0 clockwise), all degrees. To lay a
|
|
39
|
+
flat screen back like a laptop on a desk, tilt the **Screen/Group** (`tilt 25–55`) and keep the camera
|
|
40
|
+
tilt small (5–20) with some `turn` and `roll`.
|
|
41
|
+
- `fov`: 15–25 flat telephoto (default 24, product look), 35 natural, 50–70 dramatic close-ups.
|
|
42
|
+
- `focus`: a world point `[x, y, z]` (put it ON the thing that matters) or px toward the camera from
|
|
43
|
+
the target. `aperture`: 0 none, 0.4 subtle, 1 strong, 2.5–4 macro (see Macro focus), 6+ a razor line. Focus and aperture animate: a rack
|
|
44
|
+
focus is two keys with different `focus` points.
|
|
45
|
+
- `shiftX`, `shiftY`: move the subject off-center (fractions of the frame) to leave room for a title.
|
|
46
|
+
- `float` 0–1: handheld drift (0.3–0.6 on holds keeps them alive). `motionBlur` 0–1: blur on fast moves.
|
|
47
|
+
- `<Screen kind src width ...placement>` — a screenshot (`src`), a screen recording (`video`, with
|
|
48
|
+
`videoProps` for `volume`, `loop`, `trimBefore`…) or `children` (live React UI) in a device. `kind`: `browser` (+ `url`), `iphone`, `ipad`,
|
|
49
|
+
`monitor`, `none`. `width` is the SCREEN width. Set `aspect` to the screenshot's width/height when it
|
|
50
|
+
differs from the device (or `imageAspect` + `scroll` 0→1 to scroll a tall page). `finish`: `black` /
|
|
51
|
+
`silver` (hardware), `light` / `dark` (browser). Extras: `shadow` (0.7), `reflection` (0–0.5 on dark
|
|
52
|
+
floors), `rim` (glass edge light), `glare` (0→1 sweep position), `dof={false}` to keep it sharp.
|
|
53
|
+
- `<Device3D model src size lifts ...placement>` — **real 3D hardware**, and the default for every phone,
|
|
54
|
+
laptop and desktop shot (three.js, drawn through the same camera, studio-lit with real reflections):
|
|
55
|
+
`model` `iphone` (iPhone 16 Pro Max model), `macbook` (keyboard, trackpad, opening lid: animate
|
|
56
|
+
`lidAngle` 0→110), `display` (Studio Display on its foot), `iphone-color` (a modern iPhone in colour: `finish` `graphite` (default), `lavender`, `mist-blue`,
|
|
57
|
+
`white`, `cosmic-orange`, or the brand's hex; pick a colour that suits the palette, show the back in
|
|
58
|
+
orbits and turn-arounds, and use several colours side by side for "for everyone" shots). `src` is the screenshot
|
|
59
|
+
on its screen (it covers the screen; a taller one shows its top, `scroll` 0→1 moves down it). `size` =
|
|
60
|
+
largest dimension in world px (defaults 760 / 1250 / 1150), `finish` `space-black` (MacBook default) `space-gray` `silver` `starlight`
|
|
61
|
+
`midnight` `black` (MacBook, display), `exposure`, `shadow`. `lifts`: pieces of the screenshot that rise
|
|
62
|
+
off the device's screen, `[{ box: [x, y, w, h] (fractions of the SCREENSHOT), z, scale, radius }]` —
|
|
63
|
+
they follow the screen's angle, even on an opening lid. Devices blur as a whole with the lens. Credit
|
|
64
|
+
the iPhone model in the hand-off: "iPhone 16 Pro Max model by MajdyModels, CC BY 4.0".
|
|
65
|
+
**Better laptop if the workspace has one:** check `library/models/` for a user-supplied GLB (e.g.
|
|
66
|
+
`macbook-pro-14.glb`, a Sketchfab "MacBook Pro 14-inch M5" under a licence that forbids bundling it).
|
|
67
|
+
If it's there, prefer `model="macbook-pro" modelSrc={asset("library:models/macbook-pro-14.glb")}` for
|
|
68
|
+
laptop shots: it's far more detailed than the built-in `macbook`. Its lid doesn't open (`lidAngle` is
|
|
69
|
+
ignored), so use the built-in `macbook` for lid-opening shots. Never copy such a model into a project's
|
|
70
|
+
assets or anywhere it would be shared. If it isn't there and the user wants the most realistic laptop,
|
|
71
|
+
tell them they can download it free (their own Sketchfab "Free Standard" licence, fine for their
|
|
72
|
+
videos) from https://sketchfab.com/3d-models/macbook-pro-14-inch-m5-652a992f4f244122ae251f9cbb81da1e
|
|
73
|
+
(the "glb · Original format" download) and save it as `library/models/macbook-pro-14.glb` in the
|
|
74
|
+
workspace. Use `modelSrc` only with `macbook-pro` (or `iphone` with a copy of the same GLB): the
|
|
75
|
+
built-in `macbook`, `display`, `iphone-color` and `iphone-classic` are drawn in code and can't take a GLB.
|
|
76
|
+
- **Never** use the flat `Screen` `iphone` / `ipad` / `monitor` frames when the shot shows the
|
|
77
|
+
device: they look like clip-art next to the 3D models. Flat `Screen` is for browser windows
|
|
78
|
+
(`kind="browser"`), frameless UI (`kind="none"`), giant readable close-ups where the hardware is off
|
|
79
|
+
frame, and tall pages you fly over with `scroll`.
|
|
80
|
+
- `<Lift src box kind width z scale ...>` — a region of a FLAT Screen rising out of it (for 3D devices use
|
|
81
|
+
`Device3D`'s `lifts`): put it in the same `<Group>` as its `<Screen>` with the same `kind`, `width`, `aspect`. `box` = `[x, y, w, h]` in
|
|
82
|
+
fractions of the screen picture. Animate `z` 0 → 40–140 and `scale` 1 → 1.03–1.15; it casts a real
|
|
83
|
+
shadow on the screen. With the camera looking down (tilt > 0) a lift also travels up the frame.
|
|
84
|
+
- `<Group ...placement>` moves/turns screens and their lifts together. `<Plane width height ...>` is the
|
|
85
|
+
raw surface: cards, text, logos, a second screenshot, anything in depth (`radius`, `background`,
|
|
86
|
+
`shadow`, `shadowDepth`, `reflection`, `rim`, `dof`, `blur` for extra softness in world px).
|
|
87
|
+
- A Plane with lens blur or a reflection draws its content more than once (blurred and mirrored copies
|
|
88
|
+
under the sharp one). Videos inside a Plane or as Screen `children` must be `<PlaneVideo>` (same props as
|
|
89
|
+
`@remotion/media`'s `<Video>`): only the sharp copy plays sound. Your own heavy content can check
|
|
90
|
+
`usePlaneLayer().copy` and draw less in the copies.
|
|
91
|
+
- **Backgrounds are motion loops first** (`references/loops.md`): `<LoopCanvas loop … />` as the
|
|
92
|
+
Stage's first child, or on a big Plane far behind (`z -600…-1200`) so it parallaxes with the camera.
|
|
93
|
+
Rotate loops and tones across shots; add a transparent shape loop as an accent. `<Backdrop>` is for
|
|
94
|
+
quiet shots where the background should disappear.
|
|
95
|
+
- `<GenerateReveal …>` as a flat Screen's children: the UI builds itself on the 3D screen like an agent is
|
|
96
|
+
generating it (see `references/loops.md` › Generated by an agent). A strong hook or reveal shot.
|
|
97
|
+
- `<Backdrop look>`: `studio` (dark, accent glow), `light` (Apple white), `aurora`, `spotlight`, `mesh`,
|
|
98
|
+
`solid`; `color`, `accent`, `accent2`, `glowX/Y` (animate slowly), `intensity`. First child of the Stage.
|
|
99
|
+
- `<Floor y size spacing color opacity glow near>`: a receding grid floor (reads best with tilt 15–35). It is
|
|
100
|
+
drawn in tiles, so the part that passes the lens drops out on its own.
|
|
101
|
+
- `<Glare progress angle width strength>` inside any Plane; `progress(frame, from, to, ease)` → 0…1.
|
|
102
|
+
- Placement (Screen, Plane, Group, Lift offsets): `x y z tilt turn roll scale`.
|
|
103
|
+
|
|
104
|
+
## Workflow
|
|
105
|
+
|
|
106
|
+
1. **Look at every file.** Open each screenshot (Read) and `agentcut_media_info` for size; for a
|
|
107
|
+
recording, capture or sample frames. Find 3–6 **hero regions** per screen (the number that matters,
|
|
108
|
+
the button, the chart, the card with the promise) and measure their `box` fractions from the image.
|
|
109
|
+
Write them in notes.md. Read the product's words: they become the titles.
|
|
110
|
+
2. **Shot list in notes.md** (show it to the user in 2–3 lines): 4–7 shots, 1.5–4 s each, for the
|
|
111
|
+
requested length. Each line: subject, camera move, signature effect, focus target, text, frames. Arc:
|
|
112
|
+
**reveal** (the whole product in a bold angle) → **details** (lifts, rack focus, push-ins on hero
|
|
113
|
+
regions, one per shot) → **payoff** (hero angle again, wider or rotated, then the name / CTA).
|
|
114
|
+
3. **Build one shot per scene file** (`scenes/Cine01Reveal.tsx` …), one clip each on a "Cinematic" track;
|
|
115
|
+
words, colors and key timings in `props` so the user can tune them. Titles: a library text component
|
|
116
|
+
on a track above, or HTML text on a `Plane` in the stage (text in depth, with blur, is a premium look).
|
|
117
|
+
4. **Music**: `agentcut_music_options` for the direction's mood, beats with `agentcut_analyze_audio`;
|
|
118
|
+
land cuts and lift peaks on beats, whips on a downbeat. One whoosh per whip, a soft tick per lift.
|
|
119
|
+
5. **Quality gate** (below), then hand off.
|
|
120
|
+
|
|
121
|
+
## Shot vocabulary (adapt the numbers, combine, invent)
|
|
122
|
+
|
|
123
|
+
| Move | Recipe |
|
|
124
|
+
|---|---|
|
|
125
|
+
| Tilt reveal | `<Group tilt={34}>` around the Screen; camera from `zoom 0.75 tilt 14 turn -26 roll 10` to `zoom 1.05 tilt 10 turn -16 roll 8`, `expo`, 70–110 f |
|
|
126
|
+
| Hero push | same angle, zoom +15–25 % over the shot, `inOut`, `float 0.4` |
|
|
127
|
+
| Rack focus | camera still or drifting; `focus` from region A to B over 20–30 f, `aperture 0.9–1.3` |
|
|
128
|
+
| Lift-out | `Device3D` `lifts` (or `Lift` on a flat Screen) z 0→80–140, scale →1.08, `back` or `expo`, focus moves to the lift |
|
|
129
|
+
| Macro focus | see "Macro focus" below: a flat screen seen at a grazing angle, one line sharp, everything else melted; slow drift only |
|
|
130
|
+
| Push to detail | zoom 1→2.2–3 on a hero region (`x, y` = its world center), aperture up as you go in |
|
|
131
|
+
| Fly-over | low `tilt 55–65`, camera `y` travels down the page, `fov 35`, long screenshot with `scroll` |
|
|
132
|
+
| Orbit | `Device3D` iPhone: camera `turn` −35 → +25, `tilt` 5–12, `fov 28–32`, a dark backdrop with a glow behind |
|
|
133
|
+
| Laptop opens | `Device3D macbook` with `lidAngle` 0→110 over 40–60 f (`expo`), camera `tilt 15–25` pushing in |
|
|
134
|
+
| Whip pan | hold, then `x` jumps to the next subject in 12–16 f with `whip`, `motionBlur 1`; cut or keep going |
|
|
135
|
+
| Drop-in | device (Screen or Device3D) starts `y −900 tilt 25`, lands with `back`; camera tiny shake via `float` |
|
|
136
|
+
| Exploded view | 3–5 Lifts at increasing z (40, 90, 140…) with small `turn`; camera turns 15° to show depth |
|
|
137
|
+
| Spotlight | `Backdrop spotlight` glow follows the hero (`glowX/Y`), aperture high, others fall into blur |
|
|
138
|
+
| Split screens | two Screens (desktop + phone) at different z; focus pulls from one to the other |
|
|
139
|
+
| Glass sweep | `glare` 0→1 over 40–60 f on a hold; `rim 0.6` |
|
|
140
|
+
| Dolly zoom | zoom up while fov goes down (or the reverse): the background perspective warps, subject holds |
|
|
141
|
+
| Title in depth | a Plane with the headline at z 150–300 in front of the screen, focus on it, screen soft behind |
|
|
142
|
+
|
|
143
|
+
## Brand colours and variety
|
|
144
|
+
|
|
145
|
+
Find the brand colours first (logo, UI, website) and build the palette from them
|
|
146
|
+
(`references/loops.md` › Brand palette). Every take must differ in loop choice, tone rotation, shapes
|
|
147
|
+
and type, not only in camera moves: write the rotation in the shot list, and check notes.md for what
|
|
148
|
+
the last take used.
|
|
149
|
+
|
|
150
|
+
## Macro focus (an occasional signature shot)
|
|
151
|
+
|
|
152
|
+
The extreme close-up where the camera skims the screen, one line of UI is crisp and everything in front
|
|
153
|
+
and behind melts into blur (the look of a macro lens). Use it **once or twice per film at most**, for a
|
|
154
|
+
detail worth savouring: a key number, a headline, a list. It is not the default framing.
|
|
155
|
+
|
|
156
|
+
- **Keep the screen flat** (no `tilt` on the Screen/Group) and get the angle from the **camera**:
|
|
157
|
+
`tilt 60–70`, `turn ±15–30`, `roll ±10–20`, `fov 30–36`, `zoom 2.5–3.2`, `aperture 2.5–4`
|
|
158
|
+
(6+ shrinks the sharp band to a line, only for a brief accent).
|
|
159
|
+
- **Focus on the surface:** `x, y` and `focus: [x, y, 0]` = the world point of the hero line on the flat
|
|
160
|
+
screen (measure it from the screenshot like a hero region). With a tilted screen a point `[x, y, 0]` is
|
|
161
|
+
off the surface and nothing comes out sharp.
|
|
162
|
+
- **The sharp area is a band, not a dot:** real depth of field is a slice across the surface at one
|
|
163
|
+
distance. Aim the band along the line of text you want (turn/roll set its direction). **Never** cut a
|
|
164
|
+
plane into tiles or stack copies to fake a focus point: the blurred tiles leave a visible grid.
|
|
165
|
+
- **Move slowly.** A macro shot is a slow, almost still drift: over 3–5 s, the camera's `x`/`y` travel at
|
|
166
|
+
most 60–120 world px and its angles at most 3–5°, with `inOut` or `linear` keys (no `expo`, `back`
|
|
167
|
+
or `whip`), `float 0.2–0.4`, no motion blur. Optionally a slow rack: `focus` slides 80–200 px along the
|
|
168
|
+
line over the whole shot. Fast moves at this magnification look like a glitch, not a lens.
|
|
169
|
+
- Cut into and out of it on a calm beat; the shots around it should be wider so the close-up lands.
|
|
170
|
+
|
|
171
|
+
## Taste rules
|
|
172
|
+
|
|
173
|
+
- **The hero is always sharp.** Put `focus` on it; blur is for what's around it. Never blur text the
|
|
174
|
+
viewer must read during a hold.
|
|
175
|
+
- One idea per shot, one signature effect per shot. Motion never stops: every hold drifts (`float`, slow
|
|
176
|
+
zoom), and moves start/stop with eased keys.
|
|
177
|
+
- Angles between 8° and 45°; mostly telephoto (fov 18–30). Extreme angles only on whips and reveals.
|
|
178
|
+
- Depth everywhere: something nearer than the screen (a lift, a title, a second device) and something
|
|
179
|
+
behind it (backdrop glow, floor). Flat-looking frames fail the gate.
|
|
180
|
+
- Never show the screen's edge cutting through the frame at an awkward 2–3 %: either full in frame with
|
|
181
|
+
air, or confidently cropped (≥ 15 % off frame).
|
|
182
|
+
- Text: 2–6 words per title, big, with contrast against the backdrop; on screen ≥ 1.2 s.
|
|
183
|
+
- Both variants: re-frame per variant with `useStage().vertical` (smaller widths, narrower x travel,
|
|
184
|
+
more vertical moves on mobile), never just let the wide shot crop.
|
|
185
|
+
- Contrast pairs that read premium: light UI on `studio`/`spotlight`; dark UI on `light` or `mesh`.
|
|
186
|
+
|
|
187
|
+
## Quality gate (before you say it's done)
|
|
188
|
+
|
|
189
|
+
For every shot: `agentcut_capture_frames` at the entrance, the middle and the exit, in wide AND mobile.
|
|
190
|
+
Open them and check:
|
|
191
|
+
1. The hero region is sharp and readable; the blur falls off naturally (no hard seams).
|
|
192
|
+
2. Nothing important is clipped; edges are either clean or boldly cropped.
|
|
193
|
+
3. There is depth (foreground + background), and the frame isn't empty or flat.
|
|
194
|
+
4. Titles are readable and don't collide with UI.
|
|
195
|
+
5. The move has a clear start and end (compare entrance vs exit).
|
|
196
|
+
Then `agentcut_contact_sheet` over the whole video (pacing, variety: no two consecutive shots with the
|
|
197
|
+
same angle and move) and `agentcut_preview_check` (each Plane with lens blur draws several copies; if a
|
|
198
|
+
shot is choppy, lower `aperture` on secondary planes or set `dof={false}` on them, never on the hero in
|
|
199
|
+
the export path). Fix what fails and re-capture. Write what you checked in notes.md.
|
|
200
|
+
|
|
201
|
+
## Takes
|
|
202
|
+
|
|
203
|
+
"Another take" asks for a new film from the same media with a new direction. Before changing anything,
|
|
204
|
+
copy project.json, layers.json and scenes/ to a new timestamped folder under `.studio/cinematic-takes/`
|
|
205
|
+
(never overwrite one). Then replace the Cinematic track and its scenes: new shot list, new moves, new
|
|
206
|
+
backdrop and type. Reusing the previous take's structure with new colors is a failure.
|
|
@@ -1,79 +1,79 @@
|
|
|
1
|
-
# Colour grading
|
|
2
|
-
|
|
3
|
-
Grade in this order, measuring before and after. Never say a grade looks right without
|
|
4
|
-
`agentcut_color_check` numbers or a capture behind it.
|
|
5
|
-
|
|
6
|
-
1. **Measure.** `agentcut_color_check` with `stage: "source"`. Issues are conventions, not rules: a night
|
|
7
|
-
scene is meant to be dark. `differenceFromReference.noticeable` shows the shots a cut would jump on.
|
|
8
|
-
2. **Balance.** `agentcut_match_shots` when shots differ. It writes `grade.match`, under everything else, and
|
|
9
|
-
reports before and after. Pick the shot that looks best as `anchorClipId`. It doesn't copy looks or settings
|
|
10
|
-
unless you pass `copyGrade: true`, which replaces each clip's own grade with the anchor's.
|
|
11
|
-
3. **Correct.** Fix what's left per clip: exposure, white balance, then contrast. Small moves.
|
|
12
|
-
4. **Look.** Set one look over the whole video: `project.json` `grade`, or `agentcut_match_look` to match a
|
|
13
|
-
reference. `agentcut_color_looks` lists the built-in ones.
|
|
14
|
-
5. **Finish.** Grain, halation and vignette last, and lightly.
|
|
15
|
-
6. **Check again.** `agentcut_color_check` (`stage: "graded"`) and `agentcut_capture_frames` across a cut. Text
|
|
16
|
-
and logos on other tracks aren't graded, so check that they still sit well on the new picture.
|
|
17
|
-
|
|
18
|
-
## Where a grade goes
|
|
19
|
-
|
|
20
|
-
| Where | What it grades |
|
|
21
|
-
| --- | --- |
|
|
22
|
-
| `grade` on a video clip | That clip. After a cut each piece keeps a copy. |
|
|
23
|
-
| `grade` on an image clip | That image. |
|
|
24
|
-
| An `adjustment` track's clip | All footage below it while it runs. `enter` and `exit` frames fade it in and out, `opacity` scales it. |
|
|
25
|
-
| `grade` in `project.json` | All footage, last. The place for the film's overall look. |
|
|
26
|
-
|
|
27
|
-
Clips draw their own grade, then adjustment layers (lowest first), then the project grade. Set
|
|
28
|
-
`inheritGrade: false` on a video clip (a screen recording, say) to keep the last two off it. Images are the
|
|
29
|
-
other way round: they only inherit with `inheritGrade: true`, so logos keep their colours. Graphics, scenes,
|
|
30
|
-
text and captions are never graded.
|
|
31
|
-
|
|
32
|
-
```json
|
|
33
|
-
{ "id": "grade", "name": "Flashback", "kind": "adjustment", "clips": [
|
|
34
|
-
{ "id": "flashback", "from": 120, "duration": 90, "enter": { "preset": "fade", "frames": 12 }, "exit": { "preset": "fade", "frames": 12 },
|
|
35
|
-
"grade": { "look": "faded-print" } }
|
|
36
|
-
] }
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
## Fields
|
|
40
|
-
|
|
41
|
-
All optional. Multipliers are neutral at 1, amounts are neutral at 0 and run −1 to 1 unless noted.
|
|
42
|
-
|
|
43
|
-
- **Light:** `exposure` (stops, −5…5), `temperature`, `tint`, `contrast` (1), `pivot` (0…1), `brightness` (1)
|
|
44
|
-
- **Tone:** `highlights`, `shadows`, `whites`, `blacks`, `blackPoint`, `whitePoint` (0…1), `gamma` (1)
|
|
45
|
-
- **Colour:** `saturation` (1), `vibrance`, `hue` (degrees), `warmth`, `skinProtect` (0…1, keeps skin's own colour)
|
|
46
|
-
- **Wheels:** `wheels: { shadows, midtones, highlights }`, each `{ x, y, level }`. `x`/`y` push towards a hue
|
|
47
|
-
(x+ red, x− cyan, y+ green-yellow, y− blue-magenta). Teal shadows: `{ "x": -0.3, "y": -0.1 }`.
|
|
48
|
-
- **Curves:** `curves: { master, r, g, b }`, each a list of `[input, output]` pairs from 0 to 1.
|
|
49
|
-
A gentle S: `[[0,0],[0.25,0.22],[0.75,0.78],[1,1]]`.
|
|
50
|
-
- **Colour mixer:** `hsl: { red, orange, yellow, green, aqua, blue, purple, magenta }`, each
|
|
51
|
-
`{ hue, saturation, luminance }`. Skin lives in orange; leave it alone unless that's the point.
|
|
52
|
-
- **Looks:** `look` (built-in id), `lookStrength` (0…1), `lut` (a `.cube` under `assets/`), `lutStrength` (0…1)
|
|
53
|
-
- **Finish:** `grain` (0…1), `grainSize` (0.5…4), `halation` (0…1), `bloom` (0…1), `vignette` (+ darkens corners)
|
|
54
|
-
- **Over time:** `keys`, grades at clip-local frames: `[{ "frame": 0, "saturation": 0, "hold": true }, { "frame": 24, "saturation": 1 }]`.
|
|
55
|
-
A key only overrides the fields it names. Keys ease to the next one; `hold` jumps instead. Cuts on a beat with
|
|
56
|
-
`hold`: frames from `agentcut_analyze_audio`, relative to the clip's start.
|
|
57
|
-
|
|
58
|
-
`.cube` files must be 3D, up to size 65. Log footage needs its conversion LUT (usually from the camera maker)
|
|
59
|
-
before any look, so use `lut` for that and a built-in `look` over it.
|
|
60
|
-
|
|
61
|
-
## Sizes of move that work
|
|
62
|
-
|
|
63
|
-
| Goal | Fields |
|
|
64
|
-
| --- | --- |
|
|
65
|
-
| A bit more punch | `contrast` 1.05–1.15, `vibrance` 0.1–0.2 |
|
|
66
|
-
| Warmer skin | `temperature` 0.05–0.15 |
|
|
67
|
-
| Muted, editorial | `saturation` 0.8–0.9, a soft S curve |
|
|
68
|
-
| Filmic finish | `grain` 0.1–0.2, `halation` 0.1–0.25 |
|
|
69
|
-
| Teal and orange without orange people | `look: "teal-amber"`, or wheels with `skinProtect` 0.6 |
|
|
70
|
-
|
|
71
|
-
Keep `exposure` corrections under about one stop: past that, compression noise shows. A grade can't bring back
|
|
72
|
-
clipped highlights or add focus.
|
|
73
|
-
|
|
74
|
-
## Person and background
|
|
75
|
-
|
|
76
|
-
`agentcut_grade_subject` cuts the person out and grades them apart from the background, on request (it takes a
|
|
77
|
-
while: it runs the same model as `agentcut_cutout_person`). Presets: `pop`, `mono-background`, `soft-background`,
|
|
78
|
-
`night-background`. Check edges with captures, especially hair against a darker background. After changing the
|
|
79
|
-
footage's framing or trim, run it again.
|
|
1
|
+
# Colour grading
|
|
2
|
+
|
|
3
|
+
Grade in this order, measuring before and after. Never say a grade looks right without
|
|
4
|
+
`agentcut_color_check` numbers or a capture behind it.
|
|
5
|
+
|
|
6
|
+
1. **Measure.** `agentcut_color_check` with `stage: "source"`. Issues are conventions, not rules: a night
|
|
7
|
+
scene is meant to be dark. `differenceFromReference.noticeable` shows the shots a cut would jump on.
|
|
8
|
+
2. **Balance.** `agentcut_match_shots` when shots differ. It writes `grade.match`, under everything else, and
|
|
9
|
+
reports before and after. Pick the shot that looks best as `anchorClipId`. It doesn't copy looks or settings
|
|
10
|
+
unless you pass `copyGrade: true`, which replaces each clip's own grade with the anchor's.
|
|
11
|
+
3. **Correct.** Fix what's left per clip: exposure, white balance, then contrast. Small moves.
|
|
12
|
+
4. **Look.** Set one look over the whole video: `project.json` `grade`, or `agentcut_match_look` to match a
|
|
13
|
+
reference. `agentcut_color_looks` lists the built-in ones.
|
|
14
|
+
5. **Finish.** Grain, halation and vignette last, and lightly.
|
|
15
|
+
6. **Check again.** `agentcut_color_check` (`stage: "graded"`) and `agentcut_capture_frames` across a cut. Text
|
|
16
|
+
and logos on other tracks aren't graded, so check that they still sit well on the new picture.
|
|
17
|
+
|
|
18
|
+
## Where a grade goes
|
|
19
|
+
|
|
20
|
+
| Where | What it grades |
|
|
21
|
+
| --- | --- |
|
|
22
|
+
| `grade` on a video clip | That clip. After a cut each piece keeps a copy. |
|
|
23
|
+
| `grade` on an image clip | That image. |
|
|
24
|
+
| An `adjustment` track's clip | All footage below it while it runs. `enter` and `exit` frames fade it in and out, `opacity` scales it. |
|
|
25
|
+
| `grade` in `project.json` | All footage, last. The place for the film's overall look. |
|
|
26
|
+
|
|
27
|
+
Clips draw their own grade, then adjustment layers (lowest first), then the project grade. Set
|
|
28
|
+
`inheritGrade: false` on a video clip (a screen recording, say) to keep the last two off it. Images are the
|
|
29
|
+
other way round: they only inherit with `inheritGrade: true`, so logos keep their colours. Graphics, scenes,
|
|
30
|
+
text and captions are never graded.
|
|
31
|
+
|
|
32
|
+
```json
|
|
33
|
+
{ "id": "grade", "name": "Flashback", "kind": "adjustment", "clips": [
|
|
34
|
+
{ "id": "flashback", "from": 120, "duration": 90, "enter": { "preset": "fade", "frames": 12 }, "exit": { "preset": "fade", "frames": 12 },
|
|
35
|
+
"grade": { "look": "faded-print" } }
|
|
36
|
+
] }
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Fields
|
|
40
|
+
|
|
41
|
+
All optional. Multipliers are neutral at 1, amounts are neutral at 0 and run −1 to 1 unless noted.
|
|
42
|
+
|
|
43
|
+
- **Light:** `exposure` (stops, −5…5), `temperature`, `tint`, `contrast` (1), `pivot` (0…1), `brightness` (1)
|
|
44
|
+
- **Tone:** `highlights`, `shadows`, `whites`, `blacks`, `blackPoint`, `whitePoint` (0…1), `gamma` (1)
|
|
45
|
+
- **Colour:** `saturation` (1), `vibrance`, `hue` (degrees), `warmth`, `skinProtect` (0…1, keeps skin's own colour)
|
|
46
|
+
- **Wheels:** `wheels: { shadows, midtones, highlights }`, each `{ x, y, level }`. `x`/`y` push towards a hue
|
|
47
|
+
(x+ red, x− cyan, y+ green-yellow, y− blue-magenta). Teal shadows: `{ "x": -0.3, "y": -0.1 }`.
|
|
48
|
+
- **Curves:** `curves: { master, r, g, b }`, each a list of `[input, output]` pairs from 0 to 1.
|
|
49
|
+
A gentle S: `[[0,0],[0.25,0.22],[0.75,0.78],[1,1]]`.
|
|
50
|
+
- **Colour mixer:** `hsl: { red, orange, yellow, green, aqua, blue, purple, magenta }`, each
|
|
51
|
+
`{ hue, saturation, luminance }`. Skin lives in orange; leave it alone unless that's the point.
|
|
52
|
+
- **Looks:** `look` (built-in id), `lookStrength` (0…1), `lut` (a `.cube` under `assets/`), `lutStrength` (0…1)
|
|
53
|
+
- **Finish:** `grain` (0…1), `grainSize` (0.5…4), `halation` (0…1), `bloom` (0…1), `vignette` (+ darkens corners)
|
|
54
|
+
- **Over time:** `keys`, grades at clip-local frames: `[{ "frame": 0, "saturation": 0, "hold": true }, { "frame": 24, "saturation": 1 }]`.
|
|
55
|
+
A key only overrides the fields it names. Keys ease to the next one; `hold` jumps instead. Cuts on a beat with
|
|
56
|
+
`hold`: frames from `agentcut_analyze_audio`, relative to the clip's start.
|
|
57
|
+
|
|
58
|
+
`.cube` files must be 3D, up to size 65. Log footage needs its conversion LUT (usually from the camera maker)
|
|
59
|
+
before any look, so use `lut` for that and a built-in `look` over it.
|
|
60
|
+
|
|
61
|
+
## Sizes of move that work
|
|
62
|
+
|
|
63
|
+
| Goal | Fields |
|
|
64
|
+
| --- | --- |
|
|
65
|
+
| A bit more punch | `contrast` 1.05–1.15, `vibrance` 0.1–0.2 |
|
|
66
|
+
| Warmer skin | `temperature` 0.05–0.15 |
|
|
67
|
+
| Muted, editorial | `saturation` 0.8–0.9, a soft S curve |
|
|
68
|
+
| Filmic finish | `grain` 0.1–0.2, `halation` 0.1–0.25 |
|
|
69
|
+
| Teal and orange without orange people | `look: "teal-amber"`, or wheels with `skinProtect` 0.6 |
|
|
70
|
+
|
|
71
|
+
Keep `exposure` corrections under about one stop: past that, compression noise shows. A grade can't bring back
|
|
72
|
+
clipped highlights or add focus.
|
|
73
|
+
|
|
74
|
+
## Person and background
|
|
75
|
+
|
|
76
|
+
`agentcut_grade_subject` cuts the person out and grades them apart from the background, on request (it takes a
|
|
77
|
+
while: it runs the same model as `agentcut_cutout_person`). Presets: `pop`, `mono-background`, `soft-background`,
|
|
78
|
+
`night-background`. Check edges with captures, especially hair against a darker background. After changing the
|
|
79
|
+
footage's framing or trim, run it again.
|