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

Delta for Android Auto Media

Scope: Phase 1 (foundational plumbing) of android-auto-local-music only. See "Not in this delta" for explicit exclusions.

ADDED Requirements

Requirement: Local Music Root Access and Permission Persistence

The system MUST let the user select a local-music root folder via SAF (ACTION_OPEN_DOCUMENT_TREE), persist the granted URI permission, and MUST NOT crash or leave the local-music root folder in a broken state if that permission is later lost or was never granted.

Scenario: User picks a local music root folder

• GIVEN the user opens the local-music setup flow
• WHEN they complete the SAF folder picker and grant access
• THEN the selected folder's URI permission is persisted
• AND the local-music root becomes browsable in Android Auto without re-prompting the picker

Scenario: Persisted permission survives app restart

• GIVEN a local music root was previously picked and its permission persisted
• WHEN the app is restarted (cold start)
• THEN the local-music root remains browsable in Android Auto without re-prompting the SAF picker

Scenario: Permission revoked or never granted

• GIVEN the SAF permission for the local-music root was revoked outside the app, or no root was ever picked
• WHEN the local-music root folder is browsed in Android Auto
• THEN getChildren returns an empty or explanatory list, not an error
• AND the audio handler does not throw or crash

Requirement: Local Music Browsable Tree

The Android Auto browse tree MUST expose a new non-playable local-music root folder alongside the existing station folders. Browsing that root and any nested subfolder MUST recursively mirror the picked SAF folder's structure: subfolders as non-playable carpeta_local:<id> items and audio files as playable pista:<id> items resolving to PistaLocal instances, using the raw filename as the displayed title.

Scenario: Car browses the local-music root

• GIVEN a local music root folder was picked and its permission is valid
• WHEN getChildren is called with the local-music root folder id
• THEN it returns the root's immediate subfolders as carpeta_local:<id> items and audio files as pista:<id> playable items
• AND each playable item's title is the file's raw filename

Scenario: Car browses a nested subfolder

• GIVEN a carpeta_local:<id> folder returned from a prior browse call
• WHEN getChildren is called with that folder id
• THEN it returns that subfolder's own contents (nested folders and/or tracks), recursively mirroring the on-device structure
• AND browsing an empty subfolder returns an empty list, not an error

Requirement: Local Track Playback Reuses Existing Pipeline

Selecting a pista:<id> item MUST resolve to the corresponding PistaLocal and play it through the existing playMediaItem/PluriWaveAudioHandler pipeline, unchanged, including the shared EQ signal chain.

Scenario: User selects a local track

• GIVEN the user taps a pista:<id> playable item on the car head unit
• WHEN playFromMediaId(id) is called
• THEN the id resolves to a PistaLocal and playback starts through the existing playMediaItem internal path
• AND standard transport (play/pause/stop) and fallback album art work as they do for stations

Scenario: EQ still applies to local track playback (regression guard)

• GIVEN a non-flat EQ preset is currently the active/principal preset
• WHEN a pista:<id> item is played
• THEN the audible output passes through the same shared EQ signal chain used for station playback, with no separate or bypassed path for local tracks

Scenario: Unknown or stale track id

• GIVEN playFromMediaId is called with a pista:<id> that no longer resolves to a known PistaLocal
• WHEN resolution fails
• THEN playback does not start and no unhandled exception propagates from the handler

Requirement: Local Music Folder Item Cap

A local-music folder (root or nested) whose immediate children exceed _maxItemsPorCarpeta (50) MUST be capped to that limit rather than returning unbounded results; pagination is out of scope for this delta.

Scenario: Folder exceeds the item cap

• GIVEN a picked or nested local-music folder contains more than 50 immediate children (subfolders and/or tracks combined)
• WHEN getChildren is called with that folder id
• THEN at most 50 items are returned, consistent with the existing _maxItemsPorCarpeta cap applied to station folders
• AND no error or crash occurs as a result of the truncation

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, and the new local-music root) 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. The local-music root folder is non-playable and may itself be nested (see "Local Music Browsable Tree"). (Previously: root contained exactly four folders — Favoritos, Todas las emisoras, Mis emisoras, Ecualizador — with no local-music root.)

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 five folder MediaItems (Favoritos, Todas las emisoras, Mis emisoras, Ecualizador, and the local-music root), 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

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, and MUST NOT render literal placeholder text such as "null kbps"

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 exactly as before, unaffected by the local-music root's existence or content

Not in this delta

Phase 1 does NOT specify: local-track metadata display beyond the raw filename (no title/artist tagging), album art beyond the existing generic on-brand fallback, sort/filter of local tracks or folders, or shuffle. These are deferred to Phase 2/3 per the proposal and MUST NOT be implemented against this spec.