pluriwave/openspec/changes/android-auto-local-music-phase2/design.md

# Design: Android Auto Local Music — Phase 2 (Metadata, Sort, Name Buckets)

## Technical Approach

Compose real metadata onto the Phase 1 lazy-paging browse tree WITHOUT regressing the
`itemsLocales` **slice-cheap-then-map** invariant. Raw SAF enumeration (`hijos` →
`NodoLocal` list) stays cheap and eager-free. Metadata (expensive, async) is resolved
via ONE new batched native call on the existing `pluriwave/file_actions` channel
(`readAudioMetadataBatch`, `MediaMetadataRetriever`), and ONLY for the exact docIds of
the page being returned — mirroring how art/MediaItem construction is already page-scoped.
All real logic (LRU cache eviction, quality comparator, bucket partitioning, media-id
codec) lives in pure Dart; native surface stays a thin per-file extract-and-return loop.

## Architecture Decisions

### ADR-1: Embedded-art delivery via existing FileProvider cache

**Choice**: Native writes `getEmbeddedPicture()` bytes to `cacheDir/pluriwave_art/<hash(docId)>` and returns a `content://${applicationId}.fileprovider/cache/pluriwave_art/<hash>` URI (the manifest ALREADY declares `<cache-path path="."/>` under authority `${applicationId}.fileprovider` — zero new native/manifest surface). `MediaItem.artUri` gets that URI.
**Alternatives**: base64 data-URI (Auto art loader won't fetch it); a second art-only channel call at render time (extra round trip); a custom ContentProvider (new surface).
**Rationale**: reuses the proven FileProvider path (`openDirectory`/`viewDirectory` precedent). Cache key = `hash(documentId)` (docId contains `:`/`/`, illegal in filenames); stable so re-parsing the same track reuses the file (`if (file.exists()) skip extract`). **Eviction**: after each write, native trims the art subdir by lastModified while `count > 256` OR `bytes > 32MB` (LRU-by-mtime) — the ONE unavoidable native-side eviction, kept to a trivial reviewable loop because the files are native-owned and round-tripping names to Dart to pick deletions adds channel chatter for no testability gain (the `delete()` is native regardless). **Cache-miss at render**: art URI is resolved at MediaItem-build time inside the same `getChildren` call, so the file exists when the item ships; no embedded picture → native returns `artUri: null` → Dart falls back to Phase 1's `artUriLocal(documentId)` placeholder rotation. Never crashes.

### ADR-2: Parsed-metadata session cache — pure-Dart flat LRU

**Choice**: `CacheMetadatosSesion` — an in-memory `LinkedHashMap<String docId, MetadatosPista>` bounded to **256 entries**, LRU by access order, pure Dart, unit-tested. In-memory only (dies with the process → always fresh, no persistence staleness).
**Alternatives**: folder-scoped cache cleared on navigate-away (thrashes when paging a huge folder); unbounded (OOM risk on large libraries); persisted store (staleness, the proposal rejected eager-scan for this reason).
**Rationale**: 256 ≈ 5 pages of 50 → paging page 2 does NOT evict page 1; leaving and re-entering a recently-seen folder stays warm. A flat LRU keeps the natural working set without folder-boundary thrash. Batch resolution consults the cache first; only misses hit native.

### ADR-3: Quality-sort — threshold-capped, batched, blocking parse-then-sort-then-page

**Choice**: Quality-sort resolves bitrate for EVERY audio file in the folder via a SINGLE batched `readAudioMetadataBatch` call, sorts desc (mirroring `ordenarEmisoras(..., calidad)`), caches results, then applies the existing paging. Offered ONLY when the folder's audio-file count ≤ `_maxPistasParaOrdenCalidad` (**150**); above that the quality entry is omitted (name-sort + buckets only).
**Alternatives**: background-prefetch + progressive-reveal (legacy `MediaBrowserService` can't stream partial nor re-sort in place — proposal already notes this); no cap (hundreds of `MMR.setDataSource` calls ≈ many seconds → head-unit "content not loading").
**Rationale**: `onLoadChildren` has a de-facto "be snappy" expectation; 150 files × ~30-50ms batched ≈ worst-case ~5-7s paid ONCE (cached for re-paging), only when the user opts into the quality entry. The cap is the sane safety valve; buckets cover big folders instead.

### ADR-4: Browse-tree shape — mode entries prepended on page 0

**Choice**: On page 0 of a local folder, prepend non-playable "view" folders BEFORE the default name-sorted track list (same precedent as `carpetasFavoritos` prepending group folders before stations): (1) "Ordenar por calidad" IF audio count ≤ 150; (2) alphabetical bucket folders IF track count > 50 (buckets add no value for small folders). Name-sort stays the DEFAULT view (no explicit "name" entry — Auto's back button returns from any sub-view). New media-id families:

| Family | Format | View |
|--------|--------|------|
| `carpeta_local_ord:` | `carpeta_local_ord:<modo>:<pagina>:<docId>` | sorted (`modo` = `calidad`) |
| `carpeta_local_bucket:` | `carpeta_local_bucket:<idxBucket>:<pagina>:<docId>` | name-bucket slice |

**Alternatives**: sibling entries mixed into the track page (clutter, paging collisions); a wrapping "Ver/Ordenar" intermediate folder (extra tap for the common case).
**Rationale**: **Collision-free** — both diverge from `carpeta_local:` at index 13 (`:` vs `_`) and from each other/`carpeta_local_pag:` at the char after `carpeta_local_` (`o`/`b`/`p`), so no `startsWith` false-match (same proof the existing `_pag` prefix documents); routing order is irrelevant. Fixed-arity fields (`modo`/`idxBucket`, then `pagina`) precede the free-form docId, decoded by the proven **split-on-first-colon** chain from `paginaCarpetaLocalDesde` — a docId containing `:`/`/` survives verbatim. Buckets are **name-only** (partition the already-cheap name-sorted list → NO metadata) so they compose with slice-cheap-then-map untouched; only `modo=calidad` pays the metadata cost.

### ADR-5: MMR API-level degradation

**Choice**: `METADATA_KEY_SAMPLERATE` (key 38) is API 31+; guard with `Build.VERSION.SDK_INT >= 31`, else `sampleRate = null`. `METADATA_KEY_BITRATE`, `_TITLE`, `_ARTIST`, `getEmbeddedPicture()` are all ≥ API 10 → always read. Missing field → null, degraded gracefully (subtitle omits the kHz fragment), reusing Phase 1's "unknown → omit" subtitle discipline.
**Rationale**: only sample-rate needs gating; everything else the proposal wants is universally available.

## Data Flow

    getChildren(carpeta_local[_ord|_bucket]:...:docId)
       │ decode view+page+docId (pure Dart codec)
       ▼
    fuente.hijos(docId)  ── cheap NodoLocal[] (unchanged, no metadata)
       │
       ├─ name (default)  : sort by nombre           ─┐
       ├─ bucket:<i>      : name-sort → filter bucket ─┤ CHEAP, no metadata
       └─ ord:calidad     : batch-parse ALL (≤150,     │
                            cache) → sort bitrate desc  ┘ metadata for sort key only
       ▼
    paginaDe(...)  ── slice page (cheap)
       ▼
    metadatosDe(slice.trackDocIds)  ── CacheMetadatosSesion hit? else
       │                               readAudioMetadataBatch (native, page-scoped)
       ▼
    build MediaItem per node: titulo/artista/artUri from meta, filename/placeholder fallback
       ▼
    append "Más…" if hayPaginaSiguiente

## File Changes

| File | Action | Description |
|------|--------|-------------|
| `android/.../MainActivity.kt` | Modify | `readAudioMetadataBatch` case + `MediaMetadataRetriever` extract loop + art-file write/trim (static-review-only, thin) |
| `lib/modelos/pista_local.dart` | Modify | Add `MetadatosPista` DTO (titulo/artista/bitrate/sampleRate/artUri); extend `PistaLocal` with same fields |
| `lib/servicios/musica_local_auto.dart` | Modify | `metadatosDe(docIds)` on `FuenteMusicaLocalAuto` + channel call; `CacheMetadatosSesion` |
| `lib/servicios/navegacion_auto.dart` | Modify | mode/bucket prefixes + codec, `bucketsDe`, quality comparator, metadata-backed `itemsLocales`, subtitle |
| `lib/estado/orden_emisoras.dart` | (reuse) | `OrdenEmisoras.calidad` comparator shape mirrored for local tracks |
| `lib/l10n/*.arb` (13) | Modify | Sort-mode + bucket + "unknown metadata" labels |

## Interfaces / Contracts

Native (`pluriwave/file_actions`), never throws across the boundary:

    readAudioMetadataBatch(treeUri: String, documentIds: List<String>) -> List<Map>
    // one map per requested docId, in order; fields null when absent/unparseable
    { documentId: String, titulo: String?, artista: String?,
      bitrate: Int?/*bps*/, sampleRate: Int?/*API31+ else null*/, artUri: String?/*content://*/ }

Per-file try/catch → all-null entry (docId echoed); whole call try/catch → `[]`;
`MediaMetadataRetriever.release()` in `finally`.

Dart:

    class MetadatosPista { final String? titulo, artista, artUri; final int? bitrate, sampleRate; }
    abstract FuenteMusicaLocalAuto {
      Future<Map<String, MetadatosPista>> metadatosDe(List<String> documentIds); // batched, never throws
    }
    class CacheMetadatosSesion { MetadatosPista? obtener(String); void guardar(String, MetadatosPista); } // LRU 256

## Testing Strategy

| Layer | What | Approach |
|-------|------|----------|
| Unit | `CacheMetadatosSesion` LRU eviction/order | pure Dart |
| Unit | media-id encode/decode (`_ord`/`_bucket`, docId with `:`/`/`), collision guards | pure Dart |
| Unit | `bucketsDe` partitioning + labels; quality comparator | pure Dart |
| Unit | `itemsLocales` metadata-backed build: resolves ONLY sliced page's docIds (spy call-count invariant) + fallbacks | pure Dart, injected metadata map |
| Unit | subtitle format (bitrate/kHz known/unknown, no literal "null") | pure Dart |
| Static review | `readAudioMetadataBatch`, art write/trim, API-31 sample-rate guard | Kotlin review (no build/DHU) |

## Migration / Rollout

No migration. Purely additive over Phase 1. Rollback = remove `readAudioMetadataBatch`,
drop `_ord`/`_bucket` prefixes + `metadatosDe`, restore filename title + placeholder art.
Phase 1 browse/play/paging untouched.

## Open Questions

- [ ] `_maxPistasParaOrdenCalidad = 150` and art budget (256 files / 32 MB) are first-pass; validate on-device in a later hardware pass (no DHU here).