Getting Started · Default Plugins · Features · Platform Support · Development · Docs
Introduction
Mio Music is a local-first, cross-platform music player with plugin support. Play your local files, connect to a personal music server you already use, or add compatible plugins for other online sources.
- Local music: scan files and manage tags, covers, favorites and playlists. No online plugin setup is required.
- Personal libraries: built-in connectors for Songloft, Subsonic, Navidrome, Jellyfin, Emby and Plex let you search and play your server's music in one player.
- Listening experience: word-by-word and TTML lyrics, translations and romanization, animated backgrounds, an equalizer, gapless playback and crossfade.
- Multiple clients: desktop apps for macOS, Windows and Linux; a Flutter client for Android phones, tablets and TVs, plus iPhone and iPad. See Platform Support for each platform's verification status.
Mio Music is a player, not a music content service. It does not include a public music catalog or service accounts. Local playback needs no server. Built-in connectors require your server address and the appropriate account or access token; available content and permissions depend on the server and plugin.
Getting Started
Check Platform Support and Releases before choosing a package and version. To try the current source, follow Development.
| What you want to do | Where to start |
|---|
| Play local music | Open the local music page and import or scan your music files; no online plugins are needed |
| Connect a personal music server | Configure the matching built-in plugin under Settings → Plugins → Music list plugins |
| Add other online sources | Install a compatible music-list plugin; if it does not supply playback URLs, pair it with a source plugin that supports the same source |
See the user guide for detailed steps.
Default Plugins
These 6 music-list plugins ship with the app; no separate script download is needed. All provide song search, album and playlist browsing, discovery, and playback and download URL resolution. Extra features such as artist pages and lyrics vary by plugin.
| Built-in plugin | Service and extra features | Connection settings |
|---|
| Songloft | Songloft personal music server; artists, genres and lyrics | Server URL, username and password |
| Subsonic | Subsonic API-compatible music servers | Server URL, username and password |
| Navidrome | Navidrome; adds artist pages and lyrics beyond the generic Subsonic plugin | Server URL, username and password |
| Jellyfin | Jellyfin music library; artist pages and lyrics | Server URL and either a username login or access key; password as required by the account |
| Emby | Emby music library; artist pages | Server URL and either a username login or access key; password as required by the account |
| Plex | Plex Media Server music library; artist pages | Server URL and X-Plex-Token; optional library name, otherwise the first music library is used |
Set up a built-in plugin
- Open Settings → Plugins → Music list plugins, find your server's plugin and choose Configure.
- Enter the server URL and authentication details from the table. For a non-loopback
http:// server, also enable Allow HTTP (unencrypted); loopback addresses such as localhost do not need this option.
- Use Test connection to check the current form, then save it and make sure the plugin is enabled.
- Select the source on the search or discovery page to browse your server's library. Built-in plugins supply playback and download URLs by default, so no additional source plugin is needed.
At startup, the app installs any missing built-in plugins and upgrades older copies when it ships a newer version, preserving their settings and enabled state. Built-in plugins can be disabled but not uninstalled. Newly installed plugins that have not been configured do not offer selectable sources.
Features also depend on server versions and account permissions. Scripts, configuration details and server verification coverage are documented in mio-music-plugins.
Other supported plugins
| Plugin type | What it does | How it is supported |
|---|
| Music-list plugin | Supplies search, playlists, albums and discovery, and may resolve its own playback and download URLs | In addition to the built-in plugins, compatible scripts can be installed from a local file or URL; multiple plugins can be enabled together |
| Source plugin | Resolves a playback URL from track information; does not supply search or playlists | Supports LanYin scripts; LuoXue / LX scripts are converted on installation. Explicitly select the plugin to use |
Plugins run in a resource-limited QuickJS sandbox. To write your own connector, see the plugin developer guide.
Third-party plugins (community recommendation)
Unofficial. The plugins below are developed and maintained by an independent third party, not by the Mio Music project. They are listed for reference only. Mio Music is not affiliated with their author or repository, and does not bundle, host, review or endorse the scripts, nor guarantee that they are available, correct, secure or lawful in your region. Read the code before installing and use them at your own risk.
- Source: niamadoutraore89/mio-music-plugins (AGPL-3.0-only).
- Install: open Settings → Plugins → Music list plugins → Install list plugin, paste the URL from the table and confirm. The URLs always point to the latest version on that repository's
main branch; to install offline, download the file and choose it as a local file.
- Limits: these plugins only provide listing and search. They do not return playback or download URLs, so the tracks they list need a source plugin that supports the same source.
- Song recognition: the app has no recognition service of its own. The recognition entry appears only while an enabled plugin declares the
recognize capability (list plugin 6 does); without one it is hidden.
| Plugin | ID | Capabilities | Install URL |
|---|
| List plugin 1 | bd | Playlist detail and covers (search currently returns an empty page) | https://gitea.com/niamadoutraore89/mio-music-plugins/raw/branch/main/bd.list.js |
| List plugin 2 | kg | Search, playlists, albums, discovery, charts, artists, lyrics, comments, covers | https://gitea.com/niamadoutraore89/mio-music-plugins/raw/branch/main/kg.list.js |
| List plugin 3 | kw | Search, playlists, discovery, charts, artists, lyrics, comments, covers | https://gitea.com/niamadoutraore89/mio-music-plugins/raw/branch/main/kw.list.js |
| List plugin 4 | mg | Search, playlists, discovery, charts, artists, lyrics, comments, covers | https://gitea.com/niamadoutraore89/mio-music-plugins/raw/branch/main/mg.list.js |
| List plugin 5 | tx | Search, playlists, albums, discovery, charts, artists, lyrics, comments, covers | https://gitea.com/niamadoutraore89/mio-music-plugins/raw/branch/main/tx.list.js |
| List plugin 6 | wy | Search, playlists, albums, discovery, charts, artists, lyrics, comments, covers, song recognition | https://gitea.com/niamadoutraore89/mio-music-plugins/raw/branch/main/wy.list.js |
These services are separate products with their own terms and trademarks. You are responsible for having the right to access, play and download the content, and for following the laws of your region and each service's terms. Questions and issues about these plugins belong in their own repository, not in this project's tracker.
Features
Music Playback
- Native audio engine on Rodio, cpal and Symphonia for local and online tracks
- Next-track prefetch, gapless playback with configurable crossfade; online tracks decode while downloading
- 10-band equalizer with presets and AutoEq import, plus effects and stereo balance
- Real-time FFT spectrum
- System media keys, tray and global hotkeys on the desktop; lock-screen and notification controls on mobile
Lyrics
- Word-by-word and TTML lyrics rendered in the Apple Music style (AMLL)
- Translation, romanization, background and duet vocals
- Desktop lyrics window on macOS; custom lyric font
Interface
- Dynamic theme from the album cover, with brand and error colors kept at 4.5:1 contrast so buttons and text stay readable
- Audio-reactive animated background
- Light and dark modes; Chinese and English
Library & Data
- Local library scanning, tags and covers, tag editing, favorites and playlists
- Downloads with pause/resume, retry, speed display and tag writing
- S3-compatible backup and restore (AES-GCM encrypted), partial import of legacy app data
- DLNA casting, song recognition (offered only while a plugin that supports it is installed), signed auto-update
- Local first: library and settings live in local SQLite; no cloud service is required
Platform Support
| Platform | Package | Status |
|---|
| macOS (Apple Silicon) | .dmg, updater .app.tar.gz | Reference platform. Playback, lyrics, downloads, backup and the main pages verified in the native app |
| macOS (Intel x86_64) | .dmg, updater .app.tar.gz | Separate native build and updater package configured; native runtime verification is pending |
| Windows x64 | NSIS -setup.exe | Built, type-checked and unit-tested in CI; not yet run on a device |
| Linux x86_64 | .AppImage, .deb | Built, type-checked and unit-tested in CI (Ubuntu 24.04, glibc 2.39+); not yet run on a device |
| Android phone / tablet / TV (arm64-v8a, armeabi-v7a) | .apk | Acceptance runs on API 36 phone, tablet and TV emulators; physical devices and the armv7 runtime are pending |
| Android x86_64 | .apk | Local Release APK build, signature and native-library architecture verified; x86_64 runtime verification is pending |
| iPhone / iPad | unsigned .ipa | Runs in the iOS simulator; code signing and physical devices are pending |
| HarmonyOS | — | Experimental, outside main: an unsigned debug .hap builds; not yet run on a device |
macOS packages are built separately for Apple Silicon (aarch64) and Intel (x86_64); choose the package matching your Mac. Android APKs are split into arm64-v8a, armeabi-v7a and x86_64. macOS packages are ad-hoc signed and not notarized.
Releases
Builds are published on GitHub Releases by the Build workflow: whenever the version in Cargo.toml has no v<version> tag, it builds every platform, uploads the packages and latest.json, and publishes the release.
- Current state: no release of this rewrite is published yet. GitHub Releases still lists the
v0.3.x releases of the previous Tauri app, which its users keep updating from.
- Update notes: every release carries the changes since the previous one, generated from commit messages. Both apps show them in their update dialog.
- Updates: the desktop updater reads
latest.json and verifies Ed25519 signatures; the format matches the Tauri app, so its installs update in place.
The release workflow is .github/workflows/build.yml.
Tech Stack
This repository is the native rewrite of the Tauri-based Mio Music, itself rebuilt from CeruMusic. The desktop app uses Rust and GPUI Kit, while the Flutter client shares its Rust core (mio-core). The rewrite follows the original features, layouts and data formats; the AI assistant is out of scope.
| Layer | Technology |
|---|
| Desktop UI | GPUI Kit 0.7.2 (gpui-fast) |
| Mobile UI | Flutter + flutter_rust_bridge 2.13 |
| Language | Rust (edition 2024), Dart |
| Audio Engine | Rodio + cpal + Symphonia |
| Audio Processing | rustfft (spectrum), equalizer and effects in mio-core |
| Plugin Runtime | QuickJS (rquickjs), sandboxed |
| Database | SQLite (rusqlite) |
| UI Tokens & Icons | TDesign |
| CI | GitHub Actions |
Development
Prerequisites
Install & Run
The built-in plugins are a Git submodule (mio-music-plugins), so clone with submodules:
git clone --recurse-submodules https://github.com/Mio888888/Mio-Music.git
cd Mio-Music
# already cloned? git submodule update --init
# Run the desktop app
cargo run --locked -p mio-app
# Build a macOS development bundle (target/debug/Mio Music GPUI.app)
sh tools/bundle-macos.sh
Checks
cargo fmt --all -- --check
cargo test --workspace --locked
cargo check --workspace --locked
| What | Where | When |
|---|
cargo fmt --check, cargo check, cargo test for the whole workspace | macOS 15 (Apple Silicon and Intel), Windows, Ubuntu 24.04 (Desktop checks) | Every push to main |
| Release builds of all five platforms | Build workflow | When the version has no tag yet, or on demand with build_only |
| Interactive acceptance | macOS app; Android emulators; iOS simulator | Manually, during development |
Mobile acceptance evidence is described in apps/mobile/README.md. Real-device checks are explicit cases that the default offline tests skip.
Data Locations
| Platform | Directory |
|---|
| macOS | ~/Library/Application Support/Mio Music GPUI |
| Windows | %APPDATA%/Mio Music GPUI |
| Linux | $XDG_CONFIG_HOME/mio-music-gpui (default ~/.config/mio-music-gpui) |
Set MIO_GPUI_DATA_DIR to use a separate directory for testing. Data from the Tauri app is not read by default; import it from Settings → Storage → Legacy app data.
Writing Plugins
The plugin developer guide covers both plugin types, the data structures, the sandboxed runtime API and publishing; the scripts in mio-music-plugins are complete working examples. tools/golden/subsonic_fixture.py is a loopback-only Subsonic server with synthetic data for trying plugins without a real server.
Project Structure
├── crates/
│ ├── mio-app/ # Desktop app: GPUI interface, tray, hotkeys, media keys, desktop lyrics, DLNA, updater
│ ├── mio-core/ # Shared core: playback and effects, library (SQLite), downloads, backup, lyrics, themes, plugins
│ ├── mio-music-sdk/ # Music-list contract: provider trait, capabilities, data types, lyric/comment/cover decoding
│ ├── mio-plugin/ # Plugin host: sandboxed QuickJS runtime, list-plugin loader, LuoXue converter
│ ├── mio-tokens/ # UI tokens (light and dark palettes)
│ └── mio-mobile-bridge/ # flutter_rust_bridge API for the mobile app
├── apps/mobile/ # Flutter app for Android and iOS
├── plugins/ # Submodule with the built-in list plugins
├── tools/ # Packaging, CI helpers, release notes, golden-image tooling, Subsonic fixture
└── website/ # Static site and docs (GitHub Pages)
Contributing
Contributions are welcome. Please read CONTRIBUTING.md and the Code of Conduct first; the pull request and issue templates list what to include. Report security problems privately, as described in SECURITY.md.
Credits
Support the Current Author
Ongoing maintenance, cross-platform adaptation and issue fixes for Mio Music are contributed by the current project author. If this project helps you, you can support future development with the appreciation code below.
All donations are voluntary and go directly toward the current author's continued development and maintenance.
Disclaimer
Mio Music provides playback, library management and a plugin runtime; it does not provide or host a public music catalog. Online playback and downloads access third-party services or personal servers through user-configured plugins. You are responsible for having permission to access, play and download the content, following local laws and service terms, and respecting third-party rights.
License
Mio Music is free software, licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-only). You may use, study, change and share it, including commercially, as long as works derived from it are released under the same license with their source code, which also applies when users interact with them over a network.
It is derived from CeruMusic (Copyright © 2026 时迁酱, AGPL-3.0-only) through the Tauri-based Mio Music. Third-party code keeps its own license: the libraries vendored under vendor/ and apps/mobile/vendor/ are Apache-2.0 or MIT, and every other dependency is resolved in Cargo.lock and apps/mobile/pubspec.lock. Contributions are accepted under the same license; see CONTRIBUTING.md.
