openvideo 0.0.1

package/dist/clips/iclip.d.ts

@@ -0,0 +1,178 @@
+import { BaseSprite, BaseSpriteEvents } from '../sprite/base-sprite';
+export interface IClipMeta {
+    width: number;
+    height: number;
+    duration: number;
+}
+export interface ITransitionInfo {
+    name: string;
+    duration: number;
+    textureUrl?: string;
+    prevClipId?: string;
+    fromClipId?: string;
+    toClipId?: string;
+    start?: number;
+    end?: number;
+}
+/**
+ * Interface that all clips must implement
+ *
+ * Clips are abstractions of different data types, providing data to other modules
+ *
+ *
+ * You only need to implement this interface to create custom clips, giving you maximum flexibility to generate video content such as animations and transition effects
+ *
+ */
+export interface IClip<T extends BaseSpriteEvents = BaseSpriteEvents> extends Omit<BaseSprite<T>, 'destroy' | 'ready'> {
+    destroy: () => void;
+    readonly ready: Promise<IClipMeta>;
+    /**
+     * Clip type (e.g., 'video', 'image', 'text', 'audio')
+     */
+    readonly type: string;
+    /**
+     * Source URL or identifier for this clip
+     */
+    src: string;
+    /**
+     * Extract data from clip at specified time
+     * @param time Time in microseconds
+     */
+    tick: (time: number) => Promise<{
+        video?: VideoFrame | ImageBitmap | null;
+        audio?: Float32Array[];
+        state: 'done' | 'success';
+    }>;
+    /**
+     * Get video frame and audio at specified time
+     * This method is provided by BaseClip and used by Compositor
+     */
+    getFrame(time: number): Promise<{
+        video: ImageBitmap | null;
+        audio: Float32Array[];
+        done: boolean;
+    }>;
+    /**
+     * Data metadata
+     */
+    readonly meta: IClipMeta;
+    /**
+     * Clone and return a new clip
+     */
+    clone: () => Promise<this>;
+    /**
+     * Split at specified time, return two new clips before and after that moment, commonly used in editing scenarios to split clips by time
+     *
+     * This method will not corrupt original clip data
+     *
+     * @param time Time in microseconds
+     * @returns
+     */
+    split?: (time: number) => Promise<[this, this]>;
+    /**
+     * Serialize clip to JSON format
+     * Returns a plain object with only serializable data (no circular references)
+     * @param main Whether this is the main clip (for Compositor)
+     */
+    toJSON(main?: boolean): any;
+    /**
+     * Set an external renderer (e.g., from Studio)
+     * This is called by Studio when adding clips to provide a shared renderer
+     * @param renderer The PixiJS renderer to use
+     */
+    setRenderer?(renderer: any): void;
+    /**
+     * Transition info (optional)
+     */
+    transition?: ITransitionInfo;
+    /**
+     * Audio volume level (0-1)
+     */
+    volume: number;
+    /**
+     * Styling properties (e.g., stroke, dropShadow, borderRadius)
+     */
+    style: any;
+    /**
+     * Get the list of visible transformer handles for this clip type
+     * Similar to Fabric.js v6 controls visibility pattern
+     * @returns Array of handle kinds that should be visible
+     */
+    getVisibleHandles?: () => Array<'tl' | 'tr' | 'bl' | 'br' | 'ml' | 'mr' | 'mt' | 'mb' | 'rot'>;
+    /**
+     * Scale clip to fit within the scene dimensions while maintaining aspect ratio
+     */
+    scaleToFit(sceneWidth: number, sceneHeight: number): Promise<void>;
+    /**
+     * Scale clip to fill the scene dimensions while maintaining aspect ratio
+     */
+    scaleToFill(sceneWidth: number, sceneHeight: number): Promise<void>;
+    /**
+     * Center the clip within the scene dimensions
+     */
+    centerInScene(sceneWidth: number, sceneHeight: number): void;
+}
+/**
+ * Optional interface for clips that support HTML media element playback
+ * Used by Studio for interactive preview
+ */
+export interface IPlaybackCapable {
+    /**
+     * Create and initialize HTML media element for playback
+     * @returns Promise resolving to the media element and optional object URL for cleanup
+     */
+    createPlaybackElement(): Promise<{
+        element: HTMLVideoElement | HTMLAudioElement;
+        objectUrl?: string;
+    }>;
+    /**
+     * Start playback at a specific time
+     * @param element The HTML media element
+     * @param timeSeconds Time in seconds (relative to clip start)
+     */
+    play(element: HTMLVideoElement | HTMLAudioElement, timeSeconds: number): Promise<void>;
+    /**
+     * Pause playback
+     * @param element The HTML media element
+     */
+    pause(element: HTMLVideoElement | HTMLAudioElement): void;
+    /**
+     * Seek to a specific time
+     * @param element The HTML media element
+     * @param timeSeconds Time in seconds (relative to clip start)
+     */
+    seek(element: HTMLVideoElement | HTMLAudioElement, timeSeconds: number): Promise<void>;
+    /**
+     * Sync playback state during preview
+     * @param element The HTML media element
+     * @param isPlaying Whether playback should be active
+     * @param timeSeconds Current time in seconds (relative to clip start)
+     */
+    syncPlayback(element: HTMLVideoElement | HTMLAudioElement, isPlaying: boolean, timeSeconds: number): void;
+    /**
+     * Clean up playback element and resources
+     * @param element The HTML media element
+     * @param objectUrl Optional object URL to revoke
+     */
+    cleanupPlayback(element: HTMLVideoElement | HTMLAudioElement, objectUrl?: string): void;
+}
+/**
+ * Get the default audio configuration
+ * This function returns a promise that resolves to the best supported audio codec
+ */
+export declare function getDefaultAudioConf(): Promise<{
+    codec: string;
+    sampleRate: number;
+    channelCount: number;
+}>;
+/**
+ * Synchronous version that returns cached codec or a default fallback
+ * Use this only when you need synchronous access (e.g., in constants)
+ * Prefer getDefaultAudioConf() for async contexts
+ */
+export declare const DEFAULT_AUDIO_CONF: {
+    readonly codec: string;
+    readonly codecType: "aac" | "opus";
+    readonly sampleRate: number;
+    readonly channelCount: number;
+};

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

@@ -0,0 +1,115 @@
+import { Texture } from 'pixi.js';
+import { BaseClip } from './base-clip';
+import { IClip } from './iclip';
+import { ClipJSON, ImageJSON } from '../json-serialization';
+type AnimateImgType = 'avif' | 'webp' | 'png' | 'gif';
+/**
+ * Image clip supporting animated images
+ *
+ * Ordinary text can be converted to image clip using {@link renderTxt2ImgBitmap}
+ *
+ * @example
+ * // Load from URL using PixiJS Assets (optimized for Studio)
+ * const imgClip = await Image.fromUrl('path/to/image.png');
+ *
+ * @example
+ * // Traditional approach (for Compositor/export)
+ * new Image((await fetch('<img url>')).body);
+ *
+ * @example
+ * new Image(
+ *   await renderTxt2ImgBitmap(
+ *     'Watermark',
+ *    `font-size:40px; color: white; text-shadow: 2px 2px 6px red;`,
+ *   )
+ * )
+ *
+ */
+export declare class Image extends BaseClip implements IClip {
+    readonly type = "Image";
+    ready: IClip['ready'];
+    private _meta;
+    /**
+     * ⚠️ Static images have duration of Infinity
+     *
+     * When wrapping with Sprite, you need to set its duration to a finite number
+     *
+     */
+    get meta(): {
+        duration: number;
+        width: number;
+        height: number;
+    };
+    private img;
+    private pixiTexture;
+    private frames;
+    /**
+     * Unique identifier for this clip instance
+     */
+    id: string;
+    /**
+     * 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;
+    }>;
+    /**
+     * Load an image clip from a URL using PixiJS Assets
+     * This is optimized for Studio as it uses Texture directly
+     *
+     * @param url Image URL
+     * @param src Optional source identifier for serialization
+     * @returns Promise that resolves to an Image instance
+     *
+     * @example
+     * const imgClip = await Image.fromUrl('path/to/image.png');
+     */
+    static fromUrl(url: string, src?: string): Promise<Image>;
+    /**
+     * Get the PixiJS Texture (if available)
+     * This is used for optimized rendering in Studio
+     */
+    getTexture(): Texture | null;
+    /**
+     * Static images can be initialized using stream or ImageBitmap
+     *
+     * Animated images need to use VideoFrame[] or provide image type
+     */
+    constructor(dataSource: ReadableStream | ImageBitmap | VideoFrame[] | {
+        type: `image/${AnimateImgType}`;
+        stream: ReadableStream;
+    }, src?: string);
+    private initAnimateImg;
+    tickInterceptor: <T extends Awaited<ReturnType<Image['tick']>>>(time: number, tickRet: T) => Promise<T>;
+    tick(time: number): Promise<{
+        video: ImageBitmap | VideoFrame;
+        state: 'success';
+    }>;
+    split(time: number): Promise<[this, this]>;
+    clone(): Promise<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;
+    destroy(): void;
+    toJSON(main?: boolean): ImageJSON;
+    /**
+     * Create an Image instance from a JSON object (fabric.js pattern)
+     * @param json The JSON object representing the clip
+     * @returns Promise that resolves to an Image instance
+     */
+    static fromObject(json: ClipJSON): Promise<Image>;
+}
+export {};

package/dist/clips/index.d.ts

@@ -0,0 +1,14 @@
+export * from './audio-clip';
+export * from './caption-clip';
+export * from './iclip';
+export * from './image-clip';
+export * from './video-clip';
+export { Video } from './video-clip';
+export type { IMP4ClipOpts } from './video-clip';
+export * from './text-clip';
+export * from './effect-clip';
+export { Effect } from './effect-clip';
+export * from './placeholder-clip';
+export { Placeholder } from './placeholder-clip';
+export * from './transition-clip';
+export { Transition } from './transition-clip';

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

@@ -0,0 +1,15 @@
+import { BaseClip } from './base-clip';
+import { IClipMeta } from './iclip';
+export declare class Placeholder extends BaseClip {
+    type: string;
+    meta: IClipMeta;
+    constructor(src: string, meta?: Partial<IClipMeta>, type?: string);
+    private placeholderFrame;
+    tick(time: number): Promise<{
+        video?: ImageBitmap | null;
+        audio?: Float32Array[];
+        state: 'done' | 'success';
+    }>;
+    clone(): Promise<this>;
+    split(time: number): Promise<[this, this]>;
+}

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

@@ -0,0 +1,266 @@
+import { Application, Texture } from 'pixi.js';
+import { BaseClip } from './base-clip';
+import { IClip } from './iclip';
+import { TextJSON } from '../json-serialization';
+export interface ITextOpts {
+    /**
+     * Font size in pixels
+     * @default 40
+     */
+    fontSize?: number;
+    /**
+     * Font family
+     * @default 'Roboto'
+     */
+    fontFamily?: string;
+    /**
+     * Font weight (e.g., 'normal', 'bold', '400', '700')
+     * @default 'normal'
+     */
+    fontWeight?: string;
+    /**
+     * Font style (e.g., 'normal', 'italic')
+     * @default 'normal'
+     */
+    fontStyle?: string;
+    /**
+     * Font URL for custom fonts
+     */
+    fontUrl?: 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;
+        }>;
+    };
+    /**
+     * 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';
+        cap?: 'butt' | 'round' | 'square';
+        miterLimit?: number;
+    };
+    /**
+     * Stroke width in pixels (used when stroke is a simple color)
+     * @default 0
+     */
+    strokeWidth?: number;
+    /**
+     * Text alignment ('left', 'center', 'right')
+     * @default 'left'
+     */
+    align?: 'left' | 'center' | 'right';
+    /**
+     * Alias for align to match UI property naming
+     */
+    textAlign?: 'left' | 'center' | 'right';
+    /**
+     * Vertical alignment ('top', 'center', 'bottom')
+     * @default 'top'
+     */
+    verticalAlign?: 'top' | 'center' | 'bottom' | 'underline' | 'overline' | 'strikethrough';
+    /**
+     * 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'
+     */
+    wordWrap?: boolean;
+    /**
+     * 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';
+    /**
+     * Text decoration ('none', 'underline', 'line-through', 'overline')
+     * @default 'none'
+     */
+    textDecoration?: 'none' | 'underline' | 'line-through' | 'overline';
+}
+/**
+ * Text clip using PixiJS Text for rendering
+ *
+ * @example
+ * const textClip = new Text('Hello World', {
+ *   fontSize: 48,
+ *   fill: '#ffffff',
+ *   stroke: '#000000',
+ *   strokeWidth: 2,
+ *   dropShadow: {
+ *     color: '#000000',
+ *     alpha: 0.5,
+ *     blur: 4,
+ *     distance: 2,
+ *   },
+ * });
+ * textClip.duration = 5e6; // 5 seconds
+ */
+export declare class Text extends BaseClip {
+    readonly type = "Text";
+    ready: IClip['ready'];
+    private _meta;
+    get meta(): {
+        duration: number;
+        width: number;
+        height: number;
+    };
+    get width(): number;
+    set width(v: number);
+    get height(): number;
+    set height(v: number);
+    private _lastContentWidth;
+    private _lastContentHeight;
+    private _text;
+    /**
+     * Text content (hybrid JSON structure)
+     */
+    get text(): string;
+    set text(v: string);
+    /**
+     * Text styling (hybrid JSON structure)
+     * Provides direct access to styling properties
+     */
+    /**
+     * Text styling (hybrid JSON structure)
+     * Provides direct access to styling properties
+     */
+    get style(): any;
+    set style(opts: Partial<ITextOpts>);
+    /**
+     * Text alignment proxy for compatibility with UI
+     */
+    get textAlign(): 'left' | 'center' | 'right';
+    set textAlign(v: 'left' | 'center' | 'right');
+    /**
+     * Vertical alignment or decoration proxy
+     */
+    get verticalAlign(): string;
+    set verticalAlign(v: string);
+    /**
+     * Text case proxy
+     */
+    get textCase(): string;
+    set textCase(v: 'none' | 'uppercase' | 'lowercase' | 'title');
+    private pixiTextContainer;
+    private wordTexts;
+    private textStyle;
+    private textStyleBase;
+    private renderTexture;
+    private externalRenderer;
+    private pixiApp;
+    private originalOpts;
+    /**
+     * Unique identifier for this clip instance
+     */
+    id: string;
+    /**
+     * 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;
+    }>;
+    constructor(text: string, opts?: ITextOpts, renderer?: Application['renderer']);
+    /**
+     * Set an external renderer (e.g., from Studio) to avoid creating our own Pixi App
+     * This is an optimization for Studio preview
+     * Can be called before ready() completes
+     */
+    setRenderer(renderer: Application['renderer']): void;
+    /**
+     * Get the renderer for rendering text to RenderTexture
+     * Creates a minimal renderer as fallback if no external renderer is provided
+     */
+    private getRenderer;
+    /**
+     * Get the PixiJS Texture (RenderTexture) for optimized rendering in Studio
+     * This avoids ImageBitmap → Canvas → Texture conversion
+     *
+     * @returns The RenderTexture containing the rendered text, or null if not ready
+     */
+    getTexture(): Promise<Texture | null>;
+    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>;
+    /**
+     * Update text styling options and refresh the texture
+     * This is used for dynamic updates like resizing with text reflow
+     */
+    updateStyle(opts: Partial<ITextOpts>): Promise<void>;
+    /**
+     * Refresh the internal Pixi Text and RenderTexture
+     * Calculates dimensions based on text bounds and wrapping options
+     */
+    private refreshText;
+    /**
+     * Helper to create PixiJS TextStyle options from Text options
+     */
+    private createStyleFromOpts;
+    destroy(): void;
+    toJSON(main?: boolean): TextJSON;
+    /**
+     * Create a Text instance from a JSON object (fabric.js pattern)
+     * @param json The JSON object representing the clip
+     * @returns Promise that resolves to a Text instance
+     */
+    static fromObject(json: TextJSON): Promise<Text>;
+    /**
+     * Override handle visibility for text clips
+     * Text clips should only show: mr (mid-right), mb (mid-bottom), br (bottom-right), and rot (rotation)
+     * This allows resizing width and height independently while preventing corner handles that might distort text
+     */
+    getVisibleHandles(): Array<'tl' | 'tr' | 'bl' | 'br' | 'ml' | 'mr' | 'mt' | 'mb' | 'rot'>;
+}

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

@@ -0,0 +1,45 @@
+import { BaseClip } from './base-clip';
+import { IClip } from './iclip';
+import { TransitionKey } from '../transition/glsl/gl-transition';
+export declare class Transition extends BaseClip {
+    readonly type = "Transition";
+    ready: IClip['ready'];
+    private _meta;
+    get meta(): {
+        duration: number;
+        width: number;
+        height: number;
+    };
+    /**
+     * Unique identifier for this clip instance
+     */
+    id: string;
+    /**
+     * The transition configuration
+     */
+    transitionEffect: {
+        id: string;
+        key: TransitionKey;
+        name: string;
+    };
+    /**
+     * ID of the clip from which the transition starts
+     */
+    fromClipId: string | null;
+    /**
+     * ID of the clip to which the transition ends
+     */
+    toClipId: string | null;
+    constructor(transitionKey: TransitionKey);
+    clone(): Promise<this>;
+    tick(_time: number): Promise<{
+        video: ImageBitmap | undefined;
+        state: 'success';
+    }>;
+    split(_time: number): Promise<[this, this]>;
+    toJSON(main?: boolean): any;
+    /**
+     * Create a Transition instance from a JSON object
+     */
+    static fromObject(json: any): Promise<Transition>;
+}