pluriwave/openspec/changes/archive/2026-07-19-android-auto-favorite-groups/specs/android-auto-media/spec.md

Delta for android-auto-media

ADDED Requirements

Requirement: Favorite Group Sub-Folders

The Android Auto browse tree MUST expose favorite groups (GrupoFavoritos, as already modeled by Emisora.grupoFavoritosId and surfaced by EstadoRadio.gruposFavoritos) as browsable, non-playable sub-folders reachable from the existing Favoritos folder, without altering the 3 root folders (Favoritos, Todas las emisoras, Mis emisoras).

Scenario: Car requests the Favoritos folder and groups exist

• GIVEN the user has one or more favorite groups with at least one member station each
• WHEN getChildren is called with the Favoritos folder id
• THEN it returns one non-playable folder MediaItem per surfaced group, in addition to (or instead of, per the design's structural decision) any ungrouped favorite stations
• AND each group folder's id follows a browsable grupo:<id> scheme distinct from the emisora:<uuid> playable-item scheme

Scenario: Car requests a group folder's stations

• GIVEN a favorite group folder with id grupo:<id> was returned under Favoritos
• WHEN getChildren is called with that grupo:<id> folder id
• THEN it returns the playable MediaItems for exactly the stations whose Emisora.grupoFavoritosId matches <id>
• AND those items are sorted and capped using the same ordering and item-count rules already applied to the other folders (ordenarEmisoras, 50-item cap)
• AND selecting one of those items plays the corresponding station via the existing emisora:<uuid> playback path, unchanged

Scenario: Car requests an unknown or stale group id

• GIVEN a grupo:<id> id that does not match any group known to the current snapshot
• WHEN getChildren is called with that id
• THEN it returns an empty list, not an error

Requirement: Empty Favorite Group Handling

The system MUST produce a browsable tree that never presents a user-selectable folder promising content it cannot deliver: for any favorite group with zero member stations, the tree MUST either omit that group's folder from Favoritos's children, or include it and return an empty (not erroring) child list when browsed. The specific choice between omitting empty-group folders and showing-but-empty, and any related folder-count/flat-vs-nested structural decision for Favoritos, is deferred to sdd-design; whichever mechanism design selects MUST satisfy both scenarios below.

Scenario: Empty group folder is browsed (if shown)

• GIVEN a favorite group has zero member stations and the design's chosen mechanism surfaces it as a folder under Favoritos
• WHEN getChildren is called with that group's grupo:<id>
• THEN it returns an empty list, not an error

Scenario: No user-facing dead end

• GIVEN the full set of favorite groups, including any empty ones
• WHEN the Favoritos folder is browsed and then each of its returned children is browsed
• THEN no returned folder child ever throws, hangs, or surfaces a driver-facing error state
• AND the car head unit's total folder/item count presented under Favoritos remains within the driver-distraction-safe bounds design establishes

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) containing playable station items. Playable station items SHOULD carry an audio-quality subtitle when known. The Favoritos folder additionally MAY contain non-playable favorite-group sub-folders (see "Favorite Group Sub-Folders"); Todas las emisoras and Mis emisoras remain flat, unchanged by this capability. (Previously: Favoritos was a flat folder of playable station items only, with no sub-folder nesting.)

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 three folder MediaItems (Favoritos, Todas las emisoras, Mis emisoras), 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 (non-null)
• WHEN it is mapped to a playable MediaItem
• THEN displaySubtitle SHALL contain a human-readable quality hint combining bitrate and codec (e.g. "128 kbps · MP3")

Scenario: Station has unknown codec or bitrate

• GIVEN a station's Emisora.codec or Emisora.bitrate (or both) is null/unknown
• WHEN it is mapped to a playable MediaItem
• THEN displaySubtitle SHALL omit the quality hint gracefully (no subtitle, or a subtitle with no quality fragment)
• AND the subtitle MUST NOT render literal placeholder text such as "null kbps" or "null · null"

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

• GIVEN a station's Emisora.grupoFavoritosId equals GrupoFavoritos.sinAsignarId ('sin_asignar', the default when no group is assigned)
• WHEN the Favoritos, Todas las emisoras, or Mis emisoras folders are browsed
• THEN that station appears as a playable emisora:<uuid> item in exactly the same folder(s), position (subject to existing sort rules), title, art, and subtitle as it did before favorite-group folders were introduced
• AND its presence and shape are unaffected by the existence, emptiness, or content of any favorite group