@voidwasm/ffmpeg

A high-performance WebAssembly FFmpeg plugin built with the Void framework and executed via @voidwasm/runtime inside Node.js (functioning seamlessly as a Void plugin, just like Vite and Vite plugins). It enables native, cross-platform media processing—such as video resizing, cropping, trimming, video concatenation/merging, thumbnail extraction, and audio isolation—directly in JavaScript through a synchronous host filesystem bridge.

🚀 Installation & Setup

1. Add the plugin to your Void application project:

   npx void add @voidwasm/ffmpeg

2. Import and use the plugin in your JavaScript/TypeScript files:

   import ffmpeg from "@voidwasm/ffmpeg";

📖 API Reference

1. open(args: { path: string })

Opens a video file and probes comprehensive stream metadata.

const info = await ffmpeg.open({ path: "input.mp4" });
console.log(info);
/*
Output:
{
  "handle": "video_1",
  "duration": 5.758,
  "width": 1920,
  "height": 1080,
  "fps": 29.97,
  "bitrate": 3956897,
  "format": "mov,mp4,m4a,3gp,3g2,mj2",
  "hasVideo": true,
  "hasAudio": true,
  "videoCodec": "h264",
  "audioCodec": "aac",
  "pixelFormat": "yuv420p",
  "sampleRate": 44100,
  "channels": 2
}
*/

2. threads(args: { handle: string; count: number })

Configures decoder and encoder thread count (count: 0 for auto-detect based on CPU cores, count: 1 for single-thread, count: N for N threads).

await ffmpeg.threads({ handle: info.handle, count: 0 }); // Auto-detect CPU cores

3. thumbnail(args: { handle: string; time: number; outputPath: string })

Extracts a video frame at a given time timestamp (in seconds) and outputs a JPEG image.

await ffmpeg.thumbnail({
  handle: info.handle,
  time: 2.5,
  outputPath: "thumbnail.jpg"
});

4. extractAudio(args: { handle: string; outputPath: string })

Isolates and extracts the audio stream into a standalone file.

await ffmpeg.extractAudio({
  handle: info.handle,
  outputPath: "audio.mp3"
});

5. merge(args: { handle: string; otherPath: string })

Queues a second video file to be merged sequentially. Call save() afterwards to perform the operation.

await ffmpeg.merge({
  handle: info.handle,
  otherPath: "second_video.mp4"
});
await ffmpeg.save({
  handle: info.handle,
  outputPath: "merged_output.mp4"
});

6. resize(args: { handle: string; width: number; height: number })

Queues a target resolution change.

await ffmpeg.resize({ handle: info.handle, width: 640, height: 480 });

7. crop(args: { handle: string; x: number; y: number; width: number; height: number })

Queues a rectangular crop area.

await ffmpeg.crop({ handle: info.handle, x: 100, y: 100, width: 400, height: 300 });

8. trim(args: { handle: string; start: number; end: number })

Queues a duration trim range (in seconds).

await ffmpeg.trim({ handle: info.handle, start: 1.5, end: 4.5 });

9. convert(args: { handle: string; format: string })

Queues a target container format.

await ffmpeg.convert({ handle: info.handle, format: "mp4" });

10. outputFormat(args: { handle: string; format: string })

Sets the explicit output container / format.

await ffmpeg.outputFormat({ handle: info.handle, format: "mp4" });

11. videoCodec(args: { handle: string; codec: string })

Specifies the target video encoder codec (e.g. "mpeg4", "mjpeg").

await ffmpeg.videoCodec({ handle: info.handle, codec: "mpeg4" });

12. audioCodec(args: { handle: string; codec: string })

Specifies the target audio encoder codec (e.g. "aac", "mp3").

await ffmpeg.audioCodec({ handle: info.handle, codec: "aac" });

13. pixelFormat(args: { handle: string; format: string })

Specifies the pixel format (e.g. "yuv420p", "yuvj420p").

await ffmpeg.pixelFormat({ handle: info.handle, format: "yuv420p" });

14. preset(args: { handle: string; preset: string })

Configures encoding preset speed/quality tradeoff (e.g. "slow", "fast", "ultrafast").

await ffmpeg.preset({ handle: info.handle, preset: "slow" });

15. filter(args: { handle: string; graph: string })

Applies custom FFmpeg video filter graph expressions.

await ffmpeg.filter({ handle: info.handle, graph: "scale=1280:-2,crop=500:500" });

16. videoBitrate(args: { handle: string; bitrate: string | number })

Configures target video bitrate (accepts "5M", "2000k", or raw number 2000000).

await ffmpeg.videoBitrate({ handle: info.handle, bitrate: "5M" });

17. audioBitrate(args: { handle: string; bitrate: string | number })

Configures target audio bitrate (accepts "192k" or raw number 192000).

await ffmpeg.audioBitrate({ handle: info.handle, bitrate: "192k" });

18. sampleRate(args: { handle: string; rate: number })

Sets audio sample rate in Hz (e.g. 48000).

await ffmpeg.sampleRate({ handle: info.handle, rate: 48000 });

19. frameRate(args: { handle: string; fps: number })

Sets target video framerate (e.g. 60).

await ffmpeg.frameRate({ handle: info.handle, fps: 60 });

20. streamCopy(args: { handle: string })

Enables fast stream copy / remuxing without re-encoding video/audio streams.

await ffmpeg.streamCopy({ handle: info.handle });

21. metadata(args: { handle: string; [key: string]: any })

Sets container metadata tags (title, author, artist, comment, etc.).

await ffmpeg.metadata({
  handle: info.handle,
  title: "Movie Title",
  author: "Soham"
});

22. save(args: { handle: string; outputPath: string })

Executes all queued transformations and saves the output file.

await ffmpeg.save({
  handle: info.handle,
  outputPath: "output.mp4"
});

🛠 Development & Compiling

1. Install SDK dependencies:

   npm install
   npm run cpp-init

2. Build WebAssembly Plugin:

   npx void build

3. Link and Test:

   cd test
   void add ../
   node app.js