# QM-Music: a self-hosted music server that speaks the Subsonic protocol > QM-Music is a Java music server built on the Subsonic API, so existing clients such as feishin, Amperfy, substreamer and music-assistant can connect to it unchanged, and it ships as a single Docker container with optional ffmpeg transcoding and metadata enrichment from Spotify, Last.fm and Kugou. It is aimed at a personal library rather than a shared catalogue. **chenqimiao/qm-music** — 🎧☁️ Your Private Music Service - Repository: https://github.com/chenqimiao/qm-music - Stars: 586 · Forks: 41 - Language: Java - License: Apache-2.0 - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/chenqimiao-qm-music ## The protocol choice is what makes the client list possible QM-Music is a lightweight private cloud music server built on the Subsonic API, presented as a light and high performance solution designed for music enthusiasts, with one-click Docker deployment and compatibility with the Subsonic ecosystem clients. That protocol decision is the whole architectural story. Because the server implements Subsonic rather than inventing an API, every client that already speaks Subsonic works with it unchanged. The readme names them, and the client list is long enough to be the argument for the project: a Chinese streaming app, feishin, Amperfy, substreamer, music-assistant and airsonic are all listed as supported, and the readme is explicit that the library is compatible with any client that supports the Subsonic API. The practical effect is that you are not choosing a client, you are choosing a server, and the client stays whatever you already use. That is a very different decision from adopting a service that ships its own app. The other half of the positioning is self-hosting. Private deployment means complete control of your music data, and the feature list makes the contrast with hosted services explicit: a containerised quick start with no environment dependencies, roughly 150 MB of memory, and no third party holding your library. The project is written in Java, licensed under Apache 2.0, and the recent releases are v2.5.0 from 2026-09-10, v2.4.0 from 2026-08-28 and v2.3.1 from 2026-07-26. The image is published on Docker Hub as qmmusic/qm-music, and the repository has a Chinese readme with an English translation alongside it. ## One container, three volumes and a list of environment variables The deployment is a single docker run, and the shape of it tells you how the server is organised. ```bash docker run -d \ --name qm-music \ -p 6688:6688 \ -v [host_music_file_path]:/data/qm-music/music_dir \ -v [host_path_db_path]:/data/qm-music/db \ -v [host_path_cache_path]:/data/qm-music/cache \ -e QM_FFMPEG_ENABLE=true \ -e TZ=Asia/Shanghai \ -e QM_SPOTIFY_ENABLE=false \ -e QM_SPOTIFY_CLIENT_ID=[QM_SPOTIFY_CLIENT_ID] \ -e QM_SPOTIFY_CLIENT_SECRET=[QM_SPOTIFY_CLIENT_SECRET] \ -e QM_LASTFM_ENABLE=false \ -e QM_LASTFM_API_KEY=[QM_LASTFM_API_KEY] \ -e QM_REFRESH_AUTO=true \ --restart unless-stopped \ qmmusic/qm-music:latest ``` Three volumes, three distinct jobs. The music directory is where your files live. The db directory is for the database and metadata, and the readme asks you not to put anything else in it. The cache directory is for cached files. The environment variables are grouped by what they turn on. QM_FFMPEG_ENABLE turns on the smart audio transcoding, which is off by default and is recommended for users on mobile data, and it switches between the libmp3lame and acc encoders according to network conditions to save bandwidth. TZ sets the timezone, which the readme asks you to set for your region. The Spotify and Last.fm blocks are optional and exist purely to fetch extra metadata, with links to the key request pages for both services. QM_REFRESH_AUTO is the scheduled library refresh and is on by default. Two more appear in the configuration section and are also on by default: QM_CLEAN_PLAY_HISTORY_AUTO, which periodically clears play history, and QM_SAVE_PLAY_HISTORY_MONTH, which is how many months of play history to keep, 24 by default. A compose file is offered as well, with the same variables in a service block and the image, ports, volumes and restart policy declared the usual way. ## First run, and the default credentials The initialisation steps are short and one of them matters for security. You open the admin interface at the server address on port 6688, and you log in with the default credentials, which the readme gives as admin for both the username and the password. The third step is to change that password immediately on the home page, and it is listed as a distinct step rather than a note, which is a reasonable thing for a project to insist on. Then you go to the library management page and press the refresh library button. The readme tells you to wait for the track metadata parsing to finish, and that you can watch progress in the logs. That is the one operation in the setup that takes time proportional to the size of your collection, and it is the step that will be slow if you have tens of thousands of files with missing tags. Finally you point a client at it. The readme lists the parameters as the server address in the form of the server IP on port 6688, with the account and password being the administrator account you changed rather than the default. The features that sit under that flow are what the project calls the user experience and the music management. On the user side there is a multi-user system with independent accounts and permission management, custom playlists, a favourites and likes feature that syncs in real time, and synchronised lyrics that match local and online lyric sources. On the music side there is automated library handling that watches the music directory for changes and refreshes metadata on a timer, ID3 tag and album parsing, browsing by album, artist and genre, and cloud-side play statistics that record history and preferences. The discovery section adds global search across songs, albums and artists, style-based recommendations of similar songs and artists, and filtering by genre. ## Metadata enrichment and Chinese library handling Two things distinguish this from a plain Subsonic-compatible server. The first is the metadata enrichment. The ecosystem section lists Spotify, Last.fm and Kugou as integrations, and the readme explains the model: the Spotify and Last.fm integrations are optional and, when enabled, give you more metadata support, with the client id and secret, and the API key respectively, obtained from the relevant developer pages. The point is that a local library often has incomplete tags, and a metadata service fills in the missing fields, and the choice of three providers including a Chinese one reflects who the project is for. The second is the Chinese library handling, which is called out as a core feature: support for searching across traditional and simplified Chinese characters, with Chinese sorting and retrieval optimisation. That is a specific and non-trivial piece of work, because a library with Chinese titles and artists has to match them against a metadata source that stores them in a different script, and the sorting has to handle the collation rules of the script rather than falling back on byte order. The feature list also covers the formats, with MP3, FLAC, AAC and WAV among the mainstream ones, and the transcoding described again in the feature overview as dynamically switching between the libmp3lame and acc encodings on demand to save bandwidth. The development roadmap at the bottom of the readme is short and worth reading for what it says about the project's direction. Support for an external database is not done, which confirms the embedded database in the db volume is the intended design for now. Cross-platform client development and a stronger web player are not done. And raising unit test coverage is listed under quality assurance, which is an honest admission of where the project stands on that front. ## Repository layout, licence and the disclaimer A few practical things sit outside the feature list and are worth knowing before you deploy it. The repository is a Java project with a parent directory, qm-music-parent, holding the application, alongside a docker directory, a docs directory, and the two readmes. The structure suggests a multi-module build, with the server in one module and the Docker packaging kept separate from the application code. The licence is Apache 2.0, and the readme spells out the three obligations in a form that is worth reading rather than assuming. Secondary development must retain the original copyright notice, modified derivative versions must carry a clear statement of the changes, and no warranty of any kind is provided, express or implied. Then there is a disclaimer section, and it is more restrictive than a typical Apache 2.0 open source project. The readme states the project is for learning and research purposes only and must not be used for any commercial activity, that users should comply with the laws of their region, and that the project and the author bear no responsibility for consequences of unlawful use. It also warns that the project may contain unknown defects and risks including device damage and account bans, and that the author does not guarantee the accuracy, completeness, timeliness or reliability of the project, nor bears responsibility for any loss or damage arising from its use. Using the project is stated to mean you have read and accepted the whole disclaimer. That is unusual for a project published under a permissive licence with a Docker image, a public client list and a recent release cadence, and it is a genuine consideration if you are evaluating it for anything beyond a personal library. The readme closes with a sponsorship section offering a star or a tip, with QR codes for WeChat and Alipay payments and a table of past supporters. ## Conclusion Adopt QM-Music if you already keep a local music library and want to serve it to your own apps through the Subsonic protocol without a hosted service in the middle. Do not adopt it as a multi-user streaming platform, since the positioning is a private service for music enthusiasts, and note that the readme's own disclaimer restricts it to study and research use. Before you commit, change the default admin credentials on the first run, decide whether to enable the Spotify and Last.fm metadata lookups, and check that the container image on Docker Hub matches the version you want to pin. ## FAQ ### What is QM-Music? It is a lightweight private cloud music server built on the Subsonic API, designed as a light and high performance solution for music enthusiasts, with one-click Docker deployment and compatibility with the Subsonic ecosystem clients. The server is written in Java and licensed under Apache 2.0. ### Which clients can connect to QM-Music? Any client that supports the Subsonic API. The readme names a Chinese streaming app, feishin, Amperfy, substreamer, music-assistant and airsonic among them, and states that the library is compatible with any client that supports the Subsonic API, with the connection parameters being the server address on port 6688 and your administrator credentials. ### What are the three volumes QM-Music needs? The music directory holds your music files, the db directory holds the database and metadata and the readme asks that you not put anything else in it, and the cache directory holds cached files such as transcoded output. The container exposes port 6688 and restarts unless stopped. ### What do the QM-Music environment variables control? QM_FFMPEG_ENABLE turns on smart transcoding that switches between libmp3lame and acc according to network conditions, TZ sets the timezone, the Spotify and Last.fm variables are optional and enable extra metadata, QM_REFRESH_AUTO controls the scheduled library refresh, QM_CLEAN_PLAY_HISTORY_AUTO controls periodic clearing of play history, and QM_SAVE_PLAY_HISTORY_MONTH sets how many months of history to keep, 24 by default. ### Is there anything specific about Chinese music libraries in QM-Music? Yes, it is listed as a core feature: support for searching across traditional and simplified Chinese characters, with Chinese sorting and retrieval optimisation. The metadata integrations include Kugou alongside Spotify and Last.fm. ## Sources - [chenqimiao/qm-music on GitHub](https://github.com/chenqimiao/qm-music) - [Issues](https://github.com/chenqimiao/qm-music/issues) - [License: Apache-2.0](https://github.com/chenqimiao/qm-music/blob/main/LICENSE) - [README](https://github.com/chenqimiao/qm-music/blob/main/README.md) - [Releases](https://github.com/chenqimiao/qm-music/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/chenqimiao-qm-music