MusicMC

English | 简体中文

MusicMC is an open-source Spigot 1.21.11 plugin and GitHub automation stack for custom music discs. Players can submit a ZIP or a NetEase Cloud Music song ID, GitHub Actions validates and segments the audio, and the server distributes small resource bundles on demand.

What it does

• Runs on Spigot 1.21.11 with Java 21; it does not require Paper or a client mod.
• Publishes submissions automatically with no manual approval stage.
• Allows unlimited lifetime submissions while limiting each player to one active job.
• Groups up to 20 songs per rolling resource bundle and loads only bundles a player needs.
• Splits audio into roughly five-second segments so players entering the 25-block range can join at the next boundary.
• Keeps only catalog metadata on the Minecraft server. Audio goes directly from GitHub Releases or an S3-compatible public endpoint to each client, never through FRP.
• Supports local song disable/enable, uploader bans, song replacement, storage diagnostics, and an in-game song browser.
• Supports a Cookie-backed NetEase adapter inside GitHub Actions. The Cookie is optional and remains a repository secret.

Player commands

/music
/music upload <command name>
/music netease <NetEase song ID>
/music netease url <NetEase song URL>
/music search <query>
/music list [page]
/music status
/music cancel
/music pack
/getcd <command name>

See Player guide or 玩家指南. Administrators should also read Administrator guide.

Build

./mvnw --batch-mode clean verify

The shaded plugin is written to target/MusicMC-2.1.0.jar.

To build a JAR preconfigured for a particular deployment without changing tracked source files:

./scripts/build-plugin.ps1 `
  -Repository OWNER/MusicMC-Uploads `
  -PortalUrl https://owner.github.io/

Deploy

Run ./scripts/deploy.ps1 -Mode Automatic for guided one-click setup, or use manual mode to select every repository and URL. Start with Deployment or 部署指南. The source repository contains the plugin, portal, Worker, Actions processors, catalog schema, tests, and deployment scripts, but is never used as the operator's live service by default. No production URL, personal server, FRP tunnel, private key, Cookie, or access token is hard-coded.

Limits

• Without a client mod, a listener can join only at the next audio segment, not at an arbitrary sample position.
• NetEase access is unofficial and can fail because a Cookie expires, an account lacks playback access, or risk controls reject a GitHub-hosted runner.
• GitHub and object-storage quotas still apply to uploads and downloads.

License

MIT. See LICENSE and LICENSE.zh-CN.md.