ADR-002 decided never to transcode because the server is a headless,
GPU-less Xeon, and its measurements still hold. The problem is scope:
"this server cannot transcode" became "Vellum does not transcode", and
only the first is forced by the hardware.
Intel Quick Sync has been in most desktop CPUs since 2015, NVENC is in
every recent Nvidia card, and VAAPI covers AMD and Intel on Linux. Capping
the product at the hardware in one closet is the wrong constraint, and the
gap is visible: a client that cannot decode HEVC gets nothing, and in
Chrome that is not even a clean refusal - the video never decodes and
audio plays over a blank frame.
So the engine is added and its registration is gated:
- registered only when usable transcode hardware AND ffmpeg are both present
- off by default; direct play stays the default and the preference
- consulted only when no other engine can direct-play the file, which is
exactly the case that returns "no engine can play this" today
- hardware-accelerated only. No CPU fallback: that is the stall ADR-002
measured, and it fails slowly, which is worse than refusing.
This deployment is unchanged. On a GPU-less Xeon the engine is never
registered and the path is never reached, so ADR-002 holds as written.
ADR-002's status now points here rather than being deleted, per the rule
that a changed decision gets a new record instead of an edited one.
Docs
- docs/ARCHITECTURE.md: how the pieces fit and why. The request path, the six
enforced layers, the data model, the scanner, the job queue, direct-play
playback, and the three protocol surfaces over one application.
- docs/decisions/: seven ADRs with the alternatives that were rejected —
SQLite-with-a-seam, direct-play-only, mark-missing-never-delete, the modular
monolith, the one item-access chokepoint, the table-backed queue, and
fixed-width timestamps.
- README: the layout section was stale (it predated catalog, home, scanner,
providers, engine, probe, playback, apitoken, arch and the dto packages) and
now lists what exists, plus links to the new docs.
Two real bugs, both found by verifying the docs instead of trusting them
1. The CLI could not run on a fresh install. `Config.Validate` created the data
and config directories, but the CLI never called it, so `vellum user add` —
the recovery path when you are locked out — failed with "unable to open
database file" until the server had booted at least once. Split the directory
creation into `Config.EnsureDirs`, call it from the CLI, and keep the media
root check out of it: an admin command must not fail because a library is
unmounted. The CLI tests now point DBPath inside DataDir, exactly as
LoadConfig derives it, so they exercise the fresh-install path; removing
EnsureDirs fails three of them.
2. A fresh clone could not build at all. `//go:embed all:dist` fails to compile
when web/dist is absent, and web/.gitignore expected a `dist/.gitkeep` that
was never created. Added it, so a clone builds and the server logs
"web UI not embedded; run the frontend build to include it" — the intended
behaviour for someone who only wants the API.
Also: the httpapi tests depended on a built frontend and FAILED rather than
skipping, so the suite was red on any fresh clone. findAsset and readAsset now
skip with a message naming the missing step. They still RUN when a bundle is
present (verified: zero skips here), so they have not been quietly disabled.
Verified from a simulated clone of tracked files only: go build exit 0, 25
packages pass, the server boots and applies all 12 migrations, and the CLI
creates a user and takes a backup. gofmt clean, vet exit 0, svelte-check 0/0.
