docs: add audio conversion implementation plan

2026-08-01 13:41:00 +02:00
parent aa5383d7f0
commit 13d095aa4c
1 changed files with 788 additions and 0 deletions
@@ -0,0 +1,788 @@
+# Audio Conversion Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a new `audio` conversion family (mp3, wav, ogg, flac, aac, m4a; any-to-any, 30 pairs) backed by an external `ffmpeg` binary, following the exact `CALIBRE_PATH`/`ebook.js` pattern already in this codebase.
+
+**Architecture:** One generic `convert()` in `src/converters/audio.js` that shells out to `ffmpeg` via `execFile` (no ffmpeg npm wrapper — ffmpeg's own demuxer auto-detects the input format, so there is no per-source branching, only per-target codec selection). Wired into `app.js`/`worker.js` next to the other seven `registerXConverters()` calls. Bitrate (kbps) is stored in the existing nullable `ConversionJob.quality` column — no schema change.
+
+**Tech Stack:** Node.js, `node:child_process` (`execFile`), Express, Prisma/MySQL, Vitest + Supertest, React (frontend, manual verification only — no frontend test suite exists in this repo).
+
+## Global Constraints
+
+- Spec: `docs/superpowers/specs/2026-08-01-audio-conversion-design.md` — read it before starting if anything below is unclear.
+- Formats: exactly `mp3`, `wav`, `ogg`, `flac`, `aac`, `m4a`. All-pairs excluding `sourceFormat === targetFormat`.
+- ffmpeg is **not installed on this local dev machine**. Every automated test in this plan mocks `node:child_process`'s `execFile` — none may shell out to a real ffmpeg binary. Real end-to-end conversion is verified only manually on a machine/environment where ffmpeg is present (o2switch), never in this plan's automated tests.
+- Bitrate is a fixed chip set only: `128`, `192`, `256`, `320` (kbps). No arbitrary numeric range is valid.
+- `wav` and `flac` never take a quality/bitrate value — only `null` is valid for them.
+- Timeout: reuse the existing global `JOB_TIMEOUT_MS` (60s) in `src/worker.js`. Do **not** add a new `AUDIO_JOB_TIMEOUT_MS`.
+- No new npm dependency. ffmpeg is invoked as an external binary (`process.env.FFMPEG_PATH || 'ffmpeg'`), the same way `ebook.js` invokes `process.env.CALIBRE_PATH || 'ebook-convert'`.
+- No DB/schema changes anywhere in this feature.
+- Run backend tests with the project's documented local-env-var pattern (see `CLAUDE.md`): `DB_HOST=127.0.0.1 DB_USER=convert_user DB_PASSWORD=change_me DB_NAME=file_converter STORAGE_DIR=./storage PORT=3000 npx vitest run <path>`.
+
+---
+
+### Task 1: Audio converter core (`src/converters/audio.js`)
+
+**Files:**
+- Create: `src/converters/audio.js`
+- Test: `test/converters/audio.test.js`
+
+**Interfaces:**
+- Consumes: `register` from `./registry.js` (signature: `register({ family, sourceFormat, targetFormat, convert })`, already used identically by every other converter file).
+- Produces: `registerAudioConverters(): void` and `AUDIO_FORMATS: string[]` (both named exports), for Task 2 to import and call/reference. Each registered `convert(inputPath, outputPath, { quality, timeoutMs } = {})` returns a `Promise<void>`.
+
+- [ ] **Step 1: Write the failing test for registration coverage**
+
+Create `test/converters/audio.test.js` with this content (mirrors `test/converters/ebook.test.js`'s structure exactly, including the `execFile` mock):
+
+```js
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { registerAudioConverters, AUDIO_FORMATS } from '../../src/converters/audio.js';
+import { resolve, _resetForTests } from '../../src/converters/registry.js';
+
+const { execFileMock } = vi.hoisted(() => ({ execFileMock: vi.fn() }));
+vi.mock('node:child_process', () => ({ execFile: execFileMock }));
+
+beforeEach(() => {
+  _resetForTests();
+  execFileMock.mockReset();
+  execFileMock.mockImplementation((file, args, options, callback) => callback(null, '', ''));
+});
+
+describe('registerAudioConverters — registration', () => {
+  it('registers every pair among the 6 audio formats, and nothing for source === target', () => {
+    registerAudioConverters();
+
+    for (const sourceFormat of AUDIO_FORMATS) {
+      for (const targetFormat of AUDIO_FORMATS) {
+        const entry = resolve(sourceFormat, targetFormat);
+        if (sourceFormat === targetFormat) {
+          expect(entry).toBeNull();
+        } else {
+          expect(entry).not.toBeNull();
+          expect(entry.family).toBe('audio');
+        }
+      }
+    }
+  });
+
+  it('exposes exactly the 6 requested formats', () => {
+    expect(AUDIO_FORMATS.sort()).toEqual(['aac', 'flac', 'm4a', 'mp3', 'ogg', 'wav'].sort());
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `DB_HOST=127.0.0.1 DB_USER=convert_user DB_PASSWORD=change_me DB_NAME=file_converter STORAGE_DIR=./storage PORT=3000 npx vitest run test/converters/audio.test.js`
+Expected: FAIL — `Cannot find module '../../src/converters/audio.js'` (or similar "does not provide an export named" once the file exists but before exports are added).
+
+- [ ] **Step 3: Write the converter implementation**
+
+Create `src/converters/audio.js`:
+
+```js
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { register } from './registry.js';
+
+const execFileAsync = promisify(execFile);
+
+export const AUDIO_FORMATS = ['mp3', 'wav', 'ogg', 'flac', 'aac', 'm4a'];
+
+const CODEC_ARGS = {
+  mp3: ['-c:a', 'libmp3lame'],
+  ogg: ['-c:a', 'libvorbis'],
+  aac: ['-c:a', 'aac'],
+  m4a: ['-c:a', 'aac'],
+  wav: ['-c:a', 'pcm_s16le'],
+  flac: ['-c:a', 'flac'],
+};
+
+const BITRATE_CAPABLE_FORMATS = ['mp3', 'ogg', 'aac', 'm4a'];
+
+export function registerAudioConverters() {
+  for (const sourceFormat of AUDIO_FORMATS) {
+    for (const targetFormat of AUDIO_FORMATS) {
+      if (sourceFormat === targetFormat) continue;
+      register({
+        family: 'audio',
+        sourceFormat,
+        targetFormat,
+        convert: async (inputPath, outputPath, { quality, timeoutMs } = {}) => {
+          const ffmpegPath = process.env.FFMPEG_PATH || 'ffmpeg';
+          const args = ['-y', '-i', inputPath, ...CODEC_ARGS[targetFormat]];
+          if (quality != null && BITRATE_CAPABLE_FORMATS.includes(targetFormat)) {
+            args.push('-b:a', `${quality}k`);
+          }
+          args.push(outputPath);
+          await execFileAsync(ffmpegPath, args, { timeout: timeoutMs });
+        },
+      });
+    }
+  }
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `DB_HOST=127.0.0.1 DB_USER=convert_user DB_PASSWORD=change_me DB_NAME=file_converter STORAGE_DIR=./storage PORT=3000 npx vitest run test/converters/audio.test.js`
+Expected: PASS (2 tests)
+
+- [ ] **Step 5: Add subprocess-invocation tests (codec args, bitrate, env var, timeout, error propagation)**
+
+Append to `test/converters/audio.test.js`:
+
+```js
+describe('registerAudioConverters — subprocess invocation', () => {
+  beforeEach(() => {
+    registerAudioConverters();
+  });
+
+  it('calls ffmpeg with -i, the codec args, and the output path, omitting -b:a when no quality is given', async () => {
+    await resolve('wav', 'mp3').convert('/tmp/in.wav', '/tmp/out.mp3');
+
+    expect(execFileMock).toHaveBeenCalledTimes(1);
+    const [file, args, options] = execFileMock.mock.calls[0];
+    expect(file).toBe('ffmpeg');
+    expect(args).toEqual(['-y', '-i', '/tmp/in.wav', '-c:a', 'libmp3lame', '/tmp/out.mp3']);
+    expect(options).toEqual({ timeout: undefined });
+  });
+
+  it('appends -b:a when a quality/bitrate is given for a bitrate-capable target', async () => {
+    await resolve('wav', 'mp3').convert('/tmp/in.wav', '/tmp/out.mp3', { quality: 192 });
+
+    const [, args] = execFileMock.mock.calls[0];
+    expect(args).toEqual(['-y', '-i', '/tmp/in.wav', '-c:a', 'libmp3lame', '-b:a', '192k', '/tmp/out.mp3']);
+  });
+
+  it('never appends -b:a for a wav target even if a quality is passed', async () => {
+    await resolve('mp3', 'wav').convert('/tmp/in.mp3', '/tmp/out.wav', { quality: 192 });
+
+    const [, args] = execFileMock.mock.calls[0];
+    expect(args).toEqual(['-y', '-i', '/tmp/in.mp3', '-c:a', 'pcm_s16le', '/tmp/out.wav']);
+  });
+
+  it('never appends -b:a for a flac target even if a quality is passed', async () => {
+    await resolve('wav', 'flac').convert('/tmp/in.wav', '/tmp/out.flac', { quality: 320 });
+
+    const [, args] = execFileMock.mock.calls[0];
+    expect(args).toEqual(['-y', '-i', '/tmp/in.wav', '-c:a', 'flac', '/tmp/out.flac']);
+  });
+
+  it('uses the aac codec for both aac and m4a targets', async () => {
+    await resolve('wav', 'aac').convert('/tmp/in.wav', '/tmp/out.aac');
+    expect(execFileMock.mock.calls[0][1]).toEqual(['-y', '-i', '/tmp/in.wav', '-c:a', 'aac', '/tmp/out.aac']);
+
+    execFileMock.mockClear();
+    await resolve('wav', 'm4a').convert('/tmp/in.wav', '/tmp/out.m4a');
+    expect(execFileMock.mock.calls[0][1]).toEqual(['-y', '-i', '/tmp/in.wav', '-c:a', 'aac', '/tmp/out.m4a']);
+  });
+
+  it('forwards options.timeoutMs to execFile as its timeout', async () => {
+    await resolve('mp3', 'wav').convert('/tmp/in.mp3', '/tmp/out.wav', { timeoutMs: 60000 });
+
+    const [, , options] = execFileMock.mock.calls[0];
+    expect(options).toEqual({ timeout: 60000 });
+  });
+
+  it('uses FFMPEG_PATH from the environment when set', async () => {
+    const previous = process.env.FFMPEG_PATH;
+    process.env.FFMPEG_PATH = '/opt/ffmpeg/bin/ffmpeg';
+
+    await resolve('mp3', 'wav').convert('/tmp/in.mp3', '/tmp/out.wav');
+
+    expect(execFileMock.mock.calls[0][0]).toBe('/opt/ffmpeg/bin/ffmpeg');
+
+    if (previous === undefined) delete process.env.FFMPEG_PATH;
+    else process.env.FFMPEG_PATH = previous;
+  });
+
+  it('propagates a rejection from execFile as a rejected promise', async () => {
+    execFileMock.mockImplementation((file, args, options, callback) =>
+      callback(new Error('ffmpeg exited with code 1'), '', 'Unknown encoder')
+    );
+
+    await expect(resolve('mp3', 'wav').convert('/tmp/in.mp3', '/tmp/out.wav')).rejects.toThrow(
+      /exited with code 1/
+    );
+  });
+});
+```
+
+- [ ] **Step 6: Run tests to verify they pass**
+
+Run: `DB_HOST=127.0.0.1 DB_USER=convert_user DB_PASSWORD=change_me DB_NAME=file_converter STORAGE_DIR=./storage PORT=3000 npx vitest run test/converters/audio.test.js`
+Expected: PASS (9 tests total)
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/converters/audio.js test/converters/audio.test.js
+git commit -m "feat(audio): add ffmpeg-backed audio converter for mp3/wav/ogg/flac/aac/m4a"
+```
+
+---
+
+### Task 2: Wire registration + bitrate validation into `app.js`/`worker.js`
+
+**Files:**
+- Modify: `src/app.js` (import, `registerAllConverters()`, `isValidQuality`)
+- Modify: `src/worker.js` (import, `main()`)
+- Test: `test/api/jobs.test.js` (new describe block)
+
+**Interfaces:**
+- Consumes: `registerAudioConverters` from `./converters/audio.js` (Task 1).
+- Produces: `POST /api/jobs` now accepts `sourceFormat`/`targetFormat` pairs among the 6 audio formats with `family: 'audio'`, and validates `quality` as one of `[128, 192, 256, 320]` (or `null`) for `mp3`/`ogg`/`aac`/`m4a`, and only `null` for `wav`/`flac`.
+
+- [ ] **Step 1: Write the failing integration tests**
+
+Append to `test/api/jobs.test.js`, after the `POST /api/jobs — archives` block (before its closing nothing — just append at end of file):
+
+```js
+describe('POST /api/jobs — audio', () => {
+  it('creates a pending job converting a wav upload to mp3 with a valid bitrate', async () => {
+    const fixturePath = path.join(config.storageDir, 'clip.wav');
+    // Minimal RIFF/WAVE header: 'RIFF' + 4-byte size (unchecked) + 'WAVE'.
+    await fs.writeFile(fixturePath, Buffer.concat([Buffer.from('RIFF'), Buffer.alloc(4), Buffer.from('WAVE')]));
+
+    const response = await request(app)
+      .post('/api/jobs')
+      .field('targetFormats', JSON.stringify(['mp3']))
+      .field('qualities', JSON.stringify([192]))
+      .attach('files', fixturePath, 'clip.wav');
+
+    expect(response.status).toBe(201);
+    expect(response.body.jobs[0].status).toBe('pending');
+
+    const job = await getJobByUuid(prisma, response.body.jobs[0].id);
+    expect(job.sourceFormat).toBe('wav');
+    expect(job.targetFormat).toBe('mp3');
+    expect(job.family).toBe('audio');
+    expect(job.quality).toBe(192);
+
+    await fs.unlink(fixturePath);
+  });
+
+  it('rejects a bitrate outside the fixed chip set for an mp3 target', async () => {
+    const fixturePath = path.join(config.storageDir, 'bad-bitrate.wav');
+    await fs.writeFile(fixturePath, Buffer.concat([Buffer.from('RIFF'), Buffer.alloc(4), Buffer.from('WAVE')]));
+
+    const response = await request(app)
+      .post('/api/jobs')
+      .field('targetFormats', JSON.stringify(['mp3']))
+      .field('qualities', JSON.stringify([200]))
+      .attach('files', fixturePath, 'bad-bitrate.wav');
+
+    expect(response.status).toBe(201);
+    expect(response.body.jobs[0].error).toMatch(/Invalid quality/);
+
+    await fs.unlink(fixturePath);
+  });
+
+  it('rejects a quality value for a wav target (lossless, no bitrate control)', async () => {
+    const fixturePath = path.join(config.storageDir, 'to-wav.wav');
+    await fs.writeFile(fixturePath, Buffer.concat([Buffer.from('RIFF'), Buffer.alloc(4), Buffer.from('WAVE')]));
+
+    const response = await request(app)
+      .post('/api/jobs')
+      .field('targetFormats', JSON.stringify(['flac']))
+      .field('qualities', JSON.stringify([192]))
+      .attach('files', fixturePath, 'to-wav.wav');
+
+    expect(response.status).toBe(201);
+    expect(response.body.jobs[0].error).toMatch(/Invalid quality/);
+
+    await fs.unlink(fixturePath);
+  });
+
+  it('creates a pending job converting flac to wav with no quality value', async () => {
+    const fixturePath = path.join(config.storageDir, 'clip.flac');
+    await fs.writeFile(fixturePath, Buffer.from('fLaC'));
+
+    const response = await request(app)
+      .post('/api/jobs')
+      .field('targetFormats', JSON.stringify(['wav']))
+      .attach('files', fixturePath, 'clip.flac');
+
+    expect(response.status).toBe(201);
+    const job = await getJobByUuid(prisma, response.body.jobs[0].id);
+    expect(job.sourceFormat).toBe('flac');
+    expect(job.targetFormat).toBe('wav');
+    expect(job.quality).toBeNull();
+
+    await fs.unlink(fixturePath);
+  });
+
+  it('lists the other 5 audio formats as targets for mp3, and never lists mp3 as its own target', async () => {
+    const response = await request(app).get('/api/formats').query({ source: 'mp3' });
+
+    expect(response.body.targets).toEqual(expect.arrayContaining(['wav', 'ogg', 'flac', 'aac', 'm4a']));
+    expect(response.body.targets).not.toContain('mp3');
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `DB_HOST=127.0.0.1 DB_USER=convert_user DB_PASSWORD=change_me DB_NAME=file_converter STORAGE_DIR=./storage PORT=3000 npx vitest run test/api/jobs.test.js`
+Expected: FAIL — jobs come back with `error: "Unsupported conversion: wav to mp3"` (registry has no `audio` entries yet), and the `mp3` case in `GET /api/formats` returns an empty/unrelated list.
+
+- [ ] **Step 3: Wire registration into `src/app.js`**
+
+In `src/app.js`, add the import alongside the other converter imports (after line 16, `import { registerArchiveConverters } from './converters/archive.js';`):
+
+```js
+import { registerAudioConverters } from './converters/audio.js';
+```
+
+In `registerAllConverters()` (around line 42-54), add the call alongside the other eight:
+
+```js
+function registerAllConverters() {
+  if (convertersRegistered) return;
+  registerImageConverters();
+  registerImageToPdfConverter();
+  registerDocumentConverters();
+  registerIcoConverter();
+  registerHeicConverter();
+  registerFontConverter();
+  registerDfontConverter();
+  registerEbookConverter();
+  registerArchiveConverters();
+  registerAudioConverters();
+  convertersRegistered = true;
+}
+```
+
+- [ ] **Step 4: Add bitrate validation to `isValidQuality` in `src/app.js`**
+
+Replace the existing `isValidQuality` function (lines 25-32):
+
+```js
+function isValidQuality(targetFormat, quality) {
+  if (quality === null || quality === undefined) return true;
+  if (!Number.isInteger(quality)) return false;
+  if (targetFormat === 'gif' || targetFormat === 'ico' || targetFormat === 'tar') return false;
+  if (targetFormat === 'png') return quality >= 0 && quality <= 9;
+  if (['zip', 'tar.gz', 'tar.bz2', '7z', 'tar.7z'].includes(targetFormat)) return quality >= 0 && quality <= 9;
+  if (['wav', 'flac'].includes(targetFormat)) return false;
+  if (['mp3', 'ogg', 'aac', 'm4a'].includes(targetFormat)) return [128, 192, 256, 320].includes(quality);
+  return quality >= 1 && quality <= 100;
+}
+```
+
+(The `wav`/`flac` branch must come before the final fallthrough so a non-null quality for those formats is rejected rather than falling into the generic `1-100` range check.)
+
+- [ ] **Step 5: Wire registration into `src/worker.js`**
+
+Add the import alongside the other converter imports (after line 16, `import { registerArchiveConverters } from './converters/archive.js';`):
+
+```js
+import { registerAudioConverters } from './converters/audio.js';
+```
+
+In `main()` (around lines 85-93), add the call alongside the other eight:
+
+```js
+  registerImageConverters();
+  registerImageToPdfConverter();
+  registerDocumentConverters();
+  registerIcoConverter();
+  registerHeicConverter();
+  registerFontConverter();
+  registerDfontConverter();
+  registerEbookConverter();
+  registerArchiveConverters();
+  registerAudioConverters();
+```
+
+- [ ] **Step 6: Run tests to verify they pass**
+
+Run: `DB_HOST=127.0.0.1 DB_USER=convert_user DB_PASSWORD=change_me DB_NAME=file_converter STORAGE_DIR=./storage PORT=3000 npx vitest run test/api/jobs.test.js`
+Expected: PASS (all tests in the file, including the new `POST /api/jobs — audio` block)
+
+- [ ] **Step 7: Run the full backend test suite to check for regressions**
+
+Run: `DB_HOST=127.0.0.1 DB_USER=convert_user DB_PASSWORD=change_me DB_NAME=file_converter STORAGE_DIR=./storage PORT=3000 npx vitest run`
+Expected: PASS, except the two pre-existing unrelated failures documented in `CLAUDE.md` (`test/cleanup.test.js` and `test/jobs/jobRepository.test.js`, both clock/timezone issues predating this change — confirm no *new* failures beyond those two).
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add src/app.js src/worker.js test/api/jobs.test.js
+git commit -m "feat(audio): wire audio converters and bitrate validation into app.js/worker.js"
+```
+
+---
+
+### Task 3: MIME types for audio formats
+
+**Files:**
+- Modify: `src/mime.js`
+- Test: `test/mime.test.js`
+
+**Interfaces:**
+- Consumes: nothing new (existing `OUTPUT_MIME_TYPES` map and `resolveInputFormat`/`detectInputMime` in `src/mime.js`).
+- Produces: `outputMimeType('mp3'|'wav'|'ogg'|'flac'|'aac'|'m4a')` returns a real MIME string instead of throwing; `resolveInputFormat` accepts real content declared under each of these 6 formats.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `test/mime.test.js`, after the `describe('resolveInputFormat — compound archive extensions', ...)` block at the end of the file:
+
+```js
+describe('outputMimeType — audio', () => {
+  it('returns the correct MIME type for each audio target format', () => {
+    expect(outputMimeType('mp3')).toBe('audio/mpeg');
+    expect(outputMimeType('wav')).toBe('audio/wav');
+    expect(outputMimeType('ogg')).toBe('audio/ogg');
+    expect(outputMimeType('flac')).toBe('audio/flac');
+    expect(outputMimeType('aac')).toBe('audio/aac');
+    expect(outputMimeType('m4a')).toBe('audio/x-m4a');
+  });
+});
+
+describe('resolveInputFormat — audio formats', () => {
+  it('accepts a WAV file (RIFF....WAVE) declared as wav', async () => {
+    const fixturePath = path.join(import.meta.dirname, 'fixtures', 'sample-audio.wav');
+    await fs.writeFile(fixturePath, Buffer.concat([Buffer.from('RIFF'), Buffer.alloc(4), Buffer.from('WAVE')]));
+
+    const result = await resolveInputFormat(fixturePath, 'wav');
+    expect(result).toEqual({ mime: 'audio/wav', valid: true });
+
+    await fs.unlink(fixturePath);
+  });
+
+  it('accepts a FLAC file (fLaC magic) declared as flac', async () => {
+    const fixturePath = path.join(import.meta.dirname, 'fixtures', 'sample-audio.flac');
+    await fs.writeFile(fixturePath, Buffer.from('fLaC'));
+
+    const result = await resolveInputFormat(fixturePath, 'flac');
+    expect(result).toEqual({ mime: 'audio/flac', valid: true });
+
+    await fs.unlink(fixturePath);
+  });
+
+  it('accepts an MP3 file (MPEG layer 3 frame sync) declared as mp3', async () => {
+    const fixturePath = path.join(import.meta.dirname, 'fixtures', 'sample-audio.mp3');
+    // Frame sync 0xFF 0xFB: byte1 & 0xE0 == 0xE0 (sync), byte1 & 0x06 == 0x02 (layer 3, not ADTS).
+    await fs.writeFile(fixturePath, Buffer.from([0xff, 0xfb, 0x90, 0x00, 0x00, 0x00, 0x00, 0x00]));
+
+    const result = await resolveInputFormat(fixturePath, 'mp3');
+    expect(result).toEqual({ mime: 'audio/mpeg', valid: true });
+
+    await fs.unlink(fixturePath);
+  });
+
+  it('accepts an AAC/ADTS file declared as aac', async () => {
+    const fixturePath = path.join(import.meta.dirname, 'fixtures', 'sample-audio.aac');
+    // Frame sync 0xFF 0xF1: byte1 & 0xE0 == 0xE0 (sync), byte1 & 0x16 == 0x10 (ADTS, not layer 3).
+    await fs.writeFile(fixturePath, Buffer.from([0xff, 0xf1, 0x4c, 0x80, 0x01, 0x3f, 0xfc, 0x00]));
+
+    const result = await resolveInputFormat(fixturePath, 'aac');
+    expect(result).toEqual({ mime: 'audio/aac', valid: true });
+
+    await fs.unlink(fixturePath);
+  });
+
+  it('accepts an OGG/Vorbis file declared as ogg', async () => {
+    const fixturePath = path.join(import.meta.dirname, 'fixtures', 'sample-audio.ogg');
+    // 'OggS' + 28 ignored bytes + 8-byte packet-type field starting '\x01vorbis'.
+    const body = Buffer.concat([
+      Buffer.from('OggS'),
+      Buffer.alloc(28),
+      Buffer.concat([Buffer.from([0x01]), Buffer.from('vorbis'), Buffer.alloc(1)]),
+    ]);
+    await fs.writeFile(fixturePath, body);
+
+    const result = await resolveInputFormat(fixturePath, 'ogg');
+    expect(result).toEqual({ mime: 'audio/ogg', valid: true });
+
+    await fs.unlink(fixturePath);
+  });
+
+  it('accepts an M4A file (ISO-BMFF ftyp box, M4A brand) declared as m4a', async () => {
+    const fixturePath = path.join(import.meta.dirname, 'fixtures', 'sample-audio.m4a');
+    // 4-byte box size (unchecked) + 'ftyp' + major brand 'M4A ' (space-padded, 4 bytes).
+    const body = Buffer.concat([Buffer.alloc(4), Buffer.from('ftyp'), Buffer.from('M4A ')]);
+    await fs.writeFile(fixturePath, body);
+
+    const result = await resolveInputFormat(fixturePath, 'm4a');
+    expect(result).toEqual({ mime: 'audio/x-m4a', valid: true });
+
+    await fs.unlink(fixturePath);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `DB_HOST=127.0.0.1 DB_USER=convert_user DB_PASSWORD=change_me DB_NAME=file_converter STORAGE_DIR=./storage PORT=3000 npx vitest run test/mime.test.js`
+Expected: FAIL — `outputMimeType('mp3')` etc. throw `No known MIME type for target format "mp3"`.
+
+- [ ] **Step 3: Add the MIME entries in `src/mime.js`**
+
+In `src/mime.js`, add to `OUTPUT_MIME_TYPES` (after the existing `'tar.7z': 'application/x-7z-compressed',` line):
+
+```js
+  mp3: 'audio/mpeg',
+  wav: 'audio/wav',
+  ogg: 'audio/ogg',
+  flac: 'audio/flac',
+  aac: 'audio/aac',
+  m4a: 'audio/x-m4a',
+```
+
+No other changes to `src/mime.js` — `resolveInputFormat`/`normalizeFormat` need no alias entries for these six formats (each detects with an `ext` that already matches the declared format string exactly).
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `DB_HOST=127.0.0.1 DB_USER=convert_user DB_PASSWORD=change_me DB_NAME=file_converter STORAGE_DIR=./storage PORT=3000 npx vitest run test/mime.test.js`
+Expected: PASS (all tests in the file)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/mime.js test/mime.test.js
+git commit -m "feat(audio): add MIME types for mp3/wav/ogg/flac/aac/m4a"
+```
+
+---
+
+### Task 4: Frontend — recognize the `audio` family (icon, color, formats grid)
+
+**Files:**
+- Modify: `frontend/src/data/formats.js`
+- Modify: `frontend/src/utils/fileFamily.js`
+- Modify: `frontend/src/components/FormatsGrid.jsx`
+- Modify: `frontend/src/index.css`
+- Modify: `frontend/src/locales/en.json`
+- Modify: `frontend/src/locales/fr.json`
+
+**Interfaces:**
+- Consumes: nothing new from earlier tasks (this task only needs the format strings `mp3`/`wav`/`ogg`/`flac`/`aac`/`m4a`, which are plain data, not an import).
+- Produces: `familyForExtension('mp3')` (etc.) returns `'audio'`; `fileTypeMeta('mp3')` returns `{ Icon: MusicNotes, colorVar: '--color-family-audio' }`; the "Supported formats" section on the homepage shows an Audio tile listing the 6 formats. No automated test — this repo has no frontend test suite; verified manually in Task 5 once the upload flow can exercise it end-to-end.
+
+- [ ] **Step 1: Add the `audio` family to `frontend/src/data/formats.js`**
+
+Add a new entry to the `FORMAT_FAMILIES` array (after the `archives` entry):
+
+```js
+  {
+    key: 'audio',
+    formats: ['mp3', 'wav', 'ogg', 'flac', 'aac', 'm4a'],
+  },
+```
+
+- [ ] **Step 2: Add the icon mapping in `frontend/src/utils/fileFamily.js`**
+
+Change the import line to add `MusicNotes`:
+
+```js
+import { Image, FileText, TextAa, BookOpen, Archive, MusicNotes, File as FileIcon } from '@phosphor-icons/react';
+```
+
+Add to `FAMILY_ICONS`:
+
+```js
+const FAMILY_ICONS = {
+  images: Image,
+  documents: FileText,
+  fonts: TextAa,
+  ebooks: BookOpen,
+  archives: Archive,
+  audio: MusicNotes,
+};
+```
+
+- [ ] **Step 3: Add the icon mapping in `frontend/src/components/FormatsGrid.jsx`**
+
+Change the import line to add `MusicNotes`:
+
+```jsx
+import { Image, FileText, TextAa, BookOpen, Archive, MusicNotes } from '@phosphor-icons/react';
+```
+
+Add to `FAMILY_ICONS`:
+
+```js
+const FAMILY_ICONS = {
+  images: Image,
+  documents: FileText,
+  fonts: TextAa,
+  ebooks: BookOpen,
+  archives: Archive,
+  audio: MusicNotes,
+};
+```
+
+- [ ] **Step 4: Add the color variable in `frontend/src/index.css`**
+
+In the light-theme block (after `--color-family-archives: #64748b;`):
+
+```css
+  --color-family-audio: #ec4899;
+```
+
+In the dark-theme block (after `--color-family-archives: #94a3b8;`):
+
+```css
+  --color-family-audio: #f472b6;
+```
+
+- [ ] **Step 5: Add locale strings**
+
+In `frontend/src/locales/en.json`, in the `formats` object (after `"archives": "Archives"`):
+
+```json
+    "archives": "Archives",
+    "audio": "Audio"
+```
+
+In `frontend/src/locales/fr.json`, in the `formats` object (after `"archives": "Archives"`):
+
+```json
+    "archives": "Archives",
+    "audio": "Audio"
+```
+
+(Note: this adds a trailing comma to the existing `archives` line in both files — check the JSON is still valid after editing, since it's currently the last key in the object before the closing brace.)
+
+- [ ] **Step 6: Manually verify in the browser**
+
+Run: `npm run dev --prefix frontend` (check first whether a dev server is already running per `CLAUDE.md`'s guidance on pre-existing processes before starting a new one)
+
+Open the homepage, scroll to "Supported formats" / "Formats pris en charge", and confirm an "Audio" tile appears listing `MP3, WAV, OGG, FLAC, AAC, M4A` with a pink music-note icon, matching the visual style of the other family tiles.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add frontend/src/data/formats.js frontend/src/utils/fileFamily.js frontend/src/components/FormatsGrid.jsx frontend/src/index.css frontend/src/locales/en.json frontend/src/locales/fr.json
+git commit -m "feat(audio): recognize the audio family in the frontend formats grid"
+```
+
+---
+
+### Task 5: Frontend — bitrate chips, default quality, marquee pair
+
+**Files:**
+- Modify: `frontend/src/components/FileConfigCard.jsx`
+- Modify: `frontend/src/pages/HomePage.jsx`
+- Modify: `frontend/src/components/FormatMarquee.jsx`
+- Modify: `frontend/src/locales/en.json`
+- Modify: `frontend/src/locales/fr.json`
+
+**Interfaces:**
+- Consumes: `GET /api/formats?source=<audio-format>` (Task 2) to populate `item.targets` for an uploaded audio file; the `quality` field on `pendingFiles` items (existing state shape in `HomePage.jsx`, unchanged).
+- Produces: uploading an audio file shows bitrate chips (`128`/`192`/`256`/`320` kbps) for `mp3`/`ogg`/`aac`/`m4a` targets, no control for `wav`/`flac` targets, and `POST /api/jobs` receives a `qualities` entry matching the selected chip.
+
+- [ ] **Step 1: Add the bitrate chip group to `frontend/src/components/FileConfigCard.jsx`**
+
+Add a new constant near the top of the file (alongside `QUALITY_FORMATS`/`ICON_SIZES`):
+
+```js
+const AUDIO_BITRATE_FORMATS = ['mp3', 'ogg', 'aac', 'm4a'];
+const AUDIO_BITRATES = [128, 192, 256, 320];
+```
+
+Add a new conditional block inside `file-config-controls`, after the `ARCHIVE_COMPRESSION_FORMATS` block and before the `item.targetFormat === 'ico'` block:
+
+```jsx
+          {AUDIO_BITRATE_FORMATS.includes(item.targetFormat) && (
+            <div className="chip-field">
+              <span>{t('quality.bitrate')}</span>
+              <div className="chip-group" role="group" aria-label={t('quality.bitrate')}>
+                {AUDIO_BITRATES.map((bitrate) => (
+                  <button
+                    key={bitrate}
+                    type="button"
+                    className={`chip${item.quality === bitrate ? ' chip-active' : ''}`}
+                    aria-pressed={item.quality === bitrate}
+                    onClick={() => onQualityChange(index, bitrate)}
+                  >
+                    {bitrate}kbps
+                  </button>
+                ))}
+              </div>
+            </div>
+          )}
+```
+
+- [ ] **Step 2: Add default bitrates to `frontend/src/pages/HomePage.jsx`**
+
+In the `DEFAULT_QUALITY` object, add the 4 bitrate-capable audio formats:
+
+```js
+const DEFAULT_QUALITY = {
+  jpg: 80,
+  jpeg: 80,
+  webp: 80,
+  avif: 50,
+  tiff: 80,
+  png: 6,
+  zip: 6,
+  'tar.gz': 6,
+  'tar.bz2': 9,
+  '7z': 5,
+  'tar.7z': 5,
+  mp3: 192,
+  ogg: 192,
+  aac: 192,
+  m4a: 192,
+};
+```
+
+(`wav`/`flac` are intentionally omitted — `defaultQualityFor` already returns `null` for anything absent from this map.)
+
+- [ ] **Step 3: Add a marquee pair to `frontend/src/components/FormatMarquee.jsx`**
+
+Add one pair to `PAIRS`:
+
+```js
+const PAIRS = [
+  ['heic', 'jpg'],
+  ['png', 'webp'],
+  ['docx', 'pdf'],
+  ['ttf', 'woff'],
+  ['epub', 'mobi'],
+  ['rar', 'zip'],
+  ['wav', 'mp3'],
+];
+```
+
+- [ ] **Step 4: Add the `bitrate` locale key**
+
+In `frontend/src/locales/en.json`, in the `quality` object (after `"compressPdf": "Compress as JPEG"` or whatever the last existing key is — check the file first since only `fr.json` was read directly; match its existing key order/style):
+
+```json
+    "bitrate": "Bitrate"
+```
+
+In `frontend/src/locales/fr.json`, in the `quality` object (after `"compressPdf": "Compresser en JPEG"`):
+
+```json
+    "bitrate": "Bitrate"
+```
+
+- [ ] **Step 5: Manually verify in the browser**
+
+With the frontend dev server running (from Task 4, Step 6), and the backend server/worker running per `CLAUDE.md`'s guidance on pre-existing processes:
+
+1. Upload a `.wav` file. Confirm the target-format chips include `MP3`, `OGG`, `FLAC`, `AAC`, `M4A` (not `WAV`).
+2. Select `MP3` as the target. Confirm bitrate chips `128kbps`/`192kbps`/`256kbps`/`320kbps` appear, with `192kbps` pre-selected.
+3. Switch the target to `FLAC`. Confirm the bitrate chips disappear (no quality control at all).
+4. Switch back to `MP3`, click convert. Confirm the job is created as `pending` (note: since ffmpeg is not installed locally, per `CLAUDE.md` guidance the job will end up `failed` once a worker picks it up and shells out to a nonexistent `ffmpeg` binary — that failure is expected in this environment and is not a regression; it confirms the *job creation and validation* path, not the actual conversion, which can only be confirmed where ffmpeg is present).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add frontend/src/components/FileConfigCard.jsx frontend/src/pages/HomePage.jsx frontend/src/components/FormatMarquee.jsx frontend/src/locales/en.json frontend/src/locales/fr.json
+git commit -m "feat(audio): add bitrate chip control, default bitrates, and marquee pair"
+```
+
+---
+
+## Post-plan note (not a task — informational only)
+
+Deploying this to o2switch requires no migration and no new dependency install beyond what's already there — `FFMPEG_PATH` is already set per the user. Confirm `FFMPEG_PATH` points at a real, executable ffmpeg binary on that host before relying on this in production (the existing `.env.local` mirrors `CALIBRE_PATH` with a real o2switch path as a reference for what `FFMPEG_PATH` should look like there).