pluriwave/openspec/changes/android-auto-eq-presets/specs/android-auto-media/spec.md

Delta for android-auto-media

MODIFIED Requirements

Requirement: Browsable Media Tree

getChildren MUST return a browsable tree rooted at AudioService.browsableRootId, organized into non-playable folders (Favoritos, Todas las emisoras, Mis emisoras, Ecualizador) containing playable items. Playable station items SHOULD carry an audio-quality subtitle when known. The Favoritos folder additionally MAY contain non-playable favorite-group sub-folders; Todas las emisoras and Mis emisoras remain flat. The Ecualizador folder is flat, non-playable, and contains only the 6 fixed EQ preset items (see "EQ Preset Browsable Folder"). (Previously: root contained exactly 3 folders — Favoritos, Todas las emisoras, Mis emisoras — with no EQ folder.)

Scenario: Car requests the root

• GIVEN the car head unit connects and requests the root (AudioService.browsableRootId)
• WHEN getChildren is called with the root id
• THEN it returns four folder MediaItems (Favoritos, Todas las emisoras, Mis emisoras, Ecualizador), each with playable: false

Scenario: Car requests a folder with no stations

• GIVEN the user has zero favorite stations
• WHEN getChildren is called with the Favoritos folder id
• THEN it returns an empty list, not an error

Scenario: Browse requested before app state is loaded

• GIVEN the audio handler starts cold and station/favorites Provider state has not finished loading
• WHEN getChildren is called (root or any folder)
• THEN it returns a valid, possibly empty, list without throwing and without blocking or crashing the service

Scenario: Station has known codec and bitrate

• GIVEN a station's Emisora.codec and Emisora.bitrate are both known
• WHEN it is mapped to a playable MediaItem
• THEN displaySubtitle SHALL contain a human-readable quality hint (e.g. "128 kbps · MP3")

Scenario: Station has unknown codec or bitrate

• GIVEN a station's Emisora.codec or Emisora.bitrate is null/unknown
• WHEN it is mapped to a playable MediaItem
• THEN displaySubtitle SHALL omit the quality hint gracefully, never rendering literal placeholder text

Scenario: Ungrouped station appears exactly as before (regression guard)

• GIVEN a station's Emisora.grupoFavoritosId equals GrupoFavoritos.sinAsignarId
• WHEN the Favoritos, Todas las emisoras, or Mis emisoras folders are browsed
• THEN that station appears as a playable emisora:<uuid> item in the same folder(s), position, title, art, and subtitle as before this change
• AND its presence and shape are unaffected by the new Ecualizador folder

ADDED Requirements

Requirement: EQ Preset Browsable Folder

The Android Auto browse tree MUST expose the 6 fixed EQ presets (PresetEcualizador.presets) as playable items inside the Ecualizador root folder, each using a distinct eq_preset:<nombre> media-id scheme, separate from emisora:<uuid> and grupo:<id>.

Scenario: Car requests the Ecualizador folder

• GIVEN the Ecualizador folder id was returned under the root
• WHEN getChildren is called with the Ecualizador folder id
• THEN it returns exactly 6 playable MediaItems, one per PresetEcualizador.presets entry, titled with the preset's name
• AND each item's id is eq_preset:<nombre>, where <nombre> is that preset's unique name

Requirement: EQ Preset Selection Applies Without Disturbing Playback

Selecting an eq_preset:<nombre> item MUST apply that preset immediately through the headless-safe EQ seam (e.g. PluriWaveAudioHandler.aplicarPreset), via a branch in playFromMediaId intercepted BEFORE the emisora:/grupo: routing. It MUST NOT call playMediaItem, MUST NOT mutate the now-playing mediaItem, and MUST NOT start, stop, restart, or otherwise alter current playback or playback position.

Scenario: User selects a preset while a station is playing

• GIVEN a station is currently playing and projected to the car
• WHEN the user taps an eq_preset:<nombre> item, resolved via playFromMediaId
• THEN the matching preset is applied via the headless-safe apply seam
• AND the currently playing station continues uninterrupted, with no change to playback position or now-playing metadata

Scenario: User selects a preset while nothing is playing

• GIVEN no station is currently playing
• WHEN the user taps an eq_preset:<nombre> item
• THEN the matching preset is applied via the headless-safe apply seam
• AND no playback starts as a result of the selection

Scenario: Unknown or stale preset id

• GIVEN playFromMediaId receives an eq_preset:<nombre> id whose <nombre> matches no entry in the current PresetEcualizador.presets
• WHEN resolution fails to find a matching preset
• THEN the selection is a no-op: no preset is applied, no playback state changes, and no unhandled exception propagates from the handler

Requirement: EQ Preset Persistence and Phone/Car Parity

An EQ preset applied from the car MUST persist as the principal preset, with the same observable outcome as the phone's existing ServicioEcualizador.guardarPrincipal/cambiarPresetPrincipal path, and MUST be reflected on the phone. A principal preset changed on the phone MUST be observable from the car. The exact code path used to reach the headless-safe persistence seam from an Android Auto bind is deferred to sdd-design.

Scenario: Preset applied from the car persists for the phone

• GIVEN the user selects eq_preset:<nombre> from the car head unit
• WHEN the selection is processed
• THEN the preset is persisted as the principal preset
• AND opening the phone's EQ UI afterward shows that preset as the active/principal preset

Scenario: Preset applied from the phone is reflected for the car

• GIVEN the user changes the principal preset from the phone UI
• WHEN the car head unit subsequently observes EQ-related state through the browse/selection surface
• THEN the car-observable state reflects the phone's most recently applied principal preset

Requirement: Active Preset Indication (Optional)

The system MAY indicate the active/principal preset within the Ecualizador folder's rows. Because the legacy MediaBrowserService browsable-item model has no native "selected item" affordance, any indication, if implemented, MUST be conveyed via a row title text convention (e.g. a marker prefix/suffix) rather than assuming a checkmark or selection icon exists. If a reliable title-text convention is too costly to maintain, this requirement MAY instead be satisfied by explicitly not implementing active-preset indication.

Scenario: Active preset is indicated via title convention (if implemented)

• GIVEN the currently applied principal preset is known when Ecualizador's children are built
• WHEN the design's chosen title-text convention is applied
• THEN exactly one of the 6 preset rows' title carries the active-preset marker, uniquely identifying that preset among the 6

Scenario: Active preset indication is out of scope (if not implemented)

• GIVEN the design opts not to implement an active-preset marker
• WHEN the Ecualizador folder's children are built
• THEN all 6 preset rows are returned with their plain preset names, with no partial or inconsistent marking applied