agentcut 0.2.16 → 0.2.18

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 (98) 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 +11 -2
  22. package/dist/studio/host.js +124 -5
  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/projects.d.ts +1 -1
  37. package/dist/studio/proxies.d.ts +45 -0
  38. package/dist/studio/proxies.js +263 -0
  39. package/dist/studio/proxies.js.map +1 -0
  40. package/dist/studio/references.d.ts +18 -0
  41. package/dist/studio/references.js +21 -4
  42. package/dist/studio/references.js.map +1 -1
  43. package/dist/studio/release-browser.d.ts +25 -0
  44. package/dist/studio/release-browser.js +191 -0
  45. package/dist/studio/release-browser.js.map +1 -0
  46. package/dist/studio/release-cursor.d.ts +3 -0
  47. package/dist/studio/release-cursor.js +27 -0
  48. package/dist/studio/release-cursor.js.map +1 -0
  49. package/dist/studio/release-edit.d.ts +34 -0
  50. package/dist/studio/release-edit.js +183 -0
  51. package/dist/studio/release-edit.js.map +1 -0
  52. package/dist/studio/release-recorder.d.ts +30 -0
  53. package/dist/studio/release-recorder.js +273 -0
  54. package/dist/studio/release-recorder.js.map +1 -0
  55. package/dist/studio/release-video.d.ts +693 -0
  56. package/dist/studio/release-video.js +616 -0
  57. package/dist/studio/release-video.js.map +1 -0
  58. package/dist/studio/render.d.ts +2 -0
  59. package/dist/studio/render.js +33 -15
  60. package/dist/studio/render.js.map +1 -1
  61. package/dist/studio/reveal.d.ts +3 -1
  62. package/dist/studio/reveal.js +26 -8
  63. package/dist/studio/reveal.js.map +1 -1
  64. package/dist/studio/schema.d.ts +23642 -2685
  65. package/dist/studio/schema.js +61 -4
  66. package/dist/studio/schema.js.map +1 -1
  67. package/dist/studio/share.d.ts +2 -0
  68. package/dist/studio/share.js +7 -1
  69. package/dist/studio/share.js.map +1 -1
  70. package/dist/studio/tools.d.ts +4 -0
  71. package/dist/studio/tools.js +103 -4
  72. package/dist/studio/tools.js.map +1 -1
  73. package/dist/studio/transcription/service.js +2 -1
  74. package/dist/studio/transcription/service.js.map +1 -1
  75. package/dist/studio/workspace.d.ts +1 -0
  76. package/dist/studio/workspace.js +1 -0
  77. package/dist/studio/workspace.js.map +1 -1
  78. package/package.json +2 -1
  79. package/template/AGENTS.md +1 -0
  80. package/template/components/color/grade-effect.ts +650 -0
  81. package/template/components/color/grade.ts +512 -0
  82. package/template/components/color/looks.ts +154 -0
  83. package/template/components/index.ts +14 -0
  84. package/template/components/live-clip.ts +75 -0
  85. package/template/runtime/composition.tsx +274 -24
  86. package/template/runtime/helpers.tsx +2 -0
  87. package/template/runtime/types.ts +67 -4
  88. package/template/skill/SKILL.md +120 -5
  89. package/template/skill/references/broll.md +2 -1
  90. package/template/skill/references/color.md +79 -0
  91. package/template/skill/references/editing-styles.md +57 -0
  92. package/template/skill/references/footage.md +72 -73
  93. package/template/skill/references/format.md +142 -140
  94. package/template/skill/references/performance.md +14 -2
  95. package/template/skill/references/person-cutout.md +19 -0
  96. package/template/skill/references/presets.md +60 -56
  97. package/template/skill/references/sound.md +151 -151
  98. package/template/skill/references/website-howto.md +41 -0
@@ -0,0 +1,75 @@
1
+ // Edits in progress. While a slider moves, its value goes straight to the one clip it changes, so only
2
+ // that clip redraws: nothing else in the studio re-renders until the edit is saved on release.
3
+ // Renders (captures and exports) never read this, so they only ever draw what's saved.
4
+ import { useMemo, useSyncExternalStore } from "react";
5
+
6
+ type Fields = Record<string, unknown>;
7
+
8
+ /** Key for the whole-video grade, which isn't a clip. */
9
+ export const LIVE_PROJECT = "project";
10
+
11
+ const live = new Map<string, Fields>();
12
+ const clearing = new Set<string>();
13
+ const listeners = new Set<() => void>();
14
+ let scheduled = false;
15
+
16
+ function flush() {
17
+ scheduled = false;
18
+ for (const id of clearing) live.delete(id);
19
+ clearing.clear();
20
+ for (const listener of listeners) listener();
21
+ }
22
+
23
+ /** At most one redraw per display frame, however fast the pointer reports. */
24
+ function schedule() {
25
+ if (scheduled) return;
26
+ scheduled = true;
27
+ if (typeof requestAnimationFrame === "function") requestAnimationFrame(flush);
28
+ else flush();
29
+ }
30
+
31
+ function subscribe(listener: () => void) {
32
+ listeners.add(listener);
33
+ return () => {
34
+ listeners.delete(listener);
35
+ };
36
+ }
37
+
38
+ export function setLiveClip(id: string, fields: Fields) {
39
+ clearing.delete(id);
40
+ live.set(id, { ...live.get(id), ...fields });
41
+ schedule();
42
+ }
43
+
44
+ /** The edit is over. Takes effect on the next frame, after the saved value has reached the clip. */
45
+ export function clearLiveClip(id: string) {
46
+ if (!live.has(id)) return;
47
+ clearing.add(id);
48
+ schedule();
49
+ }
50
+
51
+ /** Fields being edited on this clip, or undefined. */
52
+ export function getLiveClip(id: string): Fields | undefined {
53
+ return live.get(id);
54
+ }
55
+
56
+ const none = () => undefined;
57
+
58
+ /** `clip` with any edit in progress on top. Re-renders only when this clip's own edit changes. */
59
+ export function useLiveClip<T extends { id: string }>(clip: T, isRendering = false): T {
60
+ const id = clip.id;
61
+ const snapshot = isRendering ? none : () => live.get(id);
62
+ const fields = useSyncExternalStore(subscribe, snapshot, none);
63
+ return useMemo(() => (fields ? { ...clip, ...fields } : clip), [clip, fields]);
64
+ }
65
+
66
+ /** Re-render when any of these edits change (a clip following adjustment layers and the project grade). */
67
+ export function useLiveClips(ids: string[], isRendering = false) {
68
+ const snapshot = () => {
69
+ if (isRendering) return "";
70
+ let key = "";
71
+ for (const id of ids) if (live.has(id)) key += `${id}:${JSON.stringify(live.get(id))};`;
72
+ return key;
73
+ };
74
+ useSyncExternalStore(subscribe, snapshot, () => "");
75
+ }
@@ -1,10 +1,11 @@
1
1
  // StudioComposition: draws a project's layers.json with Remotion.
2
2
  // Tracks are drawn bottom → top (tracks[0] is the top layer) so stacking never
3
3
  // depends on z-index, which the browser export ignores.
4
- import { useEffect, useMemo, useState, type ComponentType, type CSSProperties, type ReactNode } from "react";
4
+ import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type ComponentType, type CSSProperties, type ReactNode } from "react";
5
5
  import {
6
6
  AbsoluteFill,
7
7
  Img,
8
+ Internals,
8
9
  Sequence,
9
10
  continueRender,
10
11
  delayRender,
@@ -14,6 +15,7 @@ import {
14
15
  useVideoConfig,
15
16
  } from "remotion";
16
17
  import { Audio, Video } from "@remotion/media";
18
+ import type { EffectDescriptor } from "remotion";
17
19
  import { framingCropAt } from "./framing";
18
20
  // The Agentcut component library, provided by the studio page (and by a copy in
19
21
  // .agentcut/components for local renders).
@@ -59,9 +61,11 @@ import {
59
61
  } from "./helpers";
60
62
  import type {
61
63
  AudioClip,
64
+ AdjustmentClip,
62
65
  Box,
63
66
  CaptionsClip,
64
67
  ClipAnim,
68
+ ColorGrade,
65
69
  ImageClip,
66
70
  SceneClip,
67
71
  SceneProps,
@@ -251,7 +255,7 @@ function boxStyle(box: Box | undefined): CSSProperties {
251
255
  // Clip renderers (all frames local to the clip's <Sequence>)
252
256
 
253
257
  function SceneClipView({
254
- clip,
258
+ clip: saved,
255
259
  scenes,
256
260
  ctx,
257
261
  }: {
@@ -259,6 +263,7 @@ function SceneClipView({
259
263
  scenes: SceneRegistry;
260
264
  ctx: StudioRuntimeContextValue;
261
265
  }) {
266
+ const clip = useLive(saved);
262
267
  const style = useClipStyle(clip);
263
268
  if (clip.component) {
264
269
  const entry = MOTION_COMPONENTS[clip.component];
@@ -323,18 +328,165 @@ function SceneClipView({
323
328
  );
324
329
  }
325
330
 
326
- function ImageClipView({ clip }: { clip: ImageClip }) {
331
+ function ImageClipView({ clip: saved, ctx }: { clip: ImageClip; ctx: TrackContext }) {
332
+ const clip = useLive(saved);
327
333
  const style = useClipStyle(clip);
334
+ const { filter, effects } = useClipGrade(clip, ctx, clip.inheritGrade === true);
328
335
  return (
329
336
  <div style={{ ...boxStyle(clip.box), ...style, overflow: "hidden", borderRadius: clip.radius }}>
330
- <Img
331
- src={asset(clip.src)}
332
- style={{ width: "100%", height: "100%", objectFit: clip.fit ?? "cover", display: "block" }}
333
- />
337
+ {effects.length ? (
338
+ // Effects draw images on a canvas, which needs its size in pixels.
339
+ <Img
340
+ src={asset(clip.src)}
341
+ width={Math.max(1, Math.round((clip.box?.width ?? 1) * ctx.width))}
342
+ height={Math.max(1, Math.round((clip.box?.height ?? 1) * ctx.height))}
343
+ effects={effects}
344
+ style={{ width: "100%", height: "100%", display: "block", objectFit: clip.fit ?? "cover" }}
345
+ />
346
+ ) : (
347
+ <Img
348
+ src={asset(clip.src)}
349
+ style={{ width: "100%", height: "100%", objectFit: clip.fit ?? "cover", display: "block", filter }}
350
+ />
351
+ )}
334
352
  </div>
335
353
  );
336
354
  }
337
355
 
356
+ /** The runtime context plus what a clip needs to know about the stack it sits in. */
357
+ type TrackContext = StudioRuntimeContextValue & {
358
+ adjustments: { clip: AdjustmentClip; order: number }[];
359
+ /** Position in the stack, bottom to top. */
360
+ order: number;
361
+ };
362
+
363
+ // The grade engine comes from the library too. Pages from before it don't provide it: those keep the
364
+ // CSS filter below, which covers the original controls.
365
+ const LIVE_PROJECT = "project";
366
+ type GradeEntry = { grade: ColorGrade; frame: number; strength?: number };
367
+ type GradeEngine = {
368
+ gradeEffects?: (grades: GradeEntry[], options: { seed: number; luts?: ReadonlyMap<string, unknown> }) => EffectDescriptor<unknown>[];
369
+ gradeLutPaths?: (grade: ColorGrade | undefined) => string[];
370
+ isCssGrade?: (grade: ColorGrade | undefined) => boolean;
371
+ canDrawGrade?: () => boolean;
372
+ parseCube?: (text: string) => unknown;
373
+ };
374
+ const gradeEngine = ComponentLibrary as GradeEngine;
375
+
376
+ // A moving slider's value, straight from the inspector. Older pages don't provide it.
377
+ type LiveEdits = {
378
+ useLiveClip?: <T extends { id: string }>(clip: T, isRendering?: boolean) => T;
379
+ useLiveClips?: (ids: string[], isRendering?: boolean) => void;
380
+ getLiveClip?: (id: string) => Record<string, unknown> | undefined;
381
+ };
382
+ const liveEdits = ComponentLibrary as LiveEdits;
383
+ const useLiveClipEngine = liveEdits.useLiveClip;
384
+ const useLiveClipsEngine = liveEdits.useLiveClips;
385
+
386
+ function useLive<T extends { id: string }>(clip: T): T {
387
+ const { isRendering } = useRemotionEnvironment();
388
+ // The library is fixed for the page's lifetime, so this always calls the same hooks.
389
+ return useLiveClipEngine ? useLiveClipEngine(clip, isRendering) : clip;
390
+ }
391
+
392
+ const loadedLuts = new Map<string, unknown>();
393
+ const pendingLuts = new Map<string, Promise<void>>();
394
+
395
+ /** Load a .cube file once. A missing or broken file warns and the grade draws without it. */
396
+ function loadLut(path: string) {
397
+ let pending = pendingLuts.get(path);
398
+ if (!pending) {
399
+ pending = fetch(asset(path))
400
+ .then((response) => {
401
+ if (!response.ok) throw new Error(`HTTP ${response.status}`);
402
+ return response.text();
403
+ })
404
+ .then((text) => {
405
+ loadedLuts.set(path, gradeEngine.parseCube?.(text) ?? null);
406
+ })
407
+ .catch((error) => {
408
+ loadedLuts.set(path, null);
409
+ console.warn(`Could not load the LUT ${path}: ${error instanceof Error ? error.message : error}`);
410
+ });
411
+ pendingLuts.set(path, pending);
412
+ }
413
+ return pending;
414
+ }
415
+
416
+ /** Holds the render until these .cube files have loaded; later additions (preview edits) just redraw. */
417
+ function useGradeLuts(paths: string[]) {
418
+ const key = paths.join("\n");
419
+ const [, setLoaded] = useState(0);
420
+ const [handle] = useState(() =>
421
+ paths.some((path) => !loadedLuts.has(path)) ? delayRender(`Loading LUT ${paths.join(", ")}`, { timeoutInMilliseconds: 20_000 }) : null,
422
+ );
423
+ useEffect(() => {
424
+ let cancelled = false;
425
+ const wanted = key ? key.split("\n") : [];
426
+ Promise.all(wanted.map(loadLut))
427
+ .then(() => {
428
+ if (!cancelled) setLoaded((n) => n + 1);
429
+ })
430
+ .finally(() => {
431
+ if (handle !== null) continueRender(handle);
432
+ });
433
+ return () => {
434
+ cancelled = true;
435
+ };
436
+ }, [key, handle]);
437
+ return loadedLuts;
438
+ }
439
+
440
+ /** How far an adjustment clip is faded in at `local`: its enter and exit lengths ramp the grade. */
441
+ function adjustmentStrength(clip: AdjustmentClip, local: number) {
442
+ let strength = clip.opacity ?? 1;
443
+ if (clip.enter?.frames) strength *= Math.min(1, (local + 1) / clip.enter.frames);
444
+ if (clip.exit?.frames) strength *= Math.min(1, (clip.duration - local) / clip.exit.frames);
445
+ return strength;
446
+ }
447
+
448
+ /**
449
+ * What draws a clip's colour: its own grade, then the adjustment layers above it and the project
450
+ * grade. A lone clip grade using only the original controls stays a CSS filter, so existing projects
451
+ * render exactly as they did.
452
+ */
453
+ function useClipGrade(clip: VideoClip | ImageClip, ctx: TrackContext, inherits: boolean) {
454
+ const local = useCurrentFrame();
455
+ const frame = local + clip.from;
456
+ const { isRendering } = useRemotionEnvironment();
457
+ const liveIds = inherits ? [...ctx.adjustments.map((layer) => layer.clip.id), LIVE_PROJECT] : [];
458
+ useLiveClipsEngine?.(liveIds, isRendering);
459
+ const liveGrade = (id: string, saved: ColorGrade | undefined) => {
460
+ const fields = isRendering ? undefined : liveEdits.getLiveClip?.(id);
461
+ return fields && "grade" in fields ? (fields.grade as ColorGrade | undefined) : saved;
462
+ };
463
+ const grades: GradeEntry[] = [];
464
+ if (clip.grade) grades.push({ grade: clip.grade, frame: local });
465
+ const inherited: GradeEntry[] = [];
466
+ if (inherits) {
467
+ for (const layer of ctx.adjustments) {
468
+ if (layer.order <= ctx.order) continue;
469
+ const at = frame - layer.clip.from;
470
+ if (at < 0 || at >= layer.clip.duration) continue;
471
+ const grade = liveGrade(layer.clip.id, layer.clip.grade);
472
+ if (grade) inherited.push({ grade, frame: at, strength: adjustmentStrength(layer.clip, at) });
473
+ }
474
+ const projectGrade = liveGrade(LIVE_PROJECT, ctx.project.grade);
475
+ if (projectGrade) inherited.push({ grade: projectGrade, frame });
476
+ }
477
+ const paths = [...new Set([...grades, ...inherited].flatMap((entry) => gradeEngine.gradeLutPaths?.(entry.grade) ?? []))];
478
+ const luts = useGradeLuts(paths);
479
+ const useCss =
480
+ !gradeEngine.gradeEffects ||
481
+ !gradeEngine.canDrawGrade?.() ||
482
+ (inherited.length === 0 && (grades.length === 0 || gradeEngine.isCssGrade?.(grades[0].grade)));
483
+ if (useCss) return { filter: gradeFilter(clip.grade), effects: [] as EffectDescriptor<unknown>[] };
484
+ return {
485
+ filter: undefined,
486
+ effects: gradeEngine.gradeEffects!([...grades, ...inherited], { seed: frame, luts: luts as ReadonlyMap<string, unknown> }),
487
+ };
488
+ }
489
+
338
490
  /** CSS filter for a color grade (supported by the browser export). */
339
491
  function gradeFilter(grade: VideoClip["grade"]): string | undefined {
340
492
  if (!grade) return undefined;
@@ -349,8 +501,68 @@ function gradeFilter(grade: VideoClip["grade"]): string | undefined {
349
501
  return parts.length ? parts.join(" ") : undefined;
350
502
  }
351
503
 
504
+ // Frames this preview drew while paused, small and already graded. Coming back to one during a drag
505
+ // (the usual back-and-forth when looking for a cut) puts it on screen at once, over the player, until
506
+ // the decoder has redrawn it. Preview only; a wrong guess lasts only until that redraw.
507
+ const HELD_FRAME_WIDTH = 960;
508
+ /** About 200 MB at 16:9, across every clip. */
509
+ const MAX_HELD_FRAMES = 96;
510
+ const heldFrames = new Map<string, ImageBitmap>();
511
+
512
+ function holdFrame(key: string, frame: ImageBitmap) {
513
+ heldFrames.get(key)?.close();
514
+ heldFrames.delete(key);
515
+ heldFrames.set(key, frame);
516
+ if (heldFrames.size > MAX_HELD_FRAMES) {
517
+ const oldest = heldFrames.keys().next().value!;
518
+ heldFrames.get(oldest)?.close();
519
+ heldFrames.delete(oldest);
520
+ }
521
+ }
522
+
523
+ function useHeldFrames(version: string, frame: number, enabled: boolean) {
524
+ const boxRef = useRef<HTMLDivElement>(null);
525
+ const overlayRef = useRef<HTMLCanvasElement>(null);
526
+ const latest = useRef({ version, frame, enabled });
527
+ /** The frame the decoder's picture shows: nothing needs to cover it. */
528
+ const drawn = useRef<number | null>(null);
529
+ useLayoutEffect(() => {
530
+ latest.current = { version, frame, enabled };
531
+ const overlay = overlayRef.current;
532
+ if (!overlay) return;
533
+ if (!enabled || drawn.current === frame) {
534
+ overlay.style.visibility = "hidden";
535
+ return;
536
+ }
537
+ const picture = heldFrames.get(`${version}:${frame}`);
538
+ if (!picture) return;
539
+ if (overlay.width !== picture.width) overlay.width = picture.width;
540
+ if (overlay.height !== picture.height) overlay.height = picture.height;
541
+ overlay.getContext("2d")?.drawImage(picture, 0, 0);
542
+ overlay.style.visibility = "visible";
543
+ }, [version, frame, enabled]);
544
+ const onDrawn = useCallback(() => {
545
+ const now = latest.current;
546
+ drawn.current = now.frame;
547
+ const overlay = overlayRef.current;
548
+ if (overlay) overlay.style.visibility = "hidden";
549
+ if (!now.enabled) return;
550
+ // The player's own canvas, which has the grade on it (the callback's frame doesn't yet).
551
+ const canvas = boxRef.current?.querySelector<HTMLCanvasElement>("canvas");
552
+ if (!canvas || canvas === overlay || !canvas.width || !canvas.height) return;
553
+ const width = Math.min(HELD_FRAME_WIDTH, canvas.width);
554
+ const key = `${now.version}:${now.frame}`;
555
+ void createImageBitmap(canvas, {
556
+ resizeWidth: width,
557
+ resizeHeight: Math.max(1, Math.round((canvas.height * width) / canvas.width)),
558
+ resizeQuality: "low",
559
+ }).then((picture) => holdFrame(key, picture), () => undefined);
560
+ }, []);
561
+ return { boxRef, overlayRef, onDrawn };
562
+ }
563
+
352
564
  function VideoClipView({
353
- clip,
565
+ clip: saved,
354
566
  trackMuted,
355
567
  gain,
356
568
  ctx,
@@ -358,10 +570,20 @@ function VideoClipView({
358
570
  clip: VideoClip;
359
571
  trackMuted: boolean;
360
572
  gain: number;
361
- ctx: StudioRuntimeContextValue;
573
+ ctx: TrackContext;
362
574
  }) {
575
+ const clip = useLive(saved);
363
576
  const style = useClipStyle(clip);
364
577
  const frame = useCurrentFrame();
578
+ const grade = useClipGrade(clip, ctx, clip.inheritGrade !== false);
579
+ const { isRendering } = useRemotionEnvironment();
580
+ const playing = Internals.Timeline.usePlaying();
581
+ const source = (!isRendering && ctx.previewProxies?.[clip.src]) || asset(clip.src);
582
+ const held = useHeldFrames(
583
+ `${clip.id}|${source}|${clip.trimStart ?? 0}|${clip.playbackRate ?? 1}|${clip.fit ?? ""}|${grade.filter ?? ""}|${JSON.stringify(clip.grade ?? null)}|${JSON.stringify(ctx.project.grade ?? null)}|${ctx.adjustments.length}`,
584
+ frame,
585
+ !isRendering && !playing,
586
+ );
365
587
  // The project style's camera (punch-ins, drift, …) moves the footage inside its box.
366
588
  const crop = clip.framing ? framingCropAt(clip.framing, (clip.trimStart ?? 0) / ctx.project.fps + frame / ctx.project.fps * (clip.playbackRate ?? 1)) : null;
367
589
  const camera =
@@ -371,21 +593,29 @@ function VideoClipView({
371
593
  return (
372
594
  <div style={{ ...boxStyle(clip.box), ...style, overflow: "hidden", borderRadius: clip.radius }}>
373
595
  <div style={{ position: "absolute", inset: 0, ...(clip.framing ? { filter: camera?.filter } : camera) }}>
374
- <div style={crop ? {
596
+ <div ref={held.boxRef} style={crop ? {
375
597
  position: "absolute", left: `${-crop.x / crop.width * 100}%`,
376
598
  top: `${-crop.y / crop.height * 100}%`,
377
599
  width: `${100 / crop.width}%`, height: `${100 / crop.height}%`,
378
600
  } : { position: "absolute", inset: 0 }}>
379
601
  <Video
380
- src={asset(clip.src)}
602
+ src={source}
381
603
  trimBefore={clip.trimStart && clip.trimStart > 0 ? clip.trimStart : undefined}
382
604
  volume={(clip.volume ?? 1) * gain}
383
605
  muted={trackMuted || clip.muted}
384
606
  playbackRate={clip.playbackRate}
385
607
  // @remotion/media draws the frame itself: fit has to be its prop (CSS object-fit is ignored).
386
608
  objectFit={clip.framing ? "fill" : clip.fit ?? "cover"}
387
- style={{ width: "100%", height: "100%", filter: gradeFilter(clip.grade) }}
609
+ style={{ width: "100%", height: "100%", filter: grade.filter }}
610
+ {...(grade.effects.length ? { effects: grade.effects } : {})}
611
+ {...(isRendering ? {} : { onVideoFrame: held.onDrawn })}
388
612
  />
613
+ {isRendering ? null : (
614
+ <canvas
615
+ ref={held.overlayRef}
616
+ style={{ position: "absolute", inset: 0, width: "100%", height: "100%", filter: grade.filter, visibility: "hidden" }}
617
+ />
618
+ )}
389
619
  {clip.cursor ? <CursorOverlay cursor={clip.cursor} clip={clip} /> : null}
390
620
  </div>
391
621
  </div>
@@ -613,7 +843,8 @@ function CursorOverlay({ cursor, clip }: { cursor: VideoCursor; clip: VideoClip
613
843
  );
614
844
  }
615
845
 
616
- function TextClipView({ clip, ctx }: { clip: TextClip; ctx: StudioRuntimeContextValue }) {
846
+ function TextClipView({ clip: saved, ctx }: { clip: TextClip; ctx: StudioRuntimeContextValue }) {
847
+ const clip = useLive(saved);
617
848
  const style = useClipStyle(clip);
618
849
  const s = { ...projectStyle(ctx.project.style)?.text, ...clip.style };
619
850
  const align = s.align ?? "center";
@@ -648,7 +879,8 @@ function TextClipView({ clip, ctx }: { clip: TextClip; ctx: StudioRuntimeContext
648
879
  );
649
880
  }
650
881
 
651
- function CaptionsClipView({ clip, ctx }: { clip: CaptionsClip; ctx: StudioRuntimeContextValue }) {
882
+ function CaptionsClipView({ clip: saved, ctx }: { clip: CaptionsClip; ctx: StudioRuntimeContextValue }) {
883
+ const clip = useLive(saved);
652
884
  const StyledCaptions = styleLayer.StyledCaptions;
653
885
  if (ctx.project.style && !clip.style?.preset && StyledCaptions && projectStyle(ctx.project.style)) {
654
886
  return (
@@ -750,7 +982,8 @@ function PlainCaptionsClipView({ clip, ctx }: { clip: CaptionsClip; ctx: StudioR
750
982
  );
751
983
  }
752
984
 
753
- function AudioClipView({ clip, trackMuted, gain }: { clip: AudioClip; trackMuted: boolean; gain: number }) {
985
+ function AudioClipView({ clip: saved, trackMuted, gain }: { clip: AudioClip; trackMuted: boolean; gain: number }) {
986
+ const clip = useLive(saved);
754
987
  const base = (clip.volume ?? 1) * gain;
755
988
  const fadeIn = Math.max(0, clip.fadeIn ?? 0);
756
989
  const fadeOut = Math.max(0, clip.fadeOut ?? 0);
@@ -787,15 +1020,20 @@ function TrackView({
787
1020
  scenes,
788
1021
  ctx,
789
1022
  masterGain,
1023
+ order,
790
1024
  }: {
791
1025
  track: StudioTrack;
792
1026
  scenes: SceneRegistry;
793
- ctx: StudioRuntimeContextValue;
1027
+ ctx: Omit<TrackContext, "order">;
794
1028
  masterGain: number;
1029
+ order: number;
795
1030
  }) {
796
1031
  const visual = track.kind !== "audio";
797
1032
  const { isRendering } = useRemotionEnvironment();
1033
+ const trackCtx = useMemo<TrackContext>(() => ({ ...ctx, order }), [ctx, order]);
798
1034
  if (visual && track.hidden) return null;
1035
+ // Adjustment layers draw nothing themselves: the clips below them read them (useClipGrade).
1036
+ if (track.kind === "adjustment") return null;
799
1037
  const gain = (track.volume ?? 1) * masterGain;
800
1038
  const trackMuted = Boolean(track.muted);
801
1039
  return (
@@ -806,19 +1044,19 @@ function TrackView({
806
1044
  let body: ReactNode = null;
807
1045
  switch (track.kind) {
808
1046
  case "scene":
809
- body = <SceneClipView clip={clip as SceneClip} scenes={scenes} ctx={ctx} />;
1047
+ body = <SceneClipView clip={clip as SceneClip} scenes={scenes} ctx={trackCtx} />;
810
1048
  break;
811
1049
  case "image":
812
- body = <ImageClipView clip={clip as ImageClip} />;
1050
+ body = <ImageClipView clip={clip as ImageClip} ctx={trackCtx} />;
813
1051
  break;
814
1052
  case "video":
815
- body = <VideoClipView clip={clip as VideoClip} trackMuted={trackMuted} gain={gain} ctx={ctx} />;
1053
+ body = <VideoClipView clip={clip as VideoClip} trackMuted={trackMuted} gain={gain} ctx={trackCtx} />;
816
1054
  break;
817
1055
  case "text":
818
- body = <TextClipView clip={clip as TextClip} ctx={ctx} />;
1056
+ body = <TextClipView clip={clip as TextClip} ctx={trackCtx} />;
819
1057
  break;
820
1058
  case "captions":
821
- body = <CaptionsClipView clip={clip as CaptionsClip} ctx={ctx} />;
1059
+ body = <CaptionsClipView clip={clip as CaptionsClip} ctx={trackCtx} />;
822
1060
  break;
823
1061
  case "audio":
824
1062
  body = <AudioClipView clip={clip as AudioClip} trackMuted={trackMuted} gain={gain} />;
@@ -887,7 +1125,7 @@ function useStyleIsolation() {
887
1125
 
888
1126
  export function createStudioComposition(scenes: SceneRegistry) {
889
1127
  function StudioComposition(props: StudioCompositionProps) {
890
- const { project, layers, variant, assetBase, libraryBase } = props;
1128
+ const { project, layers, variant, assetBase, libraryBase, previewProxies } = props;
891
1129
  const size = project.variants[variant] ?? project.variants[project.defaultVariant] ?? {
892
1130
  width: 1920,
893
1131
  height: 1080,
@@ -904,11 +1142,23 @@ export function createStudioComposition(scenes: SceneRegistry) {
904
1142
  fps: project.fps,
905
1143
  assetBase,
906
1144
  libraryBase,
1145
+ previewProxies,
907
1146
  }),
908
- [project, variant, size.width, size.height, assetBase, libraryBase],
1147
+ [project, variant, size.width, size.height, assetBase, libraryBase, previewProxies],
909
1148
  );
910
1149
  const masterGain = props.masterGain ?? 1;
911
1150
  const ordered = [...layers.tracks].reverse();
1151
+ const adjustments = useMemo(
1152
+ () =>
1153
+ ordered.flatMap((track, order) =>
1154
+ track.kind === "adjustment" && !track.hidden
1155
+ ? (track.clips as AdjustmentClip[]).map((clip) => ({ clip: resolveClip(clip, variant) as AdjustmentClip, order }))
1156
+ : [],
1157
+ ),
1158
+ // eslint-disable-next-line react-hooks/exhaustive-deps -- `ordered` is rebuilt from layers each render
1159
+ [layers, variant],
1160
+ );
1161
+ const stackCtx = useMemo(() => ({ ...ctx, adjustments }), [ctx, adjustments]);
912
1162
  return (
913
1163
  <StudioRuntimeContext.Provider value={ctx}>
914
1164
  <AbsoluteFill
@@ -924,7 +1174,7 @@ export function createStudioComposition(scenes: SceneRegistry) {
924
1174
  >
925
1175
  {project.style && projectStyle(project.style) ? <StyleFonts /> : null}
926
1176
  {ordered.map((track, index) => (
927
- <TrackView key={`${track.id}:${index}`} track={track} scenes={scenes} ctx={ctx} masterGain={masterGain} />
1177
+ <TrackView key={`${track.id}:${index}`} track={track} scenes={scenes} ctx={stackCtx} masterGain={masterGain} order={index} />
928
1178
  ))}
929
1179
  {project.style && styleLayer.StyleOverlay ? <styleLayer.StyleOverlay styleId={project.style} /> : null}
930
1180
  </AbsoluteFill>
@@ -13,6 +13,8 @@ export interface StudioRuntimeContextValue {
13
13
  fps: number;
14
14
  assetBase: string;
15
15
  libraryBase: string;
16
+ /** Fast-seeking copies of footage, project path → URL (live preview only). */
17
+ previewProxies?: Record<string, string>;
16
18
  }
17
19
 
18
20
  const runtimeState: { fps: number; assetBase: string; libraryBase: string } = {
@@ -1,7 +1,7 @@
1
1
  // Agentcut project format (v1).
2
2
  // Keep in sync with lib/studio/types.ts (repo root) and src/studio/schema.ts.
3
3
 
4
- export type TrackKind = "scene" | "video" | "image" | "text" | "captions" | "audio";
4
+ export type TrackKind = "scene" | "video" | "image" | "text" | "captions" | "audio" | "adjustment";
5
5
 
6
6
  export interface StudioProject {
7
7
  version: 1;
@@ -15,6 +15,8 @@ export interface StudioProject {
15
15
  fonts: StudioFont[];
16
16
  /** Look for the whole video (components/styles.ts): components, captions and text follow it. */
17
17
  style?: string;
18
+ /** A grade over all footage, after each clip's own grade and any adjustment layers. */
19
+ grade?: ColorGrade;
18
20
  }
19
21
 
20
22
  export type StudioFont = string | { family: string; src: string; weight?: string; style?: "normal" | "italic" };
@@ -84,13 +86,59 @@ export interface SceneClipFields {
84
86
  props?: Record<string, unknown>;
85
87
  }
86
88
 
87
- /** Color grade for footage. 1 = unchanged; warmth -1 (cool) … 1 (warm); hue in degrees. */
88
- export interface ColorGrade {
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 {
89
96
  brightness?: number;
90
97
  contrast?: number;
91
98
  saturation?: number;
99
+ /** -1 (cool) … 1 (warm). */
92
100
  warmth?: number;
101
+ /** Degrees. */
93
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[];
94
142
  }
95
143
 
96
144
  export interface FramingKeyframe { seconds: number; crop: Box }
@@ -99,6 +147,8 @@ export interface VideoClipFields {
99
147
  src: string;
100
148
  trimStart?: number;
101
149
  grade?: ColorGrade;
150
+ /** false keeps the project grade and adjustment layers off this clip (default true). */
151
+ inheritGrade?: boolean;
102
152
  volume?: number;
103
153
  muted?: boolean;
104
154
  fit?: "cover" | "contain";
@@ -144,6 +194,9 @@ export interface CursorTrack {
144
194
 
145
195
  export interface ImageClipFields {
146
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;
147
200
  fit?: "cover" | "contain";
148
201
  box?: Box;
149
202
  radius?: number;
@@ -181,12 +234,18 @@ type WithVariants<T> = T & {
181
234
  variants?: Record<string, Partial<Omit<T, "id">>>;
182
235
  };
183
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
+
184
242
  export type SceneClip = WithVariants<BaseClipFields & SceneClipFields>;
185
243
  export type VideoClip = WithVariants<BaseClipFields & VideoClipFields>;
186
244
  export type ImageClip = WithVariants<BaseClipFields & ImageClipFields>;
187
245
  export type TextClip = WithVariants<BaseClipFields & TextClipFields>;
188
246
  export type CaptionsClip = WithVariants<BaseClipFields & CaptionsClipFields>;
189
247
  export type AudioClip = WithVariants<BaseClipFields & AudioClipFields>;
248
+ export type AdjustmentClip = WithVariants<BaseClipFields & AdjustmentClipFields>;
190
249
 
191
250
  export type StudioClip =
192
251
  | SceneClip
@@ -194,7 +253,8 @@ export type StudioClip =
194
253
  | ImageClip
195
254
  | TextClip
196
255
  | CaptionsClip
197
- | AudioClip;
256
+ | AudioClip
257
+ | AdjustmentClip;
198
258
 
199
259
  export interface ClipByKind {
200
260
  scene: SceneClip;
@@ -203,6 +263,7 @@ export interface ClipByKind {
203
263
  text: TextClip;
204
264
  captions: CaptionsClip;
205
265
  audio: AudioClip;
266
+ adjustment: AdjustmentClip;
206
267
  }
207
268
 
208
269
  export interface StudioTrack<K extends TrackKind = TrackKind> {
@@ -240,6 +301,8 @@ export interface StudioCompositionProps extends Record<string, unknown> {
240
301
  libraryBase: string;
241
302
  /** Linear gain applied to every audio clip (export loudness normalization). */
242
303
  masterGain?: number;
304
+ /** Fast-seeking copies of footage, project path → URL. Only the live preview passes these. */
305
+ previewProxies?: Record<string, string>;
243
306
  }
244
307
 
245
308
  /** Props every scene component receives (plus the clip's own `props`). */