Add typed FFmpeg command builder

[natashaannn]

Add typed FFmpeg command builder

Objective

Centralize FFmpeg argument construction behind a typed builder that consumes the hardware profile.

---

Why this matters

Current FFmpeg invocation logic is scattered.

Before replacing existing spawn sites, command generation should exist as a reusable abstraction.

---

Parallelization metadata

Track

scripts

Depends on

• Add hardware detection abstraction #22 merged

Safe to run in parallel with

• DAG runner issue
• app auth issue

Merge risk

• low/medium

---

Files in scope

Primary:

• scripts/lib/ffmpeg.ts

Avoid touching:

• existing script call sites

---

Required implementation

1. Create typed task model

Support at minimum:

• encode
• decode
• optimize

2. Implement builder

Expose:

buildFfmpegCommand(profile, task)

3. Hardware-aware codec selection

Initial support:

• VideoToolbox path
• NVENC path
• CPU fallback path

---

Constraints

• no replacement of existing FFmpeg calls yet
• builder only

---

Handoff contract

Later issues can replace inline FFmpeg spawns incrementally.

---

Acceptance criteria

Functional

• command differs appropriately by hardware profile

Unit tests

• CPU fallback test
• VideoToolbox test
• NVENC test

---

Verification commands

Run builder manually in a node shell.

Expected result:

• generated command includes expected codec flags

---

Explicitly out of scope

• replacing existing FFmpeg usage
• Dockerfile changes

---

Suggested branch

refactor/s3-ffmpeg-builder

Suggested commit slug

phase-1-step-2-ffmpeg-builder