@designcombo/video 0.0.0

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

@@ -0,0 +1,132 @@
+import { BaseClip } from './base-clip';
+import { IClip, IPlaybackCapable } from './iclip';
+import { AudioClipJSON } from '../json-serialization';
+interface IAudioClipOpts {
+    loop?: boolean;
+    volume?: number;
+}
+/**
+ * Audio clip providing audio data for creating and editing audio/video
+ *
+ * @example
+ * // Load audio clip asynchronously
+ * const audioClip = await AudioClip.fromUrl('path/to/audio.mp3', {
+ *   loop: true,
+ * });
+ *
+ * @example
+ * // Traditional approach (for advanced use)
+ * new AudioClip((await fetch('<mp3 url>')).body, {
+ *   loop: true,
+ * }),
+ */
+export declare class AudioClip extends BaseClip implements IPlaybackCapable {
+    static ctx: AudioContext | null;
+    ready: IClip['ready'];
+    private _meta;
+    /**
+     * Audio metadata
+     *
+     * ⚠️ Note, these are converted (normalized) metadata, not original audio metadata
+     */
+    get meta(): {
+        sampleRate: 48000;
+        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;
+    /**
+     * Audio volume level (0-1) (hybrid JSON structure)
+     */
+    volume: number;
+    /**
+     * 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 AudioClip.fromUrl('path/to/audio.mp3', {
+     *   loop: true,
+     *   volume: 0.8,
+     * });
+     */
+    static fromUrl(url: string, opts?: IAudioClipOpts): Promise<AudioClip>;
+    /**
+     * Create an AudioClip instance from a JSON object (fabric.js pattern)
+     * @param json The JSON object representing the clip
+     * @returns Promise that resolves to an AudioClip instance
+     */
+    static fromObject(json: AudioClipJSON): Promise<AudioClip>;
+    /**
+     *
+     * @param dataSource Audio file stream
+     * @param opts Audio configuration, controls volume and whether to loop
+     */
+    constructor(dataSource: ReadableStream<Uint8Array> | Float32Array[], opts?: IAudioClipOpts, src?: string);
+    private init;
+    /**
+     * Intercept data returned by {@link AudioClip.tick} method for secondary processing of audio data
+     * @param time Time when tick was called
+     * @param tickRet Data returned by tick
+     *
+     * @see [Remove video green screen background](https://webav-tech.github.io/WebAV/demo/3_2-chromakey-video)
+     */
+    tickInterceptor: <T extends Awaited<ReturnType<AudioClip['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): AudioClipJSON;
+    static concatAudioClip: 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: AudioClip[], opts?: IAudioClipOpts): Promise<AudioClip>;
+export {};

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

@@ -0,0 +1,86 @@
+import { BaseSprite } from '../sprite/base-sprite';
+import { IClip, IClipMeta } 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 extends BaseSprite implements IClip {
+    private lastVf;
+    protected destroyed: boolean;
+    /**
+     * Source URL or identifier for this clip
+     * Used for serialization and reloading from JSON
+     */
+    src: string;
+    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;
+    destroy(): void;
+}

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

@@ -0,0 +1,257 @@
+import { BaseClip } from './base-clip';
+import { IClip } from './iclip';
+import { CaptionClipJSON } from '../json-serialization';
+import { Application, Texture } from 'pixi.js';
+export interface ICaptionClipOpts {
+    /**
+     * 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;
+    /**
+     * 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;
+        }>;
+        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;
+    }>;
+    /**
+     * @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'
+     */
+    wordWrap?: boolean;
+    /**
+     * Line height (multiplier)
+     * @default 1
+     */
+    lineHeight?: number;
+    /**
+     * Letter spacing in pixels
+     * @default 0
+     */
+    letterSpacing?: number;
+}
+/**
+ * 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 CaptionClip extends BaseClip implements IClip {
+    ready: IClip['ready'];
+    private _meta;
+    get meta(): {
+        duration: number;
+        width: number;
+        height: number;
+    };
+    /**
+     * Caption text content (hybrid JSON structure)
+     */
+    text: string;
+    get style(): {
+        fontSize?: undefined;
+        fontFamily?: undefined;
+        fontWeight?: undefined;
+        fontStyle?: undefined;
+        color?: undefined;
+        align?: undefined;
+        stroke?: undefined;
+        shadow?: undefined;
+    } | {
+        fontSize: number | undefined;
+        fontFamily: string | undefined;
+        fontWeight: string | undefined;
+        fontStyle: string | undefined;
+        color: string | number | {
+            type: "gradient";
+            x0: number;
+            y0: number;
+            x1: number;
+            y1: number;
+            colors: Array<{
+                ratio: number;
+                color: string | number;
+            }>;
+        } | undefined;
+        align: "center" | "left" | "right" | undefined;
+        stroke: {
+            color: string | number;
+            width: number;
+        } | undefined;
+        shadow: {
+            color: string | number;
+            alpha: number;
+            blur: number;
+            offsetX: number;
+            offsetY: number;
+        } | undefined;
+    };
+    /**
+     * Bottom offset from video bottom (hybrid JSON structure)
+     */
+    bottomOffset?: number;
+    private opts;
+    private pixiTextContainer;
+    private renderTexture;
+    private wordTexts;
+    private extraPadding;
+    private textStyle;
+    private externalRenderer;
+    private pixiApp;
+    private originalOpts;
+    constructor(text: string, opts?: ICaptionClipOpts, renderer?: Application['renderer']);
+    private lastLoggedTime;
+    updateState(currentTime: number): void;
+    /**
+     * Get the PixiJS Texture (RenderTexture) for optimized rendering in Studio
+     * This avoids ImageBitmap → Canvas → Texture conversion
+     *
+     * @returns The RenderTexture containing the rendered caption, or null if not ready
+     */
+    getTexture(): Promise<Texture | null>;
+    /**
+     * 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]>;
+    clone(): Promise<this>;
+    destroy(): void;
+    toJSON(main?: boolean): CaptionClipJSON;
+    /**
+     * Create a CaptionClip instance from a JSON object (fabric.js pattern)
+     * @param json The JSON object representing the clip
+     * @returns Promise that resolves to a CaptionClip instance
+     */
+    static fromObject(json: CaptionClipJSON): Promise<CaptionClip>;
+}

package/dist/clips/iclip.d.ts

@@ -0,0 +1,120 @@
+import { BaseSprite } from '../sprite/base-sprite';
+export interface IClipMeta {
+    width: number;
+    height: number;
+    duration: number;
+}
+/**
+ * Interface that all clips must implement
+ *
+ * Clips are abstractions of different data types, providing data to other modules
+ *
+ * WebAV provides built-in {@link VideoClip}, {@link AudioClip}, {@link ImageClip} and other common clips for providing data to {@link Compositor} and {@link AVCanvas}
+ *
+ * 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
+ * @see [Custom Clip](https://webav-tech.github.io/WebAV/demo/2_6-custom-clip)
+ *
+ */
+export interface IClip extends Omit<BaseSprite, 'destroy' | 'ready'> {
+    destroy: () => void;
+    readonly ready: Promise<IClipMeta>;
+    /**
+     * 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;
+}
+/**
+ * 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;
+}
+/**
+ * Default audio settings, ⚠️ do not change its values ⚠️
+ */
+export declare const DEFAULT_AUDIO_CONF: {
+    readonly sampleRate: 48000;
+    readonly channelCount: 2;
+    readonly codec: "mp4a.40.2";
+};

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

@@ -0,0 +1,110 @@
+import { Texture } from 'pixi.js';
+import { BaseClip } from './base-clip';
+import { IClip } from './iclip';
+import { ClipJSON, ImageClipJSON } 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 ImageClip.fromUrl('path/to/image.png');
+ *
+ * @example
+ * // Traditional approach (for Compositor/export)
+ * new ImageClip((await fetch('<img url>')).body);
+ *
+ * @example
+ * new ImageClip(
+ *   await renderTxt2ImgBitmap(
+ *     'Watermark',
+ *    `font-size:40px; color: white; text-shadow: 2px 2px 6px red;`,
+ *   )
+ * )
+ *
+ * @see [Video composition](https://webav-tech.github.io/WebAV/demo/2_1-concat-video)
+ */
+export declare class ImageClip extends BaseClip {
+    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;
+    /**
+     * 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 ImageClip instance
+     *
+     * @example
+     * const imgClip = await ImageClip.fromUrl('path/to/image.png');
+     */
+    static fromUrl(url: string, src?: string): Promise<ImageClip>;
+    /**
+     * 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<ImageClip['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>;
+    destroy(): void;
+    toJSON(main?: boolean): ImageClipJSON;
+    /**
+     * Create an ImageClip instance from a JSON object (fabric.js pattern)
+     * @param json The JSON object representing the clip
+     * @returns Promise that resolves to an ImageClip instance
+     */
+    static fromObject(json: ClipJSON): Promise<ImageClip>;
+    /**
+     * Scale clip to fit within the scene dimensions while maintaining aspect ratio
+     * Similar to fabric.js scaleToFit
+     * @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. Similar to fabric.js scaleToFill
+     * @param sceneWidth Scene width
+     * @param sceneHeight Scene height
+     */
+    scaleToFill(sceneWidth: number, sceneHeight: number): Promise<void>;
+    /**
+     * Center the clip within the scene dimensions
+     * Similar to fabric.js center
+     * @param sceneWidth Scene width
+     * @param sceneHeight Scene height
+     */
+    centerInScene(sceneWidth: number, sceneHeight: number): void;
+}
+export {};