Ombrora/convert
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
convert/docs/superpowers/plans/2026-08-01-video-conversion.md
T

822 lines
32 KiB
Markdown
Raw Permalink Blame History

# Video 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 `video` converter family supporting `mp4`, `webm`, `mov`, `avi`, `mkv` (all pairs except same-format), each with an optional resolution control (`480`/`720`/`1080`/original) reusing the existing `quality` job field, ffmpeg-backed via the existing `FFMPEG_PATH` env var.
**Architecture:** One flat converter in `src/converters/video.js`, same shape as `src/converters/audio.js`: a fixed `CODEC_ARGS` map keyed by target format, registered as the full cross product (minus same-format pairs) via the existing `registry.js`. A new `VIDEO_JOB_TIMEOUT_MS` config value (default 300000ms) gives video jobs a longer worker timeout than the 60s default, matching the precedent `EBOOK_JOB_TIMEOUT_MS` already set.
**Tech Stack:** `ffmpeg` via `child_process.execFile` (already a dependency of the running system via `FFMPEG_PATH`, not an npm package — identical to `audio.js`). No new npm dependencies.
## Global Constraints
- Formats: `mp4`, `webm`, `mov`, `avi`, `mkv`. All pairs registered except `sourceFormat === targetFormat` (same rule as `audio`/`image`/`document`/`font`/`ebook` — unlike `archive`, which is a deliberate exception).
- Codec map (fixed, no user choice): `mp4`/`mov`/`mkv` → `libx264` video + `aac` audio; `webm` → `libvpx-vp9` video + `libopus` audio; `avi` → `mpeg4` video + `libmp3lame` audio.
- Resolution control reuses `ConversionJob.quality` (`Int?`, no schema change): allowed values `480`, `720`, `1080`, or `null` (original, no scale filter). `app.js`'s `isValidQuality` is the only place that range-checks the value; the converter itself applies `-vf scale=-2:<height>` whenever `quality != null`, trusting the upstream check (same division of responsibility `audio.js` uses).
- New `VIDEO_JOB_TIMEOUT_MS` config var, default `300000`, read the same way `EBOOK_JOB_TIMEOUT_MS` is.
- No video → audio-only or video → GIF conversions — out of scope, cross-family concerns not requested.
- `ffmpeg` is not installed on this dev machine (confirmed: `ffmpeg -version` → command not found), so all backend converter/worker tests mock `node:child_process`'s `execFile`, never invoking a real binary — same approach `audio.test.js` and the ebook case in `worker.test.js` already use.
- `file-type` v22's detection for all 5 formats was verified against hand-crafted magic-byte buffers (see spec) — every format's detected `ext` equals its own name, so no `normalizeFormat` alias is needed for any of them.
- Spec reference: `docs/superpowers/specs/2026-08-01-video-conversion-design.md`.
---
### Task 1: `VIDEO_JOB_TIMEOUT_MS` config value
**Files:**
- Modify: `src/config.js`
- Test: `test/config.test.js`
**Interfaces:**
- Produces: `config.videoJobTimeoutMs` (number, default `300000`, from `process.env.VIDEO_JOB_TIMEOUT_MS`).
- [ ] **Step 1: Write the failing test**
Append to `test/config.test.js`, inside the `describe('loadConfig', ...)` block (after the existing `ebookJobTimeoutMs` test):
```js
it('defaults videoJobTimeoutMs to 300000ms and reads VIDEO_JOB_TIMEOUT_MS when set', () => {
process.env.STORAGE_DIR = './storage';
process.env.DB_HOST = 'localhost';
process.env.DB_USER = 'user';
process.env.DB_PASSWORD = 'pass';
process.env.DB_NAME = 'db';
delete process.env.VIDEO_JOB_TIMEOUT_MS;
expect(loadConfig().videoJobTimeoutMs).toBe(300000);
process.env.VIDEO_JOB_TIMEOUT_MS = '400000';
expect(loadConfig().videoJobTimeoutMs).toBe(400000);
});
```
- [ ] **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/config.test.js`
Expected: FAIL — `loadConfig().videoJobTimeoutMs` is `undefined`, not `300000`.
- [ ] **Step 3: Write minimal implementation**
In `src/config.js`, add one line inside the returned object, alongside `ebookJobTimeoutMs`:
```js
ebookJobTimeoutMs: Number(process.env.EBOOK_JOB_TIMEOUT_MS ?? 180000),
videoJobTimeoutMs: Number(process.env.VIDEO_JOB_TIMEOUT_MS ?? 300000),
```
- [ ] **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/config.test.js`
Expected: PASS
- [ ] **Step 5: Commit**
```bash
git add src/config.js test/config.test.js
git commit -m "feat(video): add configurable VIDEO_JOB_TIMEOUT_MS"
```
---
### Task 2: Video converter (`src/converters/video.js`)
**Files:**
- Create: `src/converters/video.js`
- Test: `test/converters/video.test.js`
**Interfaces:**
- Consumes: `register` from `./registry.js` (existing, `register({ family, sourceFormat, targetFormat, convert })`).
- Produces: `registerVideoConverters(): void`, `VIDEO_FORMATS: string[]` (exactly `['mp4', 'webm', 'mov', 'avi', 'mkv']`).
- [ ] **Step 1: Write the failing test**
```js
// test/converters/video.test.js
import { describe, it, expect, beforeEach, vi } from 'vitest';
import { registerVideoConverters, VIDEO_FORMATS } from '../../src/converters/video.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('registerVideoConverters — registration', () => {
it('registers every pair among the 5 video formats, and nothing for source === target', () => {
registerVideoConverters();
for (const sourceFormat of VIDEO_FORMATS) {
for (const targetFormat of VIDEO_FORMATS) {
const entry = resolve(sourceFormat, targetFormat);
if (sourceFormat === targetFormat) {
expect(entry).toBeNull();
} else {
expect(entry).not.toBeNull();
expect(entry.family).toBe('video');
}
}
}
});
it('exposes exactly the 5 requested formats', () => {
expect(VIDEO_FORMATS.sort()).toEqual(['avi', 'mkv', 'mov', 'mp4', 'webm'].sort());
});
});
describe('registerVideoConverters — subprocess invocation', () => {
beforeEach(() => {
registerVideoConverters();
});
it('calls ffmpeg with -i, the codec args, and the output path, omitting -vf when no quality is given', async () => {
await resolve('mov', 'mp4').convert('/tmp/in.mov', '/tmp/out.mp4');
expect(execFileMock).toHaveBeenCalledTimes(1);
const [file, args, options] = execFileMock.mock.calls[0];
expect(file).toBe('ffmpeg');
expect(args).toEqual([
'-y', '-i', '/tmp/in.mov', '-c:v', 'libx264', '-c:a', 'aac', '/tmp/out.mp4',
]);
expect(options).toEqual({ timeout: undefined });
});
it('appends -vf scale=-2:<height> when a resolution quality is given', async () => {
await resolve('mov', 'mp4').convert('/tmp/in.mov', '/tmp/out.mp4', { quality: 720 });
const [, args] = execFileMock.mock.calls[0];
expect(args).toEqual([
'-y', '-i', '/tmp/in.mov', '-c:v', 'libx264', '-c:a', 'aac', '-vf', 'scale=-2:720', '/tmp/out.mp4',
]);
});
it('uses libvpx-vp9 and libopus for a webm target', async () => {
await resolve('mp4', 'webm').convert('/tmp/in.mp4', '/tmp/out.webm');
const [, args] = execFileMock.mock.calls[0];
expect(args).toEqual([
'-y', '-i', '/tmp/in.mp4', '-c:v', 'libvpx-vp9', '-c:a', 'libopus', '/tmp/out.webm',
]);
});
it('uses mpeg4 and libmp3lame for an avi target', async () => {
await resolve('mp4', 'avi').convert('/tmp/in.mp4', '/tmp/out.avi');
const [, args] = execFileMock.mock.calls[0];
expect(args).toEqual([
'-y', '-i', '/tmp/in.mp4', '-c:v', 'mpeg4', '-c:a', 'libmp3lame', '/tmp/out.avi',
]);
});
it('uses libx264 and aac for an mkv target', async () => {
await resolve('mp4', 'mkv').convert('/tmp/in.mp4', '/tmp/out.mkv');
const [, args] = execFileMock.mock.calls[0];
expect(args).toEqual([
'-y', '-i', '/tmp/in.mp4', '-c:v', 'libx264', '-c:a', 'aac', '/tmp/out.mkv',
]);
});
it('forwards options.timeoutMs to execFile as its timeout', async () => {
await resolve('mp4', 'webm').convert('/tmp/in.mp4', '/tmp/out.webm', { timeoutMs: 300000 });
const [, , options] = execFileMock.mock.calls[0];
expect(options).toEqual({ timeout: 300000 });
});
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('mp4', 'webm').convert('/tmp/in.mp4', '/tmp/out.webm');
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('mp4', 'webm').convert('/tmp/in.mp4', '/tmp/out.webm')).rejects.toThrow(
/exited with code 1/
);
});
});
```
- [ ] **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/video.test.js`
Expected: FAIL with a module-not-found error for `../../src/converters/video.js`.
- [ ] **Step 3: Write minimal implementation**
```js
// src/converters/video.js
import { execFile } from 'node:child_process';
import { promisify } from 'node:util';
import { register } from './registry.js';
const execFileAsync = promisify(execFile);
export const VIDEO_FORMATS = ['mp4', 'webm', 'mov', 'avi', 'mkv'];
const CODEC_ARGS = {
mp4: ['-c:v', 'libx264', '-c:a', 'aac'],
mov: ['-c:v', 'libx264', '-c:a', 'aac'],
mkv: ['-c:v', 'libx264', '-c:a', 'aac'],
webm: ['-c:v', 'libvpx-vp9', '-c:a', 'libopus'],
avi: ['-c:v', 'mpeg4', '-c:a', 'libmp3lame'],
};
export function registerVideoConverters() {
for (const sourceFormat of VIDEO_FORMATS) {
for (const targetFormat of VIDEO_FORMATS) {
if (sourceFormat === targetFormat) continue;
register({
family: 'video',
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) {
args.push('-vf', `scale=-2:${quality}`);
}
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/video.test.js`
Expected: PASS (10 tests)
- [ ] **Step 5: Commit**
```bash
git add src/converters/video.js test/converters/video.test.js
git commit -m "feat(video): add ffmpeg-backed video converter for mp4/webm/mov/avi/mkv"
```
---
### Task 3: MIME types (`src/mime.js`)
**Files:**
- Modify: `src/mime.js`
- Test: `test/mime.test.js`
**Interfaces:**
- Consumes: `OUTPUT_MIME_TYPES`, `resolveInputFormat` (both already in `src/mime.js`).
- Produces: no new exports — extends existing ones. No `normalizeFormat` changes (verified: `file-type` returns `ext` identical to the declared format name for all 5 video formats).
- [ ] **Step 1: Write the failing test**
Append to `test/mime.test.js`:
```js
describe('outputMimeType — video', () => {
it('returns the correct MIME type for each video target format', () => {
expect(outputMimeType('mp4')).toBe('video/mp4');
expect(outputMimeType('webm')).toBe('video/webm');
expect(outputMimeType('mov')).toBe('video/quicktime');
expect(outputMimeType('avi')).toBe('video/x-msvideo');
expect(outputMimeType('mkv')).toBe('video/x-matroska');
});
});
describe('resolveInputFormat — video magic bytes', () => {
it('accepts a minimal mp4 (ftyp box) declared as mp4', async () => {
const fixturePath = path.join(import.meta.dirname, 'fixtures', 'sample-video.mp4');
await fs.writeFile(
fixturePath,
Buffer.concat([Buffer.from([0, 0, 0, 0x18]), Buffer.from('ftyp'), Buffer.from('isom')])
);
const result = await resolveInputFormat(fixturePath, 'mp4');
expect(result).toEqual({ mime: 'video/mp4', valid: true });
await fs.unlink(fixturePath);
});
it('accepts a minimal mov (moov atom) declared as mov', async () => {
const fixturePath = path.join(import.meta.dirname, 'fixtures', 'sample-video.mov');
await fs.writeFile(fixturePath, Buffer.concat([Buffer.from([0, 0, 0, 0x08]), Buffer.from('moov')]));
const result = await resolveInputFormat(fixturePath, 'mov');
expect(result).toEqual({ mime: 'video/quicktime', valid: true });
await fs.unlink(fixturePath);
});
it('accepts a minimal avi (RIFF/AVI) declared as avi', async () => {
const fixturePath = path.join(import.meta.dirname, 'fixtures', 'sample-video.avi');
await fs.writeFile(
fixturePath,
Buffer.concat([Buffer.from('RIFF'), Buffer.from([0, 0, 0, 0]), Buffer.from('AVI ')])
);
const result = await resolveInputFormat(fixturePath, 'avi');
expect(result).toEqual({ mime: 'video/vnd.avi', valid: true });
await fs.unlink(fixturePath);
});
it('accepts a minimal webm (EBML DocType webm) declared as webm', async () => {
const fixturePath = path.join(import.meta.dirname, 'fixtures', 'sample-video.webm');
await fs.writeFile(
fixturePath,
Buffer.concat([Buffer.from([0x1a, 0x45, 0xdf, 0xa3, 0x81, 0x42, 0x82, 0x84]), Buffer.from('webm')])
);
const result = await resolveInputFormat(fixturePath, 'webm');
expect(result).toEqual({ mime: 'video/webm', valid: true });
await fs.unlink(fixturePath);
});
it('accepts a minimal mkv (EBML DocType matroska) declared as mkv', async () => {
const fixturePath = path.join(import.meta.dirname, 'fixtures', 'sample-video.mkv');
await fs.writeFile(
fixturePath,
Buffer.concat([Buffer.from([0x1a, 0x45, 0xdf, 0xa3, 0x81, 0x42, 0x82, 0x88]), Buffer.from('matroska')])
);
const result = await resolveInputFormat(fixturePath, 'mkv');
expect(result).toEqual({ mime: 'video/matroska', valid: true });
await fs.unlink(fixturePath);
});
it('rejects a webm file declared as mkv', async () => {
const fixturePath = path.join(import.meta.dirname, 'fixtures', 'sample-video-mismatch.webm');
await fs.writeFile(
fixturePath,
Buffer.concat([Buffer.from([0x1a, 0x45, 0xdf, 0xa3, 0x81, 0x42, 0x82, 0x84]), Buffer.from('webm')])
);
const result = await resolveInputFormat(fixturePath, 'mkv');
expect(result.valid).toBe(false);
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('mp4')` throws (unknown format).
- [ ] **Step 3: Write minimal implementation**
In `src/mime.js`, extend `OUTPUT_MIME_TYPES` (add anywhere among the existing entries):
```js
mp4: 'video/mp4',
webm: 'video/webm',
mov: 'video/quicktime',
avi: 'video/x-msvideo',
mkv: 'video/x-matroska',
```
No changes to `normalizeFormat` or `resolveInputFormat` — `file-type`'s detected `ext` already matches the declared format for all 5.
- [ ] **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/mime.test.js`
Expected: PASS
- [ ] **Step 5: Commit**
```bash
git add src/mime.js test/mime.test.js
git commit -m "feat(video): add MIME types for mp4/webm/mov/avi/mkv"
```
---
### Task 4: Wire into `app.js` and `worker.js`
**Files:**
- Modify: `src/app.js`
- Modify: `src/worker.js`
- Modify: `test/api/jobs.test.js`
- Modify: `test/worker.test.js`
**Interfaces:**
- Consumes: `registerVideoConverters` (Task 2), `config.videoJobTimeoutMs` (Task 1).
- Produces: no new exports — wires existing pieces into the two entry points.
- [ ] **Step 1: Write the failing tests**
Append to `test/api/jobs.test.js`:
```js
describe('POST /api/jobs — video', () => {
it('creates a pending job converting an mp4 upload to webm with a valid resolution', async () => {
const fixturePath = path.join(config.storageDir, 'clip.mp4');
await fs.writeFile(
fixturePath,
Buffer.concat([Buffer.from([0, 0, 0, 0x18]), Buffer.from('ftyp'), Buffer.from('isom')])
);
const response = await request(app)
.post('/api/jobs')
.field('targetFormats', JSON.stringify(['webm']))
.field('qualities', JSON.stringify([720]))
.attach('files', fixturePath, 'clip.mp4');
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('mp4');
expect(job.targetFormat).toBe('webm');
expect(job.family).toBe('video');
expect(job.quality).toBe(720);
await fs.unlink(fixturePath);
});
it('creates a pending job with no quality value (original resolution)', async () => {
const fixturePath = path.join(config.storageDir, 'clip-original.mp4');
await fs.writeFile(
fixturePath,
Buffer.concat([Buffer.from([0, 0, 0, 0x18]), Buffer.from('ftyp'), Buffer.from('isom')])
);
const response = await request(app)
.post('/api/jobs')
.field('targetFormats', JSON.stringify(['mkv']))
.attach('files', fixturePath, 'clip-original.mp4');
expect(response.status).toBe(201);
const job = await getJobByUuid(prisma, response.body.jobs[0].id);
expect(job.quality).toBeNull();
await fs.unlink(fixturePath);
});
it('rejects a resolution outside the fixed 480/720/1080 set', async () => {
const fixturePath = path.join(config.storageDir, 'bad-resolution.mp4');
await fs.writeFile(
fixturePath,
Buffer.concat([Buffer.from([0, 0, 0, 0x18]), Buffer.from('ftyp'), Buffer.from('isom')])
);
const response = await request(app)
.post('/api/jobs')
.field('targetFormats', JSON.stringify(['webm']))
.field('qualities', JSON.stringify([360]))
.attach('files', fixturePath, 'bad-resolution.mp4');
expect(response.status).toBe(201);
expect(response.body.jobs[0].error).toMatch(/Invalid quality/);
await fs.unlink(fixturePath);
});
it('lists the other 4 video formats as targets for mp4, and never lists mp4 as its own target', async () => {
const response = await request(app).get('/api/formats').query({ source: 'mp4' });
expect(response.body.targets).toEqual(expect.arrayContaining(['webm', 'mov', 'avi', 'mkv']));
expect(response.body.targets).not.toContain('mp4');
});
});
```
Append to `test/worker.test.js`, inside `describe('processPendingJobs', ...)` (after the ebook timeout test), and add `import { registerVideoConverters } from '../src/converters/video.js';` near the other converter imports at the top of the file, plus a call to `registerVideoConverters();` inside the existing `beforeAll` alongside `registerImageConverters()`/`registerIcoConverter()`/`registerEbookConverter()`:
```js
it('converts a pending video job to done using config.videoJobTimeoutMs, not the default 60s timeout', async () => {
execFileMock.mockReset();
execFileMock.mockImplementation((file, args, options, callback) => {
writeFileSync(args[args.length - 1], 'fake converted video output');
callback(null, '', '');
});
const uuid = '22222222-2222-4222-8222-222222222222';
const inputFilePath = uploadPath(config, uuid, 'mp4');
await fs.writeFile(inputFilePath, 'fake mp4 content');
await createJob(prisma, {
uuid,
family: 'video',
sourceFormat: 'mp4',
targetFormat: 'webm',
originalFilename: 'clip.mp4',
inputPath: `${uuid}.mp4`,
inputMimeType: 'video/mp4',
inputSizeBytes: 17,
expiresAt: new Date(Date.now() + 3600 * 1000),
quality: 720,
});
await processPendingJobs(prisma, config);
const job = await getJobByUuid(prisma, uuid);
expect(job.status).toBe('done');
const [file, args, options] = execFileMock.mock.calls[0];
expect(file).toBe('ffmpeg');
expect(args).toEqual([
'-y', '-i', inputFilePath, '-c:v', 'libvpx-vp9', '-c:a', 'libopus', '-vf', 'scale=-2:720',
outputPath(config, uuid, 'webm'),
]);
expect(options).toEqual({ timeout: config.videoJobTimeoutMs });
expect(config.videoJobTimeoutMs).not.toBe(60000);
});
```
- [ ] **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 test/worker.test.js`
Expected: FAIL — every video conversion is reported as `Unsupported conversion`, and the worker test errors on `No converter registered for mp4 -> webm`.
- [ ] **Step 3: Write minimal implementation**
In `src/app.js`, add the import near the other converter imports:
```js
import { registerVideoConverters } from './converters/video.js';
```
Update `registerAllConverters`:
```js
function registerAllConverters() {
if (convertersRegistered) return;
registerImageConverters();
registerImageToPdfConverter();
registerDocumentConverters();
registerIcoConverter();
registerHeicConverter();
registerFontConverter();
registerDfontConverter();
registerEbookConverter();
registerArchiveConverters();
registerAudioConverters();
registerVideoConverters();
convertersRegistered = true;
}
```
Update `isValidQuality` (add the new branch before the final fallback return):
```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);
if (['mp4', 'webm', 'mov', 'avi', 'mkv'].includes(targetFormat)) return [480, 720, 1080].includes(quality);
return quality >= 1 && quality <= 100;
}
```
In `src/worker.js`, add the import near the other converter imports:
```js
import { registerVideoConverters } from './converters/video.js';
```
Update the `timeoutMs` selection in `processJob`:
```js
const timeoutMs =
entry.family === 'ebook' ? config.ebookJobTimeoutMs :
entry.family === 'video' ? config.videoJobTimeoutMs :
JOB_TIMEOUT_MS;
```
Update `main()`:
```js
registerImageConverters();
registerImageToPdfConverter();
registerDocumentConverters();
registerIcoConverter();
registerHeicConverter();
registerFontConverter();
registerDfontConverter();
registerEbookConverter();
registerArchiveConverters();
registerAudioConverters();
registerVideoConverters();
```
- [ ] **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/api/jobs.test.js test/worker.test.js`
Expected: PASS
- [ ] **Step 5: Run the full backend test suite**
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 failing on `main` already).
- [ ] **Step 6: Commit**
```bash
git add src/app.js src/worker.js test/api/jobs.test.js test/worker.test.js
git commit -m "feat(video): wire video converters, resolution validation, and timeout into app.js/worker.js"
```
---
### Task 5: Frontend — video family, resolution control
**Files:**
- Modify: `frontend/src/data/formats.js`
- Modify: `frontend/src/utils/fileFamily.js`
- Modify: `frontend/src/components/FormatsGrid.jsx`
- Modify: `frontend/src/components/FileConfigCard.jsx`
- Modify: `frontend/src/components/FormatMarquee.jsx`
- Modify: `frontend/src/index.css`
- Modify: `frontend/src/locales/en.json`
- Modify: `frontend/src/locales/fr.json`
**Interfaces:**
- Consumes: `extensionOf` (existing, `frontend/src/utils/archiveExtensions.js` — `mp4`/`webm`/`mov`/`avi`/`mkv` are all simple single-dot extensions, so no change needed there).
There is no automated frontend test runner in this project (`frontend/package.json` has no `test` script) — every prior converter family's frontend work was verified by manual browser check, and this task follows the same convention.
- [ ] **Step 1: Add the `video` format family**
In `frontend/src/data/formats.js`, add a new entry to `FORMAT_FAMILIES`:
```js
{
key: 'video',
formats: ['mp4', 'webm', 'mov', 'avi', 'mkv'],
},
```
- [ ] **Step 2: Add the video family icon in both places it's defined**
In `frontend/src/utils/fileFamily.js`, add the import and map entry:
```js
import { Image, FileText, TextAa, BookOpen, Archive, MusicNotes, VideoCamera, File as FileIcon } from '@phosphor-icons/react';
```
```js
const FAMILY_ICONS = {
images: Image,
documents: FileText,
fonts: TextAa,
ebooks: BookOpen,
archives: Archive,
audio: MusicNotes,
video: VideoCamera,
};
```
In `frontend/src/components/FormatsGrid.jsx` (a separate, duplicated `FAMILY_ICONS` map — confirmed by reading the file):
```js
import { Image, FileText, TextAa, BookOpen, Archive, MusicNotes, VideoCamera } from '@phosphor-icons/react';
const FAMILY_ICONS = {
images: Image,
documents: FileText,
fonts: TextAa,
ebooks: BookOpen,
archives: Archive,
audio: MusicNotes,
video: VideoCamera,
};
```
- [ ] **Step 3: Add the `--color-family-video` CSS var**
In `frontend/src/index.css`, add one line to each of the two variable blocks (light `:root`, after `--color-family-audio`):
```css
--color-family-video: #38bdf8;
```
And to the dark `:root[data-theme='dark']` block, after its own `--color-family-audio`:
```css
--color-family-video: #7dd3fc;
```
- [ ] **Step 4: Add the resolution control to `FileConfigCard.jsx`**
Add the constants near `AUDIO_BITRATE_FORMATS`/`AUDIO_BITRATES`:
```js
const VIDEO_RESOLUTION_FORMATS = ['mp4', 'webm', 'mov', 'avi', 'mkv'];
const VIDEO_RESOLUTIONS = [480, 720, 1080];
```
Add a new conditional block alongside the existing `AUDIO_BITRATE_FORMATS` block:
```jsx
{VIDEO_RESOLUTION_FORMATS.includes(item.targetFormat) && (
<div className="chip-field">
<span>{t('quality.resolution')}</span>
<div className="chip-group" role="group" aria-label={t('quality.resolution')}>
<button
type="button"
className={`chip${item.quality === null ? ' chip-active' : ''}`}
aria-pressed={item.quality === null}
onClick={() => onQualityChange(index, null)}
>
{t('quality.original')}
</button>
{VIDEO_RESOLUTIONS.map((resolution) => (
<button
key={resolution}
type="button"
className={`chip${item.quality === resolution ? ' chip-active' : ''}`}
aria-pressed={item.quality === resolution}
onClick={() => onQualityChange(index, resolution)}
>
{resolution}p
</button>
))}
</div>
</div>
)}
```
- [ ] **Step 5: Add a video pair to the format marquee**
In `frontend/src/components/FormatMarquee.jsx`, add one entry to `PAIRS`:
```js
['mov', 'mp4'],
```
- [ ] **Step 6: Add the `formats.video`, `quality.resolution`, and `quality.original` translation keys**
In `frontend/src/locales/en.json`, add to the `formats` object:
```json
"video": "Video"
```
and to the `quality` object:
```json
"resolution": "Resolution",
"original": "Original"
```
In `frontend/src/locales/fr.json`, add to the `formats` object:
```json
"video": "Vidéo"
```
and to the `quality` object:
```json
"resolution": "Résolution",
"original": "Original"
```
- [ ] **Step 7: Manual verification**
Follow the project's own guidance on checking for an already-running dev server before starting a new one (`CLAUDE.md`'s manual end-to-end testing section). If none is running:
```bash
npm run dev --prefix frontend
```
In a browser: upload a small `.mp4` (any real one, or rename any small file with valid mp4 magic bytes — the browser upload path re-validates via `resolveInputFormat` server-side, so a plain renamed file without real ftyp bytes will be rejected with "File content does not match its extension"), confirm the target chips include `WEBM`, `MOV`, `AVI`, `MKV` (not `MP4`); confirm the resolution chip group (`Original`/`480p`/`720p`/`1080p`) appears for every video target; confirm the "Video" tile appears on the homepage formats grid with its own icon/color. Real end-to-end conversion requires `ffmpeg` actually installed and `FFMPEG_PATH` set wherever the worker runs — on this dev machine `ffmpeg` is not installed, so a full conversion cannot be verified locally; confirm at minimum that the job is accepted as `pending` and correctly fails with a clear ffmpeg-not-found error rather than an "Unsupported conversion" error (which would indicate a wiring bug, vs. a missing-binary environment limitation).
- [ ] **Step 8: Commit**
```bash
git add frontend/src/data/formats.js frontend/src/utils/fileFamily.js frontend/src/components/FormatsGrid.jsx frontend/src/components/FileConfigCard.jsx frontend/src/components/FormatMarquee.jsx frontend/src/index.css frontend/src/locales/en.json frontend/src/locales/fr.json
git commit -m "feat(video): add video format family, resolution control, and marquee pair"
```
---
## Self-Review Notes
- **Spec coverage:** every section of `docs/superpowers/specs/2026-08-01-video-conversion-design.md` maps to a task — codec map + registration (Task 2), resolution/quality reuse (Tasks 2, 4), timeout (Tasks 1, 4), MIME/detection (Task 3), registration wiring (Task 4), frontend (Task 5), testing (all tasks include their own, using the verified mocked-`execFile` and hand-crafted magic-byte approaches established during planning).
- **No real video fixtures needed anywhere** — confirmed during planning that `ffmpeg` is unavailable on this dev machine, and that the codebase's own precedent (`audio.test.js`, the ebook case in `worker.test.js`) already mocks `execFile` rather than shelling out for converter/worker tests; `mime.test.js` only needs magic-byte headers, not full valid media files, since `file-type` only reads the leading bytes.
- **Type/name consistency checked:** `VIDEO_FORMATS`, `registerVideoConverters`, `videoJobTimeoutMs`, `CODEC_ARGS` keys, and the `[480, 720, 1080]` resolution set are spelled identically everywhere they're referenced across tasks.
- **No placeholders:** every step has literal code, not a description of code; the one environment limitation honestly flagged (no local `ffmpeg` for true end-to-end manual verification) carries a concrete fallback check (job accepted as pending, fails with a binary-not-found error rather than an unsupported-conversion error), not a skipped step.
Reference in New Issue View Git Blame Copy Permalink