pluriwave/openspec/changes/android-auto-local-music-phase3/proposal.md

# Proposal: Android Auto Local Music — Phase 3 (Folder-Scoped Queue + Shuffle)

## Status of the local-music feature (context)

This is the FINAL planned phase of local music in Android Auto. Shipped and
archived already:

- **Phase 1**: SAF folder pick, persisted URI permission, lazy per-level
  DocumentFile traversal, `PistaLocal`/`NodoLocal`, filename titles, placeholder
  art, browse + play of a single track.
- **Paging fast-follow**: on-demand `carpeta_local_pag:` "Más…" pagination
  replacing silent 50-item truncation.
- **Phase 2**: real embedded metadata (native `readAudioMetadataBatch` /
  `MediaMetadataRetriever`), `CacheMetadatosSesion` LRU, quality-sort
  (`carpeta_local_ord:`), alphabetical name-buckets (`carpeta_local_bucket:`),
  embedded album art.

The original Phase-1 proposal sketched Phase 3 as: **"subfolder scoping
refinements + shuffle + transport-control polish."** This proposal traces that
label against the live code and defines precisely what actually remains.

## Honest scope reconciliation (the key finding — read this first)

The original label reads like "two small UX toggles." It is not. Reading the
live playback pipeline shows the real gap:

- **Browsing nested subfolders is already done** (Phase 1's SAF tree traversal).
  So "subfolder scoping refinements" is NOT about navigation — that works.
- **There is no multi-track playback of any kind.** `reproducirPistaLocal`
  (`navegacion_auto.dart`) builds exactly ONE `MediaItem` and hands it to
  `playMediaItem`. `PluriWaveAudioHandler._cambiarFuente`
  (`servicio_audio.dart`) does `_recrearPlayer()` + a single
  `_player.setUrl(mediaItem.id)`. There is NO `just_audio`
  `ConcatenatingAudioSource`, NO `audio_service` `queue`, NO `skipToNext`, NO
  auto-advance on track completion. The handler was built for RADIO — one live
  stream at a time. **Tapping a local track plays that ONE track and then
  stops.** There is no "play this folder", no "next track", nothing.

Therefore both original Phase-3 items collapse onto a single missing
foundation:

- **"subfolder scoping"** honestly resolves to: *play the audio tracks of a
  chosen (sub)folder as a scoped queue* — a sequence bounded to that folder.
- **"shuffle"** is the randomized ordering of that same folder-scoped queue.
- **"transport-control polish"** is wiring next/previous so Android Auto's
  transport controls advance within that local queue.

**Honest verdict: Phase 3 is ONE foundational feature — a local multi-track
queue inside the audio handler — with two browsable entry points (play folder /
shuffle folder) and transport wiring on top. Shuffle without a queue is
meaningless, so the queue is the real, unavoidable work. It is larger than the
label implies and it touches the app's most sensitive, most heavily-tested
component (the audio handler with its reconnect state machine and EQ chain).**

## Intent

**Problem**: Local music in Android Auto is browse-and-tap-one-track only. A
driver cannot start a folder playing and let it run; every track requires a new
tap, there is no continuous listening, and "shuffle my music" — the single most
common car-music expectation — is impossible because there is no queue to
shuffle.

**Why now**: This is the last planned phase; the browse/metadata/sort surface is
complete and the only remaining promised capability (shuffle, committed in the
very first proposal) requires the queue foundation this phase introduces.

**Success looks like**: From any local (sub)folder in Android Auto, the driver
can tap "Reproducir carpeta" to play that folder's tracks in order, or
"Reproducir aleatorio" to play them shuffled, with playback auto-advancing
track-to-track and the car's next/previous controls moving within the queue —
all reusing the existing EQ signal chain and buffering, with no regression to
radio playback.

## Scope — In (Phase 3)

- **Local multi-track queue foundation** in `PluriWaveAudioHandler`: an ordered
  list of pending local tracks + current index, auto-advance to the next track
  on completion, and `skipToNext`/`skipToPrevious` wired to move within it. A
  mode boundary keeps this active ONLY for local-queue playback, never for
  radio (live streams never "complete").
- **Two browsable, folder-scoped play actions**, prepended on page 0 of a local
  folder (same prepend precedent as Phase 2's sort/bucket entries):
  - **"Reproducir carpeta"** — the folder's direct audio children, name-ordered.
  - **"Reproducir aleatorio"** — the same set, shuffled.
- **New playable media-id families** for those actions (design settles exact
  strings; must be collision-free against the existing `pista:` / `emisora:` /
  `grupo:` / `eq_preset:` / `carpeta_local[_pag|_ord|_bucket]:` prefixes,
  reusing the proven strip-by-length + split-on-first-colon codec so raw SAF
  documentIds with `:` / `/` survive verbatim).
- **Queue building** scoped to the tapped folder's DIRECT audio children
  (non-directory `NodoLocal`s), sorted by name for sequential and randomized
  (seeded, deterministically testable) for shuffle.
- **Content-URI resolution per advance** via the existing
  `resolvePlayableUri` channel method — lazy, one track at a time as the queue
  advances (no eager whole-folder resolution, no new native method).
- Pure-Dart unit tests for shuffle ordering (seeded), queue construction, action
  media-id encode/decode + collision guards, and page-0 action prepend; handler
  tests for completion-advance and skip within the local-queue mode boundary.

## Scope — Out (explicitly deferred / rejected)

- **Recursive whole-subtree queue.** The queue is scoped to the tapped folder's
  direct audio children only — consistent with the lazy per-level enumeration
  model and every prior phase's rejection of eager subtree scans. Enqueuing a
  whole nested subtree would require recursive native traversal; out of scope.
- **OS-level shuffle toggle** (`AudioService.setShuffleMode` /
  `AudioServiceShuffleMode`). The package supports it, but it presupposes a
  persistent OS play-queue with a shuffle affordance in the transport UI — a
  model this app's browse-tree, tap-to-select integration does not use (the
  notification exposes only play/pause/stop). Shuffle is therefore exposed as a
  browsable ACTION (the EQ-preset-folder precedent), not an OS toggle. Design
  may revisit, but the browsable action is the recommended fit.
- **`ConcatenatingAudioSource` rebuild of the player pipeline** — see Approach;
  recommended AGAINST in favor of the lighter app-managed queue.
- **Cross-folder / persisted / resumable queues**, queue reordering UI, repeat
  modes. Not promised, not in scope.
- **New phone-UI strings / l10n work.** Car-tree labels are hardcoded Spanish
  by established precedent ("Favoritos", "Música Local", "Más…", "Ordenar por
  calidad"). "Reproducir carpeta" / "Reproducir aleatorio" are hardcoded Spanish
  car labels — **NO new `.arb` keys, NO 13-locale change.** If design surfaces a
  genuinely new PHONE-UI string, it must be scoped into all 13 locales
  explicitly; none is anticipated.

## Approach (with rationale)

**Recommended: an app-managed local queue that reuses the existing single-source
pipeline — do NOT rebuild the player around `ConcatenatingAudioSource`.**

The handler recreates the player + EQ on every source change
(`_recrearPlayer()` inside `_cambiarFuente`) and wraps source switches in a
revision-guarded queue built for live-stream reconnect. That machinery is the
app's most delicate, most-tested code. Bolting a `just_audio`
`ConcatenatingAudioSource` + `audio_service` `queue` + `setShuffleMode` onto it
fights the recreate-per-source model and the reconnect state machine head-on —
high blast radius on the one component we least want to destabilize.

Instead, keep the single-source player and add a thin queue LAYER in the
handler: hold the ordered local-track list + index, listen for
`ProcessingState.completed` (which only fires for finite local files, never for
radio) to advance by re-driving the existing `_cambiarFuente`, and override
`skipToNext`/`skipToPrevious` to move the index and re-drive the same path. A
mode flag scopes all of this to local-queue playback so radio behavior is
byte-identical. This mirrors Phase-2/EQ philosophy: expose the capability
through the existing seams and a browsable action, rather than adopting a
platform model the app's integration doesn't actually use.

All ordering, queue-building, media-id codec, and action-item logic stays pure
Dart in `navegacion_auto.dart` (fully unit-testable, seeded shuffle). The
handler change is the only stateful/coupled part and gets its own focused tests
behind the mode boundary. No new native method (lazy `resolvePlayableUri` per
advance), no new dependency, no manifest/pubspec change anticipated.

The design phase must settle: (1) app-managed queue vs `ConcatenatingAudioSource`
(recommendation: app-managed); (2) exact completion/advance and skip semantics
against the reconnect machine; (3) the two new media-id prefixes and their
collision proof; (4) shuffle seed strategy for deterministic tests.

## Affected areas (anticipated — design confirms)

- `lib/servicios/servicio_audio.dart` (Modify): local-queue state, completion
  auto-advance, `skipToNext`/`skipToPrevious`, mode boundary, `playFromMediaId`
  branch for the new action ids. **The sensitive change — main risk surface.**
- `lib/servicios/navegacion_auto.dart` (Modify): action media-id prefixes +
  predicates + codec, queue-building (name-order / seeded-shuffle) from
  `NodoLocal`s, page-0 action-item prepend, play orchestration.
- `lib/servicios/musica_local_auto.dart` (Possibly): a folder-tracks helper if
  the orchestration needs one; likely reuses existing `hijos` + `resolvePlayableUri`.
- `android/.../MainActivity.kt`: **no change anticipated** (lazy per-advance
  resolution reuses `resolvePlayableUri`).
- `AndroidManifest.xml` / `pubspec.yaml` / `lib/l10n/*.arb`: **no change
  anticipated.**

## Risks

- **Audio-handler blast radius (HIGH)**: the queue layer lives in the most
  sensitive, most-tested component. Mitigation: strict mode boundary so radio is
  provably untouched; app-managed layer over pipeline rebuild; focused
  regression tests. This is the dominant risk.
- **Completion-advance vs reconnect machine (MED-HIGH)**: `ProcessingState.completed`
  handling must not collide with the live-stream stall/retry logic. Design must
  prove the two paths are disjoint (mode flag).
- **Not runtime-verifiable here (HIGH, session precedent)**: no DHU/on-device
  Android Auto in this environment; queue/skip/completion behavior is
  static-review + unit-test only, same as all prior native/handler work this
  session. Real transport-control behavior in the car cannot be exercised here.
- **Scope/size (MED)**: honestly larger than the "subfolder + shuffle" label.
  See estimate below.
- **Shuffle determinism (LOW)**: seed the shuffle so tests are stable; a
  fixed/injectable seed avoids flaky ordering assertions.

## Size estimate & delivery (flag early, per session pattern)

Comparable to or larger than Phase 2 (~2000 lines) because it modifies the audio
handler core and adds handler-level tests on top of the pure-Dart surface.
**Realistically a single `size:exception` PR, consistent with every prior local-music
change this session (Phase 1 ~1300, paging ~800, Phase 2 ~2000, all
single size:exception PRs).**

Natural work-unit split if chaining is preferred: (1) **queue foundation +
"Reproducir carpeta" sequential playback + transport wiring** (the bulk / the
real foundation), then (2) **"Reproducir aleatorio" shuffle** (a thin
ordering variant once the queue exists). Shuffle is small once the foundation
lands. Surface this to the delivery-strategy guard before apply.

## Rollback plan

Additive. Rollback = remove the new action media-id prefixes/predicates/codec,
the queue-building and page-0 action prepend in `navegacion_auto.dart`, and the
queue layer (state, completion-advance, skip overrides, mode flag) in
`servicio_audio.dart`. Single-track `pista:` playback and all radio playback
revert untouched.

## Success criteria

- [ ] "Reproducir carpeta" and "Reproducir aleatorio" appear on page 0 of a
      local folder that has audio tracks; absent when it has none.
- [ ] Tapping "Reproducir carpeta" plays the folder's direct audio children in
      name order, auto-advancing track to track.
- [ ] Tapping "Reproducir aleatorio" plays the same set shuffled; ordering is
      deterministic under a fixed seed in tests.
- [ ] Car next/previous transport controls move within the local queue.
- [ ] Radio playback, reconnect, and EQ behavior are provably unchanged (mode
      boundary; regression tests green).
- [ ] Pure-Dart logic fully unit-tested; handler queue behavior tested behind
      the mode boundary; native (if any) static-reviewed. No new `.arb` keys.

## Next recommended

`sdd-spec` and `sdd-design` can run in parallel from this proposal. Design must
settle the app-managed-queue vs `ConcatenatingAudioSource` decision, the
completion/skip semantics against the reconnect machine, and the two new
media-id prefixes with a collision proof before `sdd-tasks`.