@twick/browser-render 0.15.8 → 0.15.10

package/README.md

@@ -144,6 +144,45 @@ 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`.  
+
+#### Automatic Setup with Vite Plugin (Recommended)
+
+For Vite projects, use the provided plugin to automatically copy FFmpeg files:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { twickBrowserRenderPlugin } from '@twick/browser-render/vite-plugin-ffmpeg';
+
+export default defineConfig({
+  plugins: [
+    twickBrowserRenderPlugin(),
+    // ... your other plugins
+  ],
+});
+```
+
+The plugin automatically copies `ffmpeg-core.js` and `ffmpeg-core.wasm` from `node_modules/@ffmpeg/core/dist` to your `public/ffmpeg/` directory.
+
+#### Create React App / non-Vite
+
+For CRA or any project without Vite, run the copy script before `start` and `build`:
+
+```json
+{
+  "scripts": {
+    "prestart": "node node_modules/@twick/browser-render/scripts/copy-public-assets.js",
+    "prebuild": "node node_modules/@twick/browser-render/scripts/copy-public-assets.js",
+    "start": "react-scripts start",
+    "build": "react-scripts build"
+  }
+}
+```
+
+The script copies FFmpeg core files, `mp4-wasm.wasm`, and `audio-worker.js` to your `public/` directory. No extra dependencies required.
+
+#### Manual Setup
+
 To match the setup used in `@twick/examples`, you should:
 
 1. Install the FFmpeg packages:
@@ -170,6 +209,8 @@ 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.
 
+**Note**: For Vite projects, you can use the `twickBrowserRenderPlugin()` Vite plugin to automatically copy these files. See the plugin documentation at `@twick/browser-render/vite-plugin-ffmpeg`.
+
 ## Limitations
 
 - **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.

package/dist/index.d.mts

@@ -110,6 +110,50 @@ declare const renderTwickVideoInBrowser: (config: BrowserRenderConfig) => Promis
  */
 declare const downloadVideoBlob: (videoBlob: Blob, filename?: string) => void;
 
+/**
+ * Browser-based video normalization using FFmpeg.wasm (main thread)
+ * Compatible with Next.js 15
+ *
+ * This helper converts "problematic" videos (e.g. WhatsApp exports) into a
+ * very standard H.264 + AAC, 30fps, yuv420p MP4 that behaves well with
+ * WebCodecs and <video> playback, reducing the chance of frozen-first-frame
+ * issues during browser rendering.
+ *
+ * FFmpeg core files must be served from the app's public folder, e.g.:
+ * twick-web/public/ffmpeg/ffmpeg-core.js, ffmpeg-core.wasm
+ */
+/** Normalization options */
+interface NormalizeVideoOptions {
+    /** Target width in pixels (default: 720). Height is derived to preserve aspect ratio. */
+    width?: number;
+    /** Target frames per second (default: 30). */
+    fps?: number;
+}
+/** Result of normalization */
+interface NormalizeVideoResult {
+    /** Normalized video Blob (MP4, H.264 + AAC). */
+    blob: Blob;
+    /** Size in bytes of the normalized video. */
+    size: number;
+    /** Optional debug information (durations, etc.). */
+    debug?: {
+        loadMs: number;
+        writeMs: number;
+        execMs: number;
+        readMs: number;
+        totalMs: number;
+    };
+}
+/**
+ * Normalize a video Blob into a browser- and WebCodecs-friendly MP4.
+ *
+ * Typical usage:
+ * - Call this after file upload (e.g. from an <input type="file" />)
+ * - Upload the returned Blob to your storage (S3, etc.)
+ * - Use that URL in your Twick project instead of the raw source
+ */
+declare function normalizeVideoBlob(input: Blob, options?: NormalizeVideoOptions): Promise<NormalizeVideoResult>;
+
 interface UseBrowserRendererOptions {
     /**
      * Custom Project object
@@ -222,4 +266,4 @@ interface UseBrowserRendererReturn {
  */
 declare const useBrowserRenderer: (options?: UseBrowserRendererOptions) => UseBrowserRendererReturn;
 
-export { type BrowserRenderConfig, type UseBrowserRendererOptions, type UseBrowserRendererReturn, renderTwickVideoInBrowser as default, downloadVideoBlob, renderTwickVideoInBrowser, useBrowserRenderer };
+export { type BrowserRenderConfig, type NormalizeVideoOptions, type NormalizeVideoResult, type UseBrowserRendererOptions, type UseBrowserRendererReturn, renderTwickVideoInBrowser as default, downloadVideoBlob, normalizeVideoBlob, renderTwickVideoInBrowser, useBrowserRenderer };

package/dist/index.d.ts

@@ -110,6 +110,50 @@ declare const renderTwickVideoInBrowser: (config: BrowserRenderConfig) => Promis
  */
 declare const downloadVideoBlob: (videoBlob: Blob, filename?: string) => void;
 
+/**
+ * Browser-based video normalization using FFmpeg.wasm (main thread)
+ * Compatible with Next.js 15
+ *
+ * This helper converts "problematic" videos (e.g. WhatsApp exports) into a
+ * very standard H.264 + AAC, 30fps, yuv420p MP4 that behaves well with
+ * WebCodecs and <video> playback, reducing the chance of frozen-first-frame
+ * issues during browser rendering.
+ *
+ * FFmpeg core files must be served from the app's public folder, e.g.:
+ * twick-web/public/ffmpeg/ffmpeg-core.js, ffmpeg-core.wasm
+ */
+/** Normalization options */
+interface NormalizeVideoOptions {
+    /** Target width in pixels (default: 720). Height is derived to preserve aspect ratio. */
+    width?: number;
+    /** Target frames per second (default: 30). */
+    fps?: number;
+}
+/** Result of normalization */
+interface NormalizeVideoResult {
+    /** Normalized video Blob (MP4, H.264 + AAC). */
+    blob: Blob;
+    /** Size in bytes of the normalized video. */
+    size: number;
+    /** Optional debug information (durations, etc.). */
+    debug?: {
+        loadMs: number;
+        writeMs: number;
+        execMs: number;
+        readMs: number;
+        totalMs: number;
+    };
+}
+/**
+ * Normalize a video Blob into a browser- and WebCodecs-friendly MP4.
+ *
+ * Typical usage:
+ * - Call this after file upload (e.g. from an <input type="file" />)
+ * - Upload the returned Blob to your storage (S3, etc.)
+ * - Use that URL in your Twick project instead of the raw source
+ */
+declare function normalizeVideoBlob(input: Blob, options?: NormalizeVideoOptions): Promise<NormalizeVideoResult>;
+
 interface UseBrowserRendererOptions {
     /**
      * Custom Project object
@@ -222,4 +266,4 @@ interface UseBrowserRendererReturn {
  */
 declare const useBrowserRenderer: (options?: UseBrowserRendererOptions) => UseBrowserRendererReturn;
 
-export { type BrowserRenderConfig, type UseBrowserRendererOptions, type UseBrowserRendererReturn, renderTwickVideoInBrowser as default, downloadVideoBlob, renderTwickVideoInBrowser, useBrowserRenderer };
+export { type BrowserRenderConfig, type NormalizeVideoOptions, type NormalizeVideoResult, type UseBrowserRendererOptions, type UseBrowserRendererReturn, renderTwickVideoInBrowser as default, downloadVideoBlob, normalizeVideoBlob, renderTwickVideoInBrowser, useBrowserRenderer };