vivid-editor-core 0.1.0

package/dist/ai-orchestrator.d.ts

@@ -0,0 +1,266 @@
+/**
+ * AI Art Director — State Orchestrator
+ *
+ * Processes structured AI commands against the editor Zustand store.
+ * Each command maps to one or more store mutations (e.g. adding a visual clip
+ * always creates both a TimelineClip AND a CanvasObject).
+ */
+import type { TextOverlay } from './types/editor.js';
+import type { TimelineClip, CanvasObject, TrackDefinition, AssetClip } from './store.js';
+import type { BeatAnalysis } from './types/beat.js';
+import type { Animations, Animation as AnimationCurve, AnimatableProp } from './types/animation.js';
+import type { Effect } from './types/effect.js';
+import type { Mask as MaskV2 } from './types/mask.js';
+import type { AudioReactiveModifier } from './types/audioReactive.js';
+export interface AddTextCommand {
+    type: 'ADD_TEXT';
+    payload: TextOverlay;
+}
+export interface UpdateTextCommand {
+    type: 'UPDATE_TEXT';
+    payload: Partial<TextOverlay> & {
+        id: string;
+    };
+}
+export interface RemoveTextCommand {
+    type: 'REMOVE_TEXT';
+    payload: {
+        id: string;
+    };
+}
+export interface AddClipCommand {
+    type: 'ADD_CLIP';
+    /** The asset to place on the timeline (must already exist in assetLibrary) */
+    payload: {
+        assetId: string;
+        /** Timeline placement — startMs is auto-computed if omitted */
+        startMs?: number;
+        durationMs?: number;
+        trackId?: string;
+        /** Canvas transform — defaults to full-canvas cover */
+        canvasObject?: Partial<Omit<CanvasObject, 'id' | 'clipId'>>;
+    };
+}
+export interface UpdateClipCommand {
+    type: 'UPDATE_CLIP';
+    payload: Partial<Pick<TimelineClip, 'startMs' | 'durationMs' | 'sourceOffsetMs' | 'volume' | 'opacity' | 'playbackRate'>> & {
+        id: string;
+    };
+}
+export interface RemoveClipCommand {
+    type: 'REMOVE_CLIP';
+    payload: {
+        id: string;
+    };
+}
+export interface UpdateCanvasObjectCommand {
+    type: 'UPDATE_CANVAS_OBJECT';
+    payload: Partial<CanvasObject> & {
+        id: string;
+    };
+}
+export interface SetCanvasPresetCommand {
+    type: 'SET_CANVAS_PRESET';
+    payload: {
+        id: string;
+        label: string;
+        width: number;
+        height: number;
+    };
+}
+export interface AddTrackCommand {
+    type: 'ADD_TRACK';
+    payload: {
+        type: 'visual' | 'audio';
+    };
+}
+export interface SplitClipCommand {
+    type: 'SPLIT_CLIP';
+    payload: {
+        clipId: string;
+        splitAtMs: number;
+    };
+}
+export interface DuplicateClipCommand {
+    type: 'DUPLICATE_CLIP';
+    payload: {
+        id: string;
+    };
+}
+export interface SetTransitionCommand {
+    type: 'SET_TRANSITION';
+    payload: {
+        clipId: string;
+        edge: 'in' | 'out';
+        type: 'dissolve' | 'fade-black' | 'crossfade' | 'fade-in' | 'fade-out';
+        durationMs: number;
+    };
+}
+export interface SetClipAnimationCommand {
+    type: 'SET_CLIP_ANIMATION';
+    payload: {
+        clipId: string;
+        phase: 'in' | 'out';
+        type: 'none' | 'fade' | 'slide-up' | 'slide-down' | 'zoom-in' | 'zoom-out' | 'zoom-pan' | 'spin' | 'blur-reveal';
+        durationMs: number;
+    };
+}
+export interface SetCinematicLookCommand {
+    type: 'SET_CINEMATIC_LOOK';
+    payload: {
+        look: 'none' | 'kodak-portra' | 'noir' | 'cyberpunk' | 'kodak-portra-400' | 'fuji-provia' | 'ilford-hp5' | 'cinestill-800t' | 'bleach-bypass' | 'polaroid-vintage' | 'technicolor' | 'cross-process' | 'muted-cinematic' | 'cyberpunk-neon';
+    };
+}
+export interface DetachAudioCommand {
+    type: 'DETACH_AUDIO';
+    payload: {
+        clipId: string;
+    };
+}
+/**
+ * Beat-synced rhythmic editing of the visual track to a music clip.
+ *
+ * `audioClipId` — id of an audio clip already in timeline. Must have a
+ * cached BeatAnalysis (otherwise the orchestrator returns an error).
+ *
+ * `beatInterval` — how many beats between cuts. 4 = 1 cut per measure.
+ *
+ * `mode`:
+ *  - "redistribute" (default): take all visual clips, slice them up so
+ *    each segment lasts exactly `beatInterval` beats, and lay them down
+ *    end-to-end starting at firstBeatMs. Ignores existing visual clip
+ *    positions/durations. Best when clips are placeholders that need
+ *    rhythmic timing.
+ *  - "snap": leave clips where they are, just nudge their start/end
+ *    edges to the nearest beat. Conservative.
+ *
+ * `syncClips`: which visual clips to include. "all" = every visual
+ *  clip on V* tracks. Otherwise an explicit list of clip ids.
+ */
+export interface CutToBeatCommand {
+    type: 'CUT_TO_BEAT';
+    payload: {
+        audioClipId: string;
+        beatInterval: number;
+        mode?: 'redistribute' | 'snap';
+        syncClips?: 'all' | string[];
+    };
+}
+/** Set keyframe animations on one property of a canvas object or text overlay. */
+export interface SetObjectAnimationCommand {
+    type: 'SET_OBJECT_ANIMATION';
+    payload: {
+        objectId: string;
+        objectType: 'canvas' | 'text';
+        property: AnimatableProp;
+        animation: AnimationCurve;
+    };
+}
+/** Replace ALL animations on an object at once. */
+export interface SetAnimationsCommand {
+    type: 'SET_ANIMATIONS';
+    payload: {
+        objectId: string;
+        objectType: 'canvas' | 'text';
+        animations: Animations;
+    };
+}
+/** Append (or replace by type) one effect on a canvas object / text overlay. */
+export interface AddEffectCommand {
+    type: 'ADD_EFFECT';
+    payload: {
+        objectId: string;
+        objectType: 'canvas' | 'text';
+        effect: Effect;
+        /** When true, replace any existing effect of the same type. */
+        replace?: boolean;
+    };
+}
+/** Remove an effect by type from a canvas object / text overlay. */
+export interface RemoveEffectCommand {
+    type: 'REMOVE_EFFECT';
+    payload: {
+        objectId: string;
+        objectType: 'canvas' | 'text';
+        effectType: Effect['type'];
+    };
+}
+/** Bind a property to an audio feature (RMS / band / beat). */
+export interface AddAudioReactiveCommand {
+    type: 'ADD_AUDIO_REACTIVE';
+    payload: {
+        objectId: string;
+        objectType: 'canvas' | 'text';
+        modifier: AudioReactiveModifier;
+    };
+}
+/** Set the v2 mask on a canvas object (rect / circle / reveal / clipPath). */
+export interface SetMaskCommand {
+    type: 'SET_MASK';
+    payload: {
+        objectId: string;
+        mask: MaskV2;
+    };
+}
+export type AiCommand = AddTextCommand | UpdateTextCommand | RemoveTextCommand | AddClipCommand | UpdateClipCommand | RemoveClipCommand | UpdateCanvasObjectCommand | SetCanvasPresetCommand | AddTrackCommand | SplitClipCommand | DuplicateClipCommand | SetTransitionCommand | SetClipAnimationCommand | SetCinematicLookCommand | DetachAudioCommand | CutToBeatCommand | SetObjectAnimationCommand | SetAnimationsCommand | AddEffectCommand | RemoveEffectCommand | AddAudioReactiveCommand | SetMaskCommand;
+export interface EditorSnapshot {
+    timelineClips: TimelineClip[];
+    canvasObjects: CanvasObject[];
+    tracks: TrackDefinition[];
+    textOverlays: TextOverlay[];
+    assetLibrary: AssetClip[];
+    canvasPreset: {
+        id: string;
+        label: string;
+        width: number;
+        height: number;
+    };
+    videoDurationMs: number;
+    /** Beat analysis cache, keyed by audio asset id. Optional — present
+     *  only when the AI panel was opened after audio analysis completed. */
+    audioBeatsByAssetId?: Record<string, BeatAnalysis | 'analyzing' | 'failed'>;
+}
+export interface OrchestratorActions {
+    addTextOverlay: (overlay: TextOverlay) => void;
+    updateTextOverlay: (id: string, patch: Partial<TextOverlay>) => void;
+    removeTextOverlay: (id: string) => void;
+    addClipToTimeline: (asset: AssetClip) => void;
+    updateClipBounds: (id: string, updates: Partial<Pick<TimelineClip, 'startMs' | 'durationMs' | 'sourceOffsetMs'>>) => void;
+    deleteClipById: (id: string) => void;
+    setClipVolume: (id: string, volume: number) => void;
+    setClipOpacity: (id: string, opacity: number) => void;
+    setClipSpeed: (id: string, rate: number) => void;
+    setSelectedClipId: (id: string | null) => void;
+    splitClip: (splitAtMs: number) => void;
+    duplicateClip: (id: string) => void;
+    setClipTransition: (clipId: string, edge: 'in' | 'out', config: {
+        type: string;
+        durationMs: number;
+    } | undefined) => void;
+    setClipAnimation: (clipId: string, phase: 'in' | 'out', config: {
+        type: string;
+        durationMs: number;
+    } | undefined) => void;
+    detachAudio: (clipId: string) => void;
+    updateCanvasObject: (id: string, patch: Partial<CanvasObject>) => void;
+    setCanvasPreset: (preset: {
+        id: string;
+        label: string;
+        width: number;
+        height: number;
+    }) => void;
+    setCinematicLook: (look: string) => void;
+    addTrack: (type: 'visual' | 'audio') => TrackDefinition;
+    replaceTimelineClips: (clips: TimelineClip[], canvasObjects?: CanvasObject[]) => void;
+    pushUndo: () => void;
+}
+/**
+ * Execute an array of AI commands against the editor store.
+ *
+ * Pushes a single undo checkpoint before processing all commands,
+ * so the entire AI action can be undone in one Ctrl+Z.
+ */
+export declare function executeAiCommands(commands: AiCommand[], snapshot: EditorSnapshot, actions: OrchestratorActions): {
+    applied: number;
+    errors: string[];
+};