Mio Music

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

1. Open Settings → Plugins → Music list plugins, find your server's plugin and choose Configure.
2. 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.
3. Use Test connection to check the current form, then save it and make sure the plugin is enabled.
4. 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

• Rust stable, 1.85 or newer
• Git, and the native build dependencies from the GPUI Kit docs (the exact packages CI installs are in .github/workflows/check.yml)
• For mobile: Flutter, Android SDK/NDK or Xcode — see apps/mobile/README.md

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

• CeruMusic — Original project by ShiQianJiang
• Mio Music (Tauri) — The app this project re-implements
• GPUI Kit — Native desktop UI framework
• Flutter and flutter_rust_bridge — Mobile app and its Rust bridge
• TDesign — Design tokens and icons
• Apple Music-like Lyrics — Lyrics and background style
• AutoEq — Equalizer preset data

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.