openvideo 0.0.1

package/dist/clips/audio-clip.d.ts

@@ -0,0 +1,128 @@
+import { BaseClip } from './base-clip';
+import { IClip, IPlaybackCapable } from './iclip';
+import { AudioJSON } from '../json-serialization';
+interface IAudioOpts {
+    loop?: boolean;
+    volume?: number;
+}
+/**
+ * Audio clip providing audio data for creating and editing audio/video
+ *
+ * @example
+ * // Load audio clip asynchronously
+ * const audioClip = await Audio.fromUrl('path/to/audio.mp3', {
+ *   loop: true,
+ * });
+ *
+ * @example
+ * // Traditional approach (for advanced use)
+ * new Audio((await fetch('<mp3 url>')).body, {
+ *   loop: true,
+ * }),
+ */
+export declare class Audio extends BaseClip implements IPlaybackCapable {
+    readonly type = "Audio";
+    static ctx: AudioContext | null;
+    ready: IClip['ready'];
+    private _meta;
+    /**
+     * Audio metadata
+     *
+     * ⚠️ Note, these are converted (normalized) metadata, not original audio metadata
+     */
+    get meta(): {
+        sampleRate: number;
+        chanCount: number;
+        duration: number;
+        width: number;
+        height: number;
+    };
+    private chan0Buf;
+    private chan1Buf;
+    /**
+     * Get complete PCM data from audio clip
+     */
+    getPCMData(): Float32Array[];
+    private opts;
+    /**
+     * Whether to loop the audio (hybrid JSON structure)
+     */
+    loop: boolean;
+    /**
+     * Load an audio clip from a URL
+     * @param url Audio URL
+     * @param opts Audio configuration (loop, volume)
+     * @returns Promise that resolves to an audio clip
+     *
+     * @example
+     * const audioClip = await Audio.fromUrl('path/to/audio.mp3', {
+     *   loop: true,
+     *   volume: 0.8,
+     * });
+     */
+    static fromUrl(url: string, opts?: IAudioOpts): Promise<Audio>;
+    /**
+     * Create an Audio instance from a JSON object (fabric.js pattern)
+     * @param json The JSON object representing the clip
+     * @returns Promise that resolves to an Audio instance
+     */
+    static fromObject(json: AudioJSON): Promise<Audio>;
+    /**
+     *
+     * @param dataSource Audio file stream
+     * @param opts Audio configuration, controls volume and whether to loop
+     */
+    constructor(dataSource: ReadableStream<Uint8Array> | Float32Array[], opts?: IAudioOpts, src?: string);
+    private init;
+    /**
+     * Intercept data returned by {@link Audio.tick} method for secondary processing of audio data
+     * @param time Time when tick was called
+     * @param tickRet Data returned by tick
+     *
+     */
+    tickInterceptor: <T extends Awaited<ReturnType<Audio['tick']>>>(time: number, tickRet: T) => Promise<T>;
+    private timestamp;
+    private frameOffset;
+    /**
+     * Return audio PCM data corresponding to the time difference between last and current moments
+     *
+     * If the difference exceeds 3s or current time is less than last time, reset state
+     * @example
+     * tick(0) // => []
+     * tick(1e6) // => [leftChanPCM(1s), rightChanPCM(1s)]
+     *
+     */
+    tick(time: number): Promise<{
+        audio: Float32Array[];
+        state: 'success' | 'done';
+    }>;
+    /**
+     * Split at specified time, return two audio clips before and after
+     * @param time Time in microseconds
+     */
+    split(time: number): Promise<[this, this]>;
+    clone(): Promise<this>;
+    /**
+     * Destroy instance and release resources
+     */
+    destroy(): void;
+    toJSON(main?: boolean): AudioJSON;
+    static concatAudio: typeof concatAudioClip;
+    /**
+     * Create HTMLAudioElement for playback
+     */
+    createPlaybackElement(): Promise<{
+        element: HTMLAudioElement;
+        objectUrl?: string;
+    }>;
+    play(element: HTMLVideoElement | HTMLAudioElement, timeSeconds: number): Promise<void>;
+    pause(element: HTMLVideoElement | HTMLAudioElement): void;
+    seek(element: HTMLVideoElement | HTMLAudioElement, timeSeconds: number): Promise<void>;
+    syncPlayback(element: HTMLVideoElement | HTMLAudioElement, isPlaying: boolean, timeSeconds: number): void;
+    cleanupPlayback(element: HTMLVideoElement | HTMLAudioElement, objectUrl?: string): void;
+}
+/**
+ * Concatenate multiple AudioClips
+ */
+export declare function concatAudioClip(clips: Audio[], opts?: IAudioOpts): Promise<Audio>;
+export {};

package/dist/clips/base-clip.d.ts

@@ -0,0 +1,116 @@
+import { BaseSprite, BaseSpriteEvents } from '../sprite/base-sprite';
+import { IClip, IClipMeta, ITransitionInfo } from './iclip';
+import { ClipJSON } from '../json-serialization';
+/**
+ * Base class for all clips that extends BaseSprite
+ * Provides common functionality for sprite operations (position, animation, timing)
+ * and frame management
+ */
+export declare abstract class BaseClip<T extends BaseSpriteEvents = BaseSpriteEvents> extends BaseSprite<T> implements IClip<T> {
+    abstract readonly type: string;
+    private lastVf;
+    protected destroyed: boolean;
+    /**
+     * Source URL or identifier for this clip
+     * Used for serialization and reloading from JSON
+     */
+    src: string;
+    /**
+     * Transition info (optional)
+     */
+    transition?: ITransitionInfo;
+    abstract tick(time: number): Promise<{
+        video?: VideoFrame | ImageBitmap | null;
+        audio?: Float32Array[];
+        state: 'done' | 'success';
+    }>;
+    ready: Promise<IClipMeta>;
+    abstract readonly meta: IClipMeta;
+    abstract clone(): Promise<this>;
+    abstract split?(time: number): Promise<[this, this]>;
+    constructor();
+    /**
+     * Get video frame and audio at specified time without rendering to canvas
+     * Useful for Pixi.js rendering where canvas context is not needed
+     * @param time Specified time in microseconds
+     */
+    getFrame(time: number): Promise<{
+        video: ImageBitmap | null;
+        audio: Float32Array[];
+        done: boolean;
+    }>;
+    /**
+     * Draw image at specified time to canvas context and return corresponding audio data
+     * @param time Specified time in microseconds
+     */
+    offscreenRender(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, time: number): Promise<{
+        audio: Float32Array[];
+        done: boolean;
+    }>;
+    /**
+     * Set clip properties (position, size, display timeline)
+     * @param props Properties to set
+     * @param fps Optional FPS for frame-to-time conversion (default: 30)
+     * @returns this for method chaining
+     *
+     * @example
+     * // Using frames (will be converted to microseconds)
+     * clip.set({
+     *   display: {
+     *     from: 150, // frames
+     *     to: 450, // frames (10 seconds at 30fps)
+     *   },
+     * }, 30);
+     *
+     * // Using microseconds directly
+     * clip.set({
+     *   display: {
+     *     from: 5000000, // microseconds
+     *     to: 15000000, // microseconds
+     *   },
+     * });
+     */
+    set(props: {
+        display?: {
+            from?: number;
+            to?: number;
+        };
+        x?: number;
+        y?: number;
+        width?: number;
+        height?: number;
+        duration?: number;
+    }, fps?: number): this;
+    /**
+     * Base implementation of toJSON that handles common clip properties
+     * Subclasses should override to add their specific options
+     * @param main Whether this is the main clip (for Compositor)
+     */
+    toJSON(main?: boolean): ClipJSON;
+    /**
+     * Get the list of visible transformer handles for this clip type
+     * Default implementation returns all handles
+     * Override in subclasses to customize handle visibility (e.g., TextClip)
+     */
+    getVisibleHandles(): Array<'tl' | 'tr' | 'bl' | 'br' | 'ml' | 'mr' | 'mt' | 'mb' | 'rot'>;
+    /**
+     * Scale clip to fit within the scene dimensions while maintaining aspect ratio
+     * @param sceneWidth Scene width
+     * @param sceneHeight Scene height
+     */
+    scaleToFit(sceneWidth: number, sceneHeight: number): Promise<void>;
+    /**
+     * Scale clip to fill the scene dimensions while maintaining aspect ratio
+     * May crop parts of the clip.
+     * @param sceneWidth Scene width
+     * @param sceneHeight Scene height
+     */
+    scaleToFill(sceneWidth: number, sceneHeight: number): Promise<void>;
+    /**
+     * Center the clip within the scene dimensions
+     * @param sceneWidth Scene width
+     * @param sceneHeight Scene height
+     */
+    centerInScene(sceneWidth: number, sceneHeight: number): void;
+    destroy(): void;
+}

package/dist/clips/caption-clip.d.ts

@@ -0,0 +1,392 @@
+import { BaseClip } from './base-clip';
+import { IClip } from './iclip';
+import { CaptionJSON } from '../json-serialization';
+import { Application, Texture } from 'pixi.js';
+import { BaseSpriteEvents } from '../sprite/base-sprite';
+export interface ICaptionStyle {
+    fontSize?: number;
+    fontFamily?: string;
+    fontWeight?: string | number;
+    fontStyle?: string;
+    color?: ICaptionOpts['fill'];
+    align?: ICaptionOpts['align'];
+    textCase?: ICaptionOpts['textCase'];
+    verticalAlign?: ICaptionOpts['verticalAlign'];
+    wordsPerLine?: ICaptionOpts['wordsPerLine'];
+    stroke?: {
+        color: string | number;
+        width: number;
+    };
+    shadow?: {
+        color: string | number;
+        alpha: number;
+        blur: number;
+        distance: number;
+        angle: number;
+    };
+}
+export interface ICaptionEvents extends BaseSpriteEvents {
+    propsChange: Partial<{
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+        angle: number;
+        zIndex: number;
+        opacity: number;
+        volume: number;
+        text: string;
+        words: ICaptionOpts['words'];
+        fill: ICaptionOpts['fill'];
+        align: ICaptionOpts['align'];
+        textCase: ICaptionOpts['textCase'];
+        stroke: ICaptionOpts['stroke'];
+        dropShadow: ICaptionOpts['dropShadow'];
+        caption: ICaptionOpts['caption'];
+        wordsPerLine: ICaptionOpts['wordsPerLine'];
+    }>;
+}
+export interface ICaptionOpts {
+    /**
+     * Font size in pixels
+     * @default 30
+     */
+    fontSize?: number;
+    /**
+     * Font family
+     * @default 'Arial'
+     */
+    fontFamily?: string;
+    fontUrl?: string;
+    /**
+     * Font weight (e.g., 'normal', 'bold', '400', '700')
+     * @default 'normal'
+     */
+    fontWeight?: string | number;
+    /**
+     * Font style (e.g., 'normal', 'italic')
+     * @default 'normal'
+     */
+    fontStyle?: string;
+    /**
+     * Text color (hex string, color name, or gradient object)
+     * @default '#ffffff'
+     */
+    fill?: string | number | {
+        type: 'gradient';
+        x0: number;
+        y0: number;
+        x1: number;
+        y1: number;
+        colors: Array<{
+            ratio: number;
+            color: string | number;
+        }>;
+    };
+    /**
+     * Caption data (matches caption object in JSON)
+     */
+    caption?: {
+        words?: Array<{
+            text: string;
+            from: number;
+            to: number;
+            isKeyWord: boolean;
+            paragraphIndex?: number;
+        }>;
+        colors?: {
+            appeared?: string;
+            active?: string;
+            activeFill?: string;
+            background?: string;
+            keyword?: string;
+        };
+        preserveKeywordColor?: boolean;
+        positioning?: {
+            videoWidth?: number;
+            videoHeight?: number;
+            bottomOffset?: number;
+        };
+    };
+    /**
+     * @deprecated Use caption.words instead
+     */
+    words?: Array<{
+        text: string;
+        from: number;
+        to: number;
+        isKeyWord: boolean;
+        paragraphIndex?: number;
+    }>;
+    /**
+     * @deprecated Use caption.colors instead
+     */
+    colors?: {
+        appeared?: string;
+        active?: string;
+        activeFill?: string;
+        background?: string;
+        keyword?: string;
+    };
+    /**
+     * @deprecated Use caption.preserveKeywordColor instead
+     */
+    preserveKeywordColor?: boolean;
+    /**
+     * @deprecated Use caption.positioning.videoWidth instead
+     */
+    videoWidth?: number;
+    /**
+     * @deprecated Use caption.positioning.videoHeight instead
+     */
+    videoHeight?: number;
+    /**
+     * @deprecated Use caption.positioning.bottomOffset instead
+     */
+    bottomOffset?: number;
+    /**
+     * Stroke color (hex string or color name) or stroke object with advanced options
+     */
+    stroke?: string | number | {
+        color: string | number;
+        width: number;
+        join?: 'miter' | 'round' | 'bevel';
+    };
+    /**
+     * Stroke width in pixels (used when stroke is a simple color)
+     * @default 0
+     */
+    strokeWidth?: number;
+    /**
+     * Text alignment ('left', 'center', 'right')
+     * @default 'center'
+     */
+    align?: 'left' | 'center' | 'right';
+    /**
+     * Drop shadow configuration
+     */
+    dropShadow?: {
+        color?: string | number;
+        alpha?: number;
+        blur?: number;
+        angle?: number;
+        distance?: number;
+    };
+    /**
+     * Word wrap width (0 = no wrap)
+     * @default 0
+     */
+    wordWrapWidth?: number;
+    /**
+     * Word wrap mode ('break-word' or 'normal')
+     * @default 'break-word'
+     */
+    wordWrapMode?: 'break-word' | 'normal';
+    /**
+     * Whether to enable word wrap
+     * @default true
+     */
+    wordWrap?: boolean;
+    /**
+     * Vertical alignment ('top', 'center', 'bottom')
+     * @default 'bottom'
+     */
+    verticalAlign?: 'top' | 'center' | 'bottom';
+    /**
+     * Line height (multiplier)
+     * @default 1
+     */
+    lineHeight?: number;
+    /**
+     * Letter spacing in pixels
+     * @default 0
+     */
+    letterSpacing?: number;
+    /**
+     * Text case transformation
+     * @default 'none'
+     */
+    textCase?: 'none' | 'uppercase' | 'lowercase' | 'title';
+    /**
+     * Media ID to which the captions were applied
+     */
+    mediaId?: string;
+    /**
+     * Internal flag to skip automatic positioning
+     */
+    initialLayoutApplied?: boolean;
+    /**
+     * Words per line mode ('single' or 'multiple')
+     * @default 'multiple'
+     */
+    wordsPerLine?: 'single' | 'multiple';
+}
+/**
+ * Caption clip using Canvas 2D for rendering
+ * Each instance represents a single caption segment
+ *
+ * @example
+ * const captionClip = new CaptionClip('Hello World', {
+ *   fontSize: 44,
+ *   fontFamily: 'Arial',
+ *   fill: '#ffffff',
+ *   videoWidth: 1280,
+ *   videoHeight: 720,
+ * });
+ * captionClip.display.from = 0;
+ * captionClip.duration = 3e6; // 3 seconds
+ */
+export declare class Caption extends BaseClip<ICaptionEvents> implements IClip {
+    readonly type = "Caption";
+    ready: IClip['ready'];
+    private _meta;
+    get meta(): {
+        duration: number;
+        width: number;
+        height: number;
+    };
+    private _visualPaddingX;
+    private _visualPaddingY;
+    private _lastTickTime;
+    get width(): number;
+    set width(v: number);
+    get height(): number;
+    set height(v: number);
+    get left(): number;
+    set left(v: number);
+    get top(): number;
+    set top(v: number);
+    private _initialLayoutApplied;
+    private _isXPositionedManually;
+    private _isWidthConstrained;
+    private _lastContentWidth;
+    private _lastContentHeight;
+    private _lastProcessedText;
+    private _text;
+    /**
+     * Caption text content (hybrid JSON structure)
+     */
+    get text(): string;
+    set text(v: string);
+    get style(): ICaptionStyle;
+    set style(v: Partial<ICaptionOpts> | ICaptionStyle);
+    get wordsPerLine(): 'single' | 'multiple';
+    set wordsPerLine(v: 'single' | 'multiple');
+    get fontFamily(): string;
+    set fontFamily(v: string);
+    get fontUrl(): string;
+    set fontUrl(v: string);
+    get fontSize(): number;
+    set fontSize(v: number);
+    get fontWeight(): string | number;
+    set fontWeight(v: string | number);
+    get fontStyle(): 'normal' | 'italic' | 'oblique';
+    set fontStyle(v: 'normal' | 'italic' | 'oblique');
+    get fill(): ICaptionOpts['fill'];
+    set fill(v: ICaptionOpts['fill']);
+    get align(): 'left' | 'center' | 'right';
+    set align(v: 'left' | 'center' | 'right');
+    get stroke(): ICaptionOpts['stroke'];
+    set stroke(v: ICaptionOpts['stroke']);
+    get strokeWidth(): number;
+    set strokeWidth(v: number);
+    get dropShadow(): ICaptionOpts['dropShadow'];
+    set dropShadow(v: ICaptionOpts['dropShadow']);
+    get caption(): ICaptionOpts['caption'];
+    set caption(v: ICaptionOpts['caption']);
+    /**
+     * Bottom offset from video bottom (hybrid JSON structure)
+     */
+    bottomOffset?: number;
+    /**
+     * Text case proxy
+     */
+    get textCase(): string;
+    set textCase(v: 'none' | 'uppercase' | 'lowercase' | 'title');
+    /**
+     * Unique identifier for this clip instance
+     */
+    id: string;
+    /**
+     * Media ID of the source clip
+     */
+    get mediaId(): string | undefined;
+    set mediaId(v: string | undefined);
+    /**
+     * Array of effects to be applied to this clip
+     * Each effect specifies key, startTime, duration, and optional targets
+     */
+    effects: Array<{
+        id: string;
+        key: string;
+        startTime: number;
+        duration: number;
+    }>;
+    /**
+     * Words getter for the clip
+     */
+    get words(): ICaptionOpts["words"];
+    /**
+     * Words setter that triggers re-render and ensures consistency
+     */
+    set words(v: ICaptionOpts['words']);
+    private opts;
+    private pixiTextContainer;
+    private renderTexture;
+    private wordTexts;
+    private textStyle;
+    private textStyleBase;
+    private _refreshing;
+    private _needsRefresh;
+    private externalRenderer;
+    private pixiApp;
+    private originalOpts;
+    constructor(text: string, opts?: ICaptionOpts, renderer?: Application['renderer']);
+    /**
+     * Update text styling options and refresh the caption rendering
+     */
+    updateStyle(opts: Partial<ICaptionOpts>): Promise<void>;
+    private refreshCaptions;
+    private lastLoggedTime;
+    updateState(currentTime: number): void;
+    /**
+     * Get the PixiJS Texture (RenderTexture) for optimized rendering in Studio
+     */
+    getTexture(): Promise<Texture | null>;
+    offscreenRender(ctx: CanvasRenderingContext2D, time: number): Promise<{
+        audio: Float32Array[];
+        done: boolean;
+    }>;
+    /**
+     * Set an external renderer (e.g., from Studio) to avoid creating our own Pixi App
+     */
+    setRenderer(renderer: Application['renderer']): void;
+    private getRenderer;
+    tick(time: number): Promise<{
+        video: ImageBitmap;
+        state: 'success';
+    }>;
+    split(_time: number): Promise<[this, this]>;
+    addEffect(effect: {
+        id: string;
+        key: string;
+        startTime: number;
+        duration: number;
+    }): void;
+    editEffect(effectId: string, newEffectData: Partial<{
+        key: string;
+        startTime: number;
+        duration: number;
+    }>): void;
+    removeEffect(effectId: string): void;
+    clone(): Promise<this>;
+    destroy(): void;
+    toJSON(main?: boolean): CaptionJSON;
+    /**
+     * Create a Caption instance from a JSON object (fabric.js pattern)
+     * @param json The JSON object representing the clip
+     * @returns Promise that resolves to a Caption instance
+     */
+    static fromObject(json: CaptionJSON): Promise<Caption>;
+    getVisibleHandles(): Array<'tl' | 'tr' | 'bl' | 'br' | 'ml' | 'mr' | 'mt' | 'mb' | 'rot'>;
+}

package/dist/clips/effect-clip.d.ts

@@ -0,0 +1,37 @@
+import { BaseClip } from './base-clip';
+import { IClip } from './iclip';
+import { EffectKey } from '../effect/glsl/gl-effect';
+export declare class Effect extends BaseClip {
+    readonly type = "Effect";
+    ready: IClip['ready'];
+    private _meta;
+    get meta(): {
+        duration: number;
+        width: number;
+        height: number;
+    };
+    /**
+     * Unique identifier for this clip instance
+     */
+    id: string;
+    /**
+     * The effect configuration
+     */
+    effect: {
+        id: string;
+        key: EffectKey;
+        name: string;
+    };
+    constructor(effectKey: EffectKey);
+    clone(): Promise<this>;
+    tick(_time: number): Promise<{
+        video: ImageBitmap | undefined;
+        state: 'success';
+    }>;
+    split(_time: number): Promise<[this, this]>;
+    toJSON(main?: boolean): any;
+    /**
+     * Create an Effect instance from a JSON object
+     */
+    static fromObject(json: any): Promise<Effect>;
+}