Stable · v1.0.0> windows / music collection management
Manage a local music library against a Yandex Music collection: identity matching, missing-track coverage, recording variants, metadata repair, downloads, and controlled synchronization.
MusicArk separates track identity, recording variant, and collection coverage instead of treating similar titles as a match. It combines a Flutter desktop interface with a Python backend, local SQLite state, cache-first provider access, and explicit write boundaries for local files and Yandex actions.
> context
MusicArk is designed around the gap between the music a user wants to keep and the files actually present on disk. It makes uncertainty visible instead of silently assuming that similar metadata means the same recording.
Different releases can share similar titles and artists, censored/original versions may look almost identical, and stale provider metadata can create false matches. A destructive sync built on weak identity would be risky.
MusicArk builds provider cache and local index first, runs conservative Identity Matching, keeps Variant analysis separate, derives Coverage from authoritative state, and only then enables downloads, metadata work, upload/recovery, or Controlled Sync.
> capabilities
v1.0.0 packages the complete desktop MVP for Windows x64 without requiring a separate Python installation.
Sign in with a user-provided token and browse liked tracks, playlists, and liked albums through a cache-first provider layer.
Index multiple folders without modifying files during ordinary Scan; retain technical fields and searchable local metadata in SQLite.
Conservative matching where precision is preferred over recall. Results remain MATCHED, CONFLICT, or UNMATCHED instead of forcing weak guesses.
Analyze recording differences separately from identity and support user ORIGINAL / CENSORED labels with review for uncertain cases.
Derive covered / missing / needs_review / not_analyzed from current matching state and user triage rather than maintaining a second matching engine.
Persistent queue with Wanted, retry, cancel, remove and bulk actions; a long-lived worker avoids rebuilding the provider client for each queued track.
Explicit MP3/ID3 writes, artwork, filename changes and Yandex metadata comparison with temporary-copy validation and atomic replacement.
Build an immutable plan, detect staleness, require confirmation, revalidate before Apply, and enqueue only currently valid downloads.
Play local/prepared tracks, manually upload owned/permitted MP3 files to Yandex Music, and support recovery workflows for unavailable tracks.
> interface
Current MusicArk screenshots from the project repository. Images keep their natural aspect ratio and can be opened at full size.
$ data flow
Desired state, actual files, identity and variant evidence stay separate. Coverage is derived only after matching state is known.
$ architecture
The UI and backend have explicit boundaries. Provider credentials and protected media URLs stay in the Python side rather than crossing into Flutter.
Permanent application shell, Yandex workspace, Local Library, Matching/Coverage, Downloads, Sync, Metadata, Settings/Help/About and RU/EN presentation.
Provider integration, local indexing, identity matching, variant analysis, coverage, downloads, metadata operations, sync planning, updates and feedback bridges.
Cache-first Yandex collection snapshots, local library index, matching state, variant results, coverage triage, downloads, settings and sync history.
Explicit JSON/process boundaries connect Flutter to Python services. Binary artwork and credentials are not passed through metadata bridges.
Yandex token is stored in the system credential store through keyring; signed provider URLs and auth/cookie data are not persisted in task payloads.
Flutter desktop app plus frozen Python backend runtime in both installer and portable package; user data lives separately under %LOCALAPPDATA%\MusicArk.
> engineering
MusicArk favors conservative state transitions and explicit confirmation because collection-management mistakes are more expensive than asking the user to review an uncertain track.
A false automatic identity match can poison later Coverage and Sync decisions, so uncertain candidates remain conflicts or unmatched.
Only an authoritative current UNMATCHED state becomes Missing. Stale, conflict, or unanalyzed data remains visibly separate.
Scan, Matching, Variant, Coverage and Sync-plan inspection do not mutate audio files. MP3 changes require a deliberate editor action.
MusicArk does not automatically delete, rename, move, or overwrite existing tracks just to make the filesystem resemble Yandex Music.
Apply refuses stale plans and rechecks pending downloads against current Coverage and queue state before enqueueing work.
External API/download failures should remain scoped to affected provider functions and must not block browsing cached/local collection state.
> technology
> security
EXPLICIT BOUNDARIESMusicArk is intentionally conservative around local files, credentials, and update execution. Normal analytical workflows are read-only, provider secrets stay outside Flutter, and installer execution is gated by manifest/size/SHA-256 verification plus user confirmation.
$ stable_release
v1.0.0 is the first stable public Windows release. The installer and portable package both include the Flutter application and frozen Python backend runtime. No separate Python installation is required.
A94F53F01BE23033405A6BAB2909436CC4CC1B1E99B19F57DD3A1307869BD3B8105E440C266B8EF3E9DDF2E40479FD4BEDF3ADF7253DD7A15D45127D51135D0E> project links
GitHub remains the source of truth for release notes, architecture, source boundaries, third-party licenses and issue tracking.