docs(505): retire the stale "do NOT set QSV on jazz" rule in the ersatztv skill #657

Merged

timothy merged 1 commits from docs/505-skill-qsv-stale into main 2026-07-26 22:34:21 +02:00

Conversation 1 Commits 1 Files Changed 1

+6 -3

timothy commented 2026-07-26 22:03:23 +02:00

Owner

Copy Link

Copy Source

refs #505

Found while running the #505 close-out: the ersatztv skill still carries pre-#498 guidance that is now actively wrong, and following it would degrade prod.

What was stale

Do NOT set QSV (1) here, despite the Intel hardware. … 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.

…plus HardwareAccelerationKind: … **use 3 (Vaapi)** on jazz (not Qsv — see above).

#498 resolved precisely that blocker by adding QsvPreferNativeDecoder (default ON, Linux-only), which splits decode from encode exactly like Jellyfin. Prod has run that way since.

Verified against live state, not a snapshot

The skill's claim and #523's older note disagreed, so I queried jazz directly rather than trusting either:

sqlite> select Id, Name, HardwareAcceleration, QsvPreferNativeDecoder from FFmpegProfile;
1|1080p VAAPI h264 aac|1|1

sqlite> select FFmpegProfileId, count(*) from Channel group by 1;
1|43

HardwareAcceleration = 1 (Qsv), QsvPreferNativeDecoder = 1, used by all 43 channels. The profile is still named "1080p VAAPI h264 aac" — cosmetic, and itself a trap worth noting, since the name is what a reader sees first.

Risk if left alone: a session following the old note would "correct" a working QSV profile back to VAAPI on prod.

Also recorded (so they're not re-derived)

Two QSV traps already paid for in code:

• QsvExtraHardwareFrames = 0 → the software→QSV hwupload bridge has no headroom and the transcode writes zero segments on any unthrottled read (#523/#529). Floored at 64 in code.
• HDR never tonemaps via vpp_qsv=tonemap — on this Gen9.5 iGPU it is a silent no-op (byte-identical output, exit 0, no warning). #505 moved ErsatzTV to VA-API→OpenCL. The same trap applies to Jellyfin's EnableVppTonemapping on this host, so the note points that out too (the vault page was corrected separately, homelab-docs@4f0e9c5).

Verification

Frontmatter re-parsed after the edit (name + single-line description) — the ersatztv#617 trap where a stray ": " silently kills the skill. Docs-only change; no code touched.

Note this PR touches .claude/, so it is excluded from the docs-only review-verdict auto-pass and needs a real review-verdict/h10.

🤖 Generated with Claude Code

refs #505 Found while running the #505 close-out: the `ersatztv` skill still carries pre-#498 guidance that is now **actively wrong**, and following it would degrade prod. ## What was stale > **Do NOT set QSV (1) here, despite the Intel hardware.** … 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. …plus `HardwareAccelerationKind: … **use 3 (Vaapi)** on jazz (not Qsv — see above)`. **#498 resolved precisely that blocker** by adding `QsvPreferNativeDecoder` (default ON, Linux-only), which splits decode from encode exactly like Jellyfin. Prod has run that way since. ## Verified against live state, not a snapshot The skill's claim and #523's older note disagreed, so I queried jazz directly rather than trusting either: ``` sqlite> select Id, Name, HardwareAcceleration, QsvPreferNativeDecoder from FFmpegProfile; 1|1080p VAAPI h264 aac|1|1 sqlite> select FFmpegProfileId, count(*) from Channel group by 1; 1|43 ``` `HardwareAcceleration = 1` (**Qsv**), `QsvPreferNativeDecoder = 1`, used by all 43 channels. The profile is still *named* "1080p VAAPI h264 aac" — cosmetic, and itself a trap worth noting, since the name is what a reader sees first. **Risk if left alone:** a session following the old note would "correct" a working QSV profile back to VAAPI on prod. ## Also recorded (so they're not re-derived) Two QSV traps already paid for in code: - `QsvExtraHardwareFrames = 0` → the software→QSV `hwupload` bridge has no headroom and the transcode writes **zero segments** on any unthrottled read (#523/#529). Floored at 64 in code. - **HDR never tonemaps via `vpp_qsv=tonemap`** — on this Gen9.5 iGPU it is a *silent no-op* (byte-identical output, exit 0, no warning). #505 moved ErsatzTV to VA-API→OpenCL. The same trap applies to **Jellyfin's `EnableVppTonemapping`** on this host, so the note points that out too (the vault page was corrected separately, `homelab-docs@4f0e9c5`). ## Verification Frontmatter re-parsed after the edit (`name` + single-line `description`) — the ersatztv#617 trap where a stray `": "` silently kills the skill. Docs-only change; no code touched. Note this PR touches `.claude/`, so it is **excluded** from the docs-only review-verdict auto-pass and needs a real `review-verdict/h10`. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

timothy added 1 commit 2026-07-26 22:03:23 +02:00

docs(505): retire the stale "do NOT set QSV on jazz" rule in the ersatztv skill ... 06e8181dee

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

timothy commented 2026-07-26 22:34:12 +02:00

Author

Owner

Copy Link

Copy Source

Review-verdict: MERGEABLE @ 06e8181

Docs-only skill correction (6 insertions, 3 deletions, no code). Independent review skipped per process.independent-review-rubric - no locks/auth/API-write-path/migrations and zero C# lines changed. Self-verified: the claim was checked against the LIVE prod DB on jazz rather than any doc snapshot (HardwareAcceleration=1, QsvPreferNativeDecoder=1, 43 channels), and the SKILL.md frontmatter was re-parsed after the edit for the ersatztv#617 colon trap.

Review-verdict: MERGEABLE @ 06e8181 Docs-only skill correction (6 insertions, 3 deletions, no code). Independent review skipped per process.independent-review-rubric - no locks/auth/API-write-path/migrations and zero C# lines changed. Self-verified: the claim was checked against the LIVE prod DB on jazz rather than any doc snapshot (HardwareAcceleration=1, QsvPreferNativeDecoder=1, 43 channels), and the SKILL.md frontmatter was re-parsed after the edit for the ersatztv#617 colon trap.

timothy merged commit 3684fd7ef6 into main 2026-07-26 22:34:21 +02:00

timothy deleted branch docs/505-skill-qsv-stale 2026-07-26 22:34:22 +02:00

timothy referenced this issue from a commit 2026-07-26 22:34:23 +02:00

Merge pull request 'docs(505): retire the stale "do NOT set QSV on jazz" rule in the ersatztv skill' (#657) from docs/505-skill-qsv-stale into main

timothy referenced this pull request 2026-07-26 22:42:49 +02:00

WatermarkSelector: the deco path has a different missing-logo policy than the three precedence levels #510

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

ad-hoc

One-off / ad-hoc work not tracked by a dedicated issue

api

REST API / HTTP endpoints

bug

Something isn't working

ci-cd

Build, test, deploy pipeline

content

Channel content / schedules / playlists

dependencies

Dependency updates (Renovate)

enhancement

New feature or improvement

frontend

ChicoryTV React SPA frontend

in-progress

Claimed by an active session — do not pick up

jellyfin

Jellyfin tuner / IPTV integration

parked

Excluded from automatic queue pickup; work only when explicitly selected

priority: high

priority: low

priority: medium

review

Adversarial review finding

security

Security / vulnerability fix

No labels

Milestone

No items

No Milestone

Projects

Clear projects

No projects

Assignees

Clear assignees

renovate timothy (Timothy)

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: timothy/ersatztv#657