timothy/ersatztv
1
0
Fork 0
Code Issues 57 Pull Requests 6 Actions Packages Projects Releases 9 Wiki Activity

docs(505): retire the stale "do NOT set QSV on jazz" rule in the ersatztv skill
PR Gates / CI image pin matches docker/ci (pull_request) Successful in 14s
Details
PR Gates / Docs update reminder (pull_request) Successful in 16s
Details
PR Gates / decisions lifecycle (pull_request) Successful in 19s
Details
Review verdict / Set review-verdict status (pull_request) Successful in 3s
Details
PR Gates / Script tests (pytest) (pull_request) Successful in 37s
Details
Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 9s
Details
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 8s
Details
Build ErsatzTV Image / Functional E2E (curl + UI contracts) (pull_request) Successful in 8s
Details
Build ErsatzTV Image / API docs in sync (OpenAPI + endpoint index) (pull_request) Successful in 8s
Details
Build ErsatzTV Image / Formatting (changed .cs conform to .editorconfig) (pull_request) Successful in 8s
Details
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Has been skipped
Details
review-verdict/h10 Review-verdict: MERGEABLE @ 06e8181
Details

Browse Source 
The skill told sessions to keep jazz on HardwareAcceleration=3 (Vaapi) and "do
NOT set QSV", citing the 2026-07-20 cold-start regression and the fact that one
column governed both decode and encode. #498 fixed exactly that by adding
QsvPreferNativeDecoder (VA-API decode + QSV encode, the Jellyfin split), and
prod has run that way since.

Verified live on jazz 2026-07-26: the single FFmpegProfile used by all 43
channels is HardwareAcceleration=1 (Qsv), QsvPreferNativeDecoder=1,
QsvExtraHardwareFrames=64. A session following the old note would have
"corrected" a working prod profile back to VAAPI.

Also records the two QSV traps already paid for in code so they are not
re-derived: the extra_hw_frames=0 zero-segment failure (#523/#529) and the
vpp_qsv=tonemap silent no-op (#505), including that the same tonemap trap
applies to Jellyfin's EnableVppTonemapping on this host.

refs #505
This commit is contained in:
timothy
2026-07-26 22:02:54 +02:00
parent 6dbc072837
commit 06e8181dee
1 changed files with 6 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/skills/ersatztv/SKILL.md
+6 -3
View File
@@ -331,12 +331,15 @@ docker start ersatztv
## FFmpeg & Hardware
- **VAAPI on Intel (iHD)** hardware acceleration — ErsatzTV runs on **jazz** (i7-10700K, Intel iGPU) since #633. The single `FFmpegProfile` row (`Id = 1`, referenced by all 43 channels) has `HardwareAcceleration = 3` (Vaapi), `VaapiDevice = /dev/dri/renderD128`, `VaapiDriver = 0` (auto → iHD), `VaapiDisplay = drm`.
- **Do NOT set QSV (1) here, despite the Intel hardware.** It was tried on 2026-07-20 and **regressed**: QSV's *decoder* is far stricter than VAAPI about malformed NAL units and failed **3 of 6 channel cold-starts** (`Error splitting the input into NAL units` → `dec:h264_qsv Error while opening decoder: Invalid data found`). ErsatzTV has a **single** `HardwareAcceleration` column governing *both* decode and encode, so it cannot express Jellyfin's working combination of VAAPI-decode + QSV-encode. Tracked upstream: timothy/ersatztv#498. Jellyfin **does** use QSV successfully, because it splits the two.
- **QSV encode + VA-API decode on Intel (iHD)** — ErsatzTV runs on **jazz** (i7-10700K, Intel iGPU) since #633. The single `FFmpegProfile` row (`Id = 1`, referenced by all 43 channels) has `HardwareAcceleration = 1` (**Qsv**), `QsvPreferNativeDecoder = 1` (ON), `QsvExtraHardwareFrames = 64`, `VaapiDevice = /dev/dri/renderD128`. Verified live 2026-07-26. The profile is still *named* "1080p VAAPI h264 aac" — cosmetic, ignore the name.
- **The old "do NOT set QSV" rule is RETIRED — #498 fixed the blocker it was based on.** The 2026-07-20 regression was real (QSV's *decoder* is far stricter than VAAPI about malformed NAL units and failed 3 of 6 cold-starts: `Error splitting the input into NAL units`), and the stated cause was that one `HardwareAcceleration` column governed both decode and encode. **#498 added `QsvPreferNativeDecoder` (default ON, Linux-only)**, which splits them exactly like Jellyfin: decode with the tolerant VA-API decoder, encode with QSV. That is what prod runs now. Do not "fix" prod back to `3` (Vaapi) on the strength of the old note.
- **Two QSV traps already paid for, both fixed in code — don't re-derive them:**
- `QsvExtraHardwareFrames` must never be `0`: the software→QSV `hwupload` bridge has no headroom and the transcode writes **zero segments** on any unthrottled read (#523/#529). Code now floors it at 64 (`ffmpeg.qsv-extra-hw-frames-floor`).
- **HDR tonemapping never uses `vpp_qsv=tonemap`** — on this Gen9.5 iGPU that filter is a *silent no-op* (byte-identical output, exit 0, no warning), so it looked like GPU tonemapping while doing nothing. ErsatzTV now tonemaps via VA-API→OpenCL (#505, `ffmpeg.qsv-hdr-tonemap-opencl`). Same trap applies to Jellyfin's `EnableVppTonemapping` on this host — keep it off.
- Fallback if VAAPI also misbehaves (see #631, VAAPI `hwupload -22` on 10-bit): `HardwareAcceleration = 0` (software). jazz has 16 threads at load ~2, so it is affordable and maximally tolerant of imperfect sources.
- Resolution: 1920x1080, H264, AAC stereo
- Device: `/dev/dri` passed through (`renderD128`)
- HardwareAccelerationKind: 0=None, 1=Qsv, 2=Nvenc, 3=Vaapi, 4=VideoToolbox, 5=Amf — **use 3 (Vaapi)** on jazz (not Qsv — see above)
- HardwareAccelerationKind: 0=None, 1=Qsv, 2=Nvenc, 3=Vaapi, 4=VideoToolbox, 5=Amf — **jazz uses 1 (Qsv)** with `QsvPreferNativeDecoder` ON (see above)
- jazz's iGPU is shared with Jellyfin only (Frigate stayed on bumblebee); render GID is 992 on both hosts, so `group_add: '992'` carried over unchanged
## Jellyfin Integration