@twick/browser-render 0.15.6 → 0.15.8

package/README.md

@@ -46,19 +46,21 @@ a.click();
 import { useBrowserRenderer } from '@twick/browser-render';
 
 function VideoRenderer() {
-  const { render, progress, isRendering, videoBlob, download } = useBrowserRenderer({
-    width: 1920,
-    height: 1080,
-    fps: 30,
-    autoDownload: false
-  });
+  const { render, progress, isRendering, videoBlob, download, error, reset } =
+    useBrowserRenderer({
+      width: 720,
+      height: 1280,
+      fps: 30,
+      includeAudio: true,   // enable audio rendering + FFmpeg mux
+      autoDownload: true,   // auto-download final MP4
+    });
 
   const handleRender = async () => {
     await render({
       input: {
-        properties: { width: 1920, height: 1080, fps: 30 },
-        tracks: [/* ... */]
-      }
+        properties: { width: 720, height: 1280, fps: 30 },
+        tracks: [/* ... */],
+      },
     });
   };
 
@@ -69,6 +71,12 @@ function VideoRenderer() {
       </button>
       {isRendering && <progress value={progress} max={1} />}
       {videoBlob && <button onClick={download}>Download</button>}
+      {error && (
+        <div>
+          <p>{error.message}</p>
+          <button onClick={reset}>Clear error</button>
+        </div>
+      )}
     </div>
   );
 }
@@ -92,6 +100,9 @@ function VideoRenderer() {
     fps?: number;            // Frames per second (default: 30)
     quality?: 'low' | 'medium' | 'high';
     range?: [number, number]; // [start, end] in seconds
+    includeAudio?: boolean;  // Enable audio rendering and muxing (default: false)
+    downloadAudioSeparately?: boolean; // Also download audio.wav when muxing fails
+    onAudioReady?: (audioBlob: Blob) => void; // Callback when raw audio is ready
     onProgress?: (progress: number) => void;
     onComplete?: (videoBlob: Blob) => void;
     onError?: (error: Error) => void;
@@ -112,15 +123,16 @@ const videoBlob = await renderTwickVideoInBrowser({
 
 **Note**: String paths only work in Node.js. In the browser, you must import and pass the Project object directly.
 
-## WASM Setup
+## WASM and public assets
 
-Copy the WASM file to your public directory:
+The package ships `public/` with `mp4-wasm.wasm` and `audio-worker.js`. Copy them into your app's public directory so they are served:
 
 ```bash
-cp node_modules/mp4-wasm/dist/mp4-wasm.wasm public/
+cp node_modules/@twick/browser-render/public/mp4-wasm.wasm public/
+cp node_modules/@twick/browser-render/public/audio-worker.js public/
 ```
 
-Or configure Vite to serve it:
+Alternatively, configure your bundler (e.g. Vite) to serve WASM:
 
 ```typescript
 // vite.config.ts
@@ -129,23 +141,49 @@ export default defineConfig({
 });
 ```
 
+### FFmpeg audio/video muxing (optional)
+
+When `settings.includeAudio` is enabled, `@twick/browser-render` will render audio in the browser and (by default) try to mux it into the final MP4 using `@ffmpeg/ffmpeg`.  
+To match the setup used in `@twick/examples`, you should:
+
+1. Install the FFmpeg packages:
+
+```bash
+npm install @ffmpeg/ffmpeg @ffmpeg/util @ffmpeg/core
+```
+
+2. Expose the FFmpeg core files from your app’s `public` folder so they are available at:
+
+```text
+/public/ffmpeg/ffmpeg-core.js
+/public/ffmpeg/ffmpeg-core.wasm
+```
+
+For example, you can copy them from `node_modules/@ffmpeg/core/dist`:
+
+```bash
+mkdir -p public/ffmpeg
+cp node_modules/@ffmpeg/core/dist/ffmpeg-core.js public/ffmpeg/
+cp node_modules/@ffmpeg/core/dist/ffmpeg-core.wasm public/ffmpeg/
+```
+
+In the browser, the muxer loads these files from `${window.location.origin}/ffmpeg`, so the URLs must match that structure.  
+If FFmpeg cannot be loaded, the renderer will fall back to returning a video-only file and (optionally) downloading `audio.wav` separately when `downloadAudioSeparately` is true.
+
 ## Limitations
 
-- **Audio**: Audio processing is not yet implemented. Only video encoding is supported.
+- **Audio**: Audio rendering and FFmpeg-based muxing run entirely in the browser and are still considered experimental. If FFmpeg assets are not available, only video will be muxed and audio may be downloaded as a separate file.
 - **Browser Support**: Requires WebCodecs API (Chrome 94+, Edge 94+)
 
-## API Comparison
+## License
 
-This package follows the same API as the server renderer (`@twick/renderer`):
+This package is licensed under the **Sustainable Use License (SUL) Version 1.0**.
 
-| Feature | Server | Browser |
-|---------|--------|---------|
-| Duration Calculation | `renderer.getNumberOfFrames()` | ✅ Same |
-| Playback State | `PlaybackState.Rendering` | ✅ Same |
-| Frame Progression | `playback.progress()` | ✅ Same |
-| Variables Assignment | `project.variables = {...}` | ✅ Same |
-| Audio Support | ✅ FFmpeg | ❌ Not yet |
+- Free for use in commercial and non-commercial apps
+- Can be modified and self-hosted
+- Cannot be sold, rebranded, or distributed as a standalone SDK
 
-## License
+For commercial licensing inquiries, contact: contact@kifferai.com
+
+For full license terms, see the main LICENSE.md file in the project root.
 
-MIT

package/dist/index.d.mts

@@ -0,0 +1,225 @@
+import { Project } from '@twick/core';
+
+/**
+ * Browser rendering configuration
+ */
+interface BrowserRenderConfig {
+    /**
+     * Custom Project object
+     * If not provided, defaults to @twick/visualizer project
+     *
+     * Note: Must be an imported Project object, not a string path.
+     * String paths only work in Node.js environments (server renderer).
+     *
+     * Example:
+     * ```typescript
+     * import myProject from './my-custom-project';
+     *
+     * await renderTwickVideoInBrowser({
+     *   projectFile: myProject,
+     *   variables: { input: {...} }
+     * });
+     * ```
+     */
+    projectFile?: Project;
+    /** Input variables containing project configuration */
+    variables: {
+        input: any;
+        playerId?: string;
+        [key: string]: any;
+    };
+    /** Render settings */
+    settings?: {
+        width?: number;
+        height?: number;
+        fps?: number;
+        quality?: 'low' | 'medium' | 'high';
+        range?: [number, number];
+        includeAudio?: boolean;
+        downloadAudioSeparately?: boolean;
+        onAudioReady?: (audioBlob: Blob) => void;
+        onProgress?: (progress: number) => void;
+        onComplete?: (videoBlob: Blob) => void;
+        onError?: (error: Error) => void;
+    };
+}
+/**
+ * Renders a Twick video directly in the browser without requiring a server.
+ * Uses WebCodecs API for encoding video frames into MP4 format.
+ *
+ * This function uses the same signature as the server renderer for consistency.
+ *
+ * @param config - Configuration object containing variables and settings
+ * @param config.projectFile - Optional project file path or Project object (defaults to visualizer project)
+ * @param config.variables - Variables containing input configuration (tracks, elements, etc.)
+ * @param config.settings - Optional render settings (width, height, fps, etc.)
+ * @returns Promise resolving to a Blob containing the rendered video
+ *
+ * @example
+ * ```js
+ * import { renderTwickVideoInBrowser } from '@twick/browser-render';
+ *
+ * // Using default visualizer project
+ * const videoBlob = await renderTwickVideoInBrowser({
+ *   variables: {
+ *     input: {
+ *       properties: { width: 1920, height: 1080, fps: 30 },
+ *       tracks: [
+ *         // Your tracks configuration
+ *       ]
+ *     }
+ *   },
+ *   settings: {
+ *     width: 1920,
+ *     height: 1080,
+ *     fps: 30,
+ *     quality: 'high',
+ *     onProgress: (progress) => console.log(`Rendering: ${progress * 100}%`),
+ *   }
+ * });
+ *
+ * // Using custom project
+ * import myProject from './my-custom-project';
+ * const videoBlob = await renderTwickVideoInBrowser({
+ *   projectFile: myProject, // Must be an imported Project object
+ *   variables: { input: {...} },
+ *   settings: {...}
+ * });
+ *
+ * // Download the video
+ * const url = URL.createObjectURL(videoBlob);
+ * const a = document.createElement('a');
+ * a.href = url;
+ * a.download = 'video.mp4';
+ * a.click();
+ * URL.revokeObjectURL(url);
+ * ```
+ */
+declare const renderTwickVideoInBrowser: (config: BrowserRenderConfig) => Promise<Blob>;
+/**
+ * Helper function to download a video blob as a file
+ *
+ * @param videoBlob - The video blob to download
+ * @param filename - The desired filename (default: 'video.mp4')
+ *
+ * @example
+ * ```js
+ * const blob = await renderTwickVideoInBrowser(projectData);
+ * downloadVideoBlob(blob, 'my-video.mp4');
+ * ```
+ */
+declare const downloadVideoBlob: (videoBlob: Blob, filename?: string) => void;
+
+interface UseBrowserRendererOptions {
+    /**
+     * Custom Project object
+     * If not provided, defaults to @twick/visualizer project
+     *
+     * Note: Must be an imported Project object, not a string path.
+     * String paths only work in Node.js (server renderer).
+     *
+     * Example:
+     * ```typescript
+     * import myProject from './my-custom-project';
+     * useBrowserRenderer({ projectFile: myProject })
+     * ```
+     */
+    projectFile?: any;
+    /** Video width in pixels */
+    width?: number;
+    /** Video height in pixels */
+    height?: number;
+    /** Frames per second */
+    fps?: number;
+    /** Render quality */
+    quality?: 'low' | 'medium' | 'high';
+    /** Time range to render [start, end] in seconds */
+    range?: [number, number];
+    /** Include audio in rendered video (experimental) */
+    includeAudio?: boolean;
+    /** Download audio separately as WAV file */
+    downloadAudioSeparately?: boolean;
+    /** Callback when audio is ready */
+    onAudioReady?: (audioBlob: Blob) => void;
+    /** Automatically download the video when rendering completes */
+    autoDownload?: boolean;
+    /** Default filename for downloads */
+    downloadFilename?: string;
+}
+interface UseBrowserRendererReturn {
+    /** Start rendering the video */
+    render: (variables: BrowserRenderConfig['variables']) => Promise<Blob | null>;
+    /** Current rendering progress (0-1) */
+    progress: number;
+    /** Whether rendering is in progress */
+    isRendering: boolean;
+    /** Error if rendering failed */
+    error: Error | null;
+    /** The rendered video blob (available after rendering completes) */
+    videoBlob: Blob | null;
+    /** Download the rendered video */
+    download: (filename?: string) => void;
+    /** Reset the renderer state */
+    reset: () => void;
+}
+/**
+ * React hook for rendering Twick videos in the browser
+ *
+ * Uses the same pattern as the server renderer for consistency.
+ *
+ * @param options - Rendering options
+ * @returns Renderer state and control functions
+ *
+ * @example
+ * ```tsx
+ * import { useBrowserRenderer } from '@twick/browser-render';
+ *
+ * // Using default visualizer project
+ * function MyComponent() {
+ *   const { render, progress, isRendering, videoBlob, download } = useBrowserRenderer({
+ *     width: 1920,
+ *     height: 1080,
+ *     fps: 30,
+ *     autoDownload: true,
+ *   });
+ *
+ *   const handleRender = async () => {
+ *     await render({
+ *       input: {
+ *         properties: { width: 1920, height: 1080, fps: 30 },
+ *         tracks: [
+ *           // Your tracks configuration
+ *         ]
+ *       }
+ *     });
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={handleRender} disabled={isRendering}>
+ *         {isRendering ? `Rendering... ${(progress * 100).toFixed(0)}%` : 'Render Video'}
+ *       </button>
+ *       {videoBlob && !autoDownload && (
+ *         <button onClick={() => download('my-video.mp4')}>Download</button>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ *
+ * // Using custom project (must import it first)
+ * import myProject from './my-project';
+ *
+ * function CustomProjectComponent() {
+ *   const { render } = useBrowserRenderer({
+ *     projectFile: myProject, // Pass the imported project object
+ *     width: 1920,
+ *     height: 1080,
+ *   });
+ *
+ *   // ... rest of component
+ * }
+ * ```
+ */
+declare const useBrowserRenderer: (options?: UseBrowserRendererOptions) => UseBrowserRendererReturn;
+
+export { type BrowserRenderConfig, type UseBrowserRendererOptions, type UseBrowserRendererReturn, renderTwickVideoInBrowser as default, downloadVideoBlob, renderTwickVideoInBrowser, useBrowserRenderer };

package/dist/index.d.ts

@@ -0,0 +1,225 @@
+import { Project } from '@twick/core';
+
+/**
+ * Browser rendering configuration
+ */
+interface BrowserRenderConfig {
+    /**
+     * Custom Project object
+     * If not provided, defaults to @twick/visualizer project
+     *
+     * Note: Must be an imported Project object, not a string path.
+     * String paths only work in Node.js environments (server renderer).
+     *
+     * Example:
+     * ```typescript
+     * import myProject from './my-custom-project';
+     *
+     * await renderTwickVideoInBrowser({
+     *   projectFile: myProject,
+     *   variables: { input: {...} }
+     * });
+     * ```
+     */
+    projectFile?: Project;
+    /** Input variables containing project configuration */
+    variables: {
+        input: any;
+        playerId?: string;
+        [key: string]: any;
+    };
+    /** Render settings */
+    settings?: {
+        width?: number;
+        height?: number;
+        fps?: number;
+        quality?: 'low' | 'medium' | 'high';
+        range?: [number, number];
+        includeAudio?: boolean;
+        downloadAudioSeparately?: boolean;
+        onAudioReady?: (audioBlob: Blob) => void;
+        onProgress?: (progress: number) => void;
+        onComplete?: (videoBlob: Blob) => void;
+        onError?: (error: Error) => void;
+    };
+}
+/**
+ * Renders a Twick video directly in the browser without requiring a server.
+ * Uses WebCodecs API for encoding video frames into MP4 format.
+ *
+ * This function uses the same signature as the server renderer for consistency.
+ *
+ * @param config - Configuration object containing variables and settings
+ * @param config.projectFile - Optional project file path or Project object (defaults to visualizer project)
+ * @param config.variables - Variables containing input configuration (tracks, elements, etc.)
+ * @param config.settings - Optional render settings (width, height, fps, etc.)
+ * @returns Promise resolving to a Blob containing the rendered video
+ *
+ * @example
+ * ```js
+ * import { renderTwickVideoInBrowser } from '@twick/browser-render';
+ *
+ * // Using default visualizer project
+ * const videoBlob = await renderTwickVideoInBrowser({
+ *   variables: {
+ *     input: {
+ *       properties: { width: 1920, height: 1080, fps: 30 },
+ *       tracks: [
+ *         // Your tracks configuration
+ *       ]
+ *     }
+ *   },
+ *   settings: {
+ *     width: 1920,
+ *     height: 1080,
+ *     fps: 30,
+ *     quality: 'high',
+ *     onProgress: (progress) => console.log(`Rendering: ${progress * 100}%`),
+ *   }
+ * });
+ *
+ * // Using custom project
+ * import myProject from './my-custom-project';
+ * const videoBlob = await renderTwickVideoInBrowser({
+ *   projectFile: myProject, // Must be an imported Project object
+ *   variables: { input: {...} },
+ *   settings: {...}
+ * });
+ *
+ * // Download the video
+ * const url = URL.createObjectURL(videoBlob);
+ * const a = document.createElement('a');
+ * a.href = url;
+ * a.download = 'video.mp4';
+ * a.click();
+ * URL.revokeObjectURL(url);
+ * ```
+ */
+declare const renderTwickVideoInBrowser: (config: BrowserRenderConfig) => Promise<Blob>;
+/**
+ * Helper function to download a video blob as a file
+ *
+ * @param videoBlob - The video blob to download
+ * @param filename - The desired filename (default: 'video.mp4')
+ *
+ * @example
+ * ```js
+ * const blob = await renderTwickVideoInBrowser(projectData);
+ * downloadVideoBlob(blob, 'my-video.mp4');
+ * ```
+ */
+declare const downloadVideoBlob: (videoBlob: Blob, filename?: string) => void;
+
+interface UseBrowserRendererOptions {
+    /**
+     * Custom Project object
+     * If not provided, defaults to @twick/visualizer project
+     *
+     * Note: Must be an imported Project object, not a string path.
+     * String paths only work in Node.js (server renderer).
+     *
+     * Example:
+     * ```typescript
+     * import myProject from './my-custom-project';
+     * useBrowserRenderer({ projectFile: myProject })
+     * ```
+     */
+    projectFile?: any;
+    /** Video width in pixels */
+    width?: number;
+    /** Video height in pixels */
+    height?: number;
+    /** Frames per second */
+    fps?: number;
+    /** Render quality */
+    quality?: 'low' | 'medium' | 'high';
+    /** Time range to render [start, end] in seconds */
+    range?: [number, number];
+    /** Include audio in rendered video (experimental) */
+    includeAudio?: boolean;
+    /** Download audio separately as WAV file */
+    downloadAudioSeparately?: boolean;
+    /** Callback when audio is ready */
+    onAudioReady?: (audioBlob: Blob) => void;
+    /** Automatically download the video when rendering completes */
+    autoDownload?: boolean;
+    /** Default filename for downloads */
+    downloadFilename?: string;
+}
+interface UseBrowserRendererReturn {
+    /** Start rendering the video */
+    render: (variables: BrowserRenderConfig['variables']) => Promise<Blob | null>;
+    /** Current rendering progress (0-1) */
+    progress: number;
+    /** Whether rendering is in progress */
+    isRendering: boolean;
+    /** Error if rendering failed */
+    error: Error | null;
+    /** The rendered video blob (available after rendering completes) */
+    videoBlob: Blob | null;
+    /** Download the rendered video */
+    download: (filename?: string) => void;
+    /** Reset the renderer state */
+    reset: () => void;
+}
+/**
+ * React hook for rendering Twick videos in the browser
+ *
+ * Uses the same pattern as the server renderer for consistency.
+ *
+ * @param options - Rendering options
+ * @returns Renderer state and control functions
+ *
+ * @example
+ * ```tsx
+ * import { useBrowserRenderer } from '@twick/browser-render';
+ *
+ * // Using default visualizer project
+ * function MyComponent() {
+ *   const { render, progress, isRendering, videoBlob, download } = useBrowserRenderer({
+ *     width: 1920,
+ *     height: 1080,
+ *     fps: 30,
+ *     autoDownload: true,
+ *   });
+ *
+ *   const handleRender = async () => {
+ *     await render({
+ *       input: {
+ *         properties: { width: 1920, height: 1080, fps: 30 },
+ *         tracks: [
+ *           // Your tracks configuration
+ *         ]
+ *       }
+ *     });
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={handleRender} disabled={isRendering}>
+ *         {isRendering ? `Rendering... ${(progress * 100).toFixed(0)}%` : 'Render Video'}
+ *       </button>
+ *       {videoBlob && !autoDownload && (
+ *         <button onClick={() => download('my-video.mp4')}>Download</button>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ *
+ * // Using custom project (must import it first)
+ * import myProject from './my-project';
+ *
+ * function CustomProjectComponent() {
+ *   const { render } = useBrowserRenderer({
+ *     projectFile: myProject, // Pass the imported project object
+ *     width: 1920,
+ *     height: 1080,
+ *   });
+ *
+ *   // ... rest of component
+ * }
+ * ```
+ */
+declare const useBrowserRenderer: (options?: UseBrowserRendererOptions) => UseBrowserRendererReturn;
+
+export { type BrowserRenderConfig, type UseBrowserRendererOptions, type UseBrowserRendererReturn, renderTwickVideoInBrowser as default, downloadVideoBlob, renderTwickVideoInBrowser, useBrowserRenderer };