Jusic Serve Houses: a multi-room listening server for self-hosters

A room, a queue, and a chat window

Jusic Serve Houses is the multi-room version of the earlier Jusic-serve project, and the split into three repositories is the first thing to understand. The backend is this repository, the front end is Jusic-ui, and the WeChat mini program is Jusic-mini.

The interaction model is a chat window with commands. An ordinary user sends a request with the point-song command and a keyword, starts a vote to switch the current track, sets a nickname with the set nickname command, and deletes a track by name.

The administrator commands are where the project puts its personality. An admin takes control of the site with the root password or the admin password command. From there they can pin a track to the top of the list, delete a track, blacklist a user and un-blacklist one, blacklist a track so it cannot be requested again, and un-blacklist it. There is a list of blacklisted music and a list of blacklisted users. And there are toggles for the things that would otherwise annoy a room: ban switching tracks, ban requesting songs, and a like mode that plays tracks in order of like count, with a command to leave it.

That is a fairly complete moderation toolkit for a shared room, and it is driven entirely by text commands in a chat rather than by an admin panel, which is the right design for something that runs on a phone in a WeChat mini program.

The project is GPL-3.0 licensed, the primary language is Java, the default branch is jusic_serve_houses, and the last push was on 2026-09-26. There is a live instance at music.alang.run, and the README notes that a WeChat mini program version of the app has been published to the store under the name given in the announcement.

Redis, a music API, and a Java service

The architecture has three moving parts and the README is clear about which is which.

Redis is the shared state. It is where the queues, the room state and the blacklists live, and the compose file runs it as a separate service with a data volume, with the timezone set to Asia/Shanghai.

The music API is a separate service, and this is the part that surprises newcomers. Jusic does not contain the music. It asks a Node.js music API service for song metadata and playback URLs, and there are separate projects for NetEase Cloud Music, for QQ Music, for Migu Music, and a fourth one that is described as introducing Kuwo and Xiami as fallbacks, searching them by artist and song name when the first three services have no result.

The Java service is the third piece. It is what this repository contains, and it is the component that talks to Redis and to the music API, and that serves the HTTP API which the front end and the mini program call.

The compose file expresses the dependency direction explicitly. The music API service is named jusicMusicApi and the backend service sets MusicApi to http://jusicMusicApi with a comment saying the value must match the container name of the music API service, which is the kind of note that exists because somebody got it wrong once. The backend also depends on both the Redis service and the music API service, and publishes port 8888, mapped from 8080 on the host in the shipped compose file.

There is a second, simpler option. A community member made a Docker image for the whole thing, and the README gives the one-liner:

The command is `docker run -d --name music -p 8888:8888 jonnyan404/jusic`.

That is the fastest way to see what the thing does, and it is worth doing before reading the parameter list.

Every knob is an environment variable with a default

The parameter list in the README is the real documentation for this project, and it reads like a config file.

The API authentication is a username and password, defaulting to admin and 123456, which is the first thing you must change. The Redis host defaults to redis, with a note that a Redis running outside Docker can be given as localhost. The music API host defaults to http://jusicMusicApi, or http://localhost for a local one. The music link expiry time defaults to 1200000 milliseconds, which is twenty minutes, and the retry count for a failed fetch defaults to 1.

The voting rate for switching tracks defaults to 0.3, which is the threshold of votes needed to skip. The NetEase hot songs playlist id defaults to 3778678.

Then there is the WeChat notification webhook, ServerJUrl, and the README is unusually blunt about it. The default value is the maintainer's own endpoint, and the instruction is that you must change it, otherwise when a user mentions the administrator the message goes to the maintainer instead of to you.

The limits are configurable too. IpHouse defaults to 3, the number of rooms a single IP address may create, and HouseSize defaults to 32, the maximum number of rooms the system may have at once.

The QQ Music settings are the fiddliest part. There is the account, Qquin, the QqMusicKey which you find in the QQ music cookie and which requires a membership, the QqMusicGuid defaulting to 114514, the playback link prefix defaulting to http://ws.stream.qqmusic.qq.com/, and a refresh interval for the cookie in milliseconds defaulting to 86000000, which is about a day.

The Dockerfile shows the same set expressed as ENV lines and then passed to the jar as system properties on the entry point, one -D flag per setting. That is the whole configuration model: no config file to edit, everything arrives as a property, which is what makes the Docker path the primary one.

Building from source with Maven

The manual build is a clone, a configuration edit, a package and a run.

   git clone https://github.com/JumpAlang/Jusic-Serve-Houses.git

Then you install Redis, and you install the music services, and the configuration step is to set up Redis and the music services in the application.yml under the resources directory of the source tree.

The build is Maven, and the jar is produced with:

   > mvn package

with a faster variant that skips the tests during packaging:

   > mvn package -Dmaven.test.skip

And the jar runs with:

   > java -jar jusic-serve.jar

The front end is a separate step, since it lives in the Jusic-ui repository on its own branch, and the README points there rather than bundling it.

The repository layout is a normal Java project with a few extras. There is a pom.xml, a src/ directory, an index.html at the top level, a Dockerfile, a docker-compose.yml, a start.sh and a shutdown.sh, a mvnw wrapper with mvnw.cmd, a music/ directory, a doc/ directory, and a default.txt. There is also a file whose name is a Chinese phrase about keeping a record of docker commands, which is a common way for maintainers to keep a personal command log in the repository.

The Dockerfile builds from java:8, exposes 8888, copies the built jar into /app and sets the environment variables and the -D properties on the entry point.

Where this project is the wrong choice

The first wrong case is anything that needs a supported service. The README itself says the servers are weak, often go down, and asks for sponsorship, with a link to a discount on a cloud ECS instance. That is an honest description of a hobby deployment, and a team depending on it for anything business critical is taking on a risk the author has already flagged.

The second is the security posture of the defaults. The API password defaults to 123456, the role root password is a fixed value in both the compose file and the Dockerfile, and the WeChat webhook is baked into the image pointing at the maintainer. Every one of those has to be changed, and the fact that they are defaults rather than requirements is a trap for someone deploying in a hurry.

The third is the music API dependency. Jusic does not host audio, and the third party services it calls are unofficial wrappers around commercial streaming services, one of which needs a personal account cookie with a membership. That is a dependency on services that can change or disappear, and it is outside the control of this repository.

The fourth is a shared music experience that needs more than a queue. There is no transcoding, no library management, no scrobbling, and no recommendation. The feature set is a request queue with voting and moderation, and it is a good fit for that and nothing more.

The alternative worth weighing is running one of the underlying music API services directly and using its own interface, if all you need is search and playback URLs. You lose the rooms, the voting and the blacklists, and you gain a dependency you were going to have anyway and one less service to keep alive. For a group that simply wants to queue songs together, the room server is the better answer, and for anything else the direct API is simpler.

Editorial conclusion

Adopt Jusic Serve Houses if you want a self-hosted room where a group queues songs together and votes on what plays next, since the multi-room design and the blacklists, pinning and like mode are all built in and the configuration is a set of environment variables you can read at a glance. Keep away if you need a maintained, hardened service, because the project is a hobby deployment with default credentials, a default administrator password and a note in the README that the servers are weak and often go down. Before you expose it, change every default listed in the parameter table, especially the API password and the role root password, and note that the last push was on 2026-09-26 with no tagged releases to pin.

Frequently asked questions

Official sources

1. Issues
2. JumpAlang/Jusic-Serve-Houses on GitHub
3. License: GPL-3.0
4. Project website
5. README