melies-video-editor 0.1.5 → 0.1.7

package/dist/types/App.d.ts

@@ -0,0 +1,102 @@
+import './index.less';
+import type { CusTomTimelineRow } from './mock';
+import type { FootageItem } from './footageBin';
+export type MeliesVideoEditorProps = {
+    /**
+     * URLs (often blob: URLs) to show in the footage bin.
+     * When omitted or empty, the footage bin will be empty.
+     */
+    footageUrls?: string[];
+    /**
+     * Local Files to show in the footage bin.
+     *
+     * This is ideal for OPFS (Base44 can load from OPFS and pass `File`s here).
+     */
+    footageFiles?: File[];
+    /**
+     * Handle-like objects (e.g. `FileSystemFileHandle`) that can yield `File`s.
+     *
+     * We intentionally avoid depending on `FileSystemFileHandle` directly so
+     * consumers without that DOM lib type can still compile.
+     */
+    footageFileHandles?: Array<{
+        getFile: () => Promise<File>;
+        name?: string;
+    }>;
+    /**
+     * When true, automatically place `footageUrls` onto the timeline on first initialization
+     * (one after another, starting at t=0).
+     *
+     * Defaults to false.
+     */
+    autoPlaceFootage?: boolean;
+    /**
+     * Optional initial timeline snapshot (e.g. loaded from your DB).
+     *
+     * Note: if you store `blob:` URLs in the snapshot, they will not be valid across sessions.
+     * Prefer storing stable asset ids and rehydrating to playable URLs before loading.
+     */
+    initialTimelineSnapshot?: MeliesTimelineSnapshot;
+    /**
+     * Called whenever timeline state changes.
+     *
+     * Consumers should debounce/throttle this callback when persisting to a DB.
+     */
+    onTimelineStateChange?: (snapshot: MeliesTimelineSnapshot) => void;
+    /**
+     * Fired when the user imports files into the footage bin.
+     *
+     * This exposes the actual `File` objects to the host app (for upload/OPFS/storage).
+     * Note: imported `blob:` URLs are session-only; hosts should persist and rehydrate using
+     * stable asset identifiers if they need cross-session restore.
+     */
+    onFootageImported?: (event: MeliesFootageImportEvent) => void;
+};
+export type MeliesFootageImportEntry = {
+    /** The bin item added to the footage bin. */
+    item: FootageItem;
+    /** The underlying file selected by the user. */
+    file: File;
+};
+export type MeliesFootageImportEvent = {
+    /** Pairs each created bin item to its underlying file. */
+    entries: MeliesFootageImportEntry[];
+    /** Convenience list of items. */
+    items: FootageItem[];
+    /** Convenience list of files. */
+    files: File[];
+};
+export type MeliesTimelineSnapshot = {
+    /** Bump this when snapshot schema changes. */
+    version: 1;
+    /** Timeline rows/actions data (seconds). */
+    editorData: CusTomTimelineRow[];
+    /** UI selection (optional to restore). */
+    selectedActionId: string | null;
+    /** UI zoom (optional to restore). */
+    timelineScaleWidth: number;
+};
+export type MeliesVideoEditorRef = {
+    /**
+     * Get a deep-cloned snapshot of the current timeline state.
+     * Safe to store/mutate externally.
+     */
+    getTimelineSnapshot: () => MeliesTimelineSnapshot;
+    /**
+     * Load a snapshot into the editor.
+     * Resets undo/redo history.
+     */
+    setTimelineSnapshot: (snapshot: MeliesTimelineSnapshot) => void;
+    /**
+     * Get the imported `File` for a given footage item id (only for user-imported items).
+     * Returns null if the id was not imported this session.
+     */
+    getImportedFileByFootageId: (footageId: string) => File | null;
+    /** List all imported files currently known to the editor (this session). */
+    listImportedFiles: () => Array<{
+        footageId: string;
+        file: File;
+    }>;
+};
+declare const MeliesVideoEditor: import("react").ForwardRefExoticComponent<MeliesVideoEditorProps & import("react").RefAttributes<MeliesVideoEditorRef>>;
+export default MeliesVideoEditor;

package/dist/types/appVersion.d.ts

@@ -0,0 +1,2 @@
+/** Compile-time version string injected by Vite (from package.json). */
+export declare const APP_VERSION: string;

package/dist/types/audioControl.d.ts

@@ -0,0 +1,29 @@
+import type { TimelineEngine } from '@xzdarcy/react-timeline-editor';
+declare class AudioControl {
+    private howlBySrc;
+    private activeByActionId;
+    private getHowl;
+    /**
+     * Ensure the underlying WebAudio context is resumed.
+     *
+     * Some browsers (notably iOS Safari) block audio playback until a user gesture
+     * resumes the AudioContext. Timeline engine callbacks may occur outside the
+     * original gesture call stack, so we explicitly unlock in the toolbar handler.
+     */
+    unlock(): void;
+    warm(src: string): void;
+    private seekForEngineTime;
+    start(data: {
+        actionId: string;
+        engine: TimelineEngine;
+        src: string;
+        startTime: number;
+        time: number;
+        offset?: number;
+    }): void;
+    stop(data: {
+        actionId: string;
+    }): void;
+}
+declare const _default: AudioControl;
+export default _default;

package/dist/types/custom.d.ts

@@ -0,0 +1,14 @@
+import type { FC } from 'react';
+import type { CustomTimelineAction, CusTomTimelineRow } from './mock';
+export declare const CustomRender0: FC<{
+    action: CustomTimelineAction;
+    row: CusTomTimelineRow;
+}>;
+export declare const CustomRender1: FC<{
+    action: CustomTimelineAction;
+    row: CusTomTimelineRow;
+}>;
+export declare const CustomRender2: FC<{
+    action: CustomTimelineAction;
+    row: CusTomTimelineRow;
+}>;

package/dist/types/dev/DevRoot.d.ts

@@ -0,0 +1,5 @@
+import './devRoot.css';
+export default function DevRoot({ defaultFootageUrls, useHostShell, }: {
+    defaultFootageUrls?: string[];
+    useHostShell: boolean;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/types/dev/HostApp.d.ts

@@ -0,0 +1,8 @@
+export default function HostApp({ footageUrls, footageFiles, footageFileHandles, }: {
+    footageUrls?: string[];
+    footageFiles?: File[];
+    footageFileHandles?: Array<{
+        getFile: () => Promise<File>;
+        name?: string;
+    }>;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/types/dev/opfs.d.ts

@@ -0,0 +1,35 @@
+type OpfsRoot = FileSystemDirectoryHandle;
+type Maybe<T> = T | null | undefined;
+export type OpfsSupport = {
+    supported: boolean;
+    reason?: string;
+};
+/**
+ * Best-effort OPFS capability check.
+ *
+ * Notes:
+ * - Many browsers require a secure context (HTTPS); desktop browsers often treat localhost as secure.
+ * - Some mobile browsers may not implement OPFS at all.
+ */
+export declare const getOpfsSupport: () => OpfsSupport;
+export declare const ensureOpfsRoot: () => Promise<OpfsRoot>;
+export declare const ensureDir: (root: OpfsRoot, path: string) => Promise<FileSystemDirectoryHandle>;
+export declare const writeBlobToOpfs: (opts: {
+    root: OpfsRoot;
+    dirPath: string;
+    fileName: string;
+    blob: Blob;
+}) => Promise<{
+    fileHandle: FileSystemFileHandle;
+    path: string;
+}>;
+export declare const clearDir: (opts: {
+    root: OpfsRoot;
+    dirPath: string;
+}) => Promise<void>;
+export declare const listFiles: (opts: {
+    root: OpfsRoot;
+    dirPath: string;
+}) => Promise<FileSystemFileHandle[]>;
+export declare const getFileFromPublicUrl: (url: string, fallbackName?: Maybe<string>) => Promise<File>;
+export {};

package/dist/types/footageBin.d.ts

@@ -0,0 +1,12 @@
+export type FootageItem = {
+    id: string;
+    kind: 'video' | 'audio';
+    name: string;
+    src: string;
+    /** Optional lower-res/proxy source for smooth preview playback. */
+    previewSrc?: string;
+    defaultDuration?: number;
+};
+export declare const FOOTAGE_BIN: FootageItem[];
+export declare const VIDEO_ITEMS: FootageItem[];
+export declare const AUDIO_ITEMS: FootageItem[];

package/dist/types/index.d.ts

@@ -0,0 +1 @@
+import 'antd/dist/antd.css';

package/dist/types/lib/index.d.ts

@@ -0,0 +1,3 @@
+export { default as MeliesVideoEditor } from '../App';
+export type { MeliesFootageImportEntry, MeliesFootageImportEvent, MeliesTimelineSnapshot, MeliesVideoEditorProps, MeliesVideoEditorRef, } from '../App';
+export type { TimelineAction, TimelineEffect, TimelineRow, TimelineState, } from '@xzdarcy/react-timeline-editor';

package/dist/types/lottieControl.d.ts

@@ -0,0 +1,28 @@
+import { type AnimationItem } from 'lottie-web';
+declare class LottieControl {
+    cacheMap: Record<string, AnimationItem>;
+    private _goToAndStop;
+    enter(data: {
+        id: string;
+        src: string;
+        startTime: number;
+        endTime: number;
+        time: number;
+    }): void;
+    update(data: {
+        id: string;
+        src: string;
+        startTime: number;
+        endTime: number;
+        time: number;
+    }): void;
+    leave(data: {
+        id: string;
+        startTime: number;
+        endTime: number;
+        time: number;
+    }): void;
+    destroy(): void;
+}
+declare const _default: LottieControl;
+export default _default;

package/dist/types/mediaCache.d.ts

@@ -0,0 +1,50 @@
+type MediaKind = 'video' | 'audio' | 'other';
+declare const guessKind: (src: string) => MediaKind;
+declare class MediaCache {
+    private blobUrlBySrc;
+    private pendingBySrc;
+    private metaBySrc;
+    private durationSecBySrc;
+    private pendingDurationBySrc;
+    registerSrcMeta(src: string, meta: {
+        name?: string;
+        mimeType?: string;
+    }): void;
+    getSrcMeta(src: string): {
+        name?: string;
+        mimeType?: string;
+    } | undefined;
+    /** Returns the cached duration (seconds) if known. */
+    getCachedDurationSec(src: string): number | undefined;
+    /**
+     * Attempts to read media duration from browser metadata (seconds).
+     * Returns null when duration cannot be determined (e.g. unsupported/CORS/streaming).
+     */
+    getDurationSec(src: string, kindHint?: MediaKind): Promise<number | null>;
+    /**
+     * Preloads a URL into memory and returns a blob: URL.
+     * Useful to avoid runtime buffering/stalls when seeking frequently.
+     */
+    preloadToBlobUrl(src: string): Promise<string>;
+    /** Returns a blob URL if available, otherwise the original `src`. */
+    resolve(src: string): string;
+    /** Starts preload in background (non-blocking). */
+    warm(src: string): void;
+    /**
+     * Preload a list of srcs with bounded concurrency.
+     *
+     * This is useful when you know ahead of time which assets will be scrubbed/seeked,
+     * so we can eliminate network stalls during interaction.
+     */
+    warmAll(srcs: Iterable<string>, opts?: {
+        /** Maximum number of concurrent fetches. Defaults to 3. */
+        concurrency?: number;
+        /** Yield back to the event loop between items. Defaults to true. */
+        yieldBetween?: boolean;
+    }): Promise<void>;
+    /** Convenience: preload all unique action.data.src from editor data. */
+    warmFromEditorData(editorData: unknown): void;
+}
+declare const mediaCache: MediaCache;
+export default mediaCache;
+export { guessKind };

package/dist/types/mock.d.ts

@@ -0,0 +1,25 @@
+import type { TimelineAction, TimelineEffect, TimelineRow } from '@xzdarcy/react-timeline-editor';
+export declare const scaleWidth = 160;
+export declare const scale = 5;
+export declare const startLeft = 20;
+export interface CustomTimelineAction extends TimelineAction {
+    data: {
+        src: string;
+        previewSrc?: string;
+        name: string;
+        /** Video lane index (0=V1, 1=V2). Higher value wins when overlapping. */
+        videoLayer?: number;
+        /** Shared id for clips that should move/trim together (e.g. video + its embedded audio). */
+        linkId?: string;
+        /**
+         * In-point offset into the underlying media (seconds).
+         * Used for split clips so the right segment continues from the correct time.
+         */
+        offset?: number;
+    };
+}
+export interface CusTomTimelineRow extends TimelineRow {
+    actions: CustomTimelineAction[];
+}
+export declare const mockEffect: Record<string, TimelineEffect>;
+export declare const mockData: CusTomTimelineRow[];

package/dist/types/player.d.ts

@@ -0,0 +1,18 @@
+import type { TimelineState } from '@xzdarcy/react-timeline-editor';
+export declare const Rates: number[];
+declare const TimelinePlayer: ({ timelineState, autoScrollWhenPlay, scale, scaleWidth, startLeft, editorData, selectedActionId, onDeleteSelectedClip, onSplitSelectedClip, canUndo, canRedo, onUndo, onRedo, }: {
+    timelineState: React.MutableRefObject<TimelineState | null>;
+    autoScrollWhenPlay: React.MutableRefObject<boolean>;
+    scale: number;
+    scaleWidth: number;
+    startLeft: number;
+    editorData: any[];
+    selectedActionId: string | null;
+    onDeleteSelectedClip: () => void;
+    onSplitSelectedClip: () => void;
+    canUndo: boolean;
+    canRedo: boolean;
+    onUndo: () => void;
+    onRedo: () => void;
+}) => import("react/jsx-runtime").JSX.Element;
+export default TimelinePlayer;

package/dist/types/useCoarsePointer.d.ts

@@ -0,0 +1 @@
+export declare function useCoarsePointer(): boolean;

package/dist/types/videoControl.d.ts

@@ -0,0 +1,91 @@
+import type { TimelineEngine, TimelineRow } from '@xzdarcy/react-timeline-editor';
+declare class VideoControl {
+    private primaryEl;
+    private secondaryEl;
+    private activeEl;
+    private rowData;
+    private boundEngine;
+    private vfcHandle;
+    private rafHandle;
+    private isPlaying;
+    private playbackRate;
+    private lastVideoClip;
+    private lastKnownTime;
+    constructor();
+    /**
+     * Called by App.tsx to provide the two video elements.
+     */
+    attachPrimary(el: HTMLVideoElement | null): void;
+    attachSecondary(el: HTMLVideoElement | null): void;
+    /**
+     * Helper to set initial styling/events for video elements.
+     */
+    private initElement;
+    /**
+     * Deprecated single-element attach, mapped to primary for safety.
+     */
+    attach(el: HTMLVideoElement | null): void;
+    /**
+     * Called by App.tsx whenever timeline data changes.
+     */
+    setEditorData(data: TimelineRow[]): void;
+    /**
+     * We use claimVideo to drive the dual-buffer logic from the engine's time updates.
+     * This ensures we sync to the engine's clock (Slave Mode).
+     */
+    claimVideo(data: {
+        isPlaying?: boolean;
+        time?: number;
+        [key: string]: unknown;
+    }): void;
+    bindEngine(engine: TimelineEngine): void;
+    unbindEngine(): void;
+    private startLoop;
+    private stopLoop;
+    /**
+     * The main heart beat.
+     * - If playing: sync engine time to video time.
+     * - Always: Check schedule (what should be playing vs preloading).
+     */
+    private tickLoop;
+    /**
+     * Evaluate the timeline at `time` (and `time + lookahead`).
+     * Manage Primary/Secondary elements.
+     */
+    private updateState;
+    private makeActive;
+    private loadVideo;
+    private isLoaded;
+    private findClipAtTime;
+    private findNextVideoClipStartAfter;
+    private findNextVideoClipAfter;
+    play(): void;
+    pause(): void;
+    setRate(rate: number): void;
+    seek(time: number): void;
+    warm(src: string): void;
+    releaseVideo(_actionId: string): void;
+    setActive(_active: boolean): void;
+    /**
+     * Returns the active (visible) video element, if any.
+     * Useful for UI-level logic that needs to wait for buffering after a seek.
+     */
+    getActiveVideoElement(): HTMLVideoElement | null;
+    /**
+     * Checks whether a video has at least `minSecondsAhead` buffered at its current time.
+     *
+     * Note: buffered ranges are in media time, not timeline time.
+     */
+    private hasBufferedAhead;
+    /**
+     * Waits until the active element appears ready for smooth playback after a seek.
+     * Returns true if the readiness criteria is met before timing out.
+     */
+    waitForActiveBufferedAhead(opts?: {
+        minSecondsAhead?: number;
+        timeoutMs?: number;
+        pollMs?: number;
+    }): Promise<boolean>;
+}
+declare const _default: VideoControl;
+export default _default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "melies-video-editor",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "A React video timeline editor GUI built on @xzdarcy/react-timeline-editor.",
   "type": "module",
   "license": "MIT",