1.0.4 • Published 1h ago

@voidwasm/ffmpeg

Licence

—

Version

1.0.4

Deps

Size

5.3 MB

Vulns

Weekly

Summary Dependency Versions

@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

Add the plugin to your Void application project:
```
npx void add @voidwasm/ffmpeg
```
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

Install SDK dependencies:
```
npm install
npm run cpp-init
```
Build WebAssembly Plugin:
```
npx void build
```
Link and Test:
```
cd test
void add ../
node app.js
```