How to Convert Audio Files in the Convert Project: FFmpegHandler Explained

The FFmpegHandler located in src/handlers/FFmpeg.ts is the primary handler responsible for converting audio files in the convert project, utilizing a WebAssembly-compiled FFmpeg engine to transcode between formats like MP3, WAV, FLAC, and AAC.

The p2r3/convert repository provides a modular file conversion system where specialized handlers manage specific format categories. When you need to convert audio files, the FFmpegHandler serves as the core engine, loading FFmpeg WASM, discovering supported codecs, and executing transcoding operations through a standardized interface.

What Is the FFmpegHandler?

The FFmpegHandler is a TypeScript class that implements the FormatHandler interface defined in src/FormatHandler.ts. It resides in src/handlers/FFmpeg.ts and registers itself in the global handler list via src/handlers/index.ts.

Unlike niche handlers such as libopenmptHandler or qoaFuHandler that handle specific audio formats, the FFmpegHandler provides general-purpose audio-to-audio and audio-to-video conversion capabilities. It discovers available formats by parsing the output of ffmpeg -formats and explicitly categorizes audio formats with category = "audio".

How Audio File Conversion Works

The conversion process involves three main stages: initialization, format discovery, and transcoding execution.

Initializing the Handler

Before converting audio files, you must instantiate and initialize the handler. The init() method loads the WebAssembly-compiled FFmpeg engine into memory and prepares the virtual file system.

import FFmpegHandler from "./src/handlers/FFmpeg.ts";

const ffmpeg = new FFmpegHandler();
await ffmpeg.init(); // Sets ready = true when WASM is loaded

Supported Audio Formats

During initialization, the handler builds the supportedFormats array by querying FFmpeg's capabilities. It identifies audio formats such as mp3, wav, flac, aac, and ogg, assigning them the category: "audio" property in src/handlers/FFmpeg.ts (lines 151-173).

You can inspect available formats at runtime:

const audioFormats = ffmpeg.supportedFormats.filter(f => f.category === "audio");
console.log(audioFormats.map(f => f.format)); // ["mp3", "wav", "flac", ...]

The Conversion Pipeline

The doConvert method handles the actual transcoding. It performs the following steps:

1. Writes input files to FFmpeg's virtual file system
2. Builds a concat list for batch processing
3. Executes an FFmpeg command optimized for the target format
4. Returns the resulting FileData object

This implementation spans lines 31-61 and 122-142 in src/handlers/FFmpeg.ts.

Code Example: Converting MP3 to WAV

Here is a complete example demonstrating how to convert audio files using the handler:

import FFmpegHandler from "./src/handlers/FFmpeg.ts";

// Initialize the handler
const ffmpeg = new FFmpegHandler();
await ffmpeg.init();

// Prepare input files
const inputFiles = [
  { 
    name: "input.mp3", 
    bytes: await fetch("/audio/input.mp3").then(r => r.arrayBuffer()) 
  }
];

// Locate source and target formats
const mp3Format = ffmpeg.supportedFormats.find(f => f.format === "mp3")!;
const wavFormat = ffmpeg.supportedFormats.find(f => f.format === "wav")!;

// Execute conversion
const output = await ffmpeg.doConvert(inputFiles, mp3Format, wavFormat);
// output contains [{ name: "output.wav", bytes: ArrayBuffer }]

Key Files in the Audio Conversion System

File	Role
src/handlers/FFmpeg.ts	Implements the audio/video conversion engine; loads FFmpeg WASM, discovers supported formats, and runs transcoding commands.
src/handlers/index.ts	Registers FFmpegHandler into the global handlers array used by the application.
src/FormatHandler.ts	Defines the FormatHandler interface that FFmpegHandler implements.
src/normalizeMimeType.ts	Normalizes MIME strings used when categorizing audio formats.

Summary

• The FFmpegHandler in src/handlers/FFmpeg.ts is the primary component to convert audio files in the p2r3/convert project.
• It utilizes a WebAssembly-compiled FFmpeg engine loaded via the init() method to perform transcoding.
• The handler discovers supported formats dynamically by parsing FFmpeg's capabilities and categorizes audio formats with category = "audio".
• The doConvert method manages the conversion pipeline: writing to virtual FS, building concat lists, executing FFmpeg commands, and returning FileData objects.
• While niche handlers exist for specific formats, FFmpegHandler handles general audio-to-audio conversion for formats like MP3, WAV, FLAC, AAC, and OGG.

Frequently Asked Questions

Which handler converts audio files in the convert project?

The FFmpegHandler located in src/handlers/FFmpeg.ts is responsible for converting audio files. It implements the FormatHandler interface and uses a WebAssembly-compiled FFmpeg engine to transcode between audio formats such as MP3, WAV, and FLAC.

How does the FFmpegHandler discover supported audio formats?

During initialization, the handler executes ffmpeg -formats and parses the output to build the supportedFormats array. It explicitly marks audio formats with category = "audio" (as seen in lines 151-173 of src/handlers/FFmpeg.ts), allowing the system to identify which formats support audio transcoding.

What is the difference between FFmpegHandler and other audio handlers in the project?

While FFmpegHandler provides general-purpose audio-to-audio and audio-to-video conversion for common formats, other handlers like libopenmptHandler and qoaFuHandler specialize in niche audio types. The FFmpeg-based handler serves as the core conversion engine for standard formats like MP3, AAC, and WAV.

Can FFmpegHandler convert between audio and video formats?

Yes. Although primarily used to convert audio files, the FFmpegHandler supports audio-to-video and video-to-audio conversion. The doConvert method handles transcoding between any supported format pairs, including extracting audio tracks from video files or encoding audio into video containers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}