Legendary MP3: Case Study

Where It Started

The Library

Every music player treats a broken library as the user’s chore.

3,061Songs in my own collection, which became the hostile test set

7Players compared; none performed automatic, batch metadata repair

183Artists shown for a library with one, in the player I used daily, because it split every “feat.” credit

A decade-old collection has tracks titled “Track 7,” albums called “Unknown album (4/3/2022 5:10 PM),” and missing covers. In every player I compared, tagging was a manual, one-file-at-a-time editor. That gap is the whole opening: the player is the price of admission, and the repair is the product.

The player is free, ad-free and needs no account. The repair engine is a one-time $4.99 unlock, with no backend to pay for: every lookup hits a free public database and everything else happens on the phone.

Results

Before And After

Real problems from my own files, and what changed.

Problem	Before	After
Placeholder tags	“Track 7,” “Untitled” and “Unknown album (4/3/2022…)” read as complete, so repair skipped them and they stayed broken	Judged as missing; the file name and folder stand in, and the album is queued for repair
Cover art	376 files with no embedded art	28, and those are personal recordings no database can match
A regex bug	“Daft Punk” indexed as artist “Da” featuring “Punk”	A word boundary on “feat.”; 35 Daft Punk tracks verified on a phone
Split credits	A soundtrack credited “Jack Wall & Sam Hulick” spawned an artist per credit string	Artists are album first: 142 entries became 123, and two albums and 63 songs sit under one name
Musical key	43% of songs came back in C, because kick drums were choosing the key	C is 7.3% and 90% of the library gets a key
Wrong or empty fields	Fixes meant editing files one at a time	One reviewed batch, one consent prompt, three-deep undo

The Wedge

How A Repair Works

From a scan to a rewritten file, with nothing changing until you accept it.

Scan Once, Render From The Index

The app reads MediaStore once into a Room database and every screen draws from that index. It never crawls the filesystem at launch, which is reportedly what gives AIMP a startup measured in minutes. A rescan compares modified date and size and re-reads tags only for changed files.
Judge Every Track

Each track gets a state: complete, missing art, missing tags, untagged or conflicted. A filled-in tag can still say nothing, so placeholder titles and artists count as missing.
Group By Album Before Asking

MusicBrainz allows one request per second. One release lookup resolves a whole folder, which cuts request volume by an order of magnitude.
Score The Candidates

Track count, duration within three seconds, title, artist and year are weighed together. A title floor caps a different album by the same artist below review, a fault the match tests found.
Review In Three Bands

High scores are proposed automatically, middle scores wait for confirmation, low scores are rejected. Every proposal shows a confidence chip, and nothing touches a file yet.
Write One Batch

Android 11 and later requires consent for files the app did not create, which done naively is a dialog per file. One request covers the batch. Each file is copied to cache, edited, streamed back, and verified by length and by re-reading its header, with one retry. My own review found a kill between truncating and finishing could damage a file, which is why the check exists.
Undo

The original tag block is saved before each write, and the last three batches can be reversed. A field the engine cannot write is marked failed so it stops proposing it.

Audio Analysis

Measuring Key

Four tries, and the first three were the same mistake: I tuned the scoring when the problem was the evidence.

Kick Drums Chose The Key

The first full run over 3,047 songs came back 43% in C, 18% in F and 16% in D minor: 65, 87 and 73 Hz, where bass and kick live. The analysis started at 55 Hz, so on a hip-hop library the drum was picking the key. The fix was a longer window, a 185 Hz floor and per-frame normalization.
Ambiguous Tracks Fell To C

The library was still 38% C, because a winner only needed to beat the runner-up by 0.01 and a tie went to whichever key was tested first. A strict gate cut false C to 12.4% but answered for only 46% of songs. Nothing was measured, so I could not tell which change helped.
Build The Benchmark First

Twenty-six records with published keys, scored with the MIREX weighting: exact is 1.0, a perfect fifth 0.5, relative major or minor 0.3, parallel 0.2. A fifth away is a different kind of wrong from a random key, and scoring them the same hides whether a change helped. Writing it took a couple of hours.
Rebuild The Front End

Spectral peaks only, with parabolic interpolation, harmonic voting and a tuning correction. Coverage went from 50% to 96%, exact matches from 23% to 50%, and the weighted score from 0.296 to 0.581. On my library, 2,784 of 3,061 songs now get a key.

Which Key Profile Won

Profile	Exact Matches	Weighted Score
Sha’ath (chosen)	50%	0.581
EDMA	50%	0.550
bgate	46%	0.542
Krumhansl	42%	0.531
Temperley	30%	0.385

A reference has to be more trustworthy than what it judges. The popular lookup site songbpm is Spotify’s own estimate and was wrong on four of the 26; published sheet music settled all four.
I left out a confidence gate on purpose. Adding one dropped coverage to 50% and weighted accuracy from 0.62 to 0.39, because the songs it discarded were no better or worse than the ones it kept. A near miss a DJ can mix with beats a blank every time.
Tests caught what ears could not. A held sine read as rhythmic and white noise came back in A minor, until the tests pinned both.
The honest ceiling is not 100%. Half exact, with most of the rest a fifth or a relative away, is roughly where a good open-source detector sits on a pop library.

Playback

The Audio Chain

Media3 does the decoding. The rest is custom processors, built to run on the audio thread without blocking.

Decode

Media3 and ExoPlayer inside a media-library service, so the notification, lock screen and Bluetooth controls come with it.

ReplayGain

Read from tags at index time and applied as volume, with the pause fade kept from fighting it.

Parametric EQ

Ten cascaded biquad filters in float, with a pre-amp, gain smoothing so a slider does not click, and a profile per output device.

Visualizer Tap

PCM copied into a lock-free ring buffer, with the FFT on another coroutine. No microphone permission.

Output

The platform audio path, or a USB DAC with the file’s own sample rate requested.

Crossfade is two players taking turns. Media3 will not overlap two items in one player, and fading inside a processor cannot react to a pause or a skip because the audio is already decoded. Only the audible deck holds audio focus; if the standby deck asked for it, being granted focus would pause the deck fading out and the crossfade would be a hard cut. The roles swap at the end of the fade, and skip during a fade finishes it rather than restarting the song.
Never ask a music player for the microphone. Android’s own visualizer class requires that permission, so I tapped the audio already inside the app instead, and the absence of the permission is a line in the store listing.
A known limit, written down so it is not chased again. Two MP3 halves of a pure tone pop at the join even though the files and the decoder are clean. It traces to a trim count inside the media library, it is inaudible under music, and gapless on real songs was confirmed.
USB DACs: honest about what the phone offers. I bought a small DAC to test bit-perfect output. The phone offered no bit-perfect mode on any port and no 44.1 kHz at all, so I built rate matching, verified by the DAC’s LED (yellow at 96 kHz, blue at 44.1), and the app does not call it bit-perfect.

Judgment

What I Cut

The decisions that kept the product small, each with its reason.

Cut	Why
Audio fingerprinting	The lookup service is free only for non-commercial use, and a paid app is commercial: 50 euros a month, about $650 a year, or roughly 155 sales at $4.24 net before it pays for itself. Of 3,063 tracks, 2 (0.1%) had neither an artist nor an album, the only case it solves.
Chromecast	A minority feature in this category, untestable without a Cast device, and it disables the equalizer, visualizer and crossfade while active.
Genre browsing	Six library tabs did not fit at large text. Genre survives as a tag field and a smart-playlist rule.
A skin marketplace	Third-party skins lock a layout in place forever, which is why Poweramp and AIMP are stuck with aging interfaces. Three first-party styles instead, all free.
Prompt-to-playlist	There is no catalogue to draw from. A text box that only searches your own tags while looking like AI would be a lie, so smart playlists use real values from the library with a live match count.
A “bit-perfect” claim	The phone I tested does not offer it. Rate matching is what exists, and it is named as such.

Money

Selling It Honestly

With no server, the price only has to cover a store’s cut.

Area	Free	Legendary ($4.99, Once)
Playback	The whole player: gapless, crossfade, ReplayGain, a queue, widget, no ads	Included
Equalizer	Simple preset equalizer	10-band parametric with per-device profiles
Visualizers	All five, deliberately free: they are the screenshot that sells the app	Included
Repair	A 25-track trial, so the value shows on your own library	Unlimited batch repair and automatic artwork
Organization	Playlists and M3U import and export	Smart playlists and multiple saved queues

The unit economics: Google’s small business rate nets about $4.24 a sale, and marginal cost per user is close to zero, which is what made a one-time price viable. The price started at $9.99 and was cut to $4.99; the incumbent unlock, Poweramp, is $5.99.
Reading every file before selling it. Before submitting I reviewed all 109 Kotlin files, about 17,000 lines, against the build about to ship. Three things should not have shipped: smart playlists and saved queues were promised in the terms, the listing and the paywall but nothing in the code gated either; a destructive database fallback could silently wipe play counts and playlists on a schema change; and the first screen said the app had no network permission when it had one.
The fixes are tests, not promises. A test fails if the schema version advances without a matching migration, and the paid features are gated in code.

My first plan was a second codebase in Swift. After Android shipped I reversed it, and put the numbers on the page.

94Android builds before launch, because local builds were free

$1Per iOS build on a rented macOS runner, about 20 minutes each

70%Of the app shared with iOS through a Kotlin Multiplatform module

Sharing the Kotlin is about 4 to 6 weeks; a Swift rewrite is 10 to 14. The shared module covers UI, styles, the database, matching, the DSP maths, scrobbling and the tests, so every lesson from the Android device passes carries over.
The same habit on iOS would cost about $100, so shared code is built and tested on Android first, where it is free, and iOS-only changes go in batches.
The pipeline came before the features. An empty app went from CI to TestFlight to the phone first, and the first build ran the shared Kotlin on an iPhone before any screen moved.
The database moved without touching installed copies. The schema is identical after the move, and with no destructive fallback a mismatch would crash on open instead of passing quietly.
Android is live on Google Play; iOS is in progress and not yet in the store.

Stack

Under The Hood

Local first: a native app, a playback service that outlives the screen, and an index on the phone.

About 17,000 lines of Kotlin across UI, DSP, playback, metadata and data, in Jetpack Compose with Material 3 and three first-party styles.
Room schema 9, every step a tested migration, with the library database excluded from backup.
The only network calls are MusicBrainz and the Cover Art Archive, Last.fm and ListenBrainz scrobbling that queues offline, billing, and crash reports stripped to a stack trace.
205 unit tests, 26 instrumented tests and 6 on-device flows, behind a pre-push gate that runs the UI rules check, the tests and lint. CI went red on three pushes in one day before the gate existed.
A widget that never worked, found on a device. A widget callback runs inside a receiver, which is not allowed to bind to the playback service, and a catch-all swallowed the exception.

Kotlin Jetpack Compose Media3 Room WorkManager MusicBrainz RevenueCat Sentry Maestro Kotlin Multiplatform

You cannot optimize what you have not measured, and a number is only as good as the reference it was checked against.
The through-line with my professional work is measurement. It is the same rule that makes a cloud cost report worth reading. The key detector went from argument to improvement the day it had a benchmark, and the cost of a feature became a decision the day it had a price per sale.

Visit the Legendary MP3 Site

Back to Projects

Legendary MP3

The Library

Before And After

How A Repair Works

Scan Once, Render From The Index

Judge Every Track

Group By Album Before Asking

Score The Candidates

Review In Three Bands

Write One Batch

Undo

Measuring Key

Kick Drums Chose The Key

Ambiguous Tracks Fell To C

Build The Benchmark First

Rebuild The Front End