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,315 +1,324 @@
1
- // Agentcut project format (v1).
2
- // Keep in sync with lib/studio/types.ts (repo root) and src/studio/schema.ts.
3
-
4
- export type TrackKind = "scene" | "video" | "image" | "text" | "captions" | "audio" | "adjustment";
5
-
6
- export interface StudioProject {
7
- version: 1;
8
- name: string;
9
- fps: number;
10
- durationInFrames: number;
11
- background: string;
12
- variants: Record<string, { width: number; height: number }>;
13
- defaultVariant: string;
14
- /** Google Fonts specs ("Inter:400;800") or local font files. */
15
- fonts: StudioFont[];
16
- /** Look for the whole video (components/styles.ts): components, captions and text follow it. */
17
- style?: string;
18
- /** A grade over all footage, after each clip's own grade and any adjustment layers. */
19
- grade?: ColorGrade;
20
- }
21
-
22
- export type StudioFont = string | { family: string; src: string; weight?: string; style?: "normal" | "italic" };
23
-
24
- export interface Box {
25
- x: number;
26
- y: number;
27
- width: number;
28
- height: number;
29
- }
30
-
31
- export type ClipAnimPreset =
32
- | "fade"
33
- | "slide-up"
34
- | "slide-down"
35
- | "slide-left"
36
- | "slide-right"
37
- | "pop"
38
- | "scale"
39
- | "blur"
40
- | "none";
41
-
42
- export interface ClipAnim {
43
- preset: ClipAnimPreset;
44
- frames: number;
45
- }
46
-
47
- export interface TextStyle {
48
- fontFamily?: string;
49
- fontSize?: number;
50
- fontWeight?: number;
51
- color?: string;
52
- align?: "left" | "center" | "right";
53
- lineHeight?: number;
54
- letterSpacing?: number;
55
- textTransform?: "none" | "uppercase" | "lowercase" | "capitalize";
56
- shadow?: string;
57
- }
58
-
59
- export interface CaptionStyle {
60
- preset?: "pop" | "karaoke" | "plain";
61
- fontFamily?: string;
62
- fontSize?: number;
63
- fontWeight?: number;
64
- color?: string;
65
- highlight?: string;
66
- position?: "bottom" | "center" | "top";
67
- maxWordsPerLine?: number;
68
- }
69
-
70
- interface BaseClipFields {
71
- id: string;
72
- name?: string;
73
- from: number;
74
- duration: number;
75
- enter?: ClipAnim;
76
- exit?: ClipAnim;
77
- opacity?: number;
78
- note?: string;
79
- }
80
-
81
- export interface SceneClipFields {
82
- /** A scene file in scenes/ ("Hook" → scenes/Hook.tsx)… */
83
- scene?: string;
84
- /** …or an Agentcut library component ("text-reveal"). Exactly one of the two. */
85
- component?: string;
86
- props?: Record<string, unknown>;
87
- }
88
-
89
- /** A colour wheel: x/y push towards a hue on the vectorscope disk (-1…1), level moves the brightness. */
90
- export interface GradeWheel { x?: number; y?: number; level?: number }
91
- export type GradeBand = "red" | "orange" | "yellow" | "green" | "aqua" | "blue" | "purple" | "magenta";
92
- export type GradeCurvePoint = [number, number];
93
-
94
- /** See skills/agentcut/references/color.md. Multipliers are neutral at 1, amounts at 0 (-1…1 unless noted). */
95
- export interface GradeFields {
96
- brightness?: number;
97
- contrast?: number;
98
- saturation?: number;
99
- /** -1 (cool) … 1 (warm). */
100
- warmth?: number;
101
- /** Degrees. */
102
- hue?: number;
103
- /** Stops, -5…5. */
104
- exposure?: number;
105
- temperature?: number;
106
- tint?: number;
107
- highlights?: number;
108
- shadows?: number;
109
- whites?: number;
110
- blacks?: number;
111
- vibrance?: number;
112
- pivot?: number;
113
- blackPoint?: number;
114
- whitePoint?: number;
115
- gamma?: number;
116
- wheels?: { shadows?: GradeWheel; midtones?: GradeWheel; highlights?: GradeWheel };
117
- curves?: { master?: GradeCurvePoint[]; r?: GradeCurvePoint[]; g?: GradeCurvePoint[]; b?: GradeCurvePoint[] };
118
- hsl?: Partial<Record<GradeBand, { hue?: number; saturation?: number; luminance?: number }>>;
119
- /** Built-in look id (agentcut_color_looks). */
120
- look?: string;
121
- lookStrength?: number;
122
- /** A .cube file in the project. */
123
- lut?: string;
124
- lutStrength?: number;
125
- /** 0…1: keep skin tones out of the colour changes. */
126
- skinProtect?: number;
127
- /** Written by shot matching. */
128
- match?: { gains?: [number, number, number]; contrast?: number; saturation?: number; anchor?: string };
129
- grain?: number;
130
- grainSize?: number;
131
- halation?: number;
132
- bloom?: number;
133
- vignette?: number;
134
- }
135
-
136
- /** A grade at one clip-local frame. `hold` jumps instead of easing into the next key. */
137
- export type GradeKey = GradeFields & { frame: number; hold?: boolean };
138
-
139
- /** Color grade for footage and images. */
140
- export interface ColorGrade extends GradeFields {
141
- keys?: GradeKey[];
142
- }
143
-
144
- export interface FramingKeyframe { seconds: number; crop: Box }
145
-
146
- export interface VideoClipFields {
147
- src: string;
148
- trimStart?: number;
149
- grade?: ColorGrade;
150
- /** false keeps the project grade and adjustment layers off this clip (default true). */
151
- inheritGrade?: boolean;
152
- volume?: number;
153
- muted?: boolean;
154
- fit?: "cover" | "contain";
155
- box?: Box;
156
- /** Corner radius in px (half the short side makes a circle). */
157
- radius?: number;
158
- playbackRate?: number;
159
- /** Draw the recorded mouse over this clip (Companion recordings). */
160
- cursor?: VideoCursor;
161
- /** "none" keeps the project style's camera moves off this clip. */
162
- camera?: "style" | "none";
163
- /** Stable crop in upright source fractions, shared by preview and export. */
164
- framing?: { crop: Box; path?: FramingKeyframe[]; before?: Box | null; beforePath?: FramingKeyframe[] };
165
- }
166
-
167
- export interface VideoCursor {
168
- /** `<video>.cursor.json`: path, clicks and scrolls in frames of the video file. */
169
- src: string;
170
- /** "hidden" draws no pointer (the video already shows one) but keeps click effects. */
171
- style?: "classic" | "accent" | "spotlight" | "hand" | "hidden";
172
- /** Percent of the default size (50–200). */
173
- size?: number;
174
- /** Ring that spreads from each click. */
175
- clicks?: boolean;
176
- /** 0 follows the raw path, 1 glides. */
177
- smoothing?: number;
178
- }
179
-
180
- /** Contents of a `<video>.cursor.json`. */
181
- export interface CursorTrack {
182
- version: 1;
183
- fps: number;
184
- durationInFrames: number;
185
- width?: number;
186
- height?: number;
187
- space: "video" | "source";
188
- cursorInVideo: boolean;
189
- path: [number, number | null, number | null][];
190
- kinds: [number, string][];
191
- clicks: { frame: number; x: number; y: number; button: string }[];
192
- scrolls: { frame: number; x: number; y: number; dy: number }[];
193
- }
194
-
195
- export interface ImageClipFields {
196
- src: string;
197
- grade?: ColorGrade;
198
- /** true also applies the project grade and adjustment layers (default false, so logos keep their colours). */
199
- inheritGrade?: boolean;
200
- fit?: "cover" | "contain";
201
- box?: Box;
202
- radius?: number;
203
- }
204
-
205
- export interface TextClipFields {
206
- text: string;
207
- box?: Box;
208
- style?: TextStyle;
209
- }
210
-
211
- export interface CaptionWord {
212
- text: string;
213
- from: number;
214
- to: number;
215
- }
216
-
217
- export interface CaptionsClipFields {
218
- words: CaptionWord[];
219
- style?: CaptionStyle;
220
- }
221
-
222
- export interface AudioClipFields {
223
- src: string;
224
- volume?: number;
225
- trimStart?: number;
226
- fadeIn?: number;
227
- fadeOut?: number;
228
- loop?: boolean;
229
- playbackRate?: number;
230
- role?: "voice" | "music" | "sfx" | "ambience";
231
- }
232
-
233
- type WithVariants<T> = T & {
234
- variants?: Record<string, Partial<Omit<T, "id">>>;
235
- };
236
-
237
- /** A grade over the footage below it on the timeline, for as long as the clip runs. */
238
- export interface AdjustmentClipFields {
239
- grade: ColorGrade;
240
- }
241
-
242
- export type SceneClip = WithVariants<BaseClipFields & SceneClipFields>;
243
- export type VideoClip = WithVariants<BaseClipFields & VideoClipFields>;
244
- export type ImageClip = WithVariants<BaseClipFields & ImageClipFields>;
245
- export type TextClip = WithVariants<BaseClipFields & TextClipFields>;
246
- export type CaptionsClip = WithVariants<BaseClipFields & CaptionsClipFields>;
247
- export type AudioClip = WithVariants<BaseClipFields & AudioClipFields>;
248
- export type AdjustmentClip = WithVariants<BaseClipFields & AdjustmentClipFields>;
249
-
250
- export type StudioClip =
251
- | SceneClip
252
- | VideoClip
253
- | ImageClip
254
- | TextClip
255
- | CaptionsClip
256
- | AudioClip
257
- | AdjustmentClip;
258
-
259
- export interface ClipByKind {
260
- scene: SceneClip;
261
- video: VideoClip;
262
- image: ImageClip;
263
- text: TextClip;
264
- captions: CaptionsClip;
265
- audio: AudioClip;
266
- adjustment: AdjustmentClip;
267
- }
268
-
269
- export interface StudioTrack<K extends TrackKind = TrackKind> {
270
- id: string;
271
- name: string;
272
- kind: K;
273
- hidden?: boolean;
274
- muted?: boolean;
275
- locked?: boolean;
276
- volume?: number;
277
- clips: ClipByKind[K][];
278
- }
279
-
280
- export interface StudioMarker {
281
- id: string;
282
- frame: number;
283
- label: string;
284
- kind?: "beat" | "cue" | "section";
285
- }
286
-
287
- export interface StudioLayers {
288
- version: 1;
289
- tracks: StudioTrack[];
290
- markers: StudioMarker[];
291
- }
292
-
293
- /** Props the runtime passes to `StudioComposition`. */
294
- export interface StudioCompositionProps extends Record<string, unknown> {
295
- project: StudioProject;
296
- layers: StudioLayers;
297
- variant: string;
298
- /** Base URL for `assets/…` paths, e.g. http://127.0.0.1:32118/studio/files/<slug> */
299
- assetBase: string;
300
- /** Base URL for `library:` paths, e.g. http://127.0.0.1:32118/studio/library */
301
- libraryBase: string;
302
- /** Linear gain applied to every audio clip (export loudness normalization). */
303
- masterGain?: number;
304
- /** Fast-seeking copies of footage, project path → URL. Only the live preview passes these. */
305
- previewProxies?: Record<string, string>;
306
- }
307
-
308
- /** Props every scene component receives (plus the clip's own `props`). */
309
- export interface SceneProps {
310
- clip: { id: string; from: number; duration: number };
311
- variant: string;
312
- width: number;
313
- height: number;
314
- fps: number;
315
- }
1
+ // Agentcut project format (v1).
2
+ // Keep in sync with lib/studio/types.ts (repo root) and src/studio/schema.ts.
3
+
4
+ export type TrackKind = "scene" | "video" | "image" | "text" | "captions" | "audio" | "adjustment";
5
+
6
+ export interface StudioProject {
7
+ version: 1;
8
+ name: string;
9
+ fps: number;
10
+ durationInFrames: number;
11
+ background: string;
12
+ variants: Record<string, { width: number; height: number }>;
13
+ defaultVariant: string;
14
+ /** Google Fonts specs ("Inter:400;800") or local font files. */
15
+ fonts: StudioFont[];
16
+ /** Look for the whole video (components/styles.ts): components, captions and text follow it. */
17
+ style?: string;
18
+ /** A grade over all footage, after each clip's own grade and any adjustment layers. */
19
+ grade?: ColorGrade;
20
+ }
21
+
22
+ export type StudioFont = string | { family: string; src: string; weight?: string; style?: "normal" | "italic" };
23
+
24
+ export interface Box {
25
+ x: number;
26
+ y: number;
27
+ width: number;
28
+ height: number;
29
+ }
30
+
31
+ export type ClipAnimPreset =
32
+ | "fade"
33
+ | "slide-up"
34
+ | "slide-down"
35
+ | "slide-left"
36
+ | "slide-right"
37
+ | "pop"
38
+ | "scale"
39
+ | "blur"
40
+ | "none";
41
+
42
+ export interface ClipAnim {
43
+ preset: ClipAnimPreset;
44
+ frames: number;
45
+ }
46
+
47
+ export interface TextStyle {
48
+ fontFamily?: string;
49
+ fontSize?: number;
50
+ fontWeight?: number;
51
+ color?: string;
52
+ align?: "left" | "center" | "right";
53
+ lineHeight?: number;
54
+ letterSpacing?: number;
55
+ textTransform?: "none" | "uppercase" | "lowercase" | "capitalize";
56
+ shadow?: string;
57
+ }
58
+
59
+ export interface CaptionStyle {
60
+ preset?: "pop" | "karaoke" | "plain";
61
+ fontFamily?: string;
62
+ fontSize?: number;
63
+ fontWeight?: number;
64
+ color?: string;
65
+ highlight?: string;
66
+ position?: "bottom" | "center" | "top";
67
+ maxWordsPerLine?: number;
68
+ }
69
+
70
+ interface BaseClipFields {
71
+ id: string;
72
+ name?: string;
73
+ from: number;
74
+ duration: number;
75
+ enter?: ClipAnim;
76
+ exit?: ClipAnim;
77
+ opacity?: number;
78
+ note?: string;
79
+ }
80
+
81
+ /** Where a scene was moved and resized by hand: x/y in frame fractions, scale about the frame's centre. */
82
+ export interface ClipTransform {
83
+ x?: number;
84
+ y?: number;
85
+ scale?: number;
86
+ }
87
+
88
+ export interface SceneClipFields {
89
+ /** A scene file in scenes/ ("Hook" → scenes/Hook.tsx)… */
90
+ scene?: string;
91
+ /** …or an Agentcut library component ("text-reveal"). Exactly one of the two. */
92
+ component?: string;
93
+ props?: Record<string, unknown>;
94
+ /** Moves and scales everything the scene draws (the user drags it on the preview). */
95
+ transform?: ClipTransform;
96
+ }
97
+
98
+ /** A colour wheel: x/y push towards a hue on the vectorscope disk (-1…1), level moves the brightness. */
99
+ export interface GradeWheel { x?: number; y?: number; level?: number }
100
+ export type GradeBand = "red" | "orange" | "yellow" | "green" | "aqua" | "blue" | "purple" | "magenta";
101
+ export type GradeCurvePoint = [number, number];
102
+
103
+ /** See skills/agentcut/references/color.md. Multipliers are neutral at 1, amounts at 0 (-1…1 unless noted). */
104
+ export interface GradeFields {
105
+ brightness?: number;
106
+ contrast?: number;
107
+ saturation?: number;
108
+ /** -1 (cool) … 1 (warm). */
109
+ warmth?: number;
110
+ /** Degrees. */
111
+ hue?: number;
112
+ /** Stops, -5…5. */
113
+ exposure?: number;
114
+ temperature?: number;
115
+ tint?: number;
116
+ highlights?: number;
117
+ shadows?: number;
118
+ whites?: number;
119
+ blacks?: number;
120
+ vibrance?: number;
121
+ pivot?: number;
122
+ blackPoint?: number;
123
+ whitePoint?: number;
124
+ gamma?: number;
125
+ wheels?: { shadows?: GradeWheel; midtones?: GradeWheel; highlights?: GradeWheel };
126
+ curves?: { master?: GradeCurvePoint[]; r?: GradeCurvePoint[]; g?: GradeCurvePoint[]; b?: GradeCurvePoint[] };
127
+ hsl?: Partial<Record<GradeBand, { hue?: number; saturation?: number; luminance?: number }>>;
128
+ /** Built-in look id (agentcut_color_looks). */
129
+ look?: string;
130
+ lookStrength?: number;
131
+ /** A .cube file in the project. */
132
+ lut?: string;
133
+ lutStrength?: number;
134
+ /** 0…1: keep skin tones out of the colour changes. */
135
+ skinProtect?: number;
136
+ /** Written by shot matching. */
137
+ match?: { gains?: [number, number, number]; contrast?: number; saturation?: number; anchor?: string };
138
+ grain?: number;
139
+ grainSize?: number;
140
+ halation?: number;
141
+ bloom?: number;
142
+ vignette?: number;
143
+ }
144
+
145
+ /** A grade at one clip-local frame. `hold` jumps instead of easing into the next key. */
146
+ export type GradeKey = GradeFields & { frame: number; hold?: boolean };
147
+
148
+ /** Color grade for footage and images. */
149
+ export interface ColorGrade extends GradeFields {
150
+ keys?: GradeKey[];
151
+ }
152
+
153
+ export interface FramingKeyframe { seconds: number; crop: Box }
154
+
155
+ export interface VideoClipFields {
156
+ src: string;
157
+ trimStart?: number;
158
+ grade?: ColorGrade;
159
+ /** false keeps the project grade and adjustment layers off this clip (default true). */
160
+ inheritGrade?: boolean;
161
+ volume?: number;
162
+ muted?: boolean;
163
+ fit?: "cover" | "contain";
164
+ box?: Box;
165
+ /** Corner radius in px (half the short side makes a circle). */
166
+ radius?: number;
167
+ playbackRate?: number;
168
+ /** Draw the recorded mouse over this clip (Companion recordings). */
169
+ cursor?: VideoCursor;
170
+ /** "none" keeps the project style's camera moves off this clip. */
171
+ camera?: "style" | "none";
172
+ /** Stable crop in upright source fractions, shared by preview and export. */
173
+ framing?: { crop: Box; path?: FramingKeyframe[]; before?: Box | null; beforePath?: FramingKeyframe[] };
174
+ }
175
+
176
+ export interface VideoCursor {
177
+ /** `<video>.cursor.json`: path, clicks and scrolls in frames of the video file. */
178
+ src: string;
179
+ /** "hidden" draws no pointer (the video already shows one) but keeps click effects. */
180
+ style?: "classic" | "accent" | "spotlight" | "hand" | "hidden";
181
+ /** Percent of the default size (50–200). */
182
+ size?: number;
183
+ /** Ring that spreads from each click. */
184
+ clicks?: boolean;
185
+ /** 0 follows the raw path, 1 glides. */
186
+ smoothing?: number;
187
+ }
188
+
189
+ /** Contents of a `<video>.cursor.json`. */
190
+ export interface CursorTrack {
191
+ version: 1;
192
+ fps: number;
193
+ durationInFrames: number;
194
+ width?: number;
195
+ height?: number;
196
+ space: "video" | "source";
197
+ cursorInVideo: boolean;
198
+ path: [number, number | null, number | null][];
199
+ kinds: [number, string][];
200
+ clicks: { frame: number; x: number; y: number; button: string }[];
201
+ scrolls: { frame: number; x: number; y: number; dy: number }[];
202
+ }
203
+
204
+ export interface ImageClipFields {
205
+ src: string;
206
+ grade?: ColorGrade;
207
+ /** true also applies the project grade and adjustment layers (default false, so logos keep their colours). */
208
+ inheritGrade?: boolean;
209
+ fit?: "cover" | "contain";
210
+ box?: Box;
211
+ radius?: number;
212
+ }
213
+
214
+ export interface TextClipFields {
215
+ text: string;
216
+ box?: Box;
217
+ style?: TextStyle;
218
+ }
219
+
220
+ export interface CaptionWord {
221
+ text: string;
222
+ from: number;
223
+ to: number;
224
+ }
225
+
226
+ export interface CaptionsClipFields {
227
+ words: CaptionWord[];
228
+ style?: CaptionStyle;
229
+ }
230
+
231
+ export interface AudioClipFields {
232
+ src: string;
233
+ volume?: number;
234
+ trimStart?: number;
235
+ fadeIn?: number;
236
+ fadeOut?: number;
237
+ loop?: boolean;
238
+ playbackRate?: number;
239
+ role?: "voice" | "music" | "sfx" | "ambience";
240
+ }
241
+
242
+ type WithVariants<T> = T & {
243
+ variants?: Record<string, Partial<Omit<T, "id">>>;
244
+ };
245
+
246
+ /** A grade over the footage below it on the timeline, for as long as the clip runs. */
247
+ export interface AdjustmentClipFields {
248
+ grade: ColorGrade;
249
+ }
250
+
251
+ export type SceneClip = WithVariants<BaseClipFields & SceneClipFields>;
252
+ export type VideoClip = WithVariants<BaseClipFields & VideoClipFields>;
253
+ export type ImageClip = WithVariants<BaseClipFields & ImageClipFields>;
254
+ export type TextClip = WithVariants<BaseClipFields & TextClipFields>;
255
+ export type CaptionsClip = WithVariants<BaseClipFields & CaptionsClipFields>;
256
+ export type AudioClip = WithVariants<BaseClipFields & AudioClipFields>;
257
+ export type AdjustmentClip = WithVariants<BaseClipFields & AdjustmentClipFields>;
258
+
259
+ export type StudioClip =
260
+ | SceneClip
261
+ | VideoClip
262
+ | ImageClip
263
+ | TextClip
264
+ | CaptionsClip
265
+ | AudioClip
266
+ | AdjustmentClip;
267
+
268
+ export interface ClipByKind {
269
+ scene: SceneClip;
270
+ video: VideoClip;
271
+ image: ImageClip;
272
+ text: TextClip;
273
+ captions: CaptionsClip;
274
+ audio: AudioClip;
275
+ adjustment: AdjustmentClip;
276
+ }
277
+
278
+ export interface StudioTrack<K extends TrackKind = TrackKind> {
279
+ id: string;
280
+ name: string;
281
+ kind: K;
282
+ hidden?: boolean;
283
+ muted?: boolean;
284
+ locked?: boolean;
285
+ volume?: number;
286
+ clips: ClipByKind[K][];
287
+ }
288
+
289
+ export interface StudioMarker {
290
+ id: string;
291
+ frame: number;
292
+ label: string;
293
+ kind?: "beat" | "cue" | "section";
294
+ }
295
+
296
+ export interface StudioLayers {
297
+ version: 1;
298
+ tracks: StudioTrack[];
299
+ markers: StudioMarker[];
300
+ }
301
+
302
+ /** Props the runtime passes to `StudioComposition`. */
303
+ export interface StudioCompositionProps extends Record<string, unknown> {
304
+ project: StudioProject;
305
+ layers: StudioLayers;
306
+ variant: string;
307
+ /** Base URL for `assets/…` paths, e.g. http://127.0.0.1:32118/studio/files/<slug> */
308
+ assetBase: string;
309
+ /** Base URL for `library:` paths, e.g. http://127.0.0.1:32118/studio/library */
310
+ libraryBase: string;
311
+ /** Linear gain applied to every audio clip (export loudness normalization). */
312
+ masterGain?: number;
313
+ /** Fast-seeking copies of footage, project path → URL. Only the live preview passes these. */
314
+ previewProxies?: Record<string, string>;
315
+ }
316
+
317
+ /** Props every scene component receives (plus the clip's own `props`). */
318
+ export interface SceneProps {
319
+ clip: { id: string; from: number; duration: number };
320
+ variant: string;
321
+ width: number;
322
+ height: number;
323
+ fps: number;
324
+ }