fix(playback): avoid unnecessary HDR video transcodes

[RXWatcher]

Summary

• Do not treat Android MediaCodec's reported bitrateRange as a hard hardware decode ceiling.
• Keep source-preserving direct playback eligible when codec, profile, bit depth, resolution, and frame rate are supported.
• When an HDR route still cannot be validated, try an SDR or lower-resolution alternate for automatic quality instead of returning a blocked HDR transcode terminal.
• Preserve the explicit original preference and existing 4K-transcode policy.

Why

Android TV devices such as NVIDIA Shield can direct-play HDR/HEVC files whose bitrate exceeds the conservative bitrate reported by MediaCodec. The old gate routed those files into video adaptation, where HDR encoding is intentionally unavailable, producing hdr_transcode_unsupported before the device ever received a media source.

Bitrate should influence buffering and quality selection, not declare a hardware decoder incapable of accepting a stream. Resolution, frame rate, codec, profile, and bit depth remain validated.

Verification

• go test ./internal/playback ./internal/api/handlers -run 'TestDetailedVideoEligibilityDoesNotRejectHardwareForReportedBitrate|TestShouldTryAlternateAfterTerminalV3AvoidsHDRTranscode|TestReplanAllowsAlternate'
• git diff --check

The focused tests pass on current upstream/main (95779c47).

Summary by CodeRabbit

• Bug Fixes

  • Improved playback fallback handling for HDR content when HDR transcoding is unavailable.
  • Preserved alternate-version selection where quality preferences allow it.
  • Improved hardware HDR playback eligibility by avoiding unnecessary rejection based on reported bitrate limits.

• Tests

  • Added coverage for HDR fallback decisions and hardware decoding eligibility.

[coderabbitai]

Warning

Review limit reached

@RXWatcher, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 52 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 61507db4-f435-40d4-9e0a-da834a1c2114

📥 Commits

Reviewing files that changed from the base of the PR and between b96b154 and 586a270.

📒 Files selected for processing (1)

• internal/api/handlers/playback_v3.go

📝 Walkthrough

Walkthrough

HDR playback now retries alternate files for eligible terminal outcomes and permits detailed hardware decoding despite reported bitrate limits. Tests cover alternate-selection rules and HDR decode eligibility.

Changes

HDR playback handling

Layer / File(s)	Summary
HDR alternate-file fallback internal/api/handlers/playback_v3.go, internal/api/handlers/playback_v3_test.go	Start and replan flows support hdr_transcode_unsupported alongside no_alternate_version, while quality preferences continue to control alternate selection.
Detailed decode bitrate eligibility internal/playback/capabilities_v3.go, internal/playback/capabilities_v3_test.go	Detailed decode eligibility no longer rejects sources solely because their bitrate exceeds the reported capability maximum, with HDR hardware coverage added.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested labels: v1

Suggested reviewers: quick104

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: avoiding unnecessary HDR transcodes in playback.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[RXWatcher]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

🧹 Nitpick comments (1)

internal/api/handlers/playback_v3.go (1)

1216-1218: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Consider reusing shouldTryAlternateAfterTerminalV3 to avoid duplicating terminal reason strings.

You can use the new helper function here to centralize the list of recoverable terminal reasons. Although this evaluates shouldTryAlternateFileV3(start.QualityPreference) twice (once inside the new helper and once inside replanAllowsAlternateFileV3), the overhead is negligible and it keeps the code DRY.

♻️ Proposed refactor

 	if result.Terminal != nil &&
-		(result.Terminal.Reason == "no_alternate_version" || result.Terminal.Reason == "hdr_transcode_unsupported") &&
+		shouldTryAlternateAfterTerminalV3(result.Terminal.Reason, start.QualityPreference) &&
 		replanAllowsAlternateFileV3(operation, start.QualityPreference) {

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@internal/api/handlers/playback_v3.go` around lines 1216 - 1218, Update the
terminal-condition check in the playback handler to reuse
shouldTryAlternateAfterTerminalV3 instead of duplicating the
"no_alternate_version" and "hdr_transcode_unsupported" reason comparisons. Keep
replanAllowsAlternateFileV3 as the alternate-file eligibility check and preserve
the existing behavior.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@internal/api/handlers/playback_v3.go`:
- Around line 1216-1218: Update the terminal-condition check in the playback
handler to reuse shouldTryAlternateAfterTerminalV3 instead of duplicating the
"no_alternate_version" and "hdr_transcode_unsupported" reason comparisons. Keep
replanAllowsAlternateFileV3 as the alternate-file eligibility check and preserve
the existing behavior.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ad16c8f9-dbb7-466e-b46f-0ff5b5a6eb2a

📥 Commits

Reviewing files that changed from the base of the PR and between 95779c4 and b96b154.

📒 Files selected for processing (4)

• internal/api/handlers/playback_v3.go
• internal/api/handlers/playback_v3_test.go
• internal/playback/capabilities_v3.go
• internal/playback/capabilities_v3_test.go

[RXWatcher]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.