agentcut 0.2.25 → 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.
Files changed (127) hide show
  1. package/README.md +177 -148
  2. package/dist/config.d.ts +0 -1
  3. package/dist/config.js +0 -5
  4. package/dist/config.js.map +1 -1
  5. package/dist/studio/agents/claude.js +3 -2
  6. package/dist/studio/agents/claude.js.map +1 -1
  7. package/dist/studio/chat.js +1 -1
  8. package/dist/studio/chat.js.map +1 -1
  9. package/dist/studio/cli.js +40 -21
  10. package/dist/studio/cli.js.map +1 -1
  11. package/dist/studio/download.d.ts +24 -0
  12. package/dist/studio/download.js +234 -0
  13. package/dist/studio/download.js.map +1 -0
  14. package/dist/studio/host.d.ts +1 -2
  15. package/dist/studio/host.js +36 -8
  16. package/dist/studio/host.js.map +1 -1
  17. package/dist/studio/housekeeping.d.ts +2 -2
  18. package/dist/studio/housekeeping.js +18 -17
  19. package/dist/studio/housekeeping.js.map +1 -1
  20. package/dist/studio/mcp-guides.js +1 -18
  21. package/dist/studio/mcp-guides.js.map +1 -1
  22. package/dist/studio/proc.js +16 -6
  23. package/dist/studio/proc.js.map +1 -1
  24. package/dist/studio/proxies.d.ts +4 -0
  25. package/dist/studio/proxies.js +15 -6
  26. package/dist/studio/proxies.js.map +1 -1
  27. package/dist/studio/release-cursor.js +21 -21
  28. package/dist/studio/release-video.js +10 -10
  29. package/dist/studio/schema.d.ts +0 -1
  30. package/dist/studio/schema.js +0 -1
  31. package/dist/studio/schema.js.map +1 -1
  32. package/dist/studio/tools.d.ts +0 -4
  33. package/dist/studio/tools.js +32 -31
  34. package/dist/studio/tools.js.map +1 -1
  35. package/dist/studio/voice/kokoro-catalog.d.ts +56 -28
  36. package/dist/studio/voice/kokoro-catalog.js +56 -28
  37. package/dist/studio/voice/kokoro-catalog.js.map +1 -1
  38. package/dist/studio/voice/ming-catalog.d.ts +19 -0
  39. package/dist/studio/voice/ming-catalog.js +40 -0
  40. package/dist/studio/voice/ming-catalog.js.map +1 -0
  41. package/dist/studio/voice/ming.d.ts +12 -0
  42. package/dist/studio/voice/ming.js +397 -0
  43. package/dist/studio/voice/ming.js.map +1 -0
  44. package/dist/studio/voice/previews.d.ts +5 -0
  45. package/dist/studio/voice/previews.js +50 -0
  46. package/dist/studio/voice/previews.js.map +1 -0
  47. package/dist/studio/voice/registry.js +2 -0
  48. package/dist/studio/voice/registry.js.map +1 -1
  49. package/dist/studio/voice.d.ts +1 -1
  50. package/dist/studio/voice.js +5 -6
  51. package/dist/studio/voice.js.map +1 -1
  52. package/package.json +56 -56
  53. package/template/AGENTS.md +14 -14
  54. package/template/components/README.md +70 -70
  55. package/template/components/before-after/BeforeAfter.tsx +89 -89
  56. package/template/components/catalog.ts +107 -107
  57. package/template/components/cinematic/Device3D.tsx +324 -324
  58. package/template/components/cinematic/devices3d/display-model.ts +184 -184
  59. package/template/components/cinematic/devices3d/iphone-model.ts +643 -643
  60. package/template/components/cinematic/devices3d/macbook-model.ts +608 -608
  61. package/template/components/cinematic/devices3d/models.ts +657 -657
  62. package/template/components/cinematic/devices3d/runtime.ts +267 -267
  63. package/template/components/cinematic/math.ts +100 -100
  64. package/template/components/color/grade-effect.ts +650 -650
  65. package/template/components/color/grade.ts +512 -512
  66. package/template/components/color/looks.ts +154 -154
  67. package/template/components/countdown/Countdown.tsx +166 -166
  68. package/template/components/dot-trace-title/DotTraceTitle.tsx +181 -181
  69. package/template/components/dot-trace-title/meta.json +51 -51
  70. package/template/components/generate/GenerateReveal.tsx +381 -381
  71. package/template/components/hook-card/HookCard.tsx +554 -554
  72. package/template/components/index.ts +199 -199
  73. package/template/components/lib.ts +191 -191
  74. package/template/components/line-diagram/LineDiagram.tsx +205 -205
  75. package/template/components/line-diagram/meta.json +215 -215
  76. package/template/components/list-card/ListCard.tsx +104 -104
  77. package/template/components/live-clip.ts +75 -75
  78. package/template/components/looks.tsx +1447 -1447
  79. package/template/components/loops/LoopCanvas.tsx +132 -132
  80. package/template/components/loops/engine.ts +184 -184
  81. package/template/components/loops/library.ts +667 -667
  82. package/template/components/loops/library2.ts +777 -777
  83. package/template/components/motion-loop/MotionLoop.tsx +37 -37
  84. package/template/components/motion-loop/meta.json +311 -311
  85. package/template/components/props.ts +73 -73
  86. package/template/components/quote-card/QuoteCard.tsx +71 -71
  87. package/template/components/style-layer.tsx +233 -233
  88. package/template/components/styles.ts +113 -113
  89. package/template/components/types.ts +66 -66
  90. package/template/components/word-pop/WordPop.tsx +59 -59
  91. package/template/components/word-stack/WordStack.tsx +122 -122
  92. package/template/presets/charcoal-sketch/PROMPT.md +48 -48
  93. package/template/presets/charcoal-sketch/scripts/duck_music.py +34 -34
  94. package/template/presets/punk-cut-paper/scenes/Motif.tsx +376 -376
  95. package/template/presets/punk-cut-paper/scenes/Photo.tsx +73 -73
  96. package/template/presets/punk-cut-paper/scenes/Ransom.tsx +119 -119
  97. package/template/runtime/composition.tsx +1189 -1185
  98. package/template/runtime/helpers.tsx +230 -230
  99. package/template/runtime/index.tsx +22 -22
  100. package/template/runtime/types.ts +315 -315
  101. package/template/skill/SKILL.md +186 -351
  102. package/template/skill/references/broll.md +44 -44
  103. package/template/skill/references/browser-export.md +61 -61
  104. package/template/skill/references/cinematic.md +206 -206
  105. package/template/skill/references/color.md +79 -79
  106. package/template/skill/references/craft.md +54 -10
  107. package/template/skill/references/editing-styles.md +57 -57
  108. package/template/skill/references/feature-launch.md +5 -1
  109. package/template/skill/references/footage.md +72 -72
  110. package/template/skill/references/format.md +142 -142
  111. package/template/skill/references/how-to.md +0 -15
  112. package/template/skill/references/launch-direction.md +89 -0
  113. package/template/skill/references/loops.md +151 -151
  114. package/template/skill/references/mcp-external.md +19 -0
  115. package/template/skill/references/performance.md +93 -93
  116. package/template/skill/references/person-cutout.md +19 -19
  117. package/template/skill/references/presets.md +60 -60
  118. package/template/skill/references/product-launch.md +4 -1
  119. package/template/skill/references/release-capture.md +53 -0
  120. package/template/skill/references/sound.md +167 -155
  121. package/template/skill/references/style-spy.md +160 -160
  122. package/template/skill/references/website-howto.md +45 -45
  123. package/template/starter/.studio/chat.json +1 -1
  124. package/template/starter/layers.json +46 -46
  125. package/template/starter/notes.md +4 -4
  126. package/template/starter/project.json +13 -13
  127. package/template/starter/scenes/Title.tsx +38 -38
@@ -1,315 +1,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
- 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
+ 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
+ }