# Proposal: Android Auto (Projected) Media Browsing

## Intent

PluriWave can play radio on the phone but is invisible and uncontrollable from a car head unit. A driver cannot browse stations or start playback safely while driving. Android Auto (projected) needs a media app to expose a browsable tree plus play-by-id, and to declare itself so Auto discovers it. The audio engine (`audio_service ^0.18.15`, `PluriWaveAudioHandler`) already provides `MediaBrowserService` + `MediaSession`; the browse/discovery layer is missing. Closing this gap turns PluriWave into a car-usable media app without touching the audio pipeline.

## Scope

### In Scope
- Add `android/app/src/main/res/xml/automotive_app_desc.xml` (`<uses name="media"/>`).
- Add `<meta-data com.google.android.gms.car.application>` to `AndroidManifest.xml`.
- Override `getChildren`, `getMediaItem`, `playFromMediaId` in `PluriWaveAudioHandler`.
- Build a browse tree: Favoritos / Todas las emisoras / Mis emisoras (folders + playable stations).
- Ensure every playable `MediaItem` has `title` + `artUri`; provide a default artwork for stations without a logo.
- `playFromMediaId` resolves id → `Emisora` → reuses internal `playMediaItem` (no duplicated playback logic).
- Strict-TDD Dart tests for tree building and id resolution.

### Out of Scope
- Play Console distribution / car-app review steps (separate user documentation).
- DHU / Desktop Head Unit manual testing (user-side).
- iOS CarPlay.
- Voice search (`playFromSearch`) and grid/list content-style polish (deferred; non-blocking).

## Capabilities

### New Capabilities
- `android-auto-media`: PluriWave MUST expose a browsable station tree and play-by-media-id to Android Auto projected, with every playable item carrying title + artwork, reusing the existing audio handler.

### Modified Capabilities
- None.

## Approach

Reuse, don't rebuild. Handler already runs in the main isolate, so `getChildren` reads station/favorites state directly from Provider states (`lib/estado/`). Map categories → folder `MediaItem`s (`playable: false`), stations → playable `MediaItem`s with stable ids. `playFromMediaId` reuses `_emisoraDesdeMediaItem` (servicio_audio.dart:705) and `playMediaItem` (servicio_audio.dart:433). Root is `AudioService.browsableRootId`. Start with a minimal tree (Favoritos), then widen. Dart-only + XML/manifest — no build required for logic tests.

## Affected Areas

| Area | Impact | Description |
|------|--------|-------------|
| `android/app/src/main/res/xml/automotive_app_desc.xml` | New | Auto media declaration |
| `android/app/src/main/AndroidManifest.xml` | Modified | Add car application meta-data |
| `lib/servicios/servicio_audio.dart` | Modified | Override getChildren/getMediaItem/playFromMediaId + default artwork |
| `lib/estado/` | Read | Source of stations/favorites for the tree |
| `test/` (Dart) | New | Tree + id-resolution tests |

## Risks

| Risk | Likelihood | Mitigation |
|------|------------|------------|
| Breaking the audio pipeline | Low | New browse methods only; reuse `playMediaItem`, never modify it |
| Stations without artwork fail Google quality gate | Med | Bundled default `artUri` for logo-less stations |
| Dead station streams give bad car impression | Med | Surface curated/favorite stations; existing `controlador_reconexion.dart` handles failures |
| `artUri` not loadable by system (asset scheme) | Med | Use http(s) logos or `content://`-served default asset |

## Rollback Plan

Additive change. Revert the PR: delete `automotive_app_desc.xml`, remove the manifest meta-data line, and drop the three overridden methods + tests. Phone playback path is untouched, so reverting leaves the app exactly as today with zero residual state.

## Dependencies

- `audio_service ^0.18.15` (already present).
- Default station artwork asset (to add).

## Success Criteria

- [ ] Android Auto discovers PluriWave as a media app.
- [ ] Browse tree shows Favoritos / Todas las emisoras / Mis emisoras.
- [ ] Every playable item shows title + artwork.
- [ ] Selecting a station plays it via reused `playMediaItem`.
- [ ] Play/pause/stop state stays in sync car ↔ phone.
- [ ] Dart tests for tree building + id resolution pass under `flutter test`.
- [ ] Audio pipeline behavior unchanged on phone.