FreeTLab/pluriwave
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
34388d364ba7bcc416b82d049b0f39bb64324f37
pluriwave/openspec/changes/archive/2026-07-19-android-auto-local-music-phase2/archive-report.md
T
FreeTLab 85dd043cd4 docs(openspec): archive android-auto-local-music-phase2 
Merges its delta requirements into the android-auto-media base spec.
Completes Phase 2; only Phase 3 (subfolder scoping, shuffle) remains.
On-device validation of the native metadata path is still an
outstanding pre-release gate across all local-music phases shipped
today.
2026-07-19 23:59:21 +02:00

7.8 KiB
Raw Blame History

Archive Report: android-auto-local-music-phase2

Date: 2026-07-19
Change: android-auto-local-music-phase2
Artifact Store Mode: Hybrid (OpenSpec files + Engram persistence)
Status: Complete — Change archived and closed

Executive Summary

The android-auto-local-music-phase2 change is fully implemented, verified with 0 CRITICAL and 2 WARNINGs (documentation-accuracy only, already corrected), and has been archived. Phase 2 of the local-music feature is now complete, delivering real embedded metadata resolution, quality-based sort navigation, and alphabetical name buckets for browsable audio files in Android Auto. Only Phase 3 (subfolder scoping refinements, shuffle) remains as planned future work. Outstanding pre-release gate: native metadata-extraction path (MediaMetadataRetriever, FileProvider art cache/LRU) requires on-device/DHU validation across all local-music phases before production release.

Change Artifacts

Specification Artifacts

Base Spec: openspec/specs/android-auto-media/spec.md

  • Status: MERGED with delta requirements
  • Changes:
    • MODIFIED: "Local Music Browsable Tree" requirement expanded to include metadata resolution scenarios (title/art reflection, embedded-metadata fallback)
    • ADDED: "Local Music Sort Mode Navigation" requirement (name sort, quality sort by bitrate)
    • ADDED: "Local Music Alphabetical Name Buckets" requirement (A-F/G-M/N-S/T-Z letter ranges)
    • ADDED: "Local Track Embedded Album Art Display" requirement (static URI resolution, fallback handling)

Delta Spec: openspec/changes/archive/2026-07-19-android-auto-local-music-phase2/specs/android-auto-media/spec.md

  • Archived for traceability

Change Folder Artifacts

Archived Location: openspec/changes/archive/2026-07-19-android-auto-local-music-phase2/

Contents:

  • proposal.md — Phase 2 scope, intent, capabilities, and ADRs (metadata extraction via MediaMetadataRetriever, on-demand parsing, LRU cache)
  • design.md — Technical architecture (5 ADRs, data flow, file changes, testing strategy, open questions on 150-track cap and 256-file/32MB art budget)
  • tasks.md — 37 implementation tasks across 4 phases (model/native/cache/sort/buckets/regression)
  • apply-progress.md — All 37/37 tasks completed, 137/137 tests passing, single PR with size:exception, corrected test counts (18 vs 19 claimed)
  • verify-report.md — PASS WITH WARNINGS; 0 CRITICAL, 2 WARNINGs (test-count inaccuracy corrected before archive), implementation verified sound
  • specs/android-auto-media/spec.md — Delta spec for archive trail

Merged Specification Requirements

Modified Requirement: Local Music Browsable Tree

Expanded to include:

  • Track title resolution: shows embedded metadata when available, falls back to filename
  • Track art resolution: shows embedded album art when available, falls back to generic placeholder
  • Graceful degradation: no exceptions on metadata unavailability, continues browsing

New Requirement: Local Music Sort Mode Navigation

  • Browsable, non-playable sort-mode entries on page 0
  • "By name" (filename order) always available
  • "By audio quality" (bitrate descending) available when folder <= 150 tracks
  • Mirrors ordenarEmisoras(..., calidad) comparator pattern

New Requirement: Local Music Alphabetical Name Buckets

  • Browsable, non-playable letter-range folders (A-F, G-M, N-S, T-Z)
  • Metadata-free partitioning (uses only filename)
  • Available when folder > 50 tracks
  • Enables name-based filtering on legacy MediaBrowserService surface

New Requirement: Local Track Embedded Album Art Display

  • Static URI resolution via FileProvider cache (content://...fileprovider...)
  • Art cache with LRU eviction (256 files / 32 MB budget)
  • Graceful fallback to generic rotating placeholder art

Implementation Summary

Delivery Strategy

  • Mode: Single PR with size:exception (user's established preference for high-risk changes this session)
  • Test Mode: Strict TDD (all Dart behavior-changing code), Static-review-only (native Kotlin per project precedent)
  • Result: 1979 changed lines, all 137/137 tests passing

Test Coverage

  • 114 tests in navegacion_auto_test.dart (encode/decode, buckets, quality sort, page-0 wiring, fallbacks, collision guards)
  • 18 tests in musica_local_auto_test.dart (LRU cache, metadata channel call, null tolerance)
  • 5 tests in pista_local_test.dart (DTO construction)
  • Total verified: 137/137 pass, 0 failures

Verification Status

  • Verdict: PASS WITH WARNINGS
  • CRITICAL Issues: None
  • WARNINGs (both documentation-accuracy, corrected):
    • Apply-progress claimed 138/138 tests (19 in musica_local_auto_test.dart); actual 137/137 (18 tests). Corrected in apply-progress before archive.
    • Apply-progress claimed 9 fixture corrections; actual 8. Corrected in apply-progress before archive.
  • SUGGESTIONs (non-blocking):
    • Native Kotlin code (readAudioMetadataBatch, art cache, LRU trim) remains static-review-only per established project precedent (no build/DHU environment)
    • On-device validation of 150-track cap and 256-file/32MB art budget deferred to pre-release gate (design "Open Questions")
    • Cosmetic CRLF line-ending warnings (not defects)

Key Design Decisions Verified

  1. Embedded-art delivery: FileProvider cache (content:// URI) — reuses existing authority, zero new manifest surface
  2. Metadata cache: Flat 256-entry LRU-by-access in navegacion_auto.dart — ensures paging doesn't evict earlier pages
  3. Quality-sort threshold: Offered when folder <= 150 tracks; above that, name + buckets only (head-unit latency guard)
  4. Media-ID collision safety: carpeta_local_ord: and carpeta_local_bucket: prefixes proven non-colliding against all 6 pre-existing prefixes
  5. Page-scoping invariant: Metadata resolved only for the requested page's 50 items, never the whole folder (except quality-sort, which is opt-in)

Rollback Profile

Phase 2 is fully additive over Phase 1. If needed:

  • Remove readAudioMetadataBatch native call
  • Drop _ord and _bucket media-id prefixes
  • Restore filename titles + placeholder art
  • Phase 1 browse/play/paging remains fully functional

Outstanding Pre-Release Gates

Native code validation (applies to Phases 1, paging, and 2):

  • MediaMetadataRetriever bitrate/sample-rate/embedded-picture extraction with real SAF URIs (on-device/DHU)
  • FileProvider art cache write/read on actual Android file system
  • 150-track quality-sort wall-clock latency (design "Open Questions")
  • 256-file / 32 MB art cache eviction under realistic browsing patterns

No code changes required — these are validation gates for go-live, not SDD cycle blockers.

Archive Checklist

  • Delta spec merged into main spec (openspec/specs/android-auto-media/spec.md)
  • All 4 new/modified requirements integrated into spec source of truth
  • Change folder moved to archive with ISO date prefix: openspec/changes/archive/2026-07-19-android-auto-local-music-phase2/
  • All artifacts (proposal, design, tasks, apply-progress, verify-report, delta spec) copied to archive
  • Archive report written to both filesystem and engram
  • Verification passed (PASS WITH WARNINGS, 0 CRITICAL)

SDD Cycle Completion

  • Proposed: android-auto-local-music-phase2
  • Specified: 1 modified + 3 added requirements
  • Designed: 5 ADRs, page-scoping invariant, media-ID codec, LRU cache
  • Tasked: 37 implementation tasks (4 phases, model/native/cache/sort/buckets)
  • Applied: All 37 tasks completed, single PR, 1979 changed lines, 137/137 tests green
  • Verified: PASS WITH WARNINGS (0 CRITICAL, 2 WARNINGs corrected)
  • Archived: Change folder and all artifacts persisted

Next: Phase 3 (subfolder scoping, shuffle) when scheduled. Entire local-music feature remains gated on pre-release native validation.

Reference in New Issue View Git Blame Copy Permalink