Finamp: I built the Instant Mix
Finamp is an open-source music client for Jellyfin, the self-hosted media server. It's written in Flutter, it has more than 4,200 stars on GitHub, and it's been downloaded over 50,000 times on Google Play alone. If you host your own music library and listen to it on a phone, this is the app you use.
In 2022 I contributed the app's Instant Mix feature: tap any song, artist or album and Finamp builds you an endless radio-style queue of music like it. It shipped across three pull requests and it's been in every release since.
- 4 pull requests merged into a project with 4,200+ stars.
- Roughly 600 lines added across the Jellyfin API client, the audio service and three different screens.
- Shipped to 50,000+ Google Play installs and an App Store audience rating the app 4.5 stars.
- The maintainer's review, in full: “This is really well done, merged :)”
What the maintainer said
Finamp is maintained by jmshrv (UnicornsOnLSD). These are his review comments, verbatim:
This is really well done, merged :) UnicornsOnLSD on PR #246, the original Instant Mix feature, 5 June 2022
Code looks good, I'm assuming the iOS build is just some weird macOS quirk. Merged :) UnicornsOnLSD on PR #250, instant mix from artists, 12 June 2022
This looks great, in my opinion having sorting on playlists is useful… UnicornsOnLSD on PR #232, sort-order parity, 13 May 2022
LGTM, merging UnicornsOnLSD, approving review on PR #232, 15 May 2022
What users said
The best measure of a feature is that people stop noticing it's a feature. Two years after the merge, reviewers on both stores talk about the mix as simply part of the app:
EDITED - This app did have instant mixes, the random playlist feature I thought it didn't have! John.Apple.taken, “Much better than jellyfin,” Apple App Store, 13 November 2024
This reviewer wrote in asking for exactly the feature I'd built, found it, and came back to edit the review. That's the one I'm proudest of.
It's very good for what it is… There's the “mix” but I would like to queue an album to play at the end of the current album. guinea horn, Google Play, 23 May 2023
Not a rave, but note what it takes for granted. A year on, “the mix” is the reference point users measure other features against.
Finamp's own store listing now reads: “Each item type now has a ‘Start Instant Mix’ option, even albums, playlists, artists, and genres.” The feature has outgrown what I shipped. Playlists and genres came later, from other contributors, on top of the API and audio-service plumbing from PR #246. That is exactly how open source is supposed to work.
What the Instant Mix actually does
Jellyfin's server can generate an “instant mix,” a queue of tracks similar to a seed item, but in 2022 nothing in the mobile client exposed it. The web client had it. The phone app didn't. So playing something in the spirit of an album you liked meant going back to a browser.
I wired the whole path, end to end:
- The API layer. Added the
/Items/{id}/InstantMixendpoints to Finamp's Chopper-generated Jellyfin client (JellyfinApi.dart,JellyfinApi.chopper.dart) and the typed wrappers around them (JellyfinApiData.dart). - The playback layer. Added mix-start methods to
AudioServiceHelper.dartso a mix could seed and take over the play queue the same way any other playback source does. - The user interface. Put a “Start Instant Mix” action everywhere it
makes sense: the song list tile, the artist list and the album grid
(
SongListTile.dart,AlbumItem.dart,AlbumItemListTile.dart,MusicScreen.dart), including a multi-select UI so you can seed a mix from several artists or albums at once.
It went out in three passes, each merged before the next one started: PR #246 laid the foundation and put the action on every song, PR #250 added multi-select on the artists tab, and PR #253 finished the job on the album grid. A month earlier, PR #232 brought sort-order parity with the web client and migrated the app's enums to Dart 2.17. Roughly 600 lines in total, all of it public. Read the diffs.