Software · AIFlutterLocal-firstExplainable

A music player that learns preferences without taking the user's data.

Resonance Music rebuilds an earlier Qt Widgets player as a cross-platform Flutter application for local music, licensed previews and downloads, on-device behavior history, and explainable recommendations.

Overview & context

Playback, licensing, and personalization must be designed together.

The project spans desktop and mobile layouts, local and online sources, persistent playback state, preview and download licenses, and cold-start recommendations.

Problem

A traditional single-window player does not adapt well across platforms. Opaque cloud profiles undermine privacy, while media sources require clear boundaries between preview, cache, and permanent download.

Architecture

Separate interface, application use cases, domain models, and data sources.

Ports isolate playback, media sources, persistence, and recommendation logic for testability.

01 · UIAdaptive Shell

Pages, navigation, themes, and player controls.

02 · APPAppController

Coordinates search, playback, favorites, and recommendations.

03 · DOMAINSong & Behavior

Tags, events, preference vectors, and ranking.

04 · DATASources

Local files, public search, and licensed media adapters.

05 · DEVICEPersistence

Favorites, history, cache, and preferences.

Technical decisions

Privacy, licensing, and explainability drive the architecture.

01

Flutter rebuild

One UI layer covers four platforms while preserving platform-specific file, storage, and playback capabilities.

02

Source adapters

Metadata search is separated from actual playback through licensed providers.

03

Thresholded personalization

Personalization starts only after enough useful signals have accumulated.

04

Time decay

Older behavior decays over a 45-day half-life, with freshness, repetition, and artist-diversity adjustments.

Results

A runnable and testable cross-platform core workflow.

4 platformsWindows, Ubuntu, iOS, and Android targets
17 testsWindows acceptance tests recorded as passing in the current README
Local-firstBehavior, preferences, favorites, and paths stay on-device by default
Current boundary: iTunes provides short previews only; Internet Archive metadata quality varies; background playback, cross-device sync, and batch downloads are outside the current acceptance scope.
REPOSITORY

Explore the implementation and documented boundaries.

The repository includes architecture, product specifications, recommendation formulas, tests, and four-platform build configuration.

Open GitHub