From 13d095aa4c5c05fd33e7ffae9b1485eb6b90b80a Mon Sep 17 00:00:00 2001 From: Anthony GAEREMYNCK <1@anthony.sh> Date: Sat, 1 Aug 2026 13:41:00 +0200 Subject: [PATCH] docs: add audio conversion implementation plan --- .../plans/2026-08-01-audio-conversion.md | 788 ++++++++++++++++++ 1 file changed, 788 insertions(+) create mode 100644 docs/superpowers/plans/2026-08-01-audio-conversion.md diff --git a/docs/superpowers/plans/2026-08-01-audio-conversion.md b/docs/superpowers/plans/2026-08-01-audio-conversion.md new file mode 100644 index 0000000..fbc4cc4 --- /dev/null +++ b/docs/superpowers/plans/2026-08-01-audio-conversion.md @@ -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 `. + +--- + +### 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`. + +- [ ] **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=` (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) && ( +
+ {t('quality.bitrate')} +
+ {AUDIO_BITRATES.map((bitrate) => ( + + ))} +
+
+ )} +``` + +- [ ] **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).