fix: cumplir las guias de calidad de Android Auto y localizar el arbol del coche

Google Play devolvio "Approved with Issues" en el codigo 157: "clicking on
stop button makes the entire app useless", citado contra las Android for Cars
App Quality Guidelines. La causa no era el boton de parar.

Maquina de estados del transporte

_cambiarFuente publicaba mediaItem y loading ANTES de su primer await y solo
comprobaba su revision despues de que _recrearPlayer retornase. Los cambios de
fuente se encolan incrementando la revision al encolar, no al ejecutar, asi
que tocar una emisora, tocar otra antes de que cargue y pulsar Stop dejaba que
las entradas obsoletas reescribieran loading sobre el idle que stop() acababa
de publicar. Estado final: loading para siempre sobre una sesion que
audio_service ya habia desactivado. Ahora la guarda de revision es la primera
sentencia del metodo.

pause() no invalidaba una carga en vuelo, asi que la emisora arrancaba igual
despues de pulsar pausa; se revalida la intencion antes de llamar a play().
Se anade un suelo de estado que cierra cualquier loading o buffering sin carga
viva, exento cuando el reproductor ya entrego audio y solo esta rebufferando,
para no convertir un tunel en un error. El presupuesto hasta el primer mensaje
baja a menos de diez segundos y los reintentos ya no borran el mensaje visible.

Tier gratuito en el coche

El arbol devolvia una unica fila no reproducible para cualquier carpeta cuando
no habia premium, y un revisor con instalacion limpia siempre es tier
gratuito. Ademas skipToNext, skipToPrevious, playFromSearch y playFromMediaId
retornaban en silencio. La raiz gratuita pasa a ofrecer una sola carpeta con
emisoras reales y reproducibles, compiladas en el binario para que existan en
frio, y la puerta de entitlement acota contenido en vez de bloquear acciones.
Se elimina la fila "Funcion Premium". Una consulta de voz vacia arranca la
ultima emisora, que fallaba tambien a los clientes de pago.

Localizacion

El locale del handler solo lo fijaba un widget que el motor headless nunca
construye, asi que todo error del coche salia en castellano. Se resuelve desde
el locale de plataforma. Se traducen las once etiquetas del arbol que estaban
a fuego y se retira la convencion que lo justificaba. Un test nuevo falla si
vuelve a aparecer texto visible fuera del sistema de traduccion.

Suite completa: 1455 pasan, 2 omitidos. Los mecanismos se verificaron por
mutacion: borrar cada uno pone la suite en rojo. flutter analyze mantiene los
5 avisos preexistentes.
This commit is contained in:
2026-09-04 13:26:00 +02:00
parent 575ba793ae
commit 8e155cc0ac
43 changed files with 4446 additions and 310 deletions
+174
View File
@@ -0,0 +1,174 @@
import 'dart:convert';
import 'package:shared_preferences/shared_preferences.dart';
import '../modelos/emisora.dart';
/// The last-played station's persistence key.
///
/// MUST stay byte-identical to `EstadoRadio._keyUltimaEmisora`
/// (`lib/estado/estado_radio.dart`), which is the only writer. It is
/// duplicated here rather than exported from there on purpose: this file has
/// to be readable from the headless Android Auto engine, where `EstadoRadio`
/// is never constructed, and importing a `ChangeNotifier` that pulls in the
/// whole app-state graph just to read one string constant would drag the
/// entire phone-side stack into a car bind. `emisoras_destacadas_test.dart`
/// pins the literal so a rename on either side fails loudly.
const claveUltimaEmisora = 'ultima_emisora_v1';
/// The stations a FREE-tier driver can browse and play in the car
/// (fix/auto-quality-guidelines, item 6).
///
/// Compiled into the binary, on purpose. Everything else the car could show
/// is empty on the bind a Play reviewer actually performs: a fresh install
/// is free tier (`esPremiumPersistido` is `getBool(...) ?? false`, no trial
/// key), `FuenteEmisorasAutoLocal.todas()` is literally
/// `_snapshotTodas ?? const []` until `EstadoRadio` pushes a network
/// snapshot that a headless bind never fetches, favourites and custom
/// stations are empty, and `ultima_emisora_v1` is absent. A curated const
/// list is the ONLY thing that can put real, playable rows in front of that
/// reviewer.
///
/// Deliberately small. This is not a catalogue — the catalogue is the
/// premium feature. Six rows is enough to prove the app works and short
/// enough to read at a glance from a driving position.
///
/// `favicon` is null for every entry on purpose: `artUriPara` then resolves
/// the on-brand bundled `station_art_*` drawable, so a browse row needs no
/// network at all to render its artwork.
///
/// `uuid`s are app-owned (`pw-destacada-*`), not Radio Browser uuids: these
/// rows must resolve identically whether or not the catalogue is reachable,
/// and a Radio Browser uuid we cannot re-fetch would be a promise this file
/// cannot keep.
const List<Emisora> emisorasDestacadas = [
Emisora(
uuid: 'pw-destacada-fip',
nombre: 'FIP',
url: 'https://icecast.radiofrance.fr/fip-midfi.mp3',
pais: 'France',
codigoPais: 'FR',
idioma: 'french',
),
Emisora(
uuid: 'pw-destacada-france-inter',
nombre: 'France Inter',
url: 'https://icecast.radiofrance.fr/franceinter-midfi.mp3',
pais: 'France',
codigoPais: 'FR',
idioma: 'french',
),
Emisora(
uuid: 'pw-destacada-deutschlandfunk',
nombre: 'Deutschlandfunk',
url: 'https://st01.sslstream.dlf.de/dlf/01/128/mp3/stream.mp3',
pais: 'Germany',
codigoPais: 'DE',
idioma: 'german',
),
Emisora(
uuid: 'pw-destacada-kexp',
nombre: 'KEXP 90.3 FM',
url: 'https://kexp-mp3-128.streamguys1.com/kexp128.mp3',
pais: 'United States',
codigoPais: 'US',
idioma: 'english',
),
Emisora(
uuid: 'pw-destacada-radio-paradise',
nombre: 'Radio Paradise',
url: 'https://stream.radioparadise.com/mp3-128',
pais: 'United States',
codigoPais: 'US',
idioma: 'english',
),
Emisora(
uuid: 'pw-destacada-soma-groove-salad',
nombre: 'SomaFM Groove Salad',
url: 'https://ice1.somafm.com/groovesalad-128-mp3',
pais: 'United States',
codigoPais: 'US',
idioma: 'english',
),
];
/// The free tier's complete, ordered station set: the last station the user
/// actually played (when one is persisted) first, then [emisorasDestacadas],
/// deduplicated by `uuid`.
///
/// Last-played goes first because it is the single row a returning driver is
/// most likely to want, and because it is the only entry that can make the
/// free folder feel like *their* app rather than a demo. It is NOT appended
/// a second time when it already belongs to the curated set.
///
/// Follows `esPremiumPersistido({SharedPreferences? prefs})`'s
/// inject-or-`getInstance()` convention (`estado_entitlement.dart`), so a
/// test can pin prefs without a platform channel.
///
/// Never throws: a corrupt/foreign `ultima_emisora_v1` payload, or a
/// `SharedPreferences` failure, degrades to the curated set alone. This runs
/// inside `getChildren`, and a browse call that throws is a dead folder.
Future<List<Emisora>> resolverEmisorasDestacadas({
SharedPreferences? prefs,
}) async {
final ultima = await _ultimaEmisora(prefs: prefs);
if (ultima == null) return emisorasDestacadas;
return [
ultima,
...emisorasDestacadas.where((e) => e.uuid != ultima.uuid),
];
}
/// Whether [uuid] belongs to [destacadas] — the predicate every play-path
/// gate reads to tell "free content" from "the premium catalogue".
///
/// Pure, and takes the free universe rather than resolving it, so a caller
/// that already holds the list (every one of them does — it also needs it to
/// build the response) asks the question without a second prefs round trip.
///
/// A `null` or empty [uuid] is never free: `emisora:` with no tail is a
/// malformed id, and matching it against an entry with an empty uuid would be
/// a resolution hole rather than a feature.
bool esEmisoraGratuita(String? uuid, List<Emisora> destacadas) =>
uuid != null && uuid.isNotEmpty && destacadas.any((e) => e.uuid == uuid);
/// [esEmisoraGratuita] against the CURRENT free set, resolved here. For
/// callers that do not already hold the list.
Future<bool> esEmisoraGratuitaPorUuid(
String uuid, {
SharedPreferences? prefs,
}) async =>
esEmisoraGratuita(uuid, await resolverEmisorasDestacadas(prefs: prefs));
/// Reads the persisted last-played station, or `null` when there is none.
///
/// Public because the Android Auto "recent" browse root
/// (`AudioService.recentRootId`) needs exactly this one station and nothing
/// else: `onGetRoot` (`AudioService.java:817-821`) answers `recent` whenever
/// the head unit sends `EXTRA_RECENT`, which Android Auto does on every
/// reconnect, and the platform expects a SINGLE resume item there — not a
/// station list, and not an empty folder.
///
/// Tier-independent on purpose: this station is by definition one the user
/// has already played on this device, so offering to resume it is never
/// leaking premium content they have not already had.
Future<Emisora?> ultimaEmisoraPersistida({SharedPreferences? prefs}) =>
_ultimaEmisora(prefs: prefs);
/// Reads the persisted last-played station, or `null` when there is none,
/// the payload is unreadable, or prefs themselves fail.
Future<Emisora?> _ultimaEmisora({SharedPreferences? prefs}) async {
try {
final resueltas = prefs ?? await SharedPreferences.getInstance();
final raw = resueltas.getString(claveUltimaEmisora);
if (raw == null) return null;
final emisora = Emisora.fromMap(jsonDecode(raw) as Map<String, dynamic>);
// A record with no uuid or no url cannot be turned into a playable
// `emisora:<uuid>` row, so it is worse than absent: it would occupy the
// first slot with a row that does nothing when tapped.
if (emisora.uuid.isEmpty || emisora.url.isEmpty) return null;
return emisora;
} catch (_) {
return null;
}
}
+320 -99
View File
@@ -10,6 +10,7 @@ import '../modelos/emisora.dart';
import '../modelos/grupo_favoritos.dart';
import '../modelos/pista_local.dart';
import '../modelos/preset_ecualizador.dart';
import 'emisoras_destacadas.dart';
import 'musica_local_auto.dart';
import 'persistencia_tolerante.dart';
import 'servicio_favoritos.dart';
@@ -200,10 +201,97 @@ abstract class FuenteEmisorasAuto {
}) {}
}
/// Every user-readable label of the Android Auto browse tree, already
/// resolved to one locale by the caller.
///
/// THE RULE (fix/auto-quality-guidelines, l10n item): anything a user can
/// read gets translated. This bundle replaces the previous
/// "car-tree labels are hardcoded Spanish, deliberately NOT an arb key"
/// convention, which was defensible only while those labels sat deep inside
/// a premium tree and stopped being defensible the moment Google Play
/// reviewed the car surface on an English head unit.
///
/// It exists as a plain value object rather than an `AppLocalizations`
/// dependency so [ConstructorArbolAuto] stays a PURE builder — the same
/// reason `itemsEcualizadorAuto` lives in `servicio_audio.dart`. The handler,
/// which can resolve localizations headlessly through
/// `resolverLocalizacionesRespaldo`, builds one via
/// `etiquetasArbolAutoDesde` and hands it in.
///
/// NOT in here on purpose: the alphabetical bucket labels (`'A-F'`, `'G-M'`,
/// …). Those are ranges of Latin letters, not prose — translating them would
/// make them lie about which filenames they contain.
class EtiquetasArbolAuto {
const EtiquetasArbolAuto({
required this.escuchar,
required this.favoritos,
required this.todasLasEmisoras,
required this.misEmisoras,
required this.musicaLocal,
required this.musicaLocalNoDisponible,
required this.cargarMas,
required this.ordenarPorCalidad,
required this.reproducirCarpeta,
required this.reproducirAleatorio,
required this.pistaSinNombre,
});
/// Fallback bundle for callers that have no localizations to hand: pure
/// builder tests, and any future non-car consumer.
///
/// It is NOT what the car shows. `ServicioAudio` always injects a bundle
/// resolved from `AppLocalizations`, in every browse and playback path
/// that can produce a label — `etiquetas_arbol_auto_test.dart` is the
/// guard that no NEW hardcoded label can be introduced alongside these.
static const respaldo = EtiquetasArbolAuto(
escuchar: 'Escuchar',
favoritos: 'Favoritos',
todasLasEmisoras: 'Todas las emisoras',
misEmisoras: 'Mis emisoras',
musicaLocal: 'Música Local',
musicaLocalNoDisponible: 'Abre PluriWave en el móvil para leer tu música',
cargarMas: 'Más…',
ordenarPorCalidad: 'Ordenar por calidad',
reproducirCarpeta: 'Reproducir carpeta',
reproducirAleatorio: 'Reproducir aleatorio',
pistaSinNombre: 'Pista sin nombre',
);
/// The free tier's single root folder ([ConstructorArbolAuto.idDestacadas]).
final String escuchar;
/// Premium root folders.
final String favoritos;
final String todasLasEmisoras;
final String misEmisoras;
final String musicaLocal;
/// The non-playable row shown when the local-music folder cannot be read
/// from the car ([ConstructorArbolAuto.idLocalNoLista]).
final String musicaLocalNoDisponible;
/// Trailing "load more" row of every paged local-music view.
final String cargarMas;
/// Local-folder navigation and action rows.
final String ordenarPorCalidad;
final String reproducirCarpeta;
final String reproducirAleatorio;
/// Fallback title for a local file whose name is blank after stripping.
final String pistaSinNombre;
}
/// Pure builder for the Android Auto browse tree: folders, leaf items, id
/// resolution. No platform dependency — fully testable without a running
/// car or a real `AudioHandler`.
class ConstructorArbolAuto {
const ConstructorArbolAuto({this.etiquetas = EtiquetasArbolAuto.respaldo});
/// The already-localized labels this builder stamps onto every
/// user-readable `MediaItem` it produces.
final EtiquetasArbolAuto etiquetas;
/// Root folder ids (Design "media-id scheme"). The tree root itself is
/// identified by [AudioService.browsableRootId], not by a constant here —
/// the handler compares against it directly before calling [raiz].
@@ -211,6 +299,17 @@ class ConstructorArbolAuto {
static const idTodas = 'todas';
static const idMisEmisoras = 'mis_emisoras';
/// Root folder id for the FREE tier's only browsable folder
/// (fix/auto-quality-guidelines, item 8).
///
/// Deliberately NOT added to [_idsCarpetas] — like [idMusicaLocal] and
/// [idEcualizador] it has its own dedicated children ([hijosDestacadas]),
/// fed by `emisoras_destacadas.dart`'s compiled-in set rather than by the
/// generic station-list [hijos] path over a `FuenteEmisorasAuto` that is
/// empty on the bind a Play reviewer actually performs.
static const idDestacadas = 'destacadas';
/// Root folder id for the local-music browsable root (Design "media-id
/// scheme"). Deliberately NOT added to [_idsCarpetas] — it has its own
/// dedicated branch (`hijosMusicaLocal`), not the generic station-list
@@ -322,8 +421,10 @@ class ConstructorArbolAuto {
'android.media.browse.CONTENT_STYLE_PLAYABLE_HINT': 2,
};
/// The root folders (Favoritos, Todas las emisoras, Mis emisoras,
/// optionally Música Local, Ecualizador), all non-playable.
/// The root folders, all non-playable, and TIER-DEPENDENT: Favoritos,
/// Todas las emisoras, Mis emisoras and optionally Música Local for a
/// premium driver; the single [idDestacadas] folder for a free one (see
/// [premium] below).
///
/// Decision `auto/ecualizador-diseno` SUPERSEDES the "no equalizer
/// There is NO `Ecualizador` folder. The car's only equalizer control is
@@ -343,53 +444,77 @@ class ConstructorArbolAuto {
/// `Música Local` is OMITTED entirely (not just empty) unless
/// [incluirMusicaLocal] is `true` (Design "Local root hidden until a folder
/// is configured") — the caller lo deriva de
/// `fuente.estadoCarpeta() != EstadoCarpetaLocal.noConfigurada`
/// `premium && fuente.estadoCarpeta() != EstadoCarpetaLocal.noConfigurada`
/// (fix/android-auto-musica-local: un canal nativo ausente ya NO oculta el
/// nodo), keeping this builder itself synchronous and side-effect free.
/// nodo; fix/auto-quality-guidelines item 9: el `premium &&` va delante a
/// propósito, para que el tier gratuito ni siquiera pague ese round trip
/// nativo), keeping this builder itself synchronous and side-effect free.
///
/// [premium] (iap-freemium-unlock, Design ADR-4): the ROOT keeps the exact
/// same visible folder labels for every tier — "keeps the same visible
/// folder labels for free users" is the explicit design choice, so a free
/// driver still sees a real, familiar menu rather than a wall of "Función
/// Premium" rows. The lock itself is enforced one level DOWN, at the
/// `getChildren` choke point (see [itemPremiumBloqueado] and
/// [respuestaBloqueadaPorEntitlement] below) — tapping any of these
/// folders as a free user reveals the lock there, never here.
/// [premium] (fix/auto-quality-guidelines, item 8) is finally READ. It used
/// to be accepted and ignored, on the theory that "the root keeps the same
/// visible folder labels for free users" was friendlier than a reduced
/// menu. It was not: every one of those four folders dead-ended on a single
/// non-playable "Función Premium" row, and Google Play cited exactly that
/// against the Android for Cars App Quality Guidelines.
///
/// The free root is therefore ONE browsable folder, [idDestacadas], and the
/// premium-only folders are OMITTED rather than shown-and-blocked: a folder
/// a driver cannot use is worse than a folder that is not there.
///
/// It must stay at least one BROWSABLE item, never a bare playable one:
/// `audio_service` 0.18.18 discards `rootHints`
/// (`AudioService.java:817-826`), so this code cannot detect whether the
/// head unit accepts a `FLAG_PLAYABLE` root child, and the documented
/// default of `BROWSER_ROOT_HINTS_KEY_ROOT_CHILDREN_SUPPORTED_FLAGS` is
/// `FLAG_BROWSABLE` alone — a root of one playable item renders EMPTY on
/// such a unit.
///
/// Every label here comes from [etiquetas], already resolved to the head
/// unit's locale — the free root's [EtiquetasArbolAuto.escuchar] AND the
/// four premium folders.
///
/// The four premium ones used to be hardcoded Spanish, on the theory that
/// they were leaf rows deep inside a tree only a user who had already
/// chosen the app would reach. That was never a rule, only an untested
/// assumption, and it is retired: anything a user can read gets
/// translated. `escuchar` was localized first (it is 100% of what a free
/// Play reviewer sees), which is exactly why the rest had to follow.
///
/// [tituloDestacadas] stays as an explicit per-call override of
/// [EtiquetasArbolAuto.escuchar]; `null` (the default) uses the bundle.
List<MediaItem> raiz({
required bool incluirMusicaLocal,
required bool premium,
}) => [
_carpeta(idFavoritos, 'Favoritos'),
_carpeta(idTodas, 'Todas las emisoras'),
_carpeta(idMisEmisoras, 'Mis emisoras'),
if (incluirMusicaLocal) _carpeta(idMusicaLocal, 'Música Local'),
];
String? tituloDestacadas,
}) =>
premium
? [
_carpeta(idFavoritos, etiquetas.favoritos),
_carpeta(idTodas, etiquetas.todasLasEmisoras),
_carpeta(idMisEmisoras, etiquetas.misEmisoras),
if (incluirMusicaLocal)
_carpeta(idMusicaLocal, etiquetas.musicaLocal),
]
: [_carpeta(idDestacadas, tituloDestacadas ?? etiquetas.escuchar)];
/// Free-tier id prefix reserved id (iap-freemium-unlock, Design ADR-4):
/// the single non-playable item every non-root folder collapses to for a
/// free-tier user. Hardcoded Spanish label, matching every other car-tree
/// label in this file (never routed through `AppLocalizations` —
/// established convention, see [_tituloMasLocal]'s doc).
static const idPremiumInfo = 'premium:info';
/// The free tier's playable station rows (fix/auto-quality-guidelines,
/// items 8/9): [emisoras] mapped through the SAME [itemEmisora] the premium
/// folders use, capped like every other folder.
///
/// Separate from [hijos] because that path is gated on [_idsCarpetas] and
/// fed by a `FuenteEmisorasAuto` whose lists are all empty on a cold
/// headless bind — which is precisely the bind this folder has to survive.
/// An empty [emisoras] returns `[]` rather than any placeholder row: a
/// non-playable row in the car tree is the thing Play cited.
List<MediaItem> hijosDestacadas(List<Emisora> emisoras) =>
emisoras.take(_maxItemsPorCarpeta).map(itemEmisora).toList();
/// The single locked item shown for ANY non-root folder when the browsing
/// user is free tier (Design ADR-4, android-auto-media spec "Free-Tier
/// Reduced Root Browse"). Non-playable — selecting it is a no-op, never a
/// crash (Spec "Free-tier user selects a locked item").
MediaItem itemPremiumBloqueado() => MediaItem(
id: idPremiumInfo,
title: 'Función Premium',
playable: false,
extras: _contentStyleLista,
);
/// El item de [idLocalNoLista]. Etiqueta en castellano hardcodeado, como
/// TODAS las etiquetas del árbol del coche en este archivo (ver
/// [itemPremiumBloqueado]): convención establecida, nunca
/// `AppLocalizations`. No reproducible — seleccionarlo es un no-op.
/// El item de [idLocalNoLista]. Rotulado con
/// [EtiquetasArbolAuto.musicaLocalNoDisponible], ya resuelto al idioma del
/// head unit. No reproducible — seleccionarlo es un no-op.
MediaItem itemLocalNoDisponible() => MediaItem(
id: idLocalNoLista,
title: 'Abre PluriWave en el móvil para leer tu música',
title: etiquetas.musicaLocalNoDisponible,
playable: false,
extras: _contentStyleLista,
);
@@ -488,20 +613,15 @@ class ConstructorArbolAuto {
return (documentId, pagina);
}
/// Hardcoded-Spanish car-tree label for the trailing "load more" item
/// (Design ADR-5) — matches every other car-tree label in this file
/// (`'Favoritos'`, `'Música Local'`, [_tituloLocalFallback]), none of
/// which go through `AppLocalizations`. Deliberately NOT an arb key.
static const _tituloMasLocal = 'Más…';
/// The trailing "load more" `MediaItem` (Design ADR-5): non-playable, no
/// `artUri` (the label alone is the affordance, like [_carpeta]), id
/// `carpeta_local_pag:<siguientePagina>:<documentIdPadre>` — round-trips
/// via [paginaCarpetaLocalDesde] back to the parent folder's next page.
/// Rotulado con [EtiquetasArbolAuto.cargarMas].
MediaItem _itemMasLocal(String documentIdPadre, int siguientePagina) =>
MediaItem(
id: '$_prefijoCarpetaLocalPaginada$siguientePagina:$documentIdPadre',
title: _tituloMasLocal,
title: etiquetas.cargarMas,
playable: false,
extras: _contentStyleLista,
);
@@ -626,41 +746,41 @@ class ConstructorArbolAuto {
/// for small folders.
bool ofreceBuckets(int totalPistas) => totalPistas > _minPistasParaBuckets;
/// The "Ordenar por calidad" mode-entry `MediaItem` (Design ADR-4):
/// The "sort by quality" mode-entry `MediaItem` (Design ADR-4):
/// non-playable, id `carpeta_local_ord:calidad:0:<documentIdPadre>` —
/// always page 0 of the sorted view, round-trips via [ordenLocalDesde].
/// Hardcoded Spanish label, matching every other car-tree label in this
/// file — never routed through `AppLocalizations` (established
/// car-tree-label precedent, see [_tituloMasLocal]).
/// Rotulado con [EtiquetasArbolAuto.ordenarPorCalidad].
MediaItem _itemModoOrdenCalidad(String documentIdPadre) => _carpeta(
'${_prefijoCarpetaLocalOrd}calidad:0:$documentIdPadre',
'Ordenar por calidad',
etiquetas.ordenarPorCalidad,
);
/// A single bucket-folder `MediaItem` (Design ADR-4): non-playable, id
/// `carpeta_local_bucket:<idx>:0:<documentIdPadre>` — always page 0,
/// round-trips via [bucketLocalDesde]. [etiqueta] is the hardcoded
/// alphabetical-range label (e.g. `'A-F'`), matching every other
/// car-tree label in this file — never routed through `AppLocalizations`.
/// round-trips via [bucketLocalDesde].
///
/// [etiqueta] is an alphabetical RANGE (e.g. `'A-F'`), and it is the one
/// user-visible car-tree string that deliberately does NOT go through
/// [EtiquetasArbolAuto]: it names the Latin letters the folder's filenames
/// actually start with, so translating it would make it lie.
MediaItem _itemBucket(String documentIdPadre, int idx, String etiqueta) =>
_carpeta('$_prefijoCarpetaLocalBucket$idx:0:$documentIdPadre', etiqueta);
/// The "Reproducir carpeta" playable action item (Design ADR-5): id
/// `carpeta_local_reproducir:<documentIdPadre>`. Hardcoded Spanish label,
/// matching every other car-tree label in this file — never routed
/// through `AppLocalizations`.
/// The "play folder" playable action item (Design ADR-5): id
/// `carpeta_local_reproducir:<documentIdPadre>`. Rotulado con
/// [EtiquetasArbolAuto.reproducirCarpeta].
MediaItem _itemReproducirCarpeta(String documentIdPadre) => MediaItem(
id: '$_prefijoCarpetaLocalReproducir$documentIdPadre',
title: 'Reproducir carpeta',
title: etiquetas.reproducirCarpeta,
playable: true,
extras: _contentStyleGrid,
);
/// The "Reproducir aleatorio" playable action item (Design ADR-5),
/// The "shuffle play" playable action item (Design ADR-5),
/// mirrors [_itemReproducirCarpeta].
MediaItem _itemReproducirAleatorio(String documentIdPadre) => MediaItem(
id: '$_prefijoCarpetaLocalAleatorio$documentIdPadre',
title: 'Reproducir aleatorio',
title: etiquetas.reproducirAleatorio,
playable: true,
extras: _contentStyleGrid,
);
@@ -742,7 +862,7 @@ class ConstructorArbolAuto {
int siguientePagina,
) => MediaItem(
id: '$_prefijoCarpetaLocalOrd$modo:$siguientePagina:$documentIdPadre',
title: _tituloMasLocal,
title: etiquetas.cargarMas,
playable: false,
extras: _contentStyleLista,
);
@@ -756,7 +876,7 @@ class ConstructorArbolAuto {
int siguientePagina,
) => MediaItem(
id: '$_prefijoCarpetaLocalBucket$idxBucket:$siguientePagina:$documentIdPadre',
title: _tituloMasLocal,
title: etiquetas.cargarMas,
playable: false,
extras: _contentStyleLista,
);
@@ -836,7 +956,7 @@ class ConstructorArbolAuto {
final titulo =
(tituloMeta != null && tituloMeta.isNotEmpty)
? tituloMeta
: _tituloDesdeNombre(nodo.nombre);
: _tituloDesdeNombre(nodo.nombre, etiquetas.pistaSinNombre);
final artUriMeta = meta?.artUri?.trim();
final artUri =
(artUriMeta != null && artUriMeta.isNotEmpty)
@@ -953,24 +1073,56 @@ class ConstructorArbolAuto {
}
}
/// Pure Android Auto browse-gate decision (iap-freemium-unlock, Design
/// ADR-4): the AUTHORITATIVE `getChildren` choke point, called BEFORE any
/// other resolution. For the root itself this NEVER blocks (the root always
/// resolves through [ConstructorArbolAuto.raiz] instead, which stays
/// visible for every tier). For any non-root [parentMediaId] and a free-tier
/// [premium], it returns the single locked item regardless of what the id
/// actually is — a stale/deep-linked `emisora:<uuid>` or folder id from
/// before a downgrade is blocked exactly the same way as a legitimate
/// current folder id (android-auto-media spec "Free-Tier Browse Never
/// Leaks Real Content (Authoritative Backstop)"). Returns `null` when the
/// caller should proceed with its normal resolution (root, or premium).
/// Whether [parentMediaId] is content the FREE tier is allowed to browse
/// (fix/auto-quality-guidelines, item 10): the browsable root itself, the
/// free folder [ConstructorArbolAuto.idDestacadas], and an `emisora:<uuid>`
/// whose uuid belongs to [destacadas].
///
/// Everything else — the catalogue folders, favourites, custom stations,
/// local music, the equalizer folder, group folders, local tracks, and any
/// station uuid that is not in the free set — is premium content.
///
/// Pure and id-shaped, with the free universe INJECTED, so the whole matrix
/// is testable without prefs or a handler.
bool idPermitidoEnFree(
String parentMediaId, {
required List<Emisora> destacadas,
}) {
if (parentMediaId == AudioService.browsableRootId) return true;
if (parentMediaId == ConstructorArbolAuto.idDestacadas) return true;
if (!parentMediaId.startsWith(_prefijoEmisora)) return false;
final uuid = parentMediaId.substring(_prefijoEmisora.length);
if (uuid.isEmpty) return false;
return destacadas.any((e) => e.uuid == uuid);
}
/// Pure Android Auto browse-gate decision: the AUTHORITATIVE `getChildren`
/// choke point, called BEFORE any other resolution.
///
/// REWRITTEN (fix/auto-quality-guidelines, item 10) from action-blocking to
/// content-scoping. It used to answer ANY non-root id, for a free-tier user,
/// with a single non-playable "Función Premium" row — which is what Google
/// Play cited on version code 157 ("clicking on stop button makes the entire
/// app useless" was the headline, but the browse tree it was reviewed
/// against was four folders that each dead-ended on that row). A
/// non-playable row reachable from a head unit's CACHED tree is a citation
/// waiting to happen, so there is no longer any code path that can produce
/// one: the blocked branch returns the free tier's own playable stations.
///
/// Returns `null` when the caller should proceed with its normal resolution
/// (premium, or free-tier content the free tier owns).
///
/// [destacadas] is the free universe (`resolverEmisorasDestacadas()`); the
/// caller resolves it once per browse. Passing an empty list is legal and
/// yields an empty blocked response — still never a dead row.
List<MediaItem>? respuestaBloqueadaPorEntitlement({
required String parentMediaId,
required bool premium,
required List<Emisora> destacadas,
}) {
if (parentMediaId == AudioService.browsableRootId) return null;
if (premium) return null;
return [ConstructorArbolAuto().itemPremiumBloqueado()];
if (idPermitidoEnFree(parentMediaId, destacadas: destacadas)) return null;
return ConstructorArbolAuto().hijosDestacadas(destacadas);
}
/// Routing seam between a car-tapped `emisora:<uuid>` media id and the
@@ -982,17 +1134,21 @@ List<MediaItem>? respuestaBloqueadaPorEntitlement({
/// A stale/unknown id (or a malformed one) is a no-op: [reproducir] is
/// never called and no exception propagates (Spec "Unknown or stale media
/// id").
Future<void> reproducirPorMediaId(
///
/// RETURNS whether it actually dispatched (fix/auto-quality-guidelines,
/// item 12). The caller needs to tell "played" from "resolved to nothing"
/// so the second case can publish an explained error to the car instead of
/// leaving the driver with a tap that did nothing and said nothing.
Future<bool> reproducirPorMediaId(
String id, {
required FuenteEmisorasAuto fuente,
required Future<void> Function(MediaItem) reproducir,
}) async {
if (!id.startsWith(_prefijoEmisora)) return;
final uuid = id.substring(_prefijoEmisora.length);
if (uuid.isEmpty) return;
final uuid = uuidDeMediaIdEmisora(id);
if (uuid == null) return false;
final emisora = await fuente.porUuid(uuid);
if (emisora == null) return;
if (emisora == null) return false;
final item = MediaItem(
id: emisora.url,
@@ -1008,6 +1164,58 @@ Future<void> reproducirPorMediaId(
extras: {'uuid': emisora.uuid},
);
await reproducir(item);
return true;
}
/// The uuid inside an `emisora:<uuid>` media id, or `null` for any other
/// shape — no prefix (a `pista:`/`carpeta_local_*`/`eq_preset:` id, or a
/// folder id) and an empty tail both answer `null`.
///
/// Extracted (fix/auto-quality-guidelines, item 11) because the play-path
/// entitlement gate has to ask the same question `reproducirPorMediaId` asks,
/// one step earlier: "is this a station id, and which station?".
String? uuidDeMediaIdEmisora(String id) {
if (!id.startsWith(_prefijoEmisora)) return null;
final uuid = id.substring(_prefijoEmisora.length);
return uuid.isEmpty ? null : uuid;
}
/// A [FuenteEmisorasAuto] over nothing but the free tier's station set
/// (fix/auto-quality-guidelines, item 12).
///
/// Stands in for `_fuenteNavegacionGlobal` while that is still `null` — the
/// window between the headless Android Auto engine starting and `main.dart`
/// registering the real source. A tap arriving in that window used to return
/// in silence; the free set is compiled into the binary, so it can always be
/// answered.
///
/// Reports the free stations through [todas] (they are, from the car's point
/// of view, everything there is) and nothing through the curated lists, which
/// a headless bind could not populate anyway.
class FuenteEmisorasAutoDestacadas extends FuenteEmisorasAuto {
FuenteEmisorasAutoDestacadas(this._destacadas);
final List<Emisora> _destacadas;
@override
Future<List<Emisora>> favoritos() async => const [];
@override
Future<List<Emisora>> misEmisoras() async => const [];
@override
Future<List<Emisora>> todas() async => _destacadas;
@override
Future<List<GrupoFavoritos>> grupos() async => const [];
@override
Future<Emisora?> porUuid(String uuid) async {
for (final emisora in _destacadas) {
if (emisora.uuid == uuid) return emisora;
}
return null;
}
}
/// Which list previous/next should walk for [actual]: the NARROWEST context
@@ -1188,25 +1396,22 @@ Future<void> seleccionarPresetEqPorMediaId(
if (!activo) await activarEcualizador(true);
}
/// Fallback title (Design "Title = filename minus extension") for a blank
/// or otherwise empty-after-stripping local filename — hardcoded Spanish,
/// matching every other car-tree label in this file (`'Favoritos'`,
/// `'Música Local'`, etc.), none of which go through `AppLocalizations`.
const _tituloLocalFallback = 'Pista sin nombre';
/// Filename → display title (Design "Title = filename minus extension"):
/// strips the LAST `.ext` (the whole trimmed name is kept when there is no
/// dot, or the dot is the first character — e.g. a hidden file like
/// `.mp3`), falling back to [_tituloLocalFallback] when the result would be
/// blank.
String _tituloDesdeNombre(String nombre) {
/// `.mp3`), falling back to [sinNombre] when the result would be blank.
///
/// [sinNombre] is [EtiquetasArbolAuto.pistaSinNombre], passed in rather than
/// hardcoded: it is a title the driver reads, so it is translated like every
/// other car-tree label.
String _tituloDesdeNombre(String nombre, String sinNombre) {
final recortado = nombre.trim();
if (recortado.isEmpty) return _tituloLocalFallback;
if (recortado.isEmpty) return sinNombre;
final ultimoPunto = recortado.lastIndexOf('.');
final sinExtension =
ultimoPunto > 0 ? recortado.substring(0, ultimoPunto) : recortado;
final resultado = sinExtension.trim();
return resultado.isEmpty ? _tituloLocalFallback : resultado;
return resultado.isEmpty ? sinNombre : resultado;
}
/// Resolves the on-brand fallback `artUri` for a local track (Design "art =
@@ -1479,12 +1684,13 @@ Future<void> reproducirCarpetaLocal(
Future<MediaItem?> construirMediaItemColaLocal(
NodoLocal nodo, {
required FuenteMusicaLocalAuto fuente,
EtiquetasArbolAuto etiquetas = EtiquetasArbolAuto.respaldo,
}) async {
final contentUri = await fuente.uriContenidoDePista(nodo.documentId);
if (contentUri == null || contentUri.isEmpty) return null;
return MediaItem(
id: contentUri,
title: _tituloDesdeDocumentId(nodo.documentId),
title: _tituloDesdeDocumentId(nodo.documentId, etiquetas.pistaSinNombre),
album: 'PluriWave',
// Item 3: a queued local track had NO artUri at all before — reuses
// [artUriLocal] (the SAME on-brand rotation the browse tree's
@@ -1548,8 +1754,9 @@ Future<Map<String, MetadatosPista>> _metadatosDeConCache(
Future<List<MediaItem>?> hijosMusicaLocal(
String parentMediaId, {
required FuenteMusicaLocalAuto? fuente,
EtiquetasArbolAuto etiquetas = EtiquetasArbolAuto.respaldo,
}) async {
final constructor = ConstructorArbolAuto();
final constructor = ConstructorArbolAuto(etiquetas: etiquetas);
// Sort-mode and bucket views (Design ADR-4, Phase 2) are routed FIRST —
// routing order is irrelevant to correctness (every prefix in this file
@@ -1640,11 +1847,11 @@ Future<List<MediaItem>?> hijosMusicaLocal(
/// the SAME [_tituloDesdeNombre] rule the browse tree uses. This keeps the
/// Now Playing title consistent with what the user tapped without requiring
/// a second native round trip.
String _tituloDesdeDocumentId(String documentId) {
String _tituloDesdeDocumentId(String documentId, String sinNombre) {
final ultimaBarra = documentId.lastIndexOf('/');
final segmento =
ultimaBarra >= 0 ? documentId.substring(ultimaBarra + 1) : documentId;
return _tituloDesdeNombre(segmento);
return _tituloDesdeNombre(segmento, sinNombre);
}
/// Routing seam between a car-tapped `pista:<docId>` media id and the
@@ -1663,6 +1870,7 @@ Future<void> reproducirPistaLocal(
String id, {
required FuenteMusicaLocalAuto fuente,
required Future<void> Function(MediaItem) reproducir,
EtiquetasArbolAuto etiquetas = EtiquetasArbolAuto.respaldo,
}) async {
if (!esPistaMediaId(id)) return;
final documentId = id.substring(_prefijoPista.length);
@@ -1673,7 +1881,7 @@ Future<void> reproducirPistaLocal(
final pista = PistaLocal(
documentId: documentId,
titulo: _tituloDesdeDocumentId(documentId),
titulo: _tituloDesdeDocumentId(documentId, etiquetas.pistaSinNombre),
contentUri: contentUri,
);
@@ -1768,6 +1976,16 @@ class FuenteEmisorasAutoLocal implements FuenteEmisorasAuto {
return _snapshotTodas ?? const [];
}
/// Resolves a station uuid across every list this source can reach.
///
/// The free tier's set ([resolverEmisorasDestacadas]) is searched LAST
/// (fix/auto-quality-guidelines, item 7). It has to be searched at all
/// because on a cold headless bind the three lists above are all empty —
/// `todas()` is `_snapshotTodas ?? const []`, favourites and custom
/// stations have nothing persisted on a fresh install — so a curated
/// `emisora:<uuid>` resolved to `null` and tapping the row did NOTHING.
/// It is searched last so a live catalogue/favourite record for the same
/// uuid (richer metadata, the user's own group assignment) still wins.
@override
Future<Emisora?> porUuid(String uuid) async {
final listas = await Future.wait([favoritos(), misEmisoras(), todas()]);
@@ -1776,6 +1994,9 @@ class FuenteEmisorasAutoLocal implements FuenteEmisorasAuto {
if (emisora.uuid == uuid) return emisora;
}
}
for (final emisora in await resolverEmisorasDestacadas()) {
if (emisora.uuid == uuid) return emisora;
}
return null;
}
File diff suppressed because it is too large Load Diff