@video-editor/protocol 0.0.1-beta.26 → 0.0.1-beta.28

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

@@ -20,6 +20,11 @@ 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;
 }): {
@@ -469,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>;
@@ -556,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 {
@@ -569,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 { }