@designcombo/video 0.0.0

package/dist/internal-utils/event-tool.d.ts

@@ -0,0 +1,50 @@
+type EventKey = string | symbol;
+type EventToolType = Record<EventKey, (...args: any[]) => any>;
+/**
+ * Event utility class
+ *
+ * @example
+ * const evtTool = new EventTool<{
+ *   timeupdate: (time: number) => void;
+ *   paused: () => void;
+ *   playing: () => void;
+ * }>()
+ * evtTool.on('paused', () => {})
+ * evtTool.emit('paused')
+ */
+export declare class EventTool<T extends EventToolType> {
+    /**
+     * Forward messages between two EventTool instances
+     * @param from
+     * @param to
+     * @param evtTypes Message types that need to be forwarded
+     *
+     * @example
+     * EventTool.forwardEvent(from, to, ['evtName']),
+     */
+    static forwardEvent<T1 extends EventToolType, T2 extends EventToolType, EvtType extends (keyof T1 | [keyof T1, keyof T2])[]>(from: {
+        on: EventTool<T1>['on'];
+    }, to: {
+        emit: EventTool<T2>['emit'];
+    }, evtTypes: EvtType): () => void;
+    private listeners;
+    /**
+     * Listen to events defined in EventType
+     */
+    on: <Type extends keyof T>(type: Type, listener: T[Type]) => (() => void);
+    /**
+     * Listen to event, automatically remove listener after first trigger
+     *
+     * For events that expect to callback once, use once; for events that expect multiple callbacks use on
+     */
+    once: <Type extends keyof T>(type: Type, listener: T[Type]) => (() => void);
+    /**
+     * Emit event
+     * @param type
+     * @param args
+     * @returns
+     */
+    emit: <Type extends keyof T>(type: Type, ...args: Type extends string ? T[Type] extends (...args: any[]) => any ? Parameters<T[Type]> : never : never) => void;
+    destroy(): void;
+}
+export {};

package/dist/internal-utils/index.d.ts

@@ -0,0 +1,14 @@
+export { EventTool } from './event-tool';
+export { Log } from './log';
+export { recodemux } from './recodemux';
+export { autoReadStream, file2stream } from './stream-utils';
+export { workerTimer } from './worker-timer';
+/**
+ * 函数节流
+ */
+export declare function throttle<F extends (...args: any[]) => any>(func: F, wait: number): (...rest: Parameters<F>) => undefined | ReturnType<F>;
+/**
+ * 函数防抖
+ * 在指定时间内多次调用，只执行最后一次
+ */
+export declare function debounce<F extends (...args: any[]) => any>(func: F, wait: number): (...rest: Parameters<F>) => void;

package/dist/internal-utils/log.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 全局日志对象，将日志内容写入 OPFS 临时文件
+ */
+export declare const Log: {
+    /**
+     * 生成一个 log 实例，所有输出前都会附加 tag
+     *
+     * @example
+     * const log = Log.create('<prefix>')
+     * log.info('xxx') // '<prefix> xxx'
+     */
+    create: (tag: string) => {
+        [k: string]: (...args: any[]) => void;
+    };
+    /**
+     * 将所有日志导出为一个字符串
+     *
+     * @example
+     * Log.dump() // => [level][time]  内容...
+     *
+     */
+    dump(): Promise<string>;
+    debug: (...data: any[]) => void;
+    info: (...data: any[]) => void;
+    warn: (...data: any[]) => void;
+    error: (...data: any[]) => void;
+    /**
+     * 设置记录日志的级别
+     *
+     * @example
+     * Log.setLogLevel(Log.warn) // 记录 warn，error 日志
+     */
+    setLogLevel: <T extends Function>(logfn: T) => void;
+};

package/dist/internal-utils/meta-box.d.ts

@@ -0,0 +1 @@
+export declare const createMetaBox: (data: Record<string, string>) => Uint8Array;

package/dist/internal-utils/recodemux.d.ts

@@ -0,0 +1,65 @@
+import { MP4File } from '@webav/mp4box.js';
+type CleanFn = () => void;
+/**
+ * Configuration options for recodemux function
+ */
+interface RecodeMuxOpts {
+    /**
+     * Video configuration options, if null then video is not processed
+     */
+    video: {
+        width: number;
+        height: number;
+        expectFPS: number;
+        codec: string;
+        bitrate: number;
+        /**
+         * Unsafe, may be deprecated at any time
+         */
+        __unsafe_hardwareAcceleration__?: HardwareAcceleration;
+    } | null;
+    /**
+     * Audio configuration options, if null then audio is not processed
+     */
+    audio: {
+        codec: 'opus' | 'aac';
+        sampleRate: number;
+        channelCount: number;
+    } | null;
+    /**
+     * Preset duration, does not represent actual track duration
+     */
+    duration?: number;
+    metaDataTags?: Record<string, string>;
+}
+/**
+ * Handle audio and video encoding and decoding
+ * @param opts - Configuration for encoding audio and video data
+ */
+export declare function recodemux(opts: RecodeMuxOpts): {
+    /**
+     * Encode video frame
+     */
+    encodeVideo: (frame: VideoFrame, options: VideoEncoderEncodeOptions, gopId?: number) => void;
+    /**
+     * Encode audio data
+     */
+    encodeAudio: (data: AudioData) => void;
+    /**
+     * Close encoder, stop task
+     */
+    close: CleanFn;
+    /**
+     * Flush encoder queue
+     */
+    flush: () => Promise<void>;
+    /**
+     * mp4box instance
+     */
+    mp4file: MP4File;
+    /**
+     * Returns queue length (backpressure), used to control video production progress, excessive queue will占用大量显存
+     */
+    getEncodeQueueSize: () => number;
+};
+export {};

package/dist/internal-utils/stream-utils.d.ts

@@ -0,0 +1,43 @@
+import { MP4File } from '@webav/mp4box.js';
+/**
+ * 自动读取流并处理每个数据块。
+ *
+ * @template ST - 可读流的类型。
+ * @param stream - 要读取的流。
+ * @param cbs - 回调函数对象。
+ * @param cbs.onChunk - 当读取到新的数据块时调用的函数。该函数接收一个参数，即数据块，并返回一个 Promise。
+ * @param cbs.onDone - 当读取完所有数据块时调用的函数。
+ * @returns - 返回一个函数，调用该函数可以停止读取流。
+ *
+ * @example
+ * const stream = getSomeReadableStream();
+ * const onChunk = async (chunk) => {
+ *   console.log('New chunk:', chunk);
+ * };
+ * const onDone = () => {
+ *   console.log('Done reading stream');
+ * };
+ * const stopReading = autoReadStream(stream, { onChunk, onDone });
+ * // Later...
+ * stopReading();
+ */
+export declare function autoReadStream<ST extends ReadableStream>(stream: ST, cbs: {
+    onChunk: ST extends ReadableStream<infer DT> ? (chunk: DT) => Promise<void> : never;
+    onDone: () => void;
+}): () => void;
+/**
+ * 将 mp4box file 转换为文件流，用于上传服务器或存储到本地
+ * @param file - MP4 文件实例 {@link MP4File}。
+ * @param timeSlice - 时间片，用于控制流的发送速度。
+ * @param onCancel - 当返回的流被取消时触发该回调函数
+ */
+export declare function file2stream(file: MP4File, timeSlice: number, onCancel?: () => void): {
+    /**
+     * 可读流，流的数据是 `Uint8Array`
+     */
+    stream: ReadableStream<Uint8Array>;
+    /**
+     * 流的生产者主动停止向流中输出数据，可向消费者传递错误信息
+     */
+    stop: (err?: Error) => void;
+};

package/dist/internal-utils/worker-timer.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 专门解决页面长时间处于后台时，定时器不（或延迟）执行的问题
+ *
+ * 跟 `setInterval` 很相似，⚠️ 但 time 会有一定偏差，请优先使用 `setInterval`
+ *
+ * @see [JS 定时器时长控制细节](https://hughfenghen.github.io/posts/2023/06/15/timer-delay/)
+ */
+export declare const workerTimer: (handler: () => void, time: number) => (() => void);

package/dist/json-serialization.d.ts

@@ -0,0 +1,142 @@
+import { IClip } from './clips';
+interface BaseClipJSON {
+    src: string;
+    display: {
+        from: number;
+        to: number;
+    };
+    playbackRate: number;
+    duration: number;
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+    angle: number;
+    zIndex: number;
+    opacity: number;
+    flip: 'horizontal' | 'vertical' | null;
+    animation?: {
+        keyFrames: Record<string, Partial<{
+            x: number;
+            y: number;
+            w: number;
+            h: number;
+            angle: number;
+            opacity: number;
+        }>>;
+        opts: {
+            duration: number;
+            delay?: number;
+            iterCount?: number;
+        };
+    };
+    main?: boolean;
+}
+export interface VideoClipJSON extends BaseClipJSON {
+    type: 'Video';
+    audio?: boolean;
+}
+export interface AudioClipJSON extends BaseClipJSON {
+    type: 'Audio';
+    loop?: boolean;
+    volume?: number;
+}
+export interface ImageClipJSON extends BaseClipJSON {
+    type: 'Image';
+}
+export interface TextStyleJSON {
+    fontSize?: number;
+    fontFamily?: string;
+    fontWeight?: number;
+    fontStyle?: string;
+    color?: string;
+    align?: 'left' | 'center' | 'right';
+    fontUrl?: string;
+    stroke?: {
+        color: string;
+        width: number;
+    };
+    shadow?: {
+        color: string;
+        alpha: number;
+        blur: number;
+        offsetX: number;
+        offsetY: number;
+    };
+}
+export interface TextClipJSON extends BaseClipJSON {
+    type: 'Text';
+    text: string;
+    style?: TextStyleJSON;
+}
+export interface CaptionColorsJSON {
+    appeared?: string;
+    active?: string;
+    activeFill?: string;
+    background?: string;
+    keyword?: string;
+}
+export interface CaptionPositioningJSON {
+    bottomOffset?: number;
+    videoWidth?: number;
+    videoHeight?: number;
+}
+export interface CaptionDataJSON {
+    words?: Array<{
+        text: string;
+        from: number;
+        to: number;
+        isKeyWord: boolean;
+    }>;
+    colors?: CaptionColorsJSON;
+    preserveKeywordColor?: boolean;
+    positioning?: CaptionPositioningJSON;
+}
+export interface CaptionClipJSON extends BaseClipJSON {
+    type: 'Caption';
+    text: string;
+    style?: TextStyleJSON;
+    caption?: CaptionDataJSON;
+    bottomOffset?: number;
+    words?: Array<{
+        text: string;
+        from: number;
+        to: number;
+        isKeyWord: boolean;
+    }>;
+    appearedColor?: string;
+    activeColor?: string;
+    activeFillColor?: string;
+    backgroundColor?: string;
+    isKeyWordColor?: string;
+    preservedColorKeyWord?: boolean;
+    videoWidth?: number;
+    videoHeight?: number;
+    fontUrl?: string;
+}
+export type ClipJSON = VideoClipJSON | AudioClipJSON | ImageClipJSON | TextClipJSON | CaptionClipJSON;
+export interface ProjectJSON {
+    clips: ClipJSON[];
+    settings?: {
+        width?: number;
+        height?: number;
+        fps?: number;
+        bgColor?: string;
+        videoCodec?: string;
+        bitrate?: number;
+        audio?: boolean;
+        metaDataTags?: Record<string, string>;
+    };
+}
+/**
+ * Serialize a clip to JSON format
+ * @param clip The clip to serialize
+ * @param main Whether this is the main clip (for Compositor)
+ */
+export declare function clipToJSON(clip: IClip, main?: boolean): ClipJSON;
+/**
+ * Deserialize JSON to a clip instance
+ * Uses fromObject static method if available (fabric.js pattern), otherwise falls back to manual construction
+ */
+export declare function jsonToClip(json: ClipJSON): Promise<IClip>;
+export {};

package/dist/mp4-utils/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Quick concatenate multiple MP4 file streams, requires all MP4s to have consistent properties,
+ * properties include (but not limited to): audio/video codec format, resolution, sample rate
+ *
+ * @param streams An array of readable streams containing Uint8Array.
+ * @returns Returns a Promise that resolves to a readable stream containing merged MP4 data.
+ * @throws Will throw error if unable to generate file from streams.
+ *
+ * @example
+ * const streams = [stream1, stream2, stream3];
+ * const resultStream = await fastConcatMP4(streams);
+ */
+export declare function fastConcatMP4(streams: ReadableStream<Uint8Array>[]): Promise<ReadableStream<Uint8Array>>;
+/**
+ * Set correct duration value for fMP4 files generated by WebAV
+ */
+export declare function fixFMP4Duration(stream: ReadableStream<Uint8Array>): Promise<ReadableStream<Uint8Array>>;
+/**
+ * Video dubbing; mix MP4 with audio file, only re-encode audio, video track unchanged
+ * @param mp4Stream - MP4 stream
+ * @param audio - Audio information
+ * @param audio.stream - Audio data stream
+ * @param audio.volume - Audio volume
+ * @param audio.loop - When audio duration is less than video, whether to loop audio stream
+ * @returns Output mixed audio stream
+ */
+export declare function mixinMP4AndAudio(mp4Stream: ReadableStream<Uint8Array>, audio: {
+    stream: ReadableStream<Uint8Array>;
+    volume: number;
+    loop: boolean;
+}): ReadableStream<Uint8Array<ArrayBufferLike>>;

package/dist/mp4-utils/mp4box-utils.d.ts

@@ -0,0 +1,36 @@
+import { AudioTrackOpts, MP4File, MP4Info, MP4Sample, VideoTrackOpts } from '@webav/mp4box.js';
+import { file } from 'opfs-tools';
+export declare function extractFileConfig(file: MP4File, info: MP4Info): {
+    videoTrackConf?: VideoTrackOpts;
+    videoDecoderConf?: Parameters<VideoDecoder["configure"]>[0];
+    audioTrackConf?: AudioTrackOpts;
+    audioDecoderConf?: Parameters<AudioDecoder["configure"]>[0];
+};
+/**
+ * Quick parse mp4 file, if not fMP4 format, will prioritize parsing moov box (skip mdat) to avoid excessive memory usage
+ */
+export declare function quickParseMP4File(reader: Awaited<ReturnType<ReturnType<typeof file>['createReader']>>, onReady: (data: {
+    mp4boxFile: MP4File;
+    info: MP4Info;
+}) => void, onSamples: (id: number, sampleType: 'video' | 'audio', samples: MP4Sample[]) => void): Promise<void>;
+export declare function parseMatrix(matrix?: Int32Array): {
+    scaleX?: undefined;
+    scaleY?: undefined;
+    rotationRad?: undefined;
+    rotationDeg?: undefined;
+    translateX?: undefined;
+    translateY?: undefined;
+    perspective?: undefined;
+} | {
+    scaleX: number;
+    scaleY: number;
+    rotationRad: number;
+    rotationDeg: number;
+    translateX: number;
+    translateY: number;
+    perspective: number;
+};
+/**
+ * Rotate VideoFrame
+ */
+export declare function createVFRotater(width: number, height: number, rotationDeg: number): (vf: VideoFrame | null) => VideoFrame | null;

package/dist/mp4-utils/sample-transform.d.ts

@@ -0,0 +1,23 @@
+import { MP4File, MP4Info, MP4Sample } from '@webav/mp4box.js';
+/**
+ * Transform raw byte stream into MP4Sample stream
+ */
+export declare class SampleTransform {
+    readable: ReadableStream<{
+        chunkType: 'ready';
+        data: {
+            info: MP4Info;
+            file: MP4File;
+        };
+    } | {
+        chunkType: 'samples';
+        data: {
+            id: number;
+            type: 'video' | 'audio';
+            samples: MP4Sample[];
+        };
+    }>;
+    writable: WritableStream<Uint8Array>;
+    private inputBufOffset;
+    constructor();
+}

package/dist/sprite/base-sprite.d.ts

@@ -0,0 +1,147 @@
+type IRectBaseProps = any;
+interface IAnimationOpts {
+    duration: number;
+    delay?: number;
+    iterCount?: number;
+}
+type TAnimateProps = IRectBaseProps & {
+    opacity: number;
+};
+export type TAnimationKeyFrame = Array<[number, Partial<TAnimateProps>]>;
+type TKeyFrameOpts = Partial<Record<`${number}%` | 'from' | 'to', Partial<TAnimateProps>>>;
+/**
+ * Sprite base class
+ *
+ * @see {@link OffscreenSprite}
+ */
+export declare abstract class BaseSprite {
+    /**
+     * Control display time range of clips, commonly used in editing scenario timeline (track) module
+     * from: start time offset in microseconds
+     * to: end time (from + duration) in microseconds
+     */
+    display: {
+        from: number;
+        to: number;
+    };
+    /**
+     * Duration of the clip in microseconds
+     * Cannot exceed the duration of the referenced {@link IClip}
+     */
+    duration: number;
+    /**
+     * Playback rate of current clip, 1 means normal playback
+     * **Note**
+     *    1. When setting playbackRate, duration must be actively corrected
+     *    2. Audio uses the simplest interpolation algorithm to change rate, so changing rate will cause pitch variation, for custom algorithm please use {@link VideoClip.tickInterceptor} to implement
+     */
+    playbackRate: number;
+    private evtTool;
+    /**
+     * Listen to property change events
+     * @example
+     * sprite.on('propsChange', (changedProps) => {})
+     */
+    on: <Type extends "propsChange">(type: Type, listener: {
+        propsChange: (value: Partial<{
+            left: number;
+            top: number;
+            width: number;
+            height: number;
+            angle: number;
+            zIndex: number;
+        }>) => void;
+    }[Type]) => (() => void);
+    private _left;
+    /**
+     * Left position (x coordinate)
+     */
+    get left(): number;
+    set left(v: number);
+    private _top;
+    /**
+     * Top position (y coordinate)
+     */
+    get top(): number;
+    set top(v: number);
+    private _width;
+    /**
+     * Width
+     */
+    get width(): number;
+    set width(v: number);
+    private _height;
+    /**
+     * Height
+     */
+    get height(): number;
+    set height(v: number);
+    private _angle;
+    /**
+     * Rotation angle
+     * @see [MDN Canvas rotate](https://developer.mozilla.org/docs/Web/API/CanvasRenderingContext2D/rotate)
+     */
+    get angle(): number;
+    set angle(v: number);
+    /**
+     * Center point calculated from position and dimensions
+     */
+    get center(): {
+        x: number;
+        y: number;
+    };
+    private _zIndex;
+    get zIndex(): number;
+    /**
+     * Control layering relationship between clips, clips with smaller zIndex will be occluded
+     */
+    set zIndex(v: number);
+    /**
+     * Opacity
+     */
+    opacity: number;
+    /**
+     * Flip clip horizontally or vertically
+     */
+    flip: 'horizontal' | 'vertical' | null;
+    private animatKeyFrame;
+    private animatOpts;
+    /**
+     * @see {@link IClip.ready}
+     * For clips, this should be Promise<IClipMeta>, but for BaseSprite it's just Promise<void>
+     */
+    ready: Promise<any>;
+    constructor();
+    protected _render(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D): void;
+    /**
+     * Add animation to clip, usage reference CSS animation
+     *
+     * @example
+     * sprite.setAnimation(
+     *   {
+     *     '0%': { x: 0, y: 0 },
+     *     '25%': { x: 1200, y: 680 },
+     *     '50%': { x: 1200, y: 0 },
+     *     '75%': { x: 0, y: 680 },
+     *     '100%': { x: 0, y: 0 },
+     *   },
+     *   { duration: 4e6, iterCount: 1 },
+     * );
+     *
+     * @see [Video watermark animation](https://webav-tech.github.io/WebAV/demo/2_1-concat-video)
+     */
+    setAnimation(keyFrame: TKeyFrameOpts, opts: IAnimationOpts): void;
+    /**
+     * If current sprite has animation set, set sprite's animation properties to state at specified time
+     */
+    animate(time: number): void;
+    /**
+     * Copy current sprite's properties to target
+     *
+     * Used for cloning or copying state between {@link OffscreenSprite} instances
+     */
+    copyStateTo<T extends BaseSprite>(target: T): void;
+    protected destroy(): void;
+}
+export declare function linearTimeFn(time: number, keyFrame: TAnimationKeyFrame, opts: Required<IAnimationOpts>): Partial<TAnimateProps>;
+export {};

package/dist/sprite/pixi-sprite-renderer.d.ts

@@ -0,0 +1,48 @@
+import { Application, Sprite, Texture } from 'pixi.js';
+import { IClip } from '../clips/iclip';
+/**
+ * Update sprite transform based on clip properties
+ * Utility function for updating standalone sprites (e.g., video sprites from HTMLVideoElement)
+ * For sprites managed by PixiSpriteRenderer, use renderer.updateTransforms() instead
+ */
+export declare function updateSpriteTransform(clip: IClip, sprite: Sprite): void;
+/**
+ * Renders video frames using Pixi.js
+ * Uses a canvas-based approach: draws frames to a canvas and creates texture from it
+ * This matches the pattern used in other video rendering libraries
+ */
+export declare class PixiSpriteRenderer {
+    private pixiApp;
+    private sprite;
+    private pixiSprite;
+    private texture;
+    private canvas;
+    private context;
+    private destroyed;
+    constructor(pixiApp: Application, sprite: IClip);
+    /**
+     * Update the sprite with a new video frame or Texture
+     * @param frame ImageBitmap, Texture, or null to render
+     *              (VideoFrames are converted to ImageBitmap in getFrame)
+     */
+    updateFrame(frame: ImageBitmap | Texture | null): Promise<void>;
+    /**
+     * Apply sprite transformations to the Pixi Sprite
+     * This reads the current sprite properties (which may have been updated by animations)
+     * and applies them to the Pixi sprite
+     */
+    private applySpriteTransforms;
+    /**
+     * Update sprite properties without changing the frame
+     * Useful when sprite properties change but frame stays the same
+     */
+    updateTransforms(): void;
+    /**
+     * Get the Pixi Sprite instance
+     */
+    getSprite(): Sprite | null;
+    /**
+     * Destroy the renderer and clean up resources
+     */
+    destroy(): void;
+}