agentcut 0.2.16 → 0.2.19

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 (104) hide show
  1. package/README.md +127 -0
  2. package/dist/bridge.d.ts +1 -0
  3. package/dist/bridge.js +9 -4
  4. package/dist/bridge.js.map +1 -1
  5. package/dist/index.js +3 -1
  6. package/dist/index.js.map +1 -1
  7. package/dist/log.js +6 -1
  8. package/dist/log.js.map +1 -1
  9. package/dist/studio/agents/claude.d.ts +22 -1
  10. package/dist/studio/agents/claude.js +89 -3
  11. package/dist/studio/agents/claude.js.map +1 -1
  12. package/dist/studio/agents/types.d.ts +6 -0
  13. package/dist/studio/chat.d.ts +2 -0
  14. package/dist/studio/chat.js +11 -9
  15. package/dist/studio/chat.js.map +1 -1
  16. package/dist/studio/cli.js +43 -21
  17. package/dist/studio/cli.js.map +1 -1
  18. package/dist/studio/editing-styles.d.ts +26 -0
  19. package/dist/studio/editing-styles.js +84 -0
  20. package/dist/studio/editing-styles.js.map +1 -0
  21. package/dist/studio/host.d.ts +15 -2
  22. package/dist/studio/host.js +223 -6
  23. package/dist/studio/host.js.map +1 -1
  24. package/dist/studio/housekeeping.d.ts +16 -0
  25. package/dist/studio/housekeeping.js +152 -0
  26. package/dist/studio/housekeeping.js.map +1 -0
  27. package/dist/studio/http.d.ts +3 -0
  28. package/dist/studio/http.js +25 -0
  29. package/dist/studio/http.js.map +1 -1
  30. package/dist/studio/mcp-files.d.ts +34 -0
  31. package/dist/studio/mcp-files.js +159 -0
  32. package/dist/studio/mcp-files.js.map +1 -0
  33. package/dist/studio/mcp-guides.d.ts +4 -0
  34. package/dist/studio/mcp-guides.js +93 -0
  35. package/dist/studio/mcp-guides.js.map +1 -0
  36. package/dist/studio/phone-protocol.d.ts +41 -0
  37. package/dist/studio/phone-protocol.js +91 -0
  38. package/dist/studio/phone-protocol.js.map +1 -0
  39. package/dist/studio/phone.d.ts +71 -0
  40. package/dist/studio/phone.js +340 -0
  41. package/dist/studio/phone.js.map +1 -0
  42. package/dist/studio/projects.d.ts +1 -1
  43. package/dist/studio/proxies.d.ts +45 -0
  44. package/dist/studio/proxies.js +263 -0
  45. package/dist/studio/proxies.js.map +1 -0
  46. package/dist/studio/references.d.ts +18 -0
  47. package/dist/studio/references.js +21 -4
  48. package/dist/studio/references.js.map +1 -1
  49. package/dist/studio/release-browser.d.ts +25 -0
  50. package/dist/studio/release-browser.js +191 -0
  51. package/dist/studio/release-browser.js.map +1 -0
  52. package/dist/studio/release-cursor.d.ts +3 -0
  53. package/dist/studio/release-cursor.js +27 -0
  54. package/dist/studio/release-cursor.js.map +1 -0
  55. package/dist/studio/release-edit.d.ts +34 -0
  56. package/dist/studio/release-edit.js +183 -0
  57. package/dist/studio/release-edit.js.map +1 -0
  58. package/dist/studio/release-recorder.d.ts +30 -0
  59. package/dist/studio/release-recorder.js +273 -0
  60. package/dist/studio/release-recorder.js.map +1 -0
  61. package/dist/studio/release-video.d.ts +693 -0
  62. package/dist/studio/release-video.js +616 -0
  63. package/dist/studio/release-video.js.map +1 -0
  64. package/dist/studio/render.d.ts +2 -0
  65. package/dist/studio/render.js +33 -15
  66. package/dist/studio/render.js.map +1 -1
  67. package/dist/studio/reveal.d.ts +3 -1
  68. package/dist/studio/reveal.js +26 -8
  69. package/dist/studio/reveal.js.map +1 -1
  70. package/dist/studio/schema.d.ts +23642 -2685
  71. package/dist/studio/schema.js +61 -4
  72. package/dist/studio/schema.js.map +1 -1
  73. package/dist/studio/share.d.ts +2 -0
  74. package/dist/studio/share.js +7 -1
  75. package/dist/studio/share.js.map +1 -1
  76. package/dist/studio/tools.d.ts +4 -0
  77. package/dist/studio/tools.js +103 -4
  78. package/dist/studio/tools.js.map +1 -1
  79. package/dist/studio/transcription/service.js +2 -1
  80. package/dist/studio/transcription/service.js.map +1 -1
  81. package/dist/studio/workspace.d.ts +1 -0
  82. package/dist/studio/workspace.js +1 -0
  83. package/dist/studio/workspace.js.map +1 -1
  84. package/package.json +2 -1
  85. package/template/AGENTS.md +1 -0
  86. package/template/components/color/grade-effect.ts +650 -0
  87. package/template/components/color/grade.ts +512 -0
  88. package/template/components/color/looks.ts +154 -0
  89. package/template/components/index.ts +14 -0
  90. package/template/components/live-clip.ts +75 -0
  91. package/template/runtime/composition.tsx +274 -24
  92. package/template/runtime/helpers.tsx +2 -0
  93. package/template/runtime/types.ts +67 -4
  94. package/template/skill/SKILL.md +120 -5
  95. package/template/skill/references/broll.md +2 -1
  96. package/template/skill/references/color.md +79 -0
  97. package/template/skill/references/editing-styles.md +57 -0
  98. package/template/skill/references/footage.md +72 -73
  99. package/template/skill/references/format.md +142 -140
  100. package/template/skill/references/performance.md +14 -2
  101. package/template/skill/references/person-cutout.md +19 -0
  102. package/template/skill/references/presets.md +60 -56
  103. package/template/skill/references/sound.md +151 -151
  104. package/template/skill/references/website-howto.md +41 -0
@@ -1,140 +1,142 @@
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` — `{ "brightness": 1, "contrast": 1, "saturation": 1, "warmth": 0, "hue": 0 }` (neutral values;
88
- brightness/contrast/saturation 0–3, warmth −1…1, hue −180…180 degrees). Leave out what you don't change.
89
- Footage from the editor: see `references/footage.md`.
90
-
91
- **image** — `{ "src", "fit", "box", "radius" }`.
92
-
93
- **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.
94
-
95
- **captions** — `{ "words": [{ "text", "from", "to" }], "style": { "preset": "pop" | "karaoke" | "plain", "fontFamily", "fontSize", "fontWeight", "color", "highlight", "position": "bottom" | "center" | "top", "maxWordsPerLine" } }`.
96
- Word `from`/`to` are frames **relative to the clip start**. Build them from `agentcut_transcribe`
97
- (`fromFrame - clip.from`). For custom caption looks, write a scene that takes `words` in props.
98
-
99
- `src` forms: `assets/<file>`, `library:<path>` (workspace library shared by projects), `https://…` (must
100
- allow CORS).
101
-
102
- ## Scenes
103
-
104
- ```tsx
105
- // scenes/Hook.tsx
106
- import { AbsoluteFill, useCurrentFrame } from "remotion";
107
- import { RadialGlow, SPRING, ease, sp, mix, useStudio, type SceneProps } from "agentcut";
108
-
109
- type Props = SceneProps & { title: string; accent: string };
110
-
111
- export default function Hook({ title, accent, width, height, clip }: Props) {
112
- const f = useCurrentFrame(); // 0 at the clip start
113
- const vertical = height > width;
114
- const s = sp(f, 6, SPRING.pop); // spring starting at local frame 6
115
- const out = ease(f, clip.duration - 8, clip.duration);
116
- return (
117
- <AbsoluteFill style={{ background: "linear-gradient(160deg,#0b0b14,#050507)", opacity: 1 - out }}>
118
- <RadialGlow x={0.5} y={0.45} radius={0.5} color={accent} opacity={0.25} />
119
- <AbsoluteFill style={{ alignItems: "center", justifyContent: "center" }}>
120
- <div style={{ fontFamily: "Inter", fontWeight: 900, fontSize: vertical ? 140 : 120,
121
- transform: `translateY(${mix(60, 0, s)}px)`, color: "#fff" }}>{title}</div>
122
- </AbsoluteFill>
123
- </AbsoluteFill>
124
- );
125
- }
126
- ```
127
-
128
- Scene props: everything in the clip's `props`, plus `clip` (`id`, `from`, `duration`), `variant`,
129
- `width`, `height`, `fps`.
130
-
131
- `agentcut` exports: `useStudio()` (project, variant, width, height, fps), `useIsVertical()`, `usePreviewQuality()`
132
- (cheaper drawing in the live preview, full quality in captures/export),
133
- `asset(path)` (URL for `assets/…` / `library:…`), `clamp`, `mix`, `ease(f, from, to, easing?)`,
134
- `sp(f, start, config?, duration?)`, `SPRING` (smooth, snappy, bouncy, pop, land), `sec(seconds)`,
135
- `<RadialGlow>`, `<FrameBox>`, and the format types.
136
-
137
- Shared helpers for several scenes go in `scenes/lib/*.ts(x)` (files in subfolders aren't scenes).
138
- Available packages: `react`, `remotion`, `@remotion/media`, `@remotion/transitions` (+ presentations),
139
- `@remotion/shapes`, `@remotion/paths`, `@remotion/noise`. Anything else: `npm install` it in the
140
- 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
+
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.
@@ -11,6 +11,11 @@ part previews choppy but exports perfectly.
11
11
 
12
12
  ## Measure
13
13
 
14
+ For website how-to videos, use the stall recovery in `website-howto.md`. Keep all required
15
+ format, visual, playback and audio checks. Run page-heavy tools in sequence. A timed-out request
16
+ can continue in the page; inspect `page.activeWork` before retrying. A small recovery probe does
17
+ not replace the full review or reduce final render quality.
18
+
14
19
  - `agentcut_preview_check` (from/to in frames) plays a range muted in the user's preview and returns
15
20
  per visual clip: frames played and dropped, loading stalls, the longest freeze, the most DOM elements
16
21
  the clip drew, and a verdict: `smooth`, `choppy` from 20 % dropped, `heavy` from 40 % (and at least 6
@@ -21,8 +26,15 @@ part previews choppy but exports perfectly.
21
26
  that only sits on top of a slower one: fix the other one. `slowToMount` means the clip drops frames in
22
27
  the second before it starts, while it mounts early: its setup work is heavy (see rule 4), even when it
23
28
  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.
29
+ - `agentcut_status` → `page.previewPerformance` has the latest check (`lastCheck`), the user's own
30
+ playback (`playback`) and seek timings (`scrub`). `current: false` means it was measured on an older build.
31
+ - A check also returns `scrub`: how long a seek takes to reach the screen (`medianMs`, `p95Ms`, `slowClips`),
32
+ jumping forward and back through the range. A scene can play well and still lag on a drag, because every
33
+ seek draws it from nothing. Above 120 ms a drag visibly lags: the same fixes below apply, and work a scene
34
+ repeats on every frame (not just at mount) is the usual cause.
35
+ - Footage needs nothing from you: the helper makes fast-seeking copies for the preview by itself, and
36
+ captures and exports always read the original. Only `src` on a video clip gets one, so use a video clip
37
+ rather than a video inside a scene when footage is slow to scrub.
26
38
  - Run a check after building or changing a heavy scene (walls and grids, hundreds of elements, image
27
39
  sequences, big blurs, generated images) and before you say you're done. A first run includes loading
28
40
  (stalls); run it again to see steady playback. A machine's own jitter varies between runs: act on a
@@ -0,0 +1,19 @@
1
+ # Graphics behind a person
2
+
3
+ Use agentcut_cutout_person when the user wants text or a graphic behind someone, or the person in front of something. Do not install segmentation packages, write background-removal scripts, export frames or use image APIs.
4
+
5
+ The stack, top to bottom: the person cutout, the graphic, the original footage. The footage stays in place, so a slightly loose edge only shows where the graphic touches the person.
6
+
7
+ 1. Add the graphic on a track above the footage first, and note its clip ID and frames.
8
+ 2. Call agentcut_cutout_person with the footage clipId, fromFrame and durationInFrames covering only the frames where the graphic is on screen, and behind with the graphic's clip ID. Cutting out only those frames is much faster than the whole clip. The first run also downloads a model of about 26 MB.
9
+ 3. Check captures at the start, middle and end of the range, and where the graphic overlaps the person. Look at hair, hands and fast movement.
10
+
11
+ The tool adds a muted video clip to a track named Person cutout. Keep captions on a track above the cutout so the person doesn't cover them.
12
+
13
+ - To grade a person apart from their background, use `agentcut_grade_subject` instead (see `references/color.md`).
14
+ - It copies the footage clip's trim, speed, box, crop, fit and grade once. After changing those, or moving the footage, run the tool again with the same range; it replaces the earlier cutout on that range.
15
+ - A range can't start or end inside an enter or exit animation of the footage, and a project style camera needs the whole clip: the tool returns needs_full_clip, so omit the range.
16
+ - Works on the person in front; it can't choose between people, and it doesn't handle objects. Fast movement can leave soft or smeared edges. no_person means most of the range has nobody clearly visible.
17
+ - Without WebGPU the tool is several times slower and accepts up to 1,800 frames at a time; with WebGPU, 5,400.
18
+ - Frames stay on this computer. Scene-embedded video and remote URLs aren't supported.
19
+ - Files go to assets/cutouts/. Use Undo, or delete the clip, to remove a cutout.
@@ -1,56 +1,60 @@
1
- # Video style presets
2
-
3
- A video style is a recipe for a whole video that isn't a talking head: a music or lyric video, an explainer, a
4
- promo look. It lives in the workspace library, one folder per preset:
5
-
6
- ```
7
- library/presets/<id>/
8
- PROMPT.md the recipe: what to copy, the look, the workflow. Blanks in [brackets].
9
- preset.json name, description, kind, preview/poster file names, and the blanks as form fields
10
- preview.mp4 ~10 s of a video made with it (16:9, 960×540, no audio needed)
11
- poster.jpg one strong frame from it
12
- scenes/ the scene files the recipe copies into a project
13
- assets/ textures, fonts and other files the scenes need
14
- *.example.* optional: a script or layers.json that seeds the first timeline
15
- ```
16
-
17
- The style gallery (Styles tab → Video styles) lists every folder with a PROMPT.md, plays its preview, and shows a
18
- form built from `preset.json` fields. When the user fills it in, you get a message like:
19
-
20
- > Make a video with the "Punk Cut-Paper" video style: read library/presets/punk-cut-paper/PROMPT.md and follow it,
21
- > with these values for its blanks: - Song: assets/song.mp3 - Photos: … - Lyrics: transcribe them. Make it as a new
22
- > project.
23
-
24
- ## Using a preset
25
-
26
- 1. Read the preset's PROMPT.md and fill its blanks with the values given (ask only for what's missing and needed).
27
- 2. "As a new project": create it with `agentcut_create_project`, then copy the preset's `scenes/` and
28
- `assets/` into it (and any song/photos the user picked from another project or the library). "In this project":
29
- copy them into the open project and replace its timeline.
30
- 3. Follow the recipe's look and workflow exactly; it was written from a finished video, so don't improvise a new look.
31
-
32
- ## Saving a video style
33
-
34
- When the user asks to save the open video's style ("save this as a preset", the gallery's Save style button):
35
-
36
- 1. Copy the project's scene files and the assets the look needs (textures, fonts, overlays: not the user's song or
37
- personal photos) into `library/presets/<id>/`. Make the scenes generic: no names, personal facts or lyrics baked in
38
- (put example content in an `*.example.*` file).
39
- 2. Write PROMPT.md: what to copy, fonts for project.json, every rule of the look (layout, motion, timing to beats or
40
- words, colors, overlays), and the workflow. Put what changes per video in [brackets] (song, photos, title, about,
41
- lyrics, …).
42
- 3. Write preset.json:
43
- ```json
44
- { "name": "Punk Cut-Paper", "description": "One sentence on the look.", "kind": "Music video",
45
- "preview": "preview.mp4", "poster": "poster.jpg",
46
- "fields": [
47
- { "id": "song", "label": "Song", "type": "audio", "required": true },
48
- { "id": "photos", "label": "Photos", "type": "images" },
49
- { "id": "title", "label": "Title", "type": "text", "placeholder": "HAPPY BIRTHDAY SAM" },
50
- { "id": "lyrics", "label": "Lyrics", "type": "longtext", "placeholder": "Paste the lyrics, or leave empty" }
51
- ] }
52
- ```
53
- Field types: `text`, `longtext`, `audio` (the user picks an audio file), `images` (the user picks photos).
54
- 4. preview.mp4 and poster.jpg: cut ~10 s from the latest render in `renders/` (960×540, H.264, no audio) and grab one
55
- frame, choosing a stretch without personal photos when you can. With no render yet, export one first or ask.
56
- 5. Tell the user it's in the Styles tab under Video styles.
1
+ # Video style presets
2
+
3
+ These are scene/asset kits. For Save current style, saved editing rules, or applying an editing style to different
4
+ footage, read `references/editing-styles.md` instead. Existing kits stay in `library/presets/`.
5
+
6
+ A video style is a recipe for a whole video that isn't a talking head: a music or lyric video, an explainer, a
7
+ promo look. It lives in the workspace library, one folder per preset:
8
+
9
+ ```
10
+ library/presets/<id>/
11
+ PROMPT.md the recipe: what to copy, the look, the workflow. Blanks in [brackets].
12
+ preset.json name, description, kind, preview/poster file names, and the blanks as form fields
13
+ preview.mp4 ~10 s of a video made with it (16:9, 960×540, no audio needed)
14
+ poster.jpg one strong frame from it
15
+ scenes/ the scene files the recipe copies into a project
16
+ assets/ textures, fonts and other files the scenes need
17
+ *.example.* optional: a script or layers.json that seeds the first timeline
18
+ ```
19
+
20
+ The style gallery (Styles tab → Video styles) lists every folder with a PROMPT.md, plays its preview, and shows a
21
+ form built from `preset.json` fields. When the user fills it in, you get a message like:
22
+
23
+ > Make a video with the "Punk Cut-Paper" video style: read library/presets/punk-cut-paper/PROMPT.md and follow it,
24
+ > with these values for its blanks: - Song: assets/song.mp3 - Photos: … - Lyrics: transcribe them. Make it as a new
25
+ > project.
26
+
27
+ ## Using a preset
28
+
29
+ 1. Read the preset's PROMPT.md and fill its blanks with the values given (ask only for what's missing and needed).
30
+ 2. "As a new project": create it with `agentcut_create_project`, then copy the preset's `scenes/` and
31
+ `assets/` into it (and any song/photos the user picked from another project or the library). "In this project":
32
+ copy them into the open project and replace its timeline.
33
+ 3. Follow the recipe's look and workflow exactly; it was written from a finished video, so don't improvise a new look.
34
+
35
+ ## Saving a video style
36
+
37
+ Use this workflow only when the user explicitly asks to save a scene/asset kit. The gallery's Save current style
38
+ action saves editing instructions instead; follow `references/editing-styles.md` for it.
39
+
40
+ 1. Copy the project's scene files and the assets the look needs (textures, fonts, overlays: not the user's song or
41
+ personal photos) into `library/presets/<id>/`. Make the scenes generic: no names, personal facts or lyrics baked in
42
+ (put example content in an `*.example.*` file).
43
+ 2. Write PROMPT.md: what to copy, fonts for project.json, every rule of the look (layout, motion, timing to beats or
44
+ words, colors, overlays), and the workflow. Put what changes per video in [brackets] (song, photos, title, about,
45
+ lyrics, …).
46
+ 3. Write preset.json:
47
+ ```json
48
+ { "name": "Punk Cut-Paper", "description": "One sentence on the look.", "kind": "Music video",
49
+ "preview": "preview.mp4", "poster": "poster.jpg",
50
+ "fields": [
51
+ { "id": "song", "label": "Song", "type": "audio", "required": true },
52
+ { "id": "photos", "label": "Photos", "type": "images" },
53
+ { "id": "title", "label": "Title", "type": "text", "placeholder": "HAPPY BIRTHDAY SAM" },
54
+ { "id": "lyrics", "label": "Lyrics", "type": "longtext", "placeholder": "Paste the lyrics, or leave empty" }
55
+ ] }
56
+ ```
57
+ Field types: `text`, `longtext`, `audio` (the user picks an audio file), `images` (the user picks photos).
58
+ 4. preview.mp4 and poster.jpg: cut ~10 s from the latest render in `renders/` (960×540, H.264, no audio) and grab one
59
+ frame, choosing a stretch without personal photos when you can. With no render yet, export one first or ask.
60
+ 5. Tell the user it's in the Styles tab under Video styles.