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

> Discover how the FFmpegHandler converts audio files in the p2r3 convert project. Learn about MP3, WAV, FLAC, and AAC transcoding with WebAssembly FFmpeg.

- Repository: [p2r3/convert](https://github.com/p2r3/convert)
- Tags: deep-dive
- Published: 2026-02-19

---

**The `FFmpegHandler` located in [`src/handlers/FFmpeg.ts`](https://github.com/p2r3/convert/blob/main/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`](https://github.com/p2r3/convert/blob/main/src/FormatHandler.ts). It resides in [`src/handlers/FFmpeg.ts`](https://github.com/p2r3/convert/blob/main/src/handlers/FFmpeg.ts) and registers itself in the global handler list via [`src/handlers/index.ts`](https://github.com/p2r3/convert/blob/main/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.

```typescript
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`](https://github.com/p2r3/convert/blob/main/src/handlers/FFmpeg.ts) (lines 151-173).

You can inspect available formats at runtime:

```typescript
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`](https://github.com/p2r3/convert/blob/main/src/handlers/FFmpeg.ts).

## Code Example: Converting MP3 to WAV

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

```typescript
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`](https://github.com/p2r3/convert/blob/main/src/handlers/FFmpeg.ts)** | Implements the audio/video conversion engine; loads FFmpeg WASM, discovers supported formats, and runs transcoding commands. |
| **[`src/handlers/index.ts`](https://github.com/p2r3/convert/blob/main/src/handlers/index.ts)** | Registers `FFmpegHandler` into the global `handlers` array used by the application. |
| **[`src/FormatHandler.ts`](https://github.com/p2r3/convert/blob/main/src/FormatHandler.ts)** | Defines the `FormatHandler` interface that `FFmpegHandler` implements. |
| **[`src/normalizeMimeType.ts`](https://github.com/p2r3/convert/blob/main/src/normalizeMimeType.ts)** | Normalizes MIME strings used when categorizing audio formats. |

## Summary

- The **`FFmpegHandler`** in [`src/handlers/FFmpeg.ts`](https://github.com/p2r3/convert/blob/main/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`](https://github.com/p2r3/convert/blob/main/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`](https://github.com/p2r3/convert/blob/main/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.