Harmonoid: a Flutter music player built on mpv and FFmpeg for five platforms

What Harmonoid solves for people with local music files

Streaming services solved discovery and abandoned the file. Anyone who kept a ripped CD collection, bought Bandcamp downloads or maintains a folder of lossless albums ends up with a library that no mainstream player handles well. The README states the problem directly: the author found that other players either look poor, refuse certain audio formats, read tags incorrectly, or are built on Electron. Harmonoid is the answer to that specific complaint.

The target user is someone with a local library and more than one device. The README lists Windows, GNU/Linux, macOS, Android and iOS as supported platforms, and the release notes for v0.3.32 are titled "Spreading Everywhere [macOS, Windows, Linux, Android, iOS]", so the same application is meant to run everywhere the user listens. The feature list is aimed at library owners rather than casual listeners: a tag editor, fallback cover support for files like cover.jpg and Folder.jpg, multiple artist and genre support, ReplayGain, gapless playback and a lyrics view that reads LRC files, embedded tags and online sources. None of that matters if you stream. All of it matters if you own the files.

The stated resource footprint is modest: the README claims an installer of about 35 MB and RAM usage of about 150 MB. Treat those numbers as the project's own claims rather than measured results, but they explain the design goal. A large Electron player with a bundled browser engine cannot hit that, which is why the author calls out electron.js by name.

The mpv and FFmpeg backend is the actual architecture decision

Harmonoid is a Dart and Flutter application. The repository's top level shows the expected Flutter layout: lib/ for Dart code, plus android/, ios/, linux/, macos/ and windows/ platform folders, a pubspec.yaml, and an external/ directory that pairs with .gitmodules. The topics list confirms the stack: flutter, libmpv, mpv, ffmpeg and taglib.

That combination is the interesting part. Playback is delegated to mpv, which itself uses FFmpeg's demuxers and decoders. The README says this gives support for all file formats, and it is the reason a player of this size can open formats a hand-rolled decoder would not. Tag reading is a separate concern, handled by TagLib, and the README describes the tag reader as performant. The Flutter layer draws the interface and talks to the native side.

The practical consequence is that audio quality and format support are inherited from mpv, not invented here. Features like speed adjustment, pitch adjustment, volume boost, crossfade and exclusive audio map onto capabilities mpv already exposes, and the README lists them as features rather than as custom DSP work. If mpv handles a codec on your platform, Harmonoid should too. If it does not, Harmonoid will not either.

Platform integration is also native per OS rather than uniform. The README lists System Media Transport Controls and a taskbar thumbnail toolbar for Windows, D-Bus MPRIS controls for GNU/Linux, MPNowPlayingInfoCenter for macOS and iOS, and Notification.MediaStyle for Android. Those are four separate integrations. It is more work than a single abstraction, and it is why the media keys and lock screen controls behave like the operating system expects.

Installing Harmonoid and playing your first album

The repository does not document a build-from-source path in its README. The README links to the project website, and the Download link points at harmonoid.com/downloads, so that is where a user is directed to get a build. The repository also contains Inno Setup scripts at the top level, Harmonoid_InnoSetup_x64.iss and Harmonoid_InnoSetup_arm64.iss, which are the packaging definitions for the Windows installers, and the release notes name macOS, Windows, Linux, Android and iOS as covered platforms.

Once a build is installed, the first task is pointing it at your files. Add a folder to the library from the settings or library screen, and let the tag reader index it. The README states that fallback cover support exists for files such as cover.jpg and Folder.jpg, so albums without embedded artwork still show a cover if one of those files sits in the folder.

Lyrics come from three places, and the README names them: LRC files, embedded tags, and online sources. Placing a .lrc file beside a track is the offline route and needs no network access. The README documents no command-line interface and no install command, so the only concrete instruction it gives is to get the build from harmonoid.com/downloads. The folder layout those features expect is the one the README describes: an album directory holding the audio files, an optional sidecar .lrc lyric file, and a fallback cover image such as cover.jpg or Folder.jpg.

The README also notes the application is portable, which matters on Windows where a portable build avoids an installer. For every platform, harmonoid.com/downloads is the path the project itself points to.

Where Harmonoid is the wrong tool

The licence is the first hard boundary. The README states that the project is governed by the PolyForm Strict License 1.0.0, and the repository's licence field reads NOASSERTION, which is GitHub's way of saying the licence could not be matched to a known template. PolyForm Strict is not an OSI-approved open source licence. It is a source-available licence with restrictions, and anyone planning to fork, redistribute or ship a modified build needs to read LICENSE in the repository rather than assume open source terms apply. This is a distribution question, not a legal opinion, and the file is the authority.

Harmonoid is a client, not a service. There is no server component in the repository layout, no sync engine, and no documented API for controlling playback from outside the application. If you want your library available on a phone and a laptop with play counts and playlists kept in step, the README does not describe a mechanism for that. Last.fm integration exists, and Discord RPC exists, but those are scrobbling and presence, not library sync.

The feature set is also deliberately closed. There is no plugin system in the README's feature list, so a format or behaviour the application does not implement cannot be added without patching the source. Compare that with a player that exposes a scripting layer, and the trade-off is clear: Harmonoid trades extensibility for a consistent interface, which is exactly what the README's "Why" section argues for.

Finally, the README does not document rollback, a downgrade path, or what happens to the library database when you move between release versions. If you depend on a specific version, verify that before upgrading.

Harmonoid against a plugin-driven player such as foobar2000

The clearest contrast is with foobar2000, a long-standing desktop player whose identity is its component architecture. foobar2000 is Windows-first, extensible through third-party components, and its interface is something you assemble. Harmonoid goes the other direction. The README's "Why" section says the project "very strictly implements Material Design to be a consistent, cohesive & modern music player for all platforms", and complains explicitly about inconsistent paddings and alignments. That is a statement of intent: the interface is designed by the maintainer, not configured by the user.

The second difference is reach. foobar2000 is a desktop application. Harmonoid ships for Windows, GNU/Linux, macOS, Android and iOS from the same codebase, with per-platform media control integrations named in the README. If your listening happens on a phone as often as a desktop, that coverage is the reason to pick Harmonoid.

The third difference is the audio engine. foobar2000's format support comes from its own decoders and components. Harmonoid delegates to mpv and FFmpeg, so its format coverage tracks what those projects support on each platform. Neither approach is universally better. Delegating means less code to maintain and broad format support; it also means you inherit mpv's behaviour, including its configuration surface and its platform quirks.

Maintenance, releases and what upgrades cost you

The repository is not archived. Its most recent push was on 2026-09-02, and the latest release in the list is v0.3.32, published on 2026-07-29 under the title "Spreading Everywhere". Before that, v0.3.22 and v0.3.21 were both published in January 2026 and both labelled "Bug-Bash", which suggests a pattern of larger feature releases followed by dedicated bug-fix rounds. That is a reasonable cadence for a project of this shape, and it also means bug fixes arrive in batches rather than continuously.

Upgrade cost is mostly the usual desktop application risk. There is no documented migration procedure for the library database between versions, and no documented rollback. The README does not describe a data format, a sync mechanism or an export path, so the library index should be treated as something the application owns. Keeping your audio files in a stable folder structure with sidecar covers and .lrc files, as the README's fallback cover and lyrics features expect, means the files survive whatever the application does with its index.

On licence, the practical question for a company is whether the PolyForm Strict License 1.0.0 permits the intended use. Internal use of an unmodified build is a different question from bundling Harmonoid into a product or redistributing a patched version. The LICENSE file in the repository is the document to read, and the README points to it explicitly.

Editorial conclusion

Adopt Harmonoid if you want one library interface across desktop and mobile, you keep your files locally, and you are comfortable with a PolyForm Strict 1.0.0 licence that is not an OSI open source licence. Skip it if you need a plugin ecosystem, a server component, or the freedom to redistribute a modified build. Before installing, check harmonoid.com/downloads for a build matching your platform and architecture, confirm the latest release tag, and read LICENSE in the repository so you know what the licence permits you to do with the code.

Frequently asked questions

Official sources

1. harmonoid/harmonoid on GitHub
2. Issues
3. Project website
4. README
5. Releases