Spec: Phase 8 — TV: frame-rate matching, a display and audio that change underneath playback, D-pad controls

Open
  • Is something wrong?
#264 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
8/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
android, kotlin
Domain
audio-video-rtc, mobile-dev

Research direction

This is a phase epic, not a starting task: begin with the child issues it names, ADR-0014 (#265) and the harness TV device (#266), which gate the rest. Read PRD.md §3.8 and DeviceConstraints and DeviceStatement in the harness to see how the display is read today. Done means the phase exit criteria in the issue hold on a TV emulator and device, with ./gradlew assemble check green.

Written by the indexing model from the issue text.

Description

Problem Statement

Phases 1–7 built a library for a phone. PRD.md §3.8 names what a living room needs and nothing of it exists: superplayer-tv is an empty placeholder.

  • Judder. 24fps content on a 60Hz panel judders, a top living-room complaint, and nothing asks the display for a matching rate.
  • The display is read once. DeviceConstraints reads the display's size and HDR types at construction and never its refresh rate. ADR-0009 leaves that as a constraint "until Phase 8". An HDMI hotplug to a lesser display leaves a player holding a rung the display cannot show.
  • Audio capabilities change underneath playback. An AV receiver powered on mid-playback changes the passthrough formats, and nothing listens.
  • A TV on Ethernet behaves like a phone on WiFi. NetworkTransport.Ethernet is observed, but no profile is a TV's, and TV_LEANBACK exists only in PRD.md §3.7.
  • No surface for a remote. There are no D-pad controls, and the demo does not launch on a TV.
  • #213's display-capability rule was handed here by ADR-0012.

Solution

Ship superplayer-tv (PRD.md §3.8) on the seams earlier phases built. Declare what is correctness (frame-rate matching, surviving a display or audio change) and what is policy (tunneling, the TV profile's numbers), and make the display a live condition rather than a constraint read once. The surface is Compose for TV only: Leanback is in maintenance and is not built against.

Nothing here is testable unless the harness can state a TV first. DeviceStatement declares one display mode with a fixed refresh rate and no change mid-session, and nothing about audio capabilities. That is a prefactor, and it comes early.

Scope

# Issue What it lands
#265 ADR-0014 The module's dependencies and seam, correctness versus policy, the display as a live condition, Compose for TV, #213's HDMI rule
#266 Harness TV device Display modes with refresh rates, HDMI hotplug, audio-capability change, TV UI mode
#267 TV_LEANBACK + Ethernet A fifth profile with a reason per row; an Ethernet network profile
#268 Tracer bullet Frame-rate matching on a player built with the module
#269 Display as a live condition HDMI hotplug to a lesser display re-selects
#270 Audio-capability change An AV receiver on or off mid-playback re-selects audio
#271 Tunneled playback Where the device and the content support it
#272 D-pad controls Compose-for-TV focus and seek-scrubbing
#273 TV demo Launches on a TV; the recipe a consumer copies; a TV emulator in devicelab
#274 Phase exit On a TV emulator and device: frame-rate matching, HDMI, audio changes

Order: the ADR and the harness first; they gate everything. Frame-rate matching is the tracer bullet, and the rest hang off it. Each child names its blockers.

Exit criteria

Per PRD.md Part 4:

  • Runs on a TV device and emulator.
  • Frame-rate matching verified.
  • HDMI and audio-capability changes handled.
  • No Media3 @UnstableApi type in the module's public API, and a player built without it registers and allocates nothing.
  • ./gradlew assemble check stays green.

Non-goals

  • Leanback. Compose for TV is the only TV surface.
  • Moving a benchmark number. The TV profile's QoE is reported here; tuning it is Phase 10's.
  • TV-specific download UX. Phase 7 shipped downloads; a TV screen for them is not this phase's.
Dominant language
Kotlin
Stars
1
Forks
0
Avg merge
3h 32m
Merged PRs (30d)
64

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from ramesh130/superplayer

All issues in ramesh130/superplayer

Similar issues

More Kotlin issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.