framewebworker 0.1.4 → 0.2.0

package/README.md

@@ -8,13 +8,15 @@
 
 ## Features
 
-- **Trim** any video to a time range
+- **Export segments** from a single source video with `exportClips()`
+- **Merge clips** from multiple source videos with `mergeClips()`
 - **Overlay captions** with built-in style presets (`hormozi`, `modern`, `minimal`, `bold`)
-- **Stitch** multiple clips into one
+- **Parallel rendering** via OffscreenCanvas + Web Workers — automatic on supported browsers
+- **Timing metrics** — per-segment extraction/encoding times, overall FPS throughput
 - **Pluggable renderer backend** (default: ffmpeg.wasm)
 - **Framework-agnostic core** + React hooks (`framewebworker/react`)
 - **TypeScript-first** with full type exports
-- Respects `AbortSignal` for cancellation, reports progress 0–1
+- Respects `AbortSignal` for cancellation
 
 ## Install
 
@@ -22,81 +24,334 @@
 npm install framewebworker @ffmpeg/ffmpeg @ffmpeg/util
 ```
 
-> `@ffmpeg/ffmpeg` and `@ffmpeg/util` are optional peer dependencies required only by the default ffmpeg.wasm backend. If you supply your own backend you don't need them.
+> `@ffmpeg/ffmpeg` and `@ffmpeg/util` are optional peer dependencies required only by the default ffmpeg.wasm backend.
 
-## Quick Start
+---
+
+## Which API should I use?
+
+| | `exportClips()` | `mergeClips()` |
+|---|---|---|
+| **Source videos** | One URL, multiple time ranges | Multiple clips, each with its own source |
+| **Best for** | Highlight reels, chapter exports, clip editors | Joining footage from different files |
+| **Video loading** | Loads the source once, seeks per segment | Loads each source independently |
+| **React hook** | `useExportClips(videoUrl, segments)` | `useMergeClips(fw)` |
+
+Both produce a single concatenated MP4 `Blob` and return `RenderMetrics`.
+
+---
+
+## `exportClips()` — One video, multiple time segments
+
+Use this when you're exporting multiple time ranges from the **same source file**.
 
 ```ts
-import { createFrameWorker } from 'framewebworker';
+import { exportClips } from 'framewebworker';
+import type { Segment, ExportOptions } from 'framewebworker';
+
+const segments: Segment[] = [
+  { start: 10, end: 25 },
+  { start: 42, end: 58 },
+  { start: 90, end: 110 },
+];
+
+const { blob, metrics } = await exportClips(
+  'https://example.com/interview.mp4',
+  segments,
+  {
+    width: 1280,
+    height: 720,
+    fps: 30,
+    onProgress: ({ overall, clips }) => {
+      console.log(`Overall: ${Math.round(overall * 100)}%`);
+      clips.forEach(c => console.log(`  segment ${c.index}: ${c.status}`));
+    },
+    onComplete: (m) => {
+      console.log(`Done in ${m.totalMs.toFixed(0)}ms — ${m.framesPerSecond.toFixed(1)} fps`);
+    },
+  }
+);
 
-const fw = createFrameWorker();
+const url = URL.createObjectURL(blob);
+```
+
+### With per-segment captions
 
-const blob = await fw.render({
-  source: 'https://example.com/my-video.mp4',
-  startTime: 5,
-  endTime: 15,
-  captions: {
-    segments: [
-      { text: 'Hello world', startTime: 0, endTime: 3 },
-      { text: 'This is FrameWorker', startTime: 3, endTime: 5 },
+Caption timestamps are absolute (matching the source video timeline):
+
+```ts
+import { exportClips } from 'framewebworker';
+import type { Segment } from 'framewebworker';
+
+const segments: Segment[] = [
+  {
+    start: 0,
+    end: 8,
+    captions: [
+      { text: 'Welcome back', startTime: 0, endTime: 3 },
+      { text: 'Today we cover...', startTime: 3, endTime: 8 },
     ],
-    style: { preset: 'hormozi' },
   },
-}, {
-  width: 1280,
-  height: 720,
-  fps: 30,
-  onProgress: (p) => console.log(`${Math.round(p * 100)}%`),
+  {
+    start: 45,
+    end: 60,
+    captions: [
+      { text: 'The key insight', startTime: 45, endTime: 52 },
+    ],
+  },
+];
+
+const { blob } = await exportClips('https://example.com/video.mp4', segments, {
+  width: 1080,
+  height: 1920, // 9:16 portrait
 });
+```
 
-const url = URL.createObjectURL(blob);
+### `exportClipsToUrl()`
+
+Convenience wrapper that returns an object URL directly:
+
+```ts
+import { exportClipsToUrl } from 'framewebworker';
+
+const { url, metrics } = await exportClipsToUrl(
+  'https://example.com/video.mp4',
+  [{ start: 5, end: 30 }]
+);
+
+videoElement.src = url;
 ```
 
-## React Example
+---
 
-```tsx
+## `mergeClips()` — Multiple source videos
+
+Use this when joining clips from **different source files** via a `FrameWorker` instance.
+
+```ts
 import { createFrameWorker } from 'framewebworker';
-import { useRender } from 'framewebworker/react';
+import type { ClipSource } from 'framewebworker';
 
 const fw = createFrameWorker();
 
-export function ExportButton({ videoFile }: { videoFile: File }) {
-  const { render, isRendering, progress, url, error } = useRender(fw);
-
-  const handleExport = async () => {
-    await render({
-      source: videoFile,
-      startTime: 0,
-      endTime: 30,
-      captions: {
-        segments: [{ text: 'My Clip', startTime: 0, endTime: 5 }],
-        style: { preset: 'modern' },
-      },
-    });
-  };
+const clips: ClipSource[] = [
+  { source: fileA, startTime: 0,  endTime: 10 },
+  { source: fileB, startTime: 5,  endTime: 20 },
+  { source: fileC, startTime: 12, endTime: 25 },
+];
+
+const { blob, metrics } = await fw.mergeClips(clips, {
+  width: 1920,
+  height: 1080,
+  onProgress: ({ overall }) => console.log(`${Math.round(overall * 100)}%`),
+  onComplete: (m) => console.log(`${m.framesPerSecond.toFixed(1)} fps`),
+});
+```
+
+### `mergeClipsToUrl()`
+
+```ts
+const { url, metrics } = await fw.mergeClipsToUrl(clips, { width: 1280, height: 720 });
+videoElement.src = url;
+```
+
+---
+
+## React hooks
+
+Import from `framewebworker/react`.
+
+### `useExportClips` — single video, multiple segments
+
+```tsx
+import { useExportClips } from 'framewebworker/react';
+import type { Segment } from 'framewebworker';
+
+const segments: Segment[] = [
+  { start: 10, end: 25 },
+  { start: 60, end: 80 },
+];
+
+export function HighlightExporter({ videoUrl }: { videoUrl: string }) {
+  const { start, cancel, isRendering, progress, metrics, url, error } = useExportClips(
+    videoUrl,
+    segments,
+    { width: 1280, height: 720, fps: 30 }
+  );
 
   return (
     <div>
-      <button onClick={handleExport} disabled={isRendering}>
-        {isRendering ? `Exporting… ${Math.round(progress * 100)}%` : 'Export MP4'}
+      <button onClick={start} disabled={isRendering}>
+        {isRendering
+          ? `Rendering… ${Math.round((progress?.overall ?? 0) * 100)}%`
+          : 'Export'}
       </button>
+      <button onClick={cancel} disabled={!isRendering}>Cancel</button>
+
+      {metrics && (
+        <p>
+          Done in {(metrics.totalMs / 1000).toFixed(1)}s —{' '}
+          {metrics.framesPerSecond.toFixed(1)} fps
+        </p>
+      )}
       {error && <p style={{ color: 'red' }}>{error.message}</p>}
-      {url && <a href={url} download="clip.mp4">Download</a>}
+      {url && <a href={url} download="highlight.mp4">Download</a>}
+    </div>
+  );
+}
+```
+
+`useExportClips` signature:
+
+```ts
+function useExportClips(
+  videoUrl: string | null,
+  segments: Segment[],
+  options?: Omit<ExportOptions, 'onProgress' | 'onComplete' | 'signal'>
+): {
+  start: () => void;
+  cancel: () => void;
+  isRendering: boolean;
+  progress: RichProgress | null;
+  metrics: RenderMetrics | null;
+  url: string | null;
+  error: Error | null;
+}
+```
+
+Passing `null` as `videoUrl` disables the hook; `start()` is a no-op until it is set.
+
+### `useMergeClips` — multiple source clips
+
+```tsx
+import { createFrameWorker } from 'framewebworker';
+import { useMergeClips } from 'framewebworker/react';
+
+const fw = createFrameWorker();
+
+export function MergePanel() {
+  const { mergeClips, isRendering, progress, metrics, url } = useMergeClips(fw);
+
+  const handleExport = () =>
+    mergeClips([
+      { source: fileA, startTime: 0, endTime: 10 },
+      { source: fileB, startTime: 5, endTime: 20 },
+    ]);
+
+  return (
+    <div>
+      <button onClick={handleExport} disabled={isRendering}>Export</button>
+      {progress && <progress value={progress.overall} />}
+      {metrics && <p>{metrics.framesPerSecond.toFixed(1)} fps</p>}
+      {url && <a href={url} download="output.mp4">Download</a>}
     </div>
   );
 }
 ```
 
-## Stitch Multiple Clips
+### `usePreviewClip` — single clip via FrameWorker instance
+
+For rendering a single `ClipSource` through a `FrameWorker` instance:
+
+```tsx
+import { createFrameWorker } from 'framewebworker';
+import { usePreviewClip } from 'framewebworker/react';
+import type { ClipSource } from 'framewebworker';
+
+const fw = createFrameWorker();
+
+export function ClipPreview({ file }: { file: File }) {
+  const { render, isRendering, progress, url } = usePreviewClip(fw);
+
+  const clip: ClipSource = { source: file, startTime: 0, endTime: 30 };
+
+  return (
+    <button onClick={() => render(clip)} disabled={isRendering}>
+      {isRendering ? `${Math.round(progress * 100)}%` : 'Preview clip'}
+    </button>
+  );
+}
+```
+
+---
+
+## `RenderMetrics` — timing output
+
+Both `exportClips()` and `mergeClips()` resolve with `{ blob, metrics }`. `onComplete` also receives the same object.
+
+```ts
+interface RenderMetrics {
+  totalMs: number;         // wall-clock time for the entire operation
+  extractionMs: number;    // sum of all segment/clip frame-extraction times
+  encodingMs: number;      // sum of all segment/clip ffmpeg encoding times
+  stitchMs: number;        // time for the final ffmpeg concat pass
+  framesPerSecond: number; // total frames / (totalMs / 1000)
+  clips: ClipMetrics[];    // one entry per segment or clip
+}
+
+interface ClipMetrics {
+  clipId: string;          // segment index (as string)
+  extractionMs: number;
+  encodingMs: number;
+  totalMs: number;         // extractionMs + encodingMs
+  framesExtracted: number;
+}
+```
+
+Example output for a three-segment export:
 
 ```ts
-const blob = await fw.stitch([
-  { source: fileA, startTime: 0, endTime: 10 },
-  { source: fileB, startTime: 5, endTime: 20 },
-  { source: fileC },
-], { width: 1920, height: 1080 });
+{
+  totalMs: 4820,
+  extractionMs: 3100,
+  encodingMs: 1600,
+  stitchMs: 120,
+  framesPerSecond: 94.2,
+  clips: [
+    { clipId: '0', extractionMs: 980,  encodingMs: 510, totalMs: 1490, framesExtracted: 450 },
+    { clipId: '1', extractionMs: 1050, encodingMs: 560, totalMs: 1610, framesExtracted: 480 },
+    { clipId: '2', extractionMs: 1070, encodingMs: 530, totalMs: 1600, framesExtracted: 510 },
+  ]
+}
 ```
 
+---
+
+## `ExportOptions` / `MergeOptions`
+
+`ExportOptions` is accepted by `exportClips()` / `exportClipsToUrl()` / `useExportClips()`.
+`MergeOptions` is accepted by `mergeClips()` / `mergeClipsToUrl()` / `useMergeClips()`.
+Both have identical fields:
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `width` | `number` | `1280` | Output width in pixels |
+| `height` | `number` | `720` | Output height in pixels |
+| `fps` | `number` | `30` | Frames per second |
+| `mimeType` | `string` | `'video/mp4'` | Output MIME type |
+| `quality` | `number` | `0.92` | Quality 0–1 (non-ffmpeg backends) |
+| `encoderOptions` | `Record<string, unknown>` | — | Extra options passed to the backend |
+| `signal` | `AbortSignal` | — | Cancellation signal |
+| `onProgress` | `(p: RichProgress) => void` | — | Called on every frame batch |
+| `onComplete` | `(m: RenderMetrics) => void` | — | Called once when the final blob is ready |
+
+`RichProgress` shape:
+
+```ts
+interface RichProgress {
+  overall: number;       // 0–1 weighted average across all segments/clips
+  clips: ClipProgress[];
+}
+
+interface ClipProgress {
+  index: number;
+  status: 'pending' | 'rendering' | 'encoding' | 'done' | 'error';
+  progress: number; // 0–1
+}
+```
+
+---
+
 ## Caption Style Presets
 
 | Preset | Description |
@@ -119,51 +374,29 @@ captions: {
 }
 ```
 
-## BYOB: Bring Your Own Backend
+---
 
-Implement the `RendererBackend` interface to use any encoder:
+## `createFrameWorker` API reference
 
 ```ts
-import type { RendererBackend, FrameData, EncodeOptions } from 'framewebworker';
-
-const myBackend: RendererBackend = {
-  name: 'my-encoder',
-  async init() {
-    // load WASM, warm up workers, etc.
-  },
-  async encode(frames: FrameData[], opts: EncodeOptions): Promise<Blob> {
-    // frames is FrameData[] with .imageData (ImageData), .timestamp, .width, .height
-    // return a video Blob
-  },
-  async concat(blobs: Blob[], opts: EncodeOptions): Promise<Blob> {
-    // concatenate multiple video Blobs
-  },
-};
+import { createFrameWorker } from 'framewebworker';
 
-const fw = createFrameWorker({ backend: myBackend });
+const fw = createFrameWorker({
+  backend: myBackend, // optional, defaults to ffmpeg.wasm
+  fps: 30,
+  width: 1280,
+  height: 720,
+});
 ```
 
-## API Reference
-
-### `createFrameWorker(config?)`
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `backend` | `RendererBackend` | ffmpeg.wasm | Encoder backend |
-| `fps` | `number` | `30` | Default frame rate |
-| `width` | `number` | `1280` | Default output width |
-| `height` | `number` | `720` | Default output height |
-
-Returns a `FrameWorker` object:
-
 | Method | Signature | Description |
 |--------|-----------|-------------|
-| `render` | `(clip, opts?) => Promise<Blob>` | Render one clip |
+| `mergeClips` | `(clips[], opts?) => Promise<{ blob, metrics }>` | Merge multiple `ClipSource`s |
+| `mergeClipsToUrl` | `(clips[], opts?) => Promise<{ url, metrics }>` | Merge + create object URL |
+| `render` | `(clip, opts?) => Promise<Blob>` | Render a single `ClipSource` (preview use) |
 | `renderToUrl` | `(clip, opts?) => Promise<string>` | Render + create object URL |
-| `stitch` | `(clips[], opts?) => Promise<Blob>` | Render + concat clips |
-| `stitchToUrl` | `(clips[], opts?) => Promise<string>` | Stitch + create object URL |
 
-### `ClipInput`
+### `ClipSource`
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -175,50 +408,67 @@ Returns a `FrameWorker` object:
 | `aspectRatio` | `AspectRatio` | `'16:9' \| '9:16' \| '1:1' \| '4:3' \| '3:4' \| 'original'` |
 | `volume` | `number` | Volume multiplier 0–2 |
 
-### `RenderOptions`
+### `Segment`
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `width` | `number` | Output width in pixels |
-| `height` | `number` | Output height in pixels |
-| `fps` | `number` | Frames per second |
-| `mimeType` | `string` | Output MIME type |
-| `quality` | `number` | Quality 0–1 (non-ffmpeg backends) |
-| `onProgress` | `(p: number) => void` | Progress callback 0–1 |
-| `signal` | `AbortSignal` | Cancellation signal |
+| `start` | `number` | Start time in seconds (absolute, within the source video) |
+| `end` | `number` | End time in seconds |
+| `captions` | `CaptionSegment[]` | Captions to overlay (timestamps are absolute) |
 
-### React Hooks (`framewebworker/react`)
+---
 
-#### `useRender(frameWorker)`
+## BYOB: Bring Your Own Backend
 
 ```ts
-const { progress, isRendering, error, blob, url, render, cancel, reset } = useRender(fw);
-```
+import type { RendererBackend, FrameData, EncodeOptions } from 'framewebworker';
 
-#### `useStitch(frameWorker)`
+const myBackend: RendererBackend = {
+  name: 'my-encoder',
+  async init() { /* load WASM, warm up workers, etc. */ },
+  async encode(frames: FrameData[], opts: EncodeOptions): Promise<Blob> {
+    // frames[].imageData (ImageData), .timestamp, .width, .height
+  },
+  async concat(blobs: Blob[], opts: EncodeOptions): Promise<Blob> { /* ... */ },
+};
 
-```ts
-const { progress, isRendering, error, blob, url, stitch, cancel, reset } = useStitch(fw);
+const fw = createFrameWorker({ backend: myBackend });
 ```
 
-Both hooks expose:
-- `progress` — number 0–1
-- `isRendering` — boolean
-- `error` — `Error | null`
-- `blob` — the output `Blob | null`
-- `url` — `string | null` (object URL, auto-revoked on next render)
-- `cancel()` — abort the current render
-- `reset()` — clear state and revoke URL
+---
+
+## Migration from v0.1
+
+| v0.1 | v0.2 | Notes |
+|------|------|-------|
+| `render(videoUrl, segments)` | `exportClips(videoUrl, segments)` | Deprecated alias kept |
+| `renderToUrl(videoUrl, segments)` | `exportClipsToUrl(videoUrl, segments)` | Deprecated alias kept |
+| `fw.stitch(clips)` | `fw.mergeClips(clips)` | Deprecated alias kept on FrameWorker |
+| `fw.stitchToUrl(clips)` | `fw.mergeClipsToUrl(clips)` | Deprecated alias kept on FrameWorker |
+| `useRender(videoUrl, segments)` | `useExportClips(videoUrl, segments)` | Deprecated alias kept |
+| `useStitch(fw)` | `useMergeClips(fw)` | Deprecated alias kept |
+| `useClipRender(fw)` | `usePreviewClip(fw)` | Deprecated alias kept |
+| `StitchOptions` | `MergeOptions` | Deprecated type alias kept |
+| `SingleVideoRenderOptions` | `ExportOptions` | Deprecated type alias kept |
+| `ClipInput` | `ClipSource` | Deprecated type alias kept |
+
+All v0.1 names emit a `@deprecated` JSDoc warning in editors but continue to work. They will be removed in v0.3.
+
+---
 
 ## Browser Requirements
 
-- Chrome/Edge 94+ or Firefox 90+ (OffscreenCanvas, WASM)
+- Chrome/Edge 94+ or Firefox 90+ (OffscreenCanvas, Web Workers, WASM)
 - COOP/COEP headers required for ffmpeg.wasm SharedArrayBuffer:
   ```
   Cross-Origin-Opener-Policy: same-origin
   Cross-Origin-Embedder-Policy: require-corp
   ```
 
+Browsers without `OffscreenCanvas` or `Worker` support fall back to sequential single-threaded rendering automatically.
+
+---
+
 ## License
 
 MIT © nareshipme

package/dist/index.cjs

@@ -528,7 +528,7 @@ var WorkerPool = class {
     this.available = [];
     this.waiters = [];
     for (let i = 0; i < maxConcurrency; i++) {
-      const w = new Worker(new URL("./render-worker.js", (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href))), { type: "module" });
+      const w = new Worker(new URL("./worker/render-worker.js", (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href))), { type: "module" });
       this.workers.push(w);
       this.available.push(w);
     }
@@ -864,16 +864,18 @@ function segmentsToClips(videoUrl, segments) {
     captions: seg.captions?.length ? { segments: seg.captions } : void 0
   }));
 }
-async function render(videoUrl, segments, options) {
+async function exportClips(videoUrl, segments, options) {
   const clips = segmentsToClips(videoUrl, segments);
   const backend = createFFmpegBackend();
   await backend.init();
   return stitchClips(clips, backend, options ?? {});
 }
-async function renderToUrl(videoUrl, segments, options) {
-  const { blob, metrics } = await render(videoUrl, segments, options);
+async function exportClipsToUrl(videoUrl, segments, options) {
+  const { blob, metrics } = await exportClips(videoUrl, segments, options);
   return { url: URL.createObjectURL(blob), metrics };
 }
+var render = exportClips;
+var renderToUrl = exportClipsToUrl;
 
 // src/index.ts
 function createFrameWorker(config = {}) {
@@ -912,21 +914,32 @@ function createFrameWorker(config = {}) {
     const blob = await render2(clip, options);
     return URL.createObjectURL(blob);
   }
-  async function stitch(clips, options = {}) {
+  async function mergeClips(clips, options = {}) {
     const mergedOpts = { fps, width, height, ...options };
     const backend = await getBackend();
     return stitchClips(clips, backend, mergedOpts);
   }
-  async function stitchToUrl(clips, options) {
-    const { blob, metrics } = await stitch(clips, options);
+  async function mergeClipsToUrl(clips, options) {
+    const { blob, metrics } = await mergeClips(clips, options);
     return { url: URL.createObjectURL(blob), metrics };
   }
-  return { render: render2, renderToUrl: renderToUrl2, stitch, stitchToUrl };
+  return {
+    render: render2,
+    renderToUrl: renderToUrl2,
+    mergeClips,
+    mergeClipsToUrl,
+    /** @deprecated Use mergeClips() */
+    stitch: mergeClips,
+    /** @deprecated Use mergeClipsToUrl() */
+    stitchToUrl: mergeClipsToUrl
+  };
 }
 
 exports.STYLE_PRESETS = STYLE_PRESETS;
 exports.createFFmpegBackend = createFFmpegBackend;
 exports.createFrameWorker = createFrameWorker;
+exports.exportClips = exportClips;
+exports.exportClipsToUrl = exportClipsToUrl;
 exports.render = render;
 exports.renderToUrl = renderToUrl;
 //# sourceMappingURL=index.cjs.map