@agimon-ai/video-editor-mcp 0.7.0 → 0.8.2

package/src/remotion/Root.tsx

@@ -0,0 +1,87 @@
+/**
+ * Remotion Root Component
+ *
+ * DESIGN PATTERNS:
+ * - Remotion root component pattern
+ * - Folder organization for composition groups
+ * - Type-safe props with Zod schema
+ *
+ * CODING STANDARDS:
+ * - Register all compositions
+ * - Use calculateMetadata for dynamic duration
+ * - Use schema prop for visual editing in Remotion Studio
+ * - Group compositions in folders
+ */
+
+import { Composition, Folder } from 'remotion';
+import { MainCompositionSchema } from '../schemas/index.js';
+import type { MainCompositionProps } from '../types/index.js';
+import { Main } from './compositions/Main';
+import { Square } from './compositions/Square';
+import { Vertical } from './compositions/Vertical';
+import { calculateMainMetadata } from './utils/calculateMainMetadata';
+
+const defaultProps: MainCompositionProps = {
+  clips: [],
+  backgroundColor: '#000',
+  fps: 30,
+  width: 1920,
+  height: 1080,
+};
+
+const verticalDefaultProps: MainCompositionProps = {
+  ...defaultProps,
+  width: 1080,
+  height: 1920,
+};
+
+const squareDefaultProps: MainCompositionProps = {
+  ...defaultProps,
+  width: 1080,
+  height: 1080,
+};
+
+export const RemotionRoot: React.FC = () => {
+  return (
+    <>
+      <Folder name="Standard">
+        <Composition
+          id="Main"
+          component={Main}
+          durationInFrames={300}
+          fps={30}
+          width={1920}
+          height={1080}
+          defaultProps={defaultProps}
+          calculateMetadata={calculateMainMetadata}
+          schema={MainCompositionSchema}
+        />
+      </Folder>
+
+      <Folder name="Social">
+        <Composition
+          id="Vertical"
+          component={Vertical}
+          durationInFrames={300}
+          fps={30}
+          width={1080}
+          height={1920}
+          defaultProps={verticalDefaultProps}
+          calculateMetadata={calculateMainMetadata}
+          schema={MainCompositionSchema}
+        />
+        <Composition
+          id="Square"
+          component={Square}
+          durationInFrames={300}
+          fps={30}
+          width={1080}
+          height={1080}
+          defaultProps={squareDefaultProps}
+          calculateMetadata={calculateMainMetadata}
+          schema={MainCompositionSchema}
+        />
+      </Folder>
+    </>
+  );
+};

package/src/remotion/compositions/Main.tsx

@@ -0,0 +1,51 @@
+/**
+ * Main Composition
+ *
+ * DESIGN PATTERNS:
+ * - Remotion composition pattern with Sequence
+ * - Type-safe props from Zod schema
+ * - Dispatcher pattern for clip rendering
+ *
+ * CODING STANDARDS:
+ * - Use ClipRenderer for type-safe rendering
+ * - Support captions overlay
+ * - Load fonts from props
+ * - Use premountFor for smoother playback
+ */
+
+import { AbsoluteFill, Sequence } from 'remotion';
+import type { MainCompositionProps } from '../../types/index.js';
+import { AudioLayer } from './audio/AudioLayer';
+import { CaptionOverlay } from './captions';
+import { ClipRenderer } from './clips';
+
+export const createClipSequenceKey = (
+  clip: NonNullable<MainCompositionProps['clips']>[number],
+  index: number,
+): string => `${index}-${clip.type}-${clip.startFrame}-${clip.durationInFrames}`;
+
+export const Main: React.FC<MainCompositionProps> = ({ clips = [], backgroundColor = '#000', captions, audio }) => {
+  // TODO: Load custom fonts - implement font loading using @remotion/google-fonts
+
+  return (
+    <AbsoluteFill style={{ backgroundColor }}>
+      {/* Render all clips */}
+      {clips.map((clip, index) => (
+        <Sequence
+          key={createClipSequenceKey(clip, index)}
+          from={clip.startFrame}
+          durationInFrames={clip.durationInFrames}
+          premountFor={clip.premountFor}
+        >
+          <ClipRenderer {...clip} />
+        </Sequence>
+      ))}
+
+      {/* Render captions overlay if provided */}
+      {captions && <CaptionOverlay {...captions} />}
+
+      {/* Render timeline-spanning audio layer (voiceover, music bed, sfx) */}
+      {audio && <AudioLayer {...audio} />}
+    </AbsoluteFill>
+  );
+};

package/src/remotion/compositions/Square.tsx

@@ -0,0 +1,18 @@
+/**
+ * Square Composition (Instagram Post format)
+ *
+ * DESIGN PATTERNS:
+ * - Wrapper composition for social media square format
+ * - Reuses Main composition with fixed dimensions
+ *
+ * CODING STANDARDS:
+ * - 1080x1080 for Instagram posts
+ * - Type-safe props from Zod schema
+ */
+
+import type { MainCompositionProps } from '../../types/index.js';
+import { Main } from './Main';
+
+export const Square: React.FC<MainCompositionProps> = (props) => {
+  return <Main {...props} />;
+};

package/src/remotion/compositions/Vertical.tsx

@@ -0,0 +1,18 @@
+/**
+ * Vertical Composition (TikTok/Reels format)
+ *
+ * DESIGN PATTERNS:
+ * - Wrapper composition for social media vertical format
+ * - Reuses Main composition with fixed dimensions
+ *
+ * CODING STANDARDS:
+ * - 1080x1920 for TikTok/Instagram Reels
+ * - Type-safe props from Zod schema
+ */
+
+import type { MainCompositionProps } from '../../types/index.js';
+import { Main } from './Main';
+
+export const Vertical: React.FC<MainCompositionProps> = (props) => {
+  return <Main {...props} />;
+};

package/src/remotion/compositions/audio/AudioLayer.tsx

@@ -0,0 +1,130 @@
+/**
+ * AudioLayer Component
+ *
+ * Renders the timeline-spanning audio layer (voiceover, music bed, point-in-time
+ * SFX). Distinct from clip-level audio: layer tracks span 0..duration without
+ * the caller computing frames, and music auto-loops over the timeline.
+ */
+
+import { Audio, Sequence, interpolate, useVideoConfig } from 'remotion';
+import type { AudioLayer as AudioLayerProps, MusicTrack, SfxEntry, VoiceoverTrack } from '../../../types/index.js';
+import { resolveRemotionAssetSrc } from '../../../utils/assetPaths';
+
+const msToFrames = (ms: number, fps: number): number => Math.max(0, Math.round((ms / 1000) * fps));
+
+const buildFadeVolume = (
+  baseVolume: number,
+  fadeInMs: number,
+  fadeOutMs: number,
+  spanFrames: number,
+  fps: number,
+): number | ((frame: number) => number) => {
+  const fadeInFrames = msToFrames(fadeInMs, fps);
+  const fadeOutFrames = msToFrames(fadeOutMs, fps);
+
+  if (fadeInFrames === 0 && fadeOutFrames === 0) {
+    return baseVolume;
+  }
+
+  return (frame: number) => {
+    const fadeInVolume =
+      fadeInFrames > 0
+        ? interpolate(frame, [0, fadeInFrames], [0, baseVolume], {
+            extrapolateLeft: 'clamp',
+            extrapolateRight: 'clamp',
+          })
+        : baseVolume;
+
+    const fadeOutVolume =
+      fadeOutFrames > 0
+        ? interpolate(frame, [spanFrames - fadeOutFrames, spanFrames], [baseVolume, 0], {
+            extrapolateLeft: 'clamp',
+            extrapolateRight: 'clamp',
+          })
+        : baseVolume;
+
+    return Math.min(fadeInVolume, fadeOutVolume);
+  };
+};
+
+const VoiceoverRenderer: React.FC<{ track: VoiceoverTrack; fps: number; durationInFrames: number }> = ({
+  track,
+  fps,
+  durationInFrames,
+}) => {
+  const startFrom = msToFrames(track.trimBeforeMs, fps);
+  const endAt = track.trimAfterMs ? msToFrames(track.trimAfterMs, fps) : undefined;
+  const volume = buildFadeVolume(track.volume, track.fadeInMs, track.fadeOutMs, durationInFrames, fps);
+
+  return (
+    <Audio
+      src={resolveRemotionAssetSrc(track.src)}
+      volume={volume}
+      playbackRate={track.playbackRate}
+      startFrom={startFrom}
+      endAt={endAt}
+    />
+  );
+};
+
+const MusicRenderer: React.FC<{ track: MusicTrack; fps: number; durationInFrames: number }> = ({
+  track,
+  fps,
+  durationInFrames,
+}) => {
+  const startFrom = msToFrames(track.trimBeforeMs, fps);
+  const endAt = track.trimAfterMs ? msToFrames(track.trimAfterMs, fps) : undefined;
+  const volume = buildFadeVolume(track.volume, track.fadeInMs, track.fadeOutMs, durationInFrames, fps);
+
+  return (
+    <Audio
+      src={resolveRemotionAssetSrc(track.src)}
+      volume={volume}
+      playbackRate={track.playbackRate}
+      loop={track.loop}
+      startFrom={startFrom}
+      endAt={endAt}
+    />
+  );
+};
+
+const SfxRenderer: React.FC<{ entry: SfxEntry; fps: number; index: number }> = ({ entry, fps, index }) => {
+  const from = msToFrames(entry.atMs, fps);
+  const startFrom = msToFrames(entry.trimBeforeMs, fps);
+  const endAt = entry.trimAfterMs ? msToFrames(entry.trimAfterMs, fps) : undefined;
+  const span = entry.durationMs ? msToFrames(entry.durationMs, fps) : undefined;
+  const volume =
+    entry.fadeInMs > 0 || entry.fadeOutMs > 0
+      ? buildFadeVolume(entry.volume, entry.fadeInMs, entry.fadeOutMs, span ?? fps * 60, fps)
+      : entry.volume;
+
+  return (
+    <Sequence key={`sfx-${index}-${from}`} from={from} durationInFrames={span}>
+      <Audio
+        src={resolveRemotionAssetSrc(entry.src)}
+        volume={volume}
+        playbackRate={entry.playbackRate}
+        startFrom={startFrom}
+        endAt={endAt}
+      />
+    </Sequence>
+  );
+};
+
+export const AudioLayer: React.FC<AudioLayerProps> = ({ voiceover, music, sfx = [] }) => {
+  const { fps, durationInFrames } = useVideoConfig();
+
+  if (!voiceover && !music && sfx.length === 0) {
+    return null;
+  }
+
+  return (
+    <>
+      {voiceover && <VoiceoverRenderer track={voiceover} fps={fps} durationInFrames={durationInFrames} />}
+      {music && <MusicRenderer track={music} fps={fps} durationInFrames={durationInFrames} />}
+      {sfx.map((entry, index) => (
+        <SfxRenderer key={`sfx-${index}-${entry.atMs}`} entry={entry} fps={fps} index={index} />
+      ))}
+    </>
+  );
+};

package/src/remotion/compositions/captions/CaptionOverlay.tsx

@@ -0,0 +1,250 @@
+/**
+ * CaptionOverlay Component
+ *
+ * DESIGN PATTERNS:
+ * - Remotion composition pattern with useCurrentFrame()
+ * - TikTok-style caption rendering
+ * - Type-safe props from Zod schema
+ *
+ * CODING STANDARDS:
+ * - NEVER use CSS animations - use useCurrentFrame()
+ * - Calculate active caption based on current frame
+ * - Support multiple caption styles (tiktok, standard, karaoke)
+ */
+
+import type { CSSProperties } from 'react';
+import { AbsoluteFill, interpolate, useCurrentFrame, useVideoConfig } from 'remotion';
+import type { Caption, CaptionConfig, CaptionPage, CaptionToken } from '../../../types/index.js';
+
+const PLATFORM_SAFE_ZONES: Record<string, { top: number; right: number; bottom: number; left: number }> = {
+  tiktok: { top: 270, right: 140, bottom: 480, left: 80 },
+  reels: { top: 220, right: 110, bottom: 420, left: 80 },
+  shorts: { top: 220, right: 100, bottom: 420, left: 80 },
+  universal: { top: 240, right: 140, bottom: 480, left: 80 },
+};
+
+export const CaptionOverlay: React.FC<CaptionConfig> = ({
+  captions,
+  pages,
+  style = 'tiktok',
+  preset = 'tiktok-bold',
+  platform = 'tiktok',
+  position = 'center',
+  fontSize = 48,
+  minFontSize = 42,
+  fontFamily = 'Arial, sans-serif',
+  fontWeight = 800,
+  lineHeight = 1.08,
+  maxWidthPct = 0.86,
+  maxCharsPerLine = 22,
+  maxLines = 2,
+  color = '#fff',
+  inactiveColor,
+  textColor,
+  highlightColor = '#ffeb3b',
+  strokeColor = '#000',
+  strokeWidth = 5,
+  shadow = true,
+  backgroundColor = 'rgba(0, 0, 0, 0.8)',
+  backgroundRadius = 8,
+  safeZone,
+}) => {
+  const frame = useCurrentFrame();
+  const { fps, width, height } = useVideoConfig();
+
+  const captionPages = pages && pages.length > 0 ? pages : legacyCaptionsToPages(captions ?? []);
+
+  if (captionPages.length === 0) {
+    return null;
+  }
+
+  // Convert frame to time in milliseconds
+  const currentTimeMs = (frame / fps) * 1000;
+
+  // Find active caption
+  const activePage = captionPages.find((caption) => currentTimeMs >= caption.startMs && currentTimeMs <= caption.endMs);
+
+  if (!activePage) {
+    return null;
+  }
+
+  const captionDurationMs = activePage.endMs - activePage.startMs;
+  const captionDuration = (captionDurationMs / 1000) * fps;
+  const captionFrame = ((currentTimeMs - activePage.startMs) / 1000) * fps;
+
+  // Fade in/out animation
+  const fadeInDuration = Math.min(5, captionDuration / 4);
+  const fadeOutStart = captionDuration - fadeInDuration;
+  const opacity = interpolate(captionFrame, [0, fadeInDuration, fadeOutStart, captionDuration], [0, 1, 1, 0], {
+    extrapolateLeft: 'clamp',
+    extrapolateRight: 'clamp',
+  });
+
+  const pagePosition = activePage.placement?.position ?? position;
+  const verticalPosition = pagePosition === 'top' ? 'flex-start' : pagePosition === 'bottom' ? 'flex-end' : 'center';
+  const safePadding = { ...PLATFORM_SAFE_ZONES[platform], ...safeZone };
+  const explicitPlacement = activePage.placement?.x !== undefined || activePage.placement?.y !== undefined;
+  const explicitLeft = clamp((activePage.placement?.x ?? 0.5) * width, safePadding.left, width - safePadding.right);
+  const explicitTop = clamp(
+    (activePage.placement?.y ?? positionToDefaultY(pagePosition)) * height,
+    safePadding.top,
+    height - safePadding.bottom,
+  );
+  const pageText = activePage.text ?? activePage.tokens.map((token) => token.text).join(' ');
+  const fittedFontSize = fitFontSize(pageText, fontSize, minFontSize, maxCharsPerLine, maxLines);
+  const baseTextColor = textColor ?? color;
+  const inactiveTextColor = inactiveColor ?? baseTextColor;
+  const activeTokenIndex = activePage.tokens.findIndex(
+    (token) => currentTimeMs >= token.startMs && currentTimeMs <= token.endMs,
+  );
+  const showBackground = preset === 'premium-pill' || preset === 'karaoke' || style === 'standard';
+  const textShadow = resolveTextShadow(shadow);
+  const textStroke = preset === 'minimal' || strokeWidth === 0 ? undefined : `${strokeWidth}px ${strokeColor}`;
+
+  const captionContent = (
+    <div
+      style={{
+        maxWidth: width * maxWidthPct,
+        fontSize: fittedFontSize,
+        fontFamily,
+        fontWeight,
+        lineHeight,
+        color: baseTextColor,
+        backgroundColor: showBackground ? backgroundColor : 'transparent',
+        padding: showBackground ? '14px 28px' : 0,
+        borderRadius: backgroundRadius,
+        textAlign: 'center',
+        textShadow,
+        WebkitTextStroke: textStroke,
+      }}
+    >
+      {activePage.tokens.map((token, index) => {
+        const isCurrent = index === activeTokenIndex;
+        const isPast = token.endMs < currentTimeMs;
+        const isEmphasis = token.emphasis && token.emphasis !== 'none';
+        const isHighlighted = style === 'karaoke' ? isPast || isCurrent : isCurrent || Boolean(isEmphasis);
+
+        return (
+          <span
+            key={`${token.startMs}-${index}-${token.text}`}
+            style={{
+              display: 'inline-block',
+              margin: '0 7px',
+              color: isHighlighted ? highlightColor : inactiveTextColor,
+              transform: isCurrent ? 'scale(1.08)' : 'scale(1)',
+            }}
+          >
+            {token.text}
+          </span>
+        );
+      })}
+    </div>
+  );
+
+  if (explicitPlacement) {
+    return (
+      <AbsoluteFill style={{ opacity, pointerEvents: 'none' }}>
+        <div
+          style={{
+            position: 'absolute',
+            left: explicitLeft,
+            top: explicitTop,
+            transform: 'translate(-50%, -50%)',
+          }}
+        >
+          {captionContent}
+        </div>
+      </AbsoluteFill>
+    );
+  }
+
+  return (
+    <AbsoluteFill
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: verticalPosition,
+        padding: `${safePadding.top}px ${safePadding.right}px ${safePadding.bottom}px ${safePadding.left}px`,
+        opacity,
+        pointerEvents: 'none',
+      }}
+    >
+      {captionContent}
+    </AbsoluteFill>
+  );
+};
+
+const positionToDefaultY = (position: 'top' | 'center' | 'bottom'): number => {
+  if (position === 'top') {
+    return 0.25;
+  }
+
+  if (position === 'bottom') {
+    return 0.75;
+  }
+
+  return 0.5;
+};
+
+const clamp = (value: number, min: number, max: number): number => Math.min(Math.max(value, min), max);
+
+const legacyCaptionsToPages = (captions: Caption[]): CaptionPage[] =>
+  captions.map((caption) => {
+    const tokens = splitCaption(caption);
+    return {
+      text: tokens.map((token) => token.text).join(' '),
+      startMs: caption.startMs,
+      endMs: caption.endMs,
+      tokens,
+    };
+  });
+
+const splitCaption = (caption: Caption): CaptionToken[] => {
+  const words = caption.text.trim().split(/\s+/).filter(Boolean);
+  if (words.length === 0) {
+    return [];
+  }
+
+  const duration = Math.max(1, caption.endMs - caption.startMs);
+  const wordDuration = duration / words.length;
+
+  return words.map((word, index) => {
+    const startMs = Math.round(caption.startMs + wordDuration * index);
+    const endMs = index === words.length - 1 ? caption.endMs : Math.round(caption.startMs + wordDuration * (index + 1));
+    return {
+      text: word,
+      startMs,
+      endMs: Math.max(endMs, startMs + 1),
+      timestampMs: startMs,
+      confidence: caption.confidence,
+      emphasis: caption.emphasis ?? 'none',
+    };
+  });
+};
+
+const fitFontSize = (
+  text: string,
+  fontSize: number,
+  minFontSize: number,
+  maxCharsPerLine: number,
+  maxLines: number,
+): number => {
+  const targetChars = maxCharsPerLine * maxLines;
+  if (text.length <= targetChars) {
+    return fontSize;
+  }
+
+  return Math.max(minFontSize, Math.round(fontSize * (targetChars / text.length)));
+};
+
+const resolveTextShadow = (shadow: CaptionConfig['shadow']): CSSProperties['textShadow'] => {
+  if (!shadow) {
+    return undefined;
+  }
+
+  if (shadow === true) {
+    return '0 3px 8px rgba(0, 0, 0, 0.85)';
+  }
+
+  return `${shadow.offsetX}px ${shadow.offsetY}px ${shadow.blur}px ${shadow.color}`;
+};

package/src/remotion/compositions/captions/index.ts

@@ -0,0 +1 @@
+export { CaptionOverlay } from './CaptionOverlay';

package/src/remotion/compositions/clips/AudioClipRenderer.tsx

@@ -0,0 +1,66 @@
+/**
+ * AudioClipRenderer Component
+ *
+ * DESIGN PATTERNS:
+ * - Remotion composition pattern
+ * - Type-safe props from Zod schema
+ *
+ * CODING STANDARDS:
+ * - Use Audio from remotion
+ * - Handle trimming via startFrom/endAt
+ * - Control playback with volume, playbackRate, loop
+ */
+
+import { Audio, interpolate } from 'remotion';
+import type { AudioClip } from '../../../types/index.js';
+import { resolveRemotionAssetSrc } from '../../../utils/assetPaths';
+
+const buildVolume = (
+  baseVolume: number,
+  volumeAutomation: AudioClip['volumeAutomation'],
+): number | ((frame: number) => number) => {
+  if (!volumeAutomation || volumeAutomation.length === 0) {
+    return baseVolume;
+  }
+
+  const points = [...volumeAutomation].sort((a, b) => a.frame - b.frame);
+  if (points.length === 1) {
+    return points[0]?.volume ?? baseVolume;
+  }
+
+  return (frame: number) =>
+    interpolate(
+      frame,
+      points.map((point) => point.frame),
+      points.map((point) => point.volume),
+      {
+        extrapolateLeft: 'clamp',
+        extrapolateRight: 'clamp',
+      },
+    );
+};
+
+export const AudioClipRenderer: React.FC<AudioClip> = ({
+  src,
+  volume = 1,
+  volumeAutomation,
+  playbackRate = 1,
+  loop = false,
+  trimBefore = 0,
+  trimAfter = 0,
+}) => {
+  if (!src) {
+    return null;
+  }
+
+  return (
+    <Audio
+      src={resolveRemotionAssetSrc(src)}
+      volume={buildVolume(volume, volumeAutomation)}
+      playbackRate={playbackRate}
+      loop={loop}
+      startFrom={trimBefore}
+      endAt={trimAfter > 0 ? trimAfter : undefined}
+    />
+  );
+};

package/src/remotion/compositions/clips/GifClipRenderer.tsx

@@ -0,0 +1,71 @@
+/**
+ * GifClipRenderer Component
+ *
+ * DESIGN PATTERNS:
+ * - Remotion composition pattern with @remotion/gif
+ * - Async loading with delayRender/continueRender
+ * - Type-safe props from Zod schema
+ *
+ * CODING STANDARDS:
+ * - Use Gif component from @remotion/gif
+ * - Preload with useGifAsSource()
+ * - Handle loading states properly
+ */
+
+import { Gif } from '@remotion/gif';
+import { useEffect, useState } from 'react';
+import { continueRender, delayRender } from 'remotion';
+import type { GifClip } from '../../../types/index.js';
+import { resolveRemotionAssetSrc } from '../../../utils/assetPaths';
+
+export const GifClipRenderer: React.FC<GifClip> = ({
+  src,
+  fit = 'cover',
+  playbackRate = 1,
+  loopBehavior = 'loop',
+  width,
+  height,
+}) => {
+  const [handle] = useState(() => delayRender());
+  const [gifData, setGifData] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!src) {
+      continueRender(handle);
+      return;
+    }
+
+    fetch(resolveRemotionAssetSrc(src))
+      .then((res) => res.blob())
+      .then((blob) => {
+        const url = URL.createObjectURL(blob);
+        setGifData(url);
+        continueRender(handle);
+      })
+      .catch((err) => {
+        console.error('Failed to load GIF:', err);
+        continueRender(handle);
+      });
+
+    return () => {
+      if (gifData) {
+        URL.revokeObjectURL(gifData);
+      }
+    };
+  }, [src, handle, gifData]);
+
+  if (!src || !gifData) {
+    return null;
+  }
+
+  return (
+    <Gif
+      src={gifData}
+      width={typeof width === 'number' ? width : undefined}
+      height={typeof height === 'number' ? height : undefined}
+      fit={fit}
+      playbackRate={playbackRate}
+      loopBehavior={loopBehavior}
+    />
+  );
+};