@video-editor/protocol 0.0.1-beta.3 → 0.0.1-beta.31

package/README.md

@@ -1,3 +1,94 @@
-# @video-editor/shared
+# @video-editor/protocol
 
-video editor libs common type
+Video editor protocol management, validation, and resource utilities.
+
+## Features
+
+- **Protocol Management**: Create and manage video editor protocols with undo/redo
+- **Validation**: JSON Schema validation for all segment types
+- **Resource Management**: OPFS-based caching for video/audio resources
+- **Waveform Extraction**: Extract and cache audio waveforms for visualization
+- **Thumbnail Generation**: Extract video thumbnails with caching
+
+## Installation
+
+```bash
+pnpm add @video-editor/protocol
+```
+
+## Quick Start
+
+### Audio Waveform Extraction
+
+```typescript
+import { extractWaveform, peaksToSvgPath } from '@video-editor/protocol'
+
+// Extract waveform from audio URL
+const waveform = await extractWaveform('/audio.mp3', { samples: 1000 })
+
+// Generate SVG path for rendering
+const svgPath = peaksToSvgPath(waveform.peaks, 800, 100)
+
+console.log(waveform.peaks)     // number[] - normalized 0-1
+console.log(waveform.duration)  // number - seconds
+```
+
+### Protocol Management
+
+```typescript
+import { createVideoProtocolManager } from '@video-editor/protocol'
+import type { IVideoProtocol } from '@video-editor/protocol'
+
+const protocol: IVideoProtocol = { /* ... */ }
+const manager = createVideoProtocolManager(protocol)
+
+// Add segment
+manager.addSegment({
+  id: 'audio-1',
+  segmentType: 'audio',
+  url: '/audio.mp3',
+  startTime: 0,
+  endTime: 3000,
+})
+
+// Undo/Redo
+manager.undo()
+manager.redo()
+```
+
+### Resource Caching
+
+```typescript
+import { createResourceManager } from '@video-editor/protocol'
+
+const resourceManager = createResourceManager()
+
+// Add resource to OPFS cache
+await resourceManager.add('/video-editor-res/audio.mp3', audioBlob)
+
+// Read from cache
+const cached = await resourceManager.read('/video-editor-res/audio.mp3')
+```
+
+## Documentation
+
+See [WAVEFORM.md](../../WAVEFORM.md) for detailed waveform API documentation.
+
+## Exports
+
+### Waveform
+- `extractWaveform(url, options)` - Extract waveform from URL
+- `extractWaveformFromBuffer(buffer, cacheKey, options)` - Extract from ArrayBuffer
+- `clearWaveformCache(url?)` - Clear waveform cache
+- `peaksToSvgPath(peaks, width, height)` - Generate SVG path
+- `peaksToBars(peaks, width)` - Generate bar data
+
+### Protocol
+- `createVideoProtocolManager(protocol)` - Create protocol manager
+- `createValidator()` - Create protocol validator
+- `parse(protocolString)` - Parse and validate protocol JSON
+
+### Resources
+- `createResourceManager(dir?)` - Create resource manager
+- `generateThumbnails(url, options)` - Generate video thumbnails
+- `getMp4Meta(url)` - Extract MP4 metadata

package/dist/index.d.ts

@@ -6,8 +6,8 @@ import { IEffectSegment } from '@video-editor/shared';
 import { IFillMode } from '@video-editor/shared';
 import { IFilterSegment } from '@video-editor/shared';
 import { IFramesSegmentUnion } from '@video-editor/shared';
-import { IImageSegment } from '@video-editor/shared';
 import { ISamples } from './fetch';
+import { IStickerSegment } from '@video-editor/shared';
 import { ITextSegment } from '@video-editor/shared';
 import { ITrackType } from '@video-editor/shared';
 import { ITransition } from '@video-editor/shared';
@@ -20,10 +20,17 @@ import { SegmentUnion } from '@video-editor/shared';
 import { TrackTypeMapSegment } from '@video-editor/shared';
 import { TrackUnion } from '@video-editor/shared';
 
+/**
+ * Clear waveform cache for a specific URL or all
+ */
+export declare function clearWaveformCache(url?: string): void;
+
 export declare function createResourceManager(opts?: {
     dir?: string;
 }): {
-    add: (url: string) => Promise<void>;
+    add: (url: string, opts?: {
+        body?: ReadableStream<BufferSource>;
+    }) => Promise<void>;
     get: (url: string) => Promise<void | HTMLImageElement | ISamples[]>;
     remove: (url: string) => Promise<void>;
     clear: () => Promise<void>;
@@ -36,7 +43,7 @@ export declare function createValidator(): {
     };
     verifyFramesSegment: (o: object) => IFramesSegmentUnion;
     verifyTextSegment: (o: object) => ITextSegment;
-    verifyPhotoSegment: (o: object) => IImageSegment;
+    verifyStickerSegment: (o: object) => IStickerSegment;
     verifyAudioSegment: (o: object) => IAudioSegment;
     verifyEffectSegment: (o: object) => IEffectSegment;
     verifyFilterSegment: (o: object) => IFilterSegment;
@@ -45,10 +52,15 @@ export declare function createValidator(): {
     };
     verifySegment: (o: object & {
         segmentType: ITrackType;
-    }) => IFramesSegmentUnion | IAudioSegment | IEffectSegment | IFilterSegment | IImageSegment | ITextSegment;
+    }) => IFramesSegmentUnion | IAudioSegment | IEffectSegment | IFilterSegment | IStickerSegment | ITextSegment;
 };
 
-export declare function createVideoProtocolManager(protocol: IVideoProtocol): {
+export declare function createVideoProtocolManager(protocol: IVideoProtocol, options?: {
+    idFactory?: {
+        segment?: () => string;
+        track?: () => string;
+    };
+}): {
     videoBasicInfo: {
         version: `${number}.${number}.${number}`;
         width: number;
@@ -214,6 +226,9 @@ export declare function createVideoProtocolManager(protocol: IVideoProtocol): {
     readonly [x: string]: never;
     } | null | undefined;
     })[];
+    readonly extra?: {
+    readonly [x: string]: never;
+    } | null | undefined;
     readonly isMain?: boolean | undefined;
     }[];
     text: readonly {
@@ -270,12 +285,15 @@ export declare function createVideoProtocolManager(protocol: IVideoProtocol): {
     readonly [x: string]: never;
     } | null | undefined;
     }[];
+    readonly extra?: {
+    readonly [x: string]: never;
+    } | null | undefined;
     }[];
-    image: readonly {
+    sticker: readonly {
     readonly trackId: string;
-    readonly trackType: "image";
+    readonly trackType: "sticker";
     readonly children: readonly {
-    readonly segmentType: "image";
+    readonly segmentType: "sticker";
     readonly format: "img" | "gif";
     readonly url: string;
     readonly fillMode?: IFillMode | undefined;
@@ -312,6 +330,9 @@ export declare function createVideoProtocolManager(protocol: IVideoProtocol): {
     readonly [x: string]: never;
     } | null | undefined;
     }[];
+    readonly extra?: {
+    readonly [x: string]: never;
+    } | null | undefined;
     }[];
     audio: readonly {
     readonly trackId: string;
@@ -331,6 +352,9 @@ export declare function createVideoProtocolManager(protocol: IVideoProtocol): {
     readonly [x: string]: never;
     } | null | undefined;
     }[];
+    readonly extra?: {
+    readonly [x: string]: never;
+    } | null | undefined;
     }[];
     effect: readonly {
     readonly trackId: string;
@@ -347,6 +371,9 @@ export declare function createVideoProtocolManager(protocol: IVideoProtocol): {
     readonly [x: string]: never;
     } | null | undefined;
     }[];
+    readonly extra?: {
+    readonly [x: string]: never;
+    } | null | undefined;
     }[];
     filter: readonly {
     readonly trackId: string;
@@ -364,19 +391,79 @@ export declare function createVideoProtocolManager(protocol: IVideoProtocol): {
     readonly [x: string]: never;
     } | null | undefined;
     }[];
+    readonly extra?: {
+    readonly [x: string]: never;
+    } | null | undefined;
     }[];
     }>;
     segmentMap: ComputedRef<Record<string, DeepReadonly<SegmentUnion | undefined>>>;
+    protocol: ComputedRef<IVideoProtocol>;
     getSegment: <T extends ITrackType>(id: SegmentUnion["id"], type?: T) => DeepReadonly<TrackTypeMapSegment[T]> | undefined;
-    addSegment: (segment: PartialByKeys<TrackTypeMapSegment[ITrackType], "id">) => string;
-    removeSegment: (id: SegmentUnion["id"]) => boolean;
+    addSegment: (segment: PartialByKeys<TrackTypeMapSegment[ITrackType], "id">, trackId?: string) => {
+        id: string;
+        affectedSegments: SegmentUnion[];
+        affectedTracks: TrackUnion[];
+        createdTracks: TrackUnion[];
+        removedTrackIds: string[];
+    };
+    removeSegment: (id: SegmentUnion["id"]) => {
+        success: boolean;
+        affectedSegments: SegmentUnion[];
+        affectedTracks: TrackUnion[];
+        createdTracks: TrackUnion[];
+        removedTrackIds: string[];
+    };
     updateSegment: <T extends ITrackType>(updater: (segment: TrackTypeMapSegment[T]) => void, id?: string, type?: T) => void;
+    moveSegment: (moveOptions: {
+        segmentId: string;
+        sourceTrackId: string;
+        targetTrackId?: string;
+        startTime: number;
+        endTime: number;
+        isNewTrack?: boolean;
+        newTrackInsertIndex?: number;
+        newTrackId?: string;
+    }) => {
+        success: boolean;
+        affectedSegments: SegmentUnion[];
+        affectedTracks: TrackUnion[];
+        createdTracks: TrackUnion[];
+        removedTrackIds: string[];
+    };
+    resizeSegment: (options: {
+        segmentId: string;
+        trackId: string;
+        startTime: number;
+        endTime: number;
+    }) => {
+        success: boolean;
+        affectedSegments: SegmentUnion[];
+        affectedTracks: TrackUnion[];
+        createdTracks: TrackUnion[];
+        removedTrackIds: string[];
+    };
     exportProtocol: () => IVideoProtocol;
     addTransition: (transition: ITransition, addTime?: number) => boolean;
     removeTransition: (segmentId: string) => boolean;
     updateTransition: (segmentId: string, updater: (transition: ITransition) => void) => boolean;
-    undo: () => void;
-    redo: () => void;
+    replaceTrackId: (oldTrackId: string, newTrackId: string) => boolean;
+    replaceSegmentId: (oldSegmentId: string, newSegmentId: string) => boolean;
+    undo: () => {
+        success: boolean;
+        affectedSegments: SegmentUnion[];
+        affectedTracks: TrackUnion[];
+        createdTracks: TrackUnion[];
+        removedTrackIds: string[];
+        removedSegmentIds: string[];
+    };
+    redo: () => {
+        success: boolean;
+        affectedSegments: SegmentUnion[];
+        affectedTracks: TrackUnion[];
+        createdTracks: TrackUnion[];
+        removedTrackIds: string[];
+        removedSegmentIds: string[];
+    };
     redoCount: ComputedRef<number>;
     undoCount: ComputedRef<number>;
 };
@@ -387,6 +474,17 @@ export declare const DUPLICATE_SEGMENT_ID = "duplicate segment id";
 
 export declare const DUPLICATE_TRACK_ID = "duplicate track id";
 
+/**
+ * Extract waveform peaks from an audio URL
+ * Will try to read from OPFS cache first, then fall back to fetch
+ */
+export declare function extractWaveform(url: string, options?: WaveformOptions): Promise<WaveformData>;
+
+/**
+ * Extract waveform from an ArrayBuffer directly (no fetch needed)
+ */
+export declare function extractWaveformFromBuffer(arrayBuffer: ArrayBuffer, cacheKey: string, options?: Omit<WaveformOptions, 'resourceDir'>): Promise<WaveformData>;
+
 export declare function fileTo(type: IResType): typeof fileToImage | typeof fileToMP4 | (() => Promise<void>) | (() => Promise<void>) | (() => Promise<void>);
 
 declare function fileToImage(file: OPFSToolFile): Promise<HTMLImageElement | undefined>;
@@ -421,6 +519,17 @@ declare interface GenerateThumbnailsOptions {
     resourceDir?: string;
 }
 
+export declare function getMp4Meta(url: string, options?: {
+    resourceDir?: string;
+}): Promise<Mp4Meta>;
+
+/**
+ * Convert a user-provided URL into a stable, OPFS-safe key.
+ * - Removes query/hash so signed URLs map to a single cached entry.
+ * - Avoids `://` and other path-unfriendly sequences by encoding segments.
+ */
+export declare function getResourceKey(url: string): string;
+
 export declare function getResourceType(url: string): Promise<{
     type: IResType;
     totalSize: number;
@@ -446,6 +555,15 @@ export { ITrackType }
 
 export { IVideoProtocol }
 
+declare interface Mp4Meta {
+    durationUs: number;
+    durationMs: number;
+    width: number;
+    height: number;
+    audioSampleRate: number;
+    audioChanCount: number;
+}
+
 declare type OPFSToolFile = ReturnType<typeof file>;
 
 export declare const parse: parseFn;
@@ -454,6 +572,19 @@ declare type parseFn = (videoProtocolStr: string) => object;
 
 declare type PartialByKeys<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
 
+/**
+ * Generate waveform bars data for canvas/div rendering
+ */
+export declare function peaksToBars(peaks: number[], containerWidth: number): Array<{
+    x: number;
+    height: number;
+}>;
+
+/**
+ * Create a simple waveform SVG path from peaks
+ */
+export declare function peaksToSvgPath(peaks: number[], width: number, height: number): string;
+
 export { SegmentUnion }
 
 declare interface Thumbnail {
@@ -467,4 +598,21 @@ export { TrackUnion }
 
 export declare function vFetch(url: string, init?: RequestInit): Promise<Response>;
 
+/**
+ * Extract waveform peaks from audio for visualization
+ */
+export declare interface WaveformData {
+    peaks: number[];
+    duration: number;
+}
+
+export declare interface WaveformOptions {
+    /** Number of samples to extract (default: 100) */
+    samples?: number;
+    /** Channel to use: 0 = left, 1 = right, 'mix' = average (default: 'mix') */
+    channel?: number | 'mix';
+    /** Resource directory for OPFS cache (default: DEFAULT_RESOURCE_DIR) */
+    resourceDir?: string;
+}
+
 export { }