agentcut 0.2.15 → 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 (152) 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 +13 -10
  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 +13 -2
  22. package/dist/studio/host.js +140 -9
  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/providers/http.d.ts +4 -0
  38. package/dist/studio/providers/http.js +23 -0
  39. package/dist/studio/providers/http.js.map +1 -0
  40. package/dist/studio/providers/settings.d.ts +20 -0
  41. package/dist/studio/providers/settings.js +84 -0
  42. package/dist/studio/providers/settings.js.map +1 -0
  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 +23535 -1480
  71. package/dist/studio/schema.js +71 -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 +113 -8
  78. package/dist/studio/tools.js.map +1 -1
  79. package/dist/studio/transcription/assemblyai.d.ts +11 -0
  80. package/dist/studio/transcription/assemblyai.js +123 -0
  81. package/dist/studio/transcription/assemblyai.js.map +1 -0
  82. package/dist/studio/transcription/local.d.ts +2 -0
  83. package/dist/studio/transcription/local.js +57 -0
  84. package/dist/studio/transcription/local.js.map +1 -0
  85. package/dist/studio/transcription/registry.d.ts +3 -0
  86. package/dist/studio/transcription/registry.js +5 -0
  87. package/dist/studio/transcription/registry.js.map +1 -0
  88. package/dist/studio/transcription/service.d.ts +130 -0
  89. package/dist/studio/transcription/service.js +236 -0
  90. package/dist/studio/transcription/service.js.map +1 -0
  91. package/dist/studio/transcription/types.d.ts +68 -0
  92. package/dist/studio/transcription/types.js +2 -0
  93. package/dist/studio/transcription/types.js.map +1 -0
  94. package/dist/studio/voice/audio.d.ts +1 -0
  95. package/dist/studio/voice/audio.js +18 -0
  96. package/dist/studio/voice/audio.js.map +1 -0
  97. package/dist/studio/voice/elevenlabs.d.ts +2 -0
  98. package/dist/studio/voice/elevenlabs.js +76 -0
  99. package/dist/studio/voice/elevenlabs.js.map +1 -0
  100. package/dist/studio/voice/gemini.d.ts +2 -0
  101. package/dist/studio/voice/gemini.js +95 -0
  102. package/dist/studio/voice/gemini.js.map +1 -0
  103. package/dist/studio/voice/openai.d.ts +2 -0
  104. package/dist/studio/voice/openai.js +75 -0
  105. package/dist/studio/voice/openai.js.map +1 -0
  106. package/dist/studio/voice/registry.d.ts +4 -0
  107. package/dist/studio/voice/registry.js +18 -0
  108. package/dist/studio/voice/registry.js.map +1 -0
  109. package/dist/studio/voice/types.d.ts +42 -0
  110. package/dist/studio/voice/types.js +2 -0
  111. package/dist/studio/voice/types.js.map +1 -0
  112. package/dist/studio/voice/xai.d.ts +2 -0
  113. package/dist/studio/voice/xai.js +80 -0
  114. package/dist/studio/voice/xai.js.map +1 -0
  115. package/dist/studio/voice.d.ts +32 -58
  116. package/dist/studio/voice.js +52 -308
  117. package/dist/studio/voice.js.map +1 -1
  118. package/dist/studio/workspace.d.ts +1 -0
  119. package/dist/studio/workspace.js +1 -0
  120. package/dist/studio/workspace.js.map +1 -1
  121. package/package.json +2 -1
  122. package/template/AGENTS.md +1 -0
  123. package/template/components/CATALOG.md +2 -0
  124. package/template/components/STYLES.md +108 -7
  125. package/template/components/catalog.json +29 -0
  126. package/template/components/color/grade-effect.ts +650 -0
  127. package/template/components/color/grade.ts +512 -0
  128. package/template/components/color/looks.ts +154 -0
  129. package/template/components/hook-card/HookCard.tsx +11 -5
  130. package/template/components/hook-card/meta.json +29 -0
  131. package/template/components/index.ts +14 -0
  132. package/template/components/live-clip.ts +75 -0
  133. package/template/components/sticker-badge/StickerBadge.tsx +4 -2
  134. package/template/components/styles.json +354 -3
  135. package/template/runtime/composition.tsx +283 -25
  136. package/template/runtime/framing.ts +29 -0
  137. package/template/runtime/helpers.tsx +2 -0
  138. package/template/runtime/types.ts +71 -4
  139. package/template/skill/SKILL.md +132 -6
  140. package/template/skill/references/broll.md +2 -1
  141. package/template/skill/references/color.md +79 -0
  142. package/template/skill/references/editing-styles.md +57 -0
  143. package/template/skill/references/footage.md +72 -73
  144. package/template/skill/references/format.md +142 -140
  145. package/template/skill/references/performance.md +14 -2
  146. package/template/skill/references/person-cutout.md +19 -0
  147. package/template/skill/references/person-framing.md +13 -0
  148. package/template/skill/references/presets.md +60 -56
  149. package/template/skill/references/sound.md +151 -151
  150. package/template/skill/references/style-editing.md +20 -0
  151. package/template/skill/references/transcription.md +15 -0
  152. package/template/skill/references/website-howto.md +41 -0
@@ -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,8 @@ import {
14
15
  useVideoConfig,
15
16
  } from "remotion";
16
17
  import { Audio, Video } from "@remotion/media";
18
+ import type { EffectDescriptor } from "remotion";
19
+ import { framingCropAt } from "./framing";
17
20
  // The Agentcut component library, provided by the studio page (and by a copy in
18
21
  // .agentcut/components for local renders).
19
22
  import * as ComponentLibrary from "agentcut/components";
@@ -58,9 +61,11 @@ import {
58
61
  } from "./helpers";
59
62
  import type {
60
63
  AudioClip,
64
+ AdjustmentClip,
61
65
  Box,
62
66
  CaptionsClip,
63
67
  ClipAnim,
68
+ ColorGrade,
64
69
  ImageClip,
65
70
  SceneClip,
66
71
  SceneProps,
@@ -250,7 +255,7 @@ function boxStyle(box: Box | undefined): CSSProperties {
250
255
  // Clip renderers (all frames local to the clip's <Sequence>)
251
256
 
252
257
  function SceneClipView({
253
- clip,
258
+ clip: saved,
254
259
  scenes,
255
260
  ctx,
256
261
  }: {
@@ -258,6 +263,7 @@ function SceneClipView({
258
263
  scenes: SceneRegistry;
259
264
  ctx: StudioRuntimeContextValue;
260
265
  }) {
266
+ const clip = useLive(saved);
261
267
  const style = useClipStyle(clip);
262
268
  if (clip.component) {
263
269
  const entry = MOTION_COMPONENTS[clip.component];
@@ -322,18 +328,165 @@ function SceneClipView({
322
328
  );
323
329
  }
324
330
 
325
- function ImageClipView({ clip }: { clip: ImageClip }) {
331
+ function ImageClipView({ clip: saved, ctx }: { clip: ImageClip; ctx: TrackContext }) {
332
+ const clip = useLive(saved);
326
333
  const style = useClipStyle(clip);
334
+ const { filter, effects } = useClipGrade(clip, ctx, clip.inheritGrade === true);
327
335
  return (
328
336
  <div style={{ ...boxStyle(clip.box), ...style, overflow: "hidden", borderRadius: clip.radius }}>
329
- <Img
330
- src={asset(clip.src)}
331
- style={{ width: "100%", height: "100%", objectFit: clip.fit ?? "cover", display: "block" }}
332
- />
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
+ )}
333
352
  </div>
334
353
  );
335
354
  }
336
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
+
337
490
  /** CSS filter for a color grade (supported by the browser export). */
338
491
  function gradeFilter(grade: VideoClip["grade"]): string | undefined {
339
492
  if (!grade) return undefined;
@@ -348,8 +501,68 @@ function gradeFilter(grade: VideoClip["grade"]): string | undefined {
348
501
  return parts.length ? parts.join(" ") : undefined;
349
502
  }
350
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
+
351
564
  function VideoClipView({
352
- clip,
565
+ clip: saved,
353
566
  trackMuted,
354
567
  gain,
355
568
  ctx,
@@ -357,30 +570,55 @@ function VideoClipView({
357
570
  clip: VideoClip;
358
571
  trackMuted: boolean;
359
572
  gain: number;
360
- ctx: StudioRuntimeContextValue;
573
+ ctx: TrackContext;
361
574
  }) {
575
+ const clip = useLive(saved);
362
576
  const style = useClipStyle(clip);
363
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
+ );
364
587
  // The project style's camera (punch-ins, drift, …) moves the footage inside its box.
588
+ const crop = clip.framing ? framingCropAt(clip.framing, (clip.trimStart ?? 0) / ctx.project.fps + frame / ctx.project.fps * (clip.playbackRate ?? 1)) : null;
365
589
  const camera =
366
590
  ctx.project.style && clip.camera !== "none" && styleLayer.styleCamera
367
591
  ? styleLayer.styleCamera(ctx.project.style, { frame, durationInFrames: clip.duration, width: ctx.width, height: ctx.height })
368
592
  : null;
369
593
  return (
370
594
  <div style={{ ...boxStyle(clip.box), ...style, overflow: "hidden", borderRadius: clip.radius }}>
371
- <div style={{ position: "absolute", inset: 0, ...camera }}>
595
+ <div style={{ position: "absolute", inset: 0, ...(clip.framing ? { filter: camera?.filter } : camera) }}>
596
+ <div ref={held.boxRef} style={crop ? {
597
+ position: "absolute", left: `${-crop.x / crop.width * 100}%`,
598
+ top: `${-crop.y / crop.height * 100}%`,
599
+ width: `${100 / crop.width}%`, height: `${100 / crop.height}%`,
600
+ } : { position: "absolute", inset: 0 }}>
372
601
  <Video
373
- src={asset(clip.src)}
602
+ src={source}
374
603
  trimBefore={clip.trimStart && clip.trimStart > 0 ? clip.trimStart : undefined}
375
604
  volume={(clip.volume ?? 1) * gain}
376
605
  muted={trackMuted || clip.muted}
377
606
  playbackRate={clip.playbackRate}
378
607
  // @remotion/media draws the frame itself: fit has to be its prop (CSS object-fit is ignored).
379
- objectFit={clip.fit ?? "cover"}
380
- style={{ width: "100%", height: "100%", filter: gradeFilter(clip.grade) }}
608
+ objectFit={clip.framing ? "fill" : clip.fit ?? "cover"}
609
+ style={{ width: "100%", height: "100%", filter: grade.filter }}
610
+ {...(grade.effects.length ? { effects: grade.effects } : {})}
611
+ {...(isRendering ? {} : { onVideoFrame: held.onDrawn })}
381
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
+ )}
382
619
  {clip.cursor ? <CursorOverlay cursor={clip.cursor} clip={clip} /> : null}
383
620
  </div>
621
+ </div>
384
622
  </div>
385
623
  );
386
624
  }
@@ -605,7 +843,8 @@ function CursorOverlay({ cursor, clip }: { cursor: VideoCursor; clip: VideoClip
605
843
  );
606
844
  }
607
845
 
608
- function TextClipView({ clip, ctx }: { clip: TextClip; ctx: StudioRuntimeContextValue }) {
846
+ function TextClipView({ clip: saved, ctx }: { clip: TextClip; ctx: StudioRuntimeContextValue }) {
847
+ const clip = useLive(saved);
609
848
  const style = useClipStyle(clip);
610
849
  const s = { ...projectStyle(ctx.project.style)?.text, ...clip.style };
611
850
  const align = s.align ?? "center";
@@ -640,7 +879,8 @@ function TextClipView({ clip, ctx }: { clip: TextClip; ctx: StudioRuntimeContext
640
879
  );
641
880
  }
642
881
 
643
- function CaptionsClipView({ clip, ctx }: { clip: CaptionsClip; ctx: StudioRuntimeContextValue }) {
882
+ function CaptionsClipView({ clip: saved, ctx }: { clip: CaptionsClip; ctx: StudioRuntimeContextValue }) {
883
+ const clip = useLive(saved);
644
884
  const StyledCaptions = styleLayer.StyledCaptions;
645
885
  if (ctx.project.style && !clip.style?.preset && StyledCaptions && projectStyle(ctx.project.style)) {
646
886
  return (
@@ -742,7 +982,8 @@ function PlainCaptionsClipView({ clip, ctx }: { clip: CaptionsClip; ctx: StudioR
742
982
  );
743
983
  }
744
984
 
745
- 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);
746
987
  const base = (clip.volume ?? 1) * gain;
747
988
  const fadeIn = Math.max(0, clip.fadeIn ?? 0);
748
989
  const fadeOut = Math.max(0, clip.fadeOut ?? 0);
@@ -779,15 +1020,20 @@ function TrackView({
779
1020
  scenes,
780
1021
  ctx,
781
1022
  masterGain,
1023
+ order,
782
1024
  }: {
783
1025
  track: StudioTrack;
784
1026
  scenes: SceneRegistry;
785
- ctx: StudioRuntimeContextValue;
1027
+ ctx: Omit<TrackContext, "order">;
786
1028
  masterGain: number;
1029
+ order: number;
787
1030
  }) {
788
1031
  const visual = track.kind !== "audio";
789
1032
  const { isRendering } = useRemotionEnvironment();
1033
+ const trackCtx = useMemo<TrackContext>(() => ({ ...ctx, order }), [ctx, order]);
790
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;
791
1037
  const gain = (track.volume ?? 1) * masterGain;
792
1038
  const trackMuted = Boolean(track.muted);
793
1039
  return (
@@ -798,19 +1044,19 @@ function TrackView({
798
1044
  let body: ReactNode = null;
799
1045
  switch (track.kind) {
800
1046
  case "scene":
801
- body = <SceneClipView clip={clip as SceneClip} scenes={scenes} ctx={ctx} />;
1047
+ body = <SceneClipView clip={clip as SceneClip} scenes={scenes} ctx={trackCtx} />;
802
1048
  break;
803
1049
  case "image":
804
- body = <ImageClipView clip={clip as ImageClip} />;
1050
+ body = <ImageClipView clip={clip as ImageClip} ctx={trackCtx} />;
805
1051
  break;
806
1052
  case "video":
807
- 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} />;
808
1054
  break;
809
1055
  case "text":
810
- body = <TextClipView clip={clip as TextClip} ctx={ctx} />;
1056
+ body = <TextClipView clip={clip as TextClip} ctx={trackCtx} />;
811
1057
  break;
812
1058
  case "captions":
813
- body = <CaptionsClipView clip={clip as CaptionsClip} ctx={ctx} />;
1059
+ body = <CaptionsClipView clip={clip as CaptionsClip} ctx={trackCtx} />;
814
1060
  break;
815
1061
  case "audio":
816
1062
  body = <AudioClipView clip={clip as AudioClip} trackMuted={trackMuted} gain={gain} />;
@@ -879,7 +1125,7 @@ function useStyleIsolation() {
879
1125
 
880
1126
  export function createStudioComposition(scenes: SceneRegistry) {
881
1127
  function StudioComposition(props: StudioCompositionProps) {
882
- const { project, layers, variant, assetBase, libraryBase } = props;
1128
+ const { project, layers, variant, assetBase, libraryBase, previewProxies } = props;
883
1129
  const size = project.variants[variant] ?? project.variants[project.defaultVariant] ?? {
884
1130
  width: 1920,
885
1131
  height: 1080,
@@ -896,11 +1142,23 @@ export function createStudioComposition(scenes: SceneRegistry) {
896
1142
  fps: project.fps,
897
1143
  assetBase,
898
1144
  libraryBase,
1145
+ previewProxies,
899
1146
  }),
900
- [project, variant, size.width, size.height, assetBase, libraryBase],
1147
+ [project, variant, size.width, size.height, assetBase, libraryBase, previewProxies],
901
1148
  );
902
1149
  const masterGain = props.masterGain ?? 1;
903
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]);
904
1162
  return (
905
1163
  <StudioRuntimeContext.Provider value={ctx}>
906
1164
  <AbsoluteFill
@@ -916,7 +1174,7 @@ export function createStudioComposition(scenes: SceneRegistry) {
916
1174
  >
917
1175
  {project.style && projectStyle(project.style) ? <StyleFonts /> : null}
918
1176
  {ordered.map((track, index) => (
919
- <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} />
920
1178
  ))}
921
1179
  {project.style && styleLayer.StyleOverlay ? <styleLayer.StyleOverlay styleId={project.style} /> : null}
922
1180
  </AbsoluteFill>
@@ -0,0 +1,29 @@
1
+ import type { Box, FramingKeyframe } from "./types";
2
+
3
+ /** Stateless source-time interpolation: identical for seeking, preview and every export frame. */
4
+ export function framingCropAt(
5
+ framing: { crop: Box; path?: FramingKeyframe[] },
6
+ seconds: number,
7
+ ): Box {
8
+ const path = framing.path;
9
+ if (!path?.length || !Number.isFinite(seconds)) return framing.crop;
10
+ if (seconds <= path[0].seconds) return path[0].crop;
11
+ if (seconds >= path[path.length - 1].seconds)
12
+ return path[path.length - 1].crop;
13
+ let low = 0,
14
+ high = path.length - 1;
15
+ while (high - low > 1) {
16
+ const mid = (low + high) >> 1;
17
+ if (path[mid].seconds <= seconds) low = mid;
18
+ else high = mid;
19
+ }
20
+ const a = path[low],
21
+ b = path[high];
22
+ const progress = (seconds - a.seconds) / (b.seconds - a.seconds);
23
+ return {
24
+ x: a.crop.x + (b.crop.x - a.crop.x) * progress,
25
+ y: a.crop.y + (b.crop.y - a.crop.y) * progress,
26
+ width: a.crop.width + (b.crop.width - a.crop.width) * progress,
27
+ height: a.crop.height + (b.crop.height - a.crop.height) * progress,
28
+ };
29
+ }
@@ -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,19 +86,69 @@ 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
 
144
+ export interface FramingKeyframe { seconds: number; crop: Box }
145
+
96
146
  export interface VideoClipFields {
97
147
  src: string;
98
148
  trimStart?: number;
99
149
  grade?: ColorGrade;
150
+ /** false keeps the project grade and adjustment layers off this clip (default true). */
151
+ inheritGrade?: boolean;
100
152
  volume?: number;
101
153
  muted?: boolean;
102
154
  fit?: "cover" | "contain";
@@ -108,6 +160,8 @@ export interface VideoClipFields {
108
160
  cursor?: VideoCursor;
109
161
  /** "none" keeps the project style's camera moves off this clip. */
110
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[] };
111
165
  }
112
166
 
113
167
  export interface VideoCursor {
@@ -140,6 +194,9 @@ export interface CursorTrack {
140
194
 
141
195
  export interface ImageClipFields {
142
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;
143
200
  fit?: "cover" | "contain";
144
201
  box?: Box;
145
202
  radius?: number;
@@ -177,12 +234,18 @@ type WithVariants<T> = T & {
177
234
  variants?: Record<string, Partial<Omit<T, "id">>>;
178
235
  };
179
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
+
180
242
  export type SceneClip = WithVariants<BaseClipFields & SceneClipFields>;
181
243
  export type VideoClip = WithVariants<BaseClipFields & VideoClipFields>;
182
244
  export type ImageClip = WithVariants<BaseClipFields & ImageClipFields>;
183
245
  export type TextClip = WithVariants<BaseClipFields & TextClipFields>;
184
246
  export type CaptionsClip = WithVariants<BaseClipFields & CaptionsClipFields>;
185
247
  export type AudioClip = WithVariants<BaseClipFields & AudioClipFields>;
248
+ export type AdjustmentClip = WithVariants<BaseClipFields & AdjustmentClipFields>;
186
249
 
187
250
  export type StudioClip =
188
251
  | SceneClip
@@ -190,7 +253,8 @@ export type StudioClip =
190
253
  | ImageClip
191
254
  | TextClip
192
255
  | CaptionsClip
193
- | AudioClip;
256
+ | AudioClip
257
+ | AdjustmentClip;
194
258
 
195
259
  export interface ClipByKind {
196
260
  scene: SceneClip;
@@ -199,6 +263,7 @@ export interface ClipByKind {
199
263
  text: TextClip;
200
264
  captions: CaptionsClip;
201
265
  audio: AudioClip;
266
+ adjustment: AdjustmentClip;
202
267
  }
203
268
 
204
269
  export interface StudioTrack<K extends TrackKind = TrackKind> {
@@ -236,6 +301,8 @@ export interface StudioCompositionProps extends Record<string, unknown> {
236
301
  libraryBase: string;
237
302
  /** Linear gain applied to every audio clip (export loudness normalization). */
238
303
  masterGain?: number;
304
+ /** Fast-seeking copies of footage, project path → URL. Only the live preview passes these. */
305
+ previewProxies?: Record<string, string>;
239
306
  }
240
307
 
241
308
  /** Props every scene component receives (plus the clip's own `props`). */