agentcut 0.2.26 → 0.2.28

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.
Files changed (97) hide show
  1. package/README.md +177 -177
  2. package/dist/studio/agents/claude.js +3 -2
  3. package/dist/studio/agents/claude.js.map +1 -1
  4. package/dist/studio/chat.js +1 -1
  5. package/dist/studio/chat.js.map +1 -1
  6. package/dist/studio/cli.js +24 -24
  7. package/dist/studio/download.d.ts +24 -0
  8. package/dist/studio/download.js +234 -0
  9. package/dist/studio/download.js.map +1 -0
  10. package/dist/studio/host.js +8 -0
  11. package/dist/studio/host.js.map +1 -1
  12. package/dist/studio/housekeeping.d.ts +2 -2
  13. package/dist/studio/housekeeping.js +18 -17
  14. package/dist/studio/housekeeping.js.map +1 -1
  15. package/dist/studio/release-cursor.js +21 -21
  16. package/dist/studio/release-video.js +10 -10
  17. package/dist/studio/schema.d.ts +102 -0
  18. package/dist/studio/schema.js +5 -0
  19. package/dist/studio/schema.js.map +1 -1
  20. package/dist/studio/tools.js +7 -0
  21. package/dist/studio/tools.js.map +1 -1
  22. package/package.json +56 -56
  23. package/template/AGENTS.md +14 -14
  24. package/template/components/README.md +70 -70
  25. package/template/components/before-after/BeforeAfter.tsx +89 -89
  26. package/template/components/catalog.ts +107 -107
  27. package/template/components/cinematic/Device3D.tsx +324 -324
  28. package/template/components/cinematic/devices3d/display-model.ts +184 -184
  29. package/template/components/cinematic/devices3d/iphone-model.ts +643 -643
  30. package/template/components/cinematic/devices3d/macbook-model.ts +608 -608
  31. package/template/components/cinematic/devices3d/models.ts +657 -657
  32. package/template/components/cinematic/devices3d/runtime.ts +267 -267
  33. package/template/components/cinematic/math.ts +100 -100
  34. package/template/components/color/grade-effect.ts +650 -650
  35. package/template/components/color/grade.ts +512 -512
  36. package/template/components/color/looks.ts +154 -154
  37. package/template/components/countdown/Countdown.tsx +166 -166
  38. package/template/components/dot-trace-title/DotTraceTitle.tsx +181 -181
  39. package/template/components/dot-trace-title/meta.json +51 -51
  40. package/template/components/generate/GenerateReveal.tsx +381 -381
  41. package/template/components/hook-card/HookCard.tsx +554 -554
  42. package/template/components/index.ts +199 -199
  43. package/template/components/lib.ts +191 -191
  44. package/template/components/line-diagram/LineDiagram.tsx +205 -205
  45. package/template/components/line-diagram/meta.json +215 -215
  46. package/template/components/list-card/ListCard.tsx +104 -104
  47. package/template/components/live-clip.ts +75 -75
  48. package/template/components/looks.tsx +1447 -1447
  49. package/template/components/loops/LoopCanvas.tsx +132 -132
  50. package/template/components/loops/engine.ts +184 -184
  51. package/template/components/loops/library.ts +667 -667
  52. package/template/components/loops/library2.ts +777 -777
  53. package/template/components/motion-loop/MotionLoop.tsx +37 -37
  54. package/template/components/motion-loop/meta.json +311 -311
  55. package/template/components/props.ts +73 -73
  56. package/template/components/quote-card/QuoteCard.tsx +71 -71
  57. package/template/components/style-layer.tsx +233 -233
  58. package/template/components/styles.ts +113 -113
  59. package/template/components/types.ts +66 -66
  60. package/template/components/word-pop/WordPop.tsx +59 -59
  61. package/template/components/word-stack/WordStack.tsx +122 -122
  62. package/template/presets/charcoal-sketch/PROMPT.md +48 -48
  63. package/template/presets/charcoal-sketch/scripts/duck_music.py +34 -34
  64. package/template/presets/punk-cut-paper/scenes/Motif.tsx +376 -376
  65. package/template/presets/punk-cut-paper/scenes/Photo.tsx +73 -73
  66. package/template/presets/punk-cut-paper/scenes/Ransom.tsx +119 -119
  67. package/template/runtime/composition.tsx +1207 -1189
  68. package/template/runtime/helpers.tsx +230 -230
  69. package/template/runtime/index.tsx +26 -22
  70. package/template/runtime/types.ts +324 -315
  71. package/template/skill/SKILL.md +188 -187
  72. package/template/skill/references/broll.md +44 -44
  73. package/template/skill/references/browser-export.md +61 -61
  74. package/template/skill/references/cinematic.md +206 -206
  75. package/template/skill/references/color.md +79 -79
  76. package/template/skill/references/craft.md +97 -97
  77. package/template/skill/references/editing-styles.md +57 -57
  78. package/template/skill/references/feature-launch.md +34 -34
  79. package/template/skill/references/footage.md +72 -72
  80. package/template/skill/references/format.md +145 -142
  81. package/template/skill/references/how-to.md +146 -146
  82. package/template/skill/references/launch-direction.md +89 -89
  83. package/template/skill/references/loops.md +151 -151
  84. package/template/skill/references/mcp-external.md +19 -19
  85. package/template/skill/references/performance.md +93 -93
  86. package/template/skill/references/person-cutout.md +19 -19
  87. package/template/skill/references/presets.md +60 -60
  88. package/template/skill/references/product-launch.md +134 -134
  89. package/template/skill/references/release-capture.md +53 -53
  90. package/template/skill/references/sound.md +167 -166
  91. package/template/skill/references/style-spy.md +160 -160
  92. package/template/skill/references/website-howto.md +45 -45
  93. package/template/starter/.studio/chat.json +1 -1
  94. package/template/starter/layers.json +46 -46
  95. package/template/starter/notes.md +4 -4
  96. package/template/starter/project.json +13 -13
  97. package/template/starter/scenes/Title.tsx +38 -38
@@ -1,72 +1,72 @@
1
- # Footage sent from the editor
2
-
3
- "Send to Agentcut" in the ScreenSlick editor renders the user's edit and opens it here as a new
4
- project sized to the video:
5
-
6
- - **Footage** track: one video clip `footage` with `src: "assets/footage.<ext>"`, `fit: "contain"`,
7
- covering the whole project. Its audio is the user's voice and the editor mix.
8
- - **Captions** track (when the edit had subtitles): one captions clip with the editor's words, timed in
9
- frames. Restyle it with `style`; don't retype the words.
10
- - `notes.md` says what came over.
11
-
12
- The user finishes the video here: cuts, color, motion graphics, sound, then exports from the studio.
13
-
14
- ## Remove silences / tighten pacing
15
-
16
- 1. `agentcut_transcribe` on `assets/footage.<ext>` for word timings (or
17
- `agentcut_analyze_audio` for per-frame energy when there is no speech).
18
- 2. Find gaps longer than ~0.6 s between words (keep ~0.15 s of air before and after each word; never cut
19
- inside a word). Keep breaths that land on a beat or a reveal.
20
- 3. Replace the single footage clip with one clip per kept range, back to back on the Footage track:
21
- each clip has `src` of the footage, `trimStart` = range start (frames in the file), `from` = where it
22
- lands on the timeline, `duration` = range length. Give them ids `footage-1`, `footage-2`, …
23
- 4. Move every caption word with its range (subtract the time removed before it), drop words in removed
24
- ranges, and set the project `durationInFrames` to the new end.
25
- 5. Tell the user how much you cut ("removed 14 pauses, 0:52 → 0:41"), then check the cut points with
26
- `agentcut_capture_frames` and `agentcut_listen_critique`.
27
-
28
- Cuts "by transcript" ("remove the part where I say …") work the same way: find the words, cut their range.
29
-
30
- ## Color
31
-
32
- Read `references/color.md`. Measure with `agentcut_color_check`, even out shots with `agentcut_match_shots`,
33
- then put one look over the whole video (`grade` in `project.json`). Check before and after.
34
-
35
- ## Motion graphics over footage
36
-
37
- Add tracks above Footage (text, scenes, images) and keep the footage readable: lower thirds and callouts
38
- at the edges, punch-in zooms by splitting the footage and giving that piece a bigger `box`, never covering
39
- the speaker's face for long.
40
-
41
- ## Raw takes
42
-
43
- "Send to Agentcut → Raw takes" sends the untouched recordings instead of a render. The project is
44
- sized to the screen recording:
45
-
46
- - **Screen** track: one clip per take (`screen`, or `screen-1`, `screen-2`, … back to back), `src:
47
- "assets/screen.<ext>"`, `fit: "contain"`. Its audio is the user's voice: the only audio in the project.
48
- - **Camera** track (when they recorded one): clip `camera`, `src: "assets/camera.<ext>"`, `fit: "cover"`,
49
- a `box` where the editor showed it and a `radius` for its rounded corners. It is `muted` (the voice is on
50
- the screen file) and already synced: its `from`/`trimStart` line it up with the screen. Keep it muted.
51
- - **Captions** track (when the editor had subtitles): words timed to the raw recording.
52
- - **Cursor** (Companion recordings): `assets/screen.cursor.json` with the mouse path, clicks and scrolls,
53
- and a `cursor` field on the screen clip that draws the pointer. Copy that field to every piece you cut.
54
- See `references/cursor.md`; it also finds zoom, cut and speed-up candidates for step 1.
55
- - `notes.md` lists the files and whether the user had the camera mirrored.
56
-
57
- Nothing is cut yet, so a raw take is usually long. Ask what the video is for when it isn't clear, then:
58
-
59
- 1. **Cut both tracks together.** Work out the kept ranges on the screen take (silences, retakes, "by
60
- transcript" cuts, as above). For every range, add a screen piece *and* a camera piece with the same
61
- `from` and `duration`. With the range start `R` in frames on the *original* timeline, the screen
62
- piece's `trimStart` is `R` − its take's original `from`, and the camera piece's `trimStart` is
63
- `R` − camera's original `from` + camera's original `trimStart` (skip camera pieces where that is
64
- negative: the camera wasn't rolling yet). Ids: `screen-1…`, `camera-1…`. Move the captions with the cuts.
65
- Spot-check sync after cutting with `agentcut_capture_frames` (lips vs. the voice).
66
- 2. **Frame the screen.** A `box` is fixed for the whole clip, so a zoom is a cut: split the screen piece
67
- where the action starts and give that piece a bigger box (width/height 1.5–2, x/y negative to keep the
68
- area of interest in frame), then cut back. Hold each zoom long enough to read.
69
- 3. **Place the camera.** Bubble in a corner (keep `radius` at half the short side for a circle), full frame
70
- for an intro or outro (camera `box` to the whole frame; the Camera track sits above Screen), or
71
- side by side (shrink the screen `box`, give the camera the rest). Change layouts at cuts, not mid-sentence.
72
- 4. Then grade, captions, music and motion graphics as for any footage.
1
+ # Footage sent from the editor
2
+
3
+ "Send to Agentcut" in the ScreenSlick editor renders the user's edit and opens it here as a new
4
+ project sized to the video:
5
+
6
+ - **Footage** track: one video clip `footage` with `src: "assets/footage.<ext>"`, `fit: "contain"`,
7
+ covering the whole project. Its audio is the user's voice and the editor mix.
8
+ - **Captions** track (when the edit had subtitles): one captions clip with the editor's words, timed in
9
+ frames. Restyle it with `style`; don't retype the words.
10
+ - `notes.md` says what came over.
11
+
12
+ The user finishes the video here: cuts, color, motion graphics, sound, then exports from the studio.
13
+
14
+ ## Remove silences / tighten pacing
15
+
16
+ 1. `agentcut_transcribe` on `assets/footage.<ext>` for word timings (or
17
+ `agentcut_analyze_audio` for per-frame energy when there is no speech).
18
+ 2. Find gaps longer than ~0.6 s between words (keep ~0.15 s of air before and after each word; never cut
19
+ inside a word). Keep breaths that land on a beat or a reveal.
20
+ 3. Replace the single footage clip with one clip per kept range, back to back on the Footage track:
21
+ each clip has `src` of the footage, `trimStart` = range start (frames in the file), `from` = where it
22
+ lands on the timeline, `duration` = range length. Give them ids `footage-1`, `footage-2`, …
23
+ 4. Move every caption word with its range (subtract the time removed before it), drop words in removed
24
+ ranges, and set the project `durationInFrames` to the new end.
25
+ 5. Tell the user how much you cut ("removed 14 pauses, 0:52 → 0:41"), then check the cut points with
26
+ `agentcut_capture_frames` and `agentcut_listen_critique`.
27
+
28
+ Cuts "by transcript" ("remove the part where I say …") work the same way: find the words, cut their range.
29
+
30
+ ## Color
31
+
32
+ Read `references/color.md`. Measure with `agentcut_color_check`, even out shots with `agentcut_match_shots`,
33
+ then put one look over the whole video (`grade` in `project.json`). Check before and after.
34
+
35
+ ## Motion graphics over footage
36
+
37
+ Add tracks above Footage (text, scenes, images) and keep the footage readable: lower thirds and callouts
38
+ at the edges, punch-in zooms by splitting the footage and giving that piece a bigger `box`, never covering
39
+ the speaker's face for long.
40
+
41
+ ## Raw takes
42
+
43
+ "Send to Agentcut → Raw takes" sends the untouched recordings instead of a render. The project is
44
+ sized to the screen recording:
45
+
46
+ - **Screen** track: one clip per take (`screen`, or `screen-1`, `screen-2`, … back to back), `src:
47
+ "assets/screen.<ext>"`, `fit: "contain"`. Its audio is the user's voice: the only audio in the project.
48
+ - **Camera** track (when they recorded one): clip `camera`, `src: "assets/camera.<ext>"`, `fit: "cover"`,
49
+ a `box` where the editor showed it and a `radius` for its rounded corners. It is `muted` (the voice is on
50
+ the screen file) and already synced: its `from`/`trimStart` line it up with the screen. Keep it muted.
51
+ - **Captions** track (when the editor had subtitles): words timed to the raw recording.
52
+ - **Cursor** (Companion recordings): `assets/screen.cursor.json` with the mouse path, clicks and scrolls,
53
+ and a `cursor` field on the screen clip that draws the pointer. Copy that field to every piece you cut.
54
+ See `references/cursor.md`; it also finds zoom, cut and speed-up candidates for step 1.
55
+ - `notes.md` lists the files and whether the user had the camera mirrored.
56
+
57
+ Nothing is cut yet, so a raw take is usually long. Ask what the video is for when it isn't clear, then:
58
+
59
+ 1. **Cut both tracks together.** Work out the kept ranges on the screen take (silences, retakes, "by
60
+ transcript" cuts, as above). For every range, add a screen piece *and* a camera piece with the same
61
+ `from` and `duration`. With the range start `R` in frames on the *original* timeline, the screen
62
+ piece's `trimStart` is `R` − its take's original `from`, and the camera piece's `trimStart` is
63
+ `R` − camera's original `from` + camera's original `trimStart` (skip camera pieces where that is
64
+ negative: the camera wasn't rolling yet). Ids: `screen-1…`, `camera-1…`. Move the captions with the cuts.
65
+ Spot-check sync after cutting with `agentcut_capture_frames` (lips vs. the voice).
66
+ 2. **Frame the screen.** A `box` is fixed for the whole clip, so a zoom is a cut: split the screen piece
67
+ where the action starts and give that piece a bigger box (width/height 1.5–2, x/y negative to keep the
68
+ area of interest in frame), then cut back. Hold each zoom long enough to read.
69
+ 3. **Place the camera.** Bubble in a corner (keep `radius` at half the short side for a circle), full frame
70
+ for an intro or outro (camera `box` to the whole frame; the Camera track sits above Screen), or
71
+ side by side (shrink the screen `box`, give the camera the rest). Change layouts at cuts, not mid-sentence.
72
+ 4. Then grade, captions, music and motion graphics as for any footage.
@@ -1,142 +1,145 @@
1
- # Project format (v1)
2
-
3
- All times are **integer frames** at `project.fps`. Clip `from` is the timeline frame where the clip
4
- starts; `duration` is its length in frames. Inside a clip (scene code, caption words, fades) frames are
5
- **relative to the clip start**.
6
-
7
- ## project.json
8
-
9
- ```json
10
- {
11
- "version": 1,
12
- "name": "Rolino launch",
13
- "fps": 30,
14
- "durationInFrames": 1800,
15
- "background": "#060a16",
16
- "variants": {
17
- "wide": { "width": 1920, "height": 1080 },
18
- "mobile": { "width": 1080, "height": 1920 }
19
- },
20
- "defaultVariant": "wide",
21
- "fonts": [
22
- "Inter:400;600;800",
23
- { "family": "Brand Onest", "src": "assets/fonts/onest-700.woff2", "weight": "700" }
24
- ]
25
- }
26
- ```
27
-
28
- - `durationInFrames` is the export length; keep it equal to the end of the last clip.
29
- - Fonts: Google Fonts specs (`"Family:400;700"`) or local files (preferred for brand fonts: renders
30
- then never depend on Google Fonts). Reference them by `family` in styles.
31
-
32
- ## layers.json
33
-
34
- ```json
35
- {
36
- "version": 1,
37
- "tracks": [
38
- { "id": "captions", "name": "Captions", "kind": "captions", "clips": [] },
39
- { "id": "text", "name": "Titles", "kind": "text", "clips": [] },
40
- { "id": "grain", "name": "Film grain", "kind": "scene", "clips": [] },
41
- { "id": "scenes", "name": "Scenes", "kind": "scene", "clips": [] },
42
- { "id": "voice", "name": "Voice", "kind": "audio", "clips": [] },
43
- { "id": "music", "name": "Music", "kind": "audio", "clips": [] },
44
- { "id": "sfx", "name": "SFX", "kind": "audio", "clips": [] }
45
- ],
46
- "markers": [
47
- { "id": "m-drop", "frame": 204, "label": "Drop", "kind": "beat" },
48
- { "id": "m-reveal", "frame": 198, "label": "Reveal", "kind": "section" }
49
- ]
50
- }
51
- ```
52
-
53
- `tracks[0]` is drawn **on top**; later tracks are drawn underneath. Clips on a track are sorted by
54
- `from`. Clips may overlap only on `scene` and `audio` tracks (use more tracks otherwise).
55
-
56
- Track fields: `id` (kebab-case, unique), `name`, `kind`, `clips`, optional `hidden` (visual), `muted`
57
- (audio/video), `locked` (user lock — don't move locked clips), `volume` (audio track gain).
58
-
59
- Markers (`section` = scene starts, `cue` = moments sounds/animations hit, `beat` = music beats you rely
60
- on) show on the timeline ruler. Keep section markers in sync with scene clips.
61
-
62
- ### Clip fields (all kinds)
63
-
64
- | field | |
65
- |---|---|
66
- | `id` | unique in the project, stable, readable |
67
- | `name` | timeline label (optional) |
68
- | `from`, `duration` | frames |
69
- | `enter`, `exit` | `{ "preset": "fade" \| "slide-up" \| "slide-down" \| "slide-left" \| "slide-right" \| "pop" \| "scale" \| "blur" \| "none", "frames": 12 }` (visual clips) |
70
- | `opacity` | 0..1 (visual clips) |
71
- | `note` | why the clip is there (cue reason) |
72
- | `variants` | per-variant overrides, e.g. `{ "mobile": { "box": {…}, "style": {…} } }` |
73
-
74
- `box` = `{ "x", "y", "width", "height" }` as fractions of the frame (0..1), top-left origin.
75
-
76
- ### Kinds
77
-
78
- **scene** — `{ "scene": "Hook", "props": { … } }` renders `scenes/Hook.tsx`; or
79
- `{ "component": "text-reveal", "props": { … } }` renders a library component (one of the two per clip;
80
- see `references/components.md`).
81
-
82
- **audio** — `{ "src": "assets/voice.wav", "volume": 1, "trimStart": 0, "fadeIn": 0, "fadeOut": 0, "loop": false, "playbackRate": 1, "role": "voice" | "music" | "sfx" | "ambience" }`.
83
- `trimStart` skips frames of the file. Set `duration` from `agentcut_media_info` (frames). An SFX
84
- clip's `from` is the cue frame minus the file's onset (see sound.md).
85
-
86
- **video** — `{ "src", "trimStart", "volume", "muted", "fit": "cover" | "contain", "box", "playbackRate", "grade" }`.
87
- `grade` — colour: `{ "exposure": 0.2, "contrast": 1.1, "temperature": 0.1, "look": "golden-stock" }` and more (fields and workflow:
88
- `references/color.md`). Leave out what you don't change. `inheritGrade: false` keeps the project grade and adjustment layers off it.
89
- Footage from the editor: see `references/footage.md`.
90
-
91
- **image** — `{ "src", "fit", "box", "radius", "grade", "inheritGrade" }`. `inheritGrade: true` also applies the project grade and adjustment layers.
92
-
93
- **adjustment** — `{ "grade" }`. Draws nothing: it grades the footage below it while it runs (`references/color.md`).
94
-
95
- **text** — `{ "text", "box", "style": { "fontFamily", "fontSize" (px at the variant size), "fontWeight", "color", "align", "lineHeight", "letterSpacing", "textTransform", "shadow" } }`. For styled kinetic type use a scene instead.
96
-
97
- **captions** — `{ "words": [{ "text", "from", "to" }], "style": { "preset": "pop" | "karaoke" | "plain", "fontFamily", "fontSize", "fontWeight", "color", "highlight", "position": "bottom" | "center" | "top", "maxWordsPerLine" } }`.
98
- Word `from`/`to` are frames **relative to the clip start**. Build them from `agentcut_transcribe`
99
- (`fromFrame - clip.from`). For custom caption looks, write a scene that takes `words` in props.
100
-
101
- `src` forms: `assets/<file>`, `library:<path>` (workspace library shared by projects), `https://…` (must
102
- allow CORS).
103
-
104
- ## Scenes
105
-
106
- ```tsx
107
- // scenes/Hook.tsx
108
- import { AbsoluteFill, useCurrentFrame } from "remotion";
109
- import { RadialGlow, SPRING, ease, sp, mix, useStudio, type SceneProps } from "agentcut";
110
-
111
- type Props = SceneProps & { title: string; accent: string };
112
-
113
- export default function Hook({ title, accent, width, height, clip }: Props) {
114
- const f = useCurrentFrame(); // 0 at the clip start
115
- const vertical = height > width;
116
- const s = sp(f, 6, SPRING.pop); // spring starting at local frame 6
117
- const out = ease(f, clip.duration - 8, clip.duration);
118
- return (
119
- <AbsoluteFill style={{ background: "linear-gradient(160deg,#0b0b14,#050507)", opacity: 1 - out }}>
120
- <RadialGlow x={0.5} y={0.45} radius={0.5} color={accent} opacity={0.25} />
121
- <AbsoluteFill style={{ alignItems: "center", justifyContent: "center" }}>
122
- <div style={{ fontFamily: "Inter", fontWeight: 900, fontSize: vertical ? 140 : 120,
123
- transform: `translateY(${mix(60, 0, s)}px)`, color: "#fff" }}>{title}</div>
124
- </AbsoluteFill>
125
- </AbsoluteFill>
126
- );
127
- }
128
- ```
129
-
130
- Scene props: everything in the clip's `props`, plus `clip` (`id`, `from`, `duration`), `variant`,
131
- `width`, `height`, `fps`.
132
-
133
- `agentcut` exports: `useStudio()` (project, variant, width, height, fps), `useIsVertical()`, `usePreviewQuality()`
134
- (cheaper drawing in the live preview, full quality in captures/export),
135
- `asset(path)` (URL for `assets/…` / `library:…`), `clamp`, `mix`, `ease(f, from, to, easing?)`,
136
- `sp(f, start, config?, duration?)`, `SPRING` (smooth, snappy, bouncy, pop, land), `sec(seconds)`,
137
- `<RadialGlow>`, `<FrameBox>`, and the format types.
138
-
139
- Shared helpers for several scenes go in `scenes/lib/*.ts(x)` (files in subfolders aren't scenes).
140
- Available packages: `react`, `remotion`, `@remotion/media`, `@remotion/transitions` (+ presentations),
141
- `@remotion/shapes`, `@remotion/paths`, `@remotion/noise`. Anything else: `npm install` it in the
142
- workspace root and it gets bundled.
1
+ # Project format (v1)
2
+
3
+ All times are **integer frames** at `project.fps`. Clip `from` is the timeline frame where the clip
4
+ starts; `duration` is its length in frames. Inside a clip (scene code, caption words, fades) frames are
5
+ **relative to the clip start**.
6
+
7
+ ## project.json
8
+
9
+ ```json
10
+ {
11
+ "version": 1,
12
+ "name": "Rolino launch",
13
+ "fps": 30,
14
+ "durationInFrames": 1800,
15
+ "background": "#060a16",
16
+ "variants": {
17
+ "wide": { "width": 1920, "height": 1080 },
18
+ "mobile": { "width": 1080, "height": 1920 }
19
+ },
20
+ "defaultVariant": "wide",
21
+ "fonts": [
22
+ "Inter:400;600;800",
23
+ { "family": "Brand Onest", "src": "assets/fonts/onest-700.woff2", "weight": "700" }
24
+ ]
25
+ }
26
+ ```
27
+
28
+ - `durationInFrames` is the export length; keep it equal to the end of the last clip.
29
+ - Fonts: Google Fonts specs (`"Family:400;700"`) or local files (preferred for brand fonts: renders
30
+ then never depend on Google Fonts). Reference them by `family` in styles.
31
+
32
+ ## layers.json
33
+
34
+ ```json
35
+ {
36
+ "version": 1,
37
+ "tracks": [
38
+ { "id": "captions", "name": "Captions", "kind": "captions", "clips": [] },
39
+ { "id": "text", "name": "Titles", "kind": "text", "clips": [] },
40
+ { "id": "grain", "name": "Film grain", "kind": "scene", "clips": [] },
41
+ { "id": "scenes", "name": "Scenes", "kind": "scene", "clips": [] },
42
+ { "id": "voice", "name": "Voice", "kind": "audio", "clips": [] },
43
+ { "id": "music", "name": "Music", "kind": "audio", "clips": [] },
44
+ { "id": "sfx", "name": "SFX", "kind": "audio", "clips": [] }
45
+ ],
46
+ "markers": [
47
+ { "id": "m-drop", "frame": 204, "label": "Drop", "kind": "beat" },
48
+ { "id": "m-reveal", "frame": 198, "label": "Reveal", "kind": "section" }
49
+ ]
50
+ }
51
+ ```
52
+
53
+ `tracks[0]` is drawn **on top**; later tracks are drawn underneath. Clips on a track are sorted by
54
+ `from`. Clips may overlap only on `scene` and `audio` tracks (use more tracks otherwise).
55
+
56
+ Track fields: `id` (kebab-case, unique), `name`, `kind`, `clips`, optional `hidden` (visual), `muted`
57
+ (audio/video), `locked` (user lock — don't move locked clips), `volume` (audio track gain).
58
+
59
+ Markers (`section` = scene starts, `cue` = moments sounds/animations hit, `beat` = music beats you rely
60
+ on) show on the timeline ruler. Keep section markers in sync with scene clips.
61
+
62
+ ### Clip fields (all kinds)
63
+
64
+ | field | |
65
+ |---|---|
66
+ | `id` | unique in the project, stable, readable |
67
+ | `name` | timeline label (optional) |
68
+ | `from`, `duration` | frames |
69
+ | `enter`, `exit` | `{ "preset": "fade" \| "slide-up" \| "slide-down" \| "slide-left" \| "slide-right" \| "pop" \| "scale" \| "blur" \| "none", "frames": 12 }` (visual clips) |
70
+ | `opacity` | 0..1 (visual clips) |
71
+ | `note` | why the clip is there (cue reason) |
72
+ | `variants` | per-variant overrides, e.g. `{ "mobile": { "box": {…}, "style": {…} } }` |
73
+
74
+ `box` = `{ "x", "y", "width", "height" }` as fractions of the frame (0..1), top-left origin.
75
+
76
+ ### Kinds
77
+
78
+ **scene** — `{ "scene": "Hook", "props": { … } }` renders `scenes/Hook.tsx`; or
79
+ `{ "component": "text-reveal", "props": { … } }` renders a library component (one of the two per clip;
80
+ see `references/components.md`).
81
+ `transform: { "x", "y", "scale" }` moves and scales everything the clip draws (x/y in frame fractions,
82
+ scale about the frame's centre). The user sets it by dragging the scene on the preview: keep it, and
83
+ change the scene's own layout instead when you are asked to reposition something.
84
+
85
+ **audio** — `{ "src": "assets/voice.wav", "volume": 1, "trimStart": 0, "fadeIn": 0, "fadeOut": 0, "loop": false, "playbackRate": 1, "role": "voice" | "music" | "sfx" | "ambience" }`.
86
+ `trimStart` skips frames of the file. Set `duration` from `agentcut_media_info` (frames). An SFX
87
+ clip's `from` is the cue frame minus the file's onset (see sound.md).
88
+
89
+ **video** — `{ "src", "trimStart", "volume", "muted", "fit": "cover" | "contain", "box", "playbackRate", "grade" }`.
90
+ `grade` — colour: `{ "exposure": 0.2, "contrast": 1.1, "temperature": 0.1, "look": "golden-stock" }` and more (fields and workflow:
91
+ `references/color.md`). Leave out what you don't change. `inheritGrade: false` keeps the project grade and adjustment layers off it.
92
+ Footage from the editor: see `references/footage.md`.
93
+
94
+ **image** — `{ "src", "fit", "box", "radius", "grade", "inheritGrade" }`. `inheritGrade: true` also applies the project grade and adjustment layers.
95
+
96
+ **adjustment** — `{ "grade" }`. Draws nothing: it grades the footage below it while it runs (`references/color.md`).
97
+
98
+ **text** — `{ "text", "box", "style": { "fontFamily", "fontSize" (px at the variant size), "fontWeight", "color", "align", "lineHeight", "letterSpacing", "textTransform", "shadow" } }`. For styled kinetic type use a scene instead.
99
+
100
+ **captions** — `{ "words": [{ "text", "from", "to" }], "style": { "preset": "pop" | "karaoke" | "plain", "fontFamily", "fontSize", "fontWeight", "color", "highlight", "position": "bottom" | "center" | "top", "maxWordsPerLine" } }`.
101
+ Word `from`/`to` are frames **relative to the clip start**. Build them from `agentcut_transcribe`
102
+ (`fromFrame - clip.from`). For custom caption looks, write a scene that takes `words` in props.
103
+
104
+ `src` forms: `assets/<file>`, `library:<path>` (workspace library shared by projects), `https://…` (must
105
+ allow CORS).
106
+
107
+ ## Scenes
108
+
109
+ ```tsx
110
+ // scenes/Hook.tsx
111
+ import { AbsoluteFill, useCurrentFrame } from "remotion";
112
+ import { RadialGlow, SPRING, ease, sp, mix, useStudio, type SceneProps } from "agentcut";
113
+
114
+ type Props = SceneProps & { title: string; accent: string };
115
+
116
+ export default function Hook({ title, accent, width, height, clip }: Props) {
117
+ const f = useCurrentFrame(); // 0 at the clip start
118
+ const vertical = height > width;
119
+ const s = sp(f, 6, SPRING.pop); // spring starting at local frame 6
120
+ const out = ease(f, clip.duration - 8, clip.duration);
121
+ return (
122
+ <AbsoluteFill style={{ background: "linear-gradient(160deg,#0b0b14,#050507)", opacity: 1 - out }}>
123
+ <RadialGlow x={0.5} y={0.45} radius={0.5} color={accent} opacity={0.25} />
124
+ <AbsoluteFill style={{ alignItems: "center", justifyContent: "center" }}>
125
+ <div style={{ fontFamily: "Inter", fontWeight: 900, fontSize: vertical ? 140 : 120,
126
+ transform: `translateY(${mix(60, 0, s)}px)`, color: "#fff" }}>{title}</div>
127
+ </AbsoluteFill>
128
+ </AbsoluteFill>
129
+ );
130
+ }
131
+ ```
132
+
133
+ Scene props: everything in the clip's `props`, plus `clip` (`id`, `from`, `duration`), `variant`,
134
+ `width`, `height`, `fps`.
135
+
136
+ `agentcut` exports: `useStudio()` (project, variant, width, height, fps), `useIsVertical()`, `usePreviewQuality()`
137
+ (cheaper drawing in the live preview, full quality in captures/export),
138
+ `asset(path)` (URL for `assets/…` / `library:…`), `clamp`, `mix`, `ease(f, from, to, easing?)`,
139
+ `sp(f, start, config?, duration?)`, `SPRING` (smooth, snappy, bouncy, pop, land), `sec(seconds)`,
140
+ `<RadialGlow>`, `<FrameBox>`, and the format types.
141
+
142
+ Shared helpers for several scenes go in `scenes/lib/*.ts(x)` (files in subfolders aren't scenes).
143
+ Available packages: `react`, `remotion`, `@remotion/media`, `@remotion/transitions` (+ presentations),
144
+ `@remotion/shapes`, `@remotion/paths`, `@remotion/noise`. Anything else: `npm install` it in the
145
+ workspace root and it gets bundled.