Skip to content

Open source CapCut alternative.

TypeScript
6.0 KB
Raw Blame
/**
 * The editor bridge — the typed tool set the orchestrator drives the timeline
 * through. Nothing else touches the editor.
 *
 * Frames, not seconds, cross this boundary: the orchestrator plans in frames
 * and this interface is where the conversion to the editor's seconds happens,
 * once, using the timeline fps. The real bridge (wired later) forwards to Cut's
 * editor store; the fake bridge records placements in memory so a test can
 * assert the track is fully covered and correctly timed.
 */

export interface TimelineInfo {
  fps: number;
  durationFrames: number;
  aspect: "9:16" | "16:9";
}

export interface AudioClipInfo {
  clipId: string;
  assetId: string;
  startFrame: number;
  durationFrames: number;
}

export interface EditorBridge {
  getTimeline(): TimelineInfo;
  getAudioClips(): AudioClipInfo[];
  /** Bring a generated media asset into the project pool; returns its media id. */
  importMedia(mediaId: string): Promise<string>;
  /**
   * Place a video clip on the video track filling a [startFrame, endFrame)-
   * sized slot. Where it lands is the editor's call: the planned frames are the
   * target, and the anchors keep a moving timeline honest — the clip lands
   * after the furthest of `anchorAfterIds` (clips the run's earlier shots still
   * hold), never slides past any of `followClipIds` (clips its later shots
   * hold; those push right instead), and clears whatever else occupies the row.
   * `srcInSec` starts the clip's source window there (the reviewer's chosen
   * moment) instead of at 0. `muted` silences the clip's own audio — set for a
   * provided-audio scene's b-roll, cleared for a generated scene whose shot
   * carries its own burned-in narration (defaults to muted).
   * Returns the new timeline clip id.
   */
  placeClip(
    mediaId: string,
    startFrame: number,
    endFrame: number,
    opts?: { srcInSec?: number; muted?: boolean; anchorAfterIds?: string[]; followClipIds?: string[] }
  ): Promise<string>;
  /** Swap the media under an existing clip (regeneration), keeping its slot. */
  replaceClipMedia(clipId: string, mediaId: string): Promise<void>;
  /** Retime a clip so its footprint is exactly `durationFrames`. */
  retimeClip(clipId: string, durationFrames: number): Promise<void>;
  /** Remove a clip, leaving its slot empty. */
  removeClip(clipId: string): Promise<void>;
  /** Add a transition from a clip into the next, in frames. */
  addTransition(clipId: string, style: string, durationFrames: number): Promise<void>;
  /** Place audio (voiceover or a music bed) on the soundtrack. `volume` sets its
   * baseline gain — a music bed sits under the shots' burned-in narration. */
  placeAudio(
    mediaId: string,
    startFrame: number,
    durationFrames: number,
    opts?: { kind?: "voice" | "music"; duck?: number; lane?: number; volume?: number }
  ): Promise<string>;
  /** Remove a soundtrack clip, so voice/music placement stays idempotent. */
  removeAudio(clipId: string): Promise<void>;
}

export interface PlacedAudio {
  clipId: string;
  mediaId: string;
  startFrame: number;
  durationFrames: number;
  kind: "voice" | "music";
  volume?: number;
}

/** What the fake editor recorded for one placed clip. */
export interface PlacedClip {
  clipId: string;
  mediaId: string;
  startFrame: number;
  endFrame: number;
  srcInSec?: number;
  muted?: boolean;
  transition?: { style: string; durationFrames: number };
}

/** In-memory editor that records placements instead of touching a real store. */
export class FakeEditor implements EditorBridge {
  readonly placed: PlacedClip[] = [];
  readonly placedAudio: PlacedAudio[] = [];
  private seq = 0;

  constructor(private readonly timeline: TimelineInfo, private readonly audio: AudioClipInfo[]) {}

  getTimeline(): TimelineInfo {
    return this.timeline;
  }

  getAudioClips(): AudioClipInfo[] {
    return this.audio;
  }

  async importMedia(mediaId: string): Promise<string> {
    return mediaId;
  }

  async placeClip(
    mediaId: string,
    startFrame: number,
    endFrame: number,
    opts?: { srcInSec?: number; muted?: boolean; anchorAfterIds?: string[]; followClipIds?: string[] }
  ): Promise<string> {
    const clipId = `clip:${this.seq++}`;
    this.placed.push({
      clipId,
      mediaId,
      startFrame,
      endFrame,
      ...(opts?.srcInSec ? { srcInSec: opts.srcInSec } : {}),
      muted: opts?.muted ?? true,
    });
    return clipId;
  }

  async replaceClipMedia(clipId: string, mediaId: string): Promise<void> {
    const clip = this.require(clipId);
    clip.mediaId = mediaId;
  }

  async retimeClip(clipId: string, durationFrames: number): Promise<void> {
    const clip = this.require(clipId);
    clip.endFrame = clip.startFrame + durationFrames;
  }

  async removeClip(clipId: string): Promise<void> {
    const i = this.placed.findIndex((c) => c.clipId === clipId);
    if (i >= 0) this.placed.splice(i, 1);
  }

  async addTransition(clipId: string, style: string, durationFrames: number): Promise<void> {
    this.require(clipId).transition = { style, durationFrames };
  }

  async placeAudio(
    mediaId: string,
    startFrame: number,
    durationFrames: number,
    opts?: { kind?: "voice" | "music"; duck?: number; lane?: number; volume?: number }
  ): Promise<string> {
    const clipId = `audio:${this.seq++}`;
    this.placedAudio.push({
      clipId,
      mediaId,
      startFrame,
      durationFrames,
      kind: opts?.kind ?? "voice",
      ...(opts?.volume !== undefined ? { volume: opts.volume } : {}),
    });
    return clipId;
  }

  async removeAudio(clipId: string): Promise<void> {
    const i = this.placedAudio.findIndex((c) => c.clipId === clipId);
    if (i >= 0) this.placedAudio.splice(i, 1);
  }

  /** The placed clips sorted by start — the timeline as the fake sees it. */
  timeline_clips(): PlacedClip[] {
    return [...this.placed].sort((a, b) => a.startFrame - b.startFrame);
  }

  private require(clipId: string): PlacedClip {
    const clip = this.placed.find((c) => c.clipId === clipId);
    if (!clip) throw new Error(`no clip ${clipId}`);
    return clip;
  }
}