URL Custom Discs

THE INSTALLATION INSTRUCTIONS ARE AT THE BOTTOM OF THE PAGE AND TAKE 5 MINUTES.

About

This plugin, along with a server resource pack, allows you to create and play custom music discs from YouTube URLs or MP3 files on your Minecraft server, with real-time updates for players.

Once installed, everything is done in-game, and there's no need to manually edit the resource pack files to add or remove custom discs.

The plugin supports Minecraft's spatial audio for music, but you can also play it in stereo.

Additionally, vanilla commands such as /playsound and /stopsound work with the custom music, so you do not need to use a disc in a jukebox.

Usage

Create a custom disc
1. Use the "create" command and paste your URL	3. All logged-in players receive the updated server resource pack containing the created custom disc
2. Wait for the track to be downloaded, converted, and added to the server resource pack	4. The custom disc is given to you, enjoy the music!

Commands Overview

Display the list of commands:
/customdisc help

Create a custom music disc from a YouTube URL or local MP3 file:
/customdisc create <URL OR audio_name.mp3> <disc_name> <mono/stereo>

• mono: enables spatial audio (as when played in a jukebox)
• stereo: plays the audio in the traditional way

Instructions for local MP3 files (admin-only):

• Place your MP3 file inside the audio_to_send folder in the plugin directory.
• Rename the MP3 file to a simple name with no spaces and no special characters.
• Run the create command with the audio_name.mp3.
  • Don't forget to include the .mp3 extension in the audio_name.mp3 field.

Give yourself a custom music disc:
/customdisc give <disc_name>

Show the list of custom music discs (click a disc name to autofill the give command):
/customdisc list

Delete a custom music disc:
/customdisc delete <disc_name>

Show details of the custom music disc you're holding (useful for debugging):
/customdisc info

Update Deno and yt-dlp dependencies:
/customdisc updatedep

Vanilla command to play a custom track (can be used with coordinates):
/playsound minecraft:customdisc.<disc_name> ambient @a ~ ~ ~ 1 1

Vanilla command to stop a custom track:
/stopsound @a * minecraft:customdisc.<disc_name>

Usage Modes

The plugin offers three modes of use, depending on your setup and preferences:

• API Mode (default):
  Uses a dedicated remote API to manage custom discs, the resource pack, and dependencies. Ideal for quick and easy setup, but with some limitations on the resource pack and audio files.
• Self-Hosted Mode:
  For advanced users who prefer to host and manage everything themselves. You can bypass the API and configure the plugin manually using your own setup and HTTP server.
• Edit-Only Mode:
  Allows you to update the resource pack locally and duplicate it to a custom path with a custom name. Useful if you already host another resource pack and want to merge it with the URLCustomDiscsPack.zip.

API Mode Resource Pack Limitations

To minimize storage space and ensure fast downloads, the resource pack has the following limitations:

• Up to 10 custom discs can be included in the resource pack at the same time.
• Each custom disc is limited to a maximum duration of 5 minutes.
• The resource pack size is limited to 80 MB (more than enough).
• If no activity (adding or deleting a custom disc) occurs for 3 months, the token and resource pack will be automatically deleted to free up space.

Self-Hosted Mode Requirements

You must provide a personal HTTP server to host the resource pack. Depending on whether your Minecraft server and HTTP server are on the same machine or on separate machines, the HTTP server must support:

• Local access: The plugin can update the resource pack via an absolute path.
• Online access: The plugin can download and upload the resource pack using HTTP requests.
• Player access: Players must be able to download the resource pack and receive real-time updates for custom music discs.

Documentation

This Modrinth page focuses on the default API Mode, which is the recommended setup for most users.
You can also find this documentation on the URLCustomDiscs GitHub repository.

If you want to use the Self-Hosted Mode or the Edit-Only Mode instead, please refer to the dedicated documentation from the URLCustomDiscs GitHub repository: Self-Hosted and Edit-Only Modes documentation

For more details, you may explore the API documentation, source code and architecture in the URLCustomDiscsAPI GitHub repository.

Audio Download Options

Warning: YouTube may block my API server in the future (never happened). Please notify me via Discord if this occurs, so I can resolve it.

In the meantime, you have two alternative options:

• Use the auto-installed yt-dlp dependency (Minecraft server-side download)
  The plugin uses the yt-dlp dependency to download the audio from the YouTube URL into the plugin folder and then send it to the API.

  This method is unlikely to work on shared Minecraft hosting providers, such as Shockbyte, as they often do not allow execution of yt-dlp, or the IP ranges of those servers are likely already banned by YouTube.

• Manually download the MP3 file (admin-only, 100% reliable)
  If you don't mind downloading the audio as an MP3 file, use a website like noTube to download it manually. Then, place the MP3 file directly into the audio_to_send folder inside the URLCustomDiscs plugin directory.
  After that, use the appropriate command to create a custom disc with this MP3 file.

  This method only works for Minecraft server admins, as it requires access to the server’s file system.

Dependencies

Optional plugin

ProtocolLib [Download]: used to display a custom "Now Playing" toast when a custom disc is inserted into a jukebox

External Tools

License & Attribution

The plugin automatically installs and uses the following tools (Deno and yt-dlp are also kept up to date):

• Deno, from the Deno GitHub repository, licensed under the MIT License
• yt-dlp, from the yt-dlp GitHub repository, licensed under the Unlicense
• FFmpeg, from the FFmpeg-Builds GitHub repository (Windows) and the FFmpeg Static Builds (Linux), licensed under the GNU General Public License version 3 (GPLv3)

Tool Usage

• Deno is used by yt-dlp to interpret YouTube’s JavaScript and decrypt its signature cipher, which is required to extract and download audio data from YouTube.
• yt-dlp downloads MP3 audio files from YouTube URLs.
• FFmpeg converts MP3 files to Ogg Vorbis format for Minecraft compatibility.

Installation

This plugin requires a brief setup to ensure players automatically download the resource pack when they join the Minecraft server.

Steps to install with the API Mode (default mode):

1. Download the URLCustomDiscs.jar plugin into your Minecraft server's plugins folder.
2. Start your Minecraft server so the plugin generates the plugins/URLCustomDiscs folder containing a config.yml file.
3. Open plugins/URLCustomDiscs/config.yml and set the following field to pluginUsageMode: api
4. In the same config file, locate the REMOTE API MODE CONFIGURATION section.
   Important fields include:
   • apiBaseURL: the base URL of the remote API
   • token: initially empty, automatically generated after creating your first custom disc
   • apiDownloadResourcePackURL: initially empty, automatically generated after creating your first custom disc
   • localYtDlp: defines whether to use the auto-installed yt-dlp tool in the plugin folder to download audio files from YouTube directly on your own server instead of relying on the external API. This field is set to false by default.
5. Create your first custom disc in-game using the /customdisc create <URL OR audio_name.mp3> <disc_name> <mono/stereo> command.
   This action will generate your unique token and the apiDownloadResourcePackURL.
6. Copy the generated apiDownloadResourcePackURL and paste it into your Minecraft server's server.properties file under the resource-pack= filed, for example:
   resource-pack=https://your-generated-apiDownloadResourcePackURL.zip
7. Restart your Minecraft server to apply the resource pack settings.
8. (Optional) To force players to download the resource pack, set require-resource-pack=true in server.properties and restart your Minecraft server.
9. (Optional fallback) In the extremely rare case that the API server gets blocked by YouTube, if you don’t want to manually download MP3 files and would prefer to keep using YouTube URLs, you can configure the plugin to use the auto-installed yt-dlp dependency directly on your Minecraft server.
   To do this, set the following field in the config.yml file: localYtDlp: true, then restart your Minecraft server.

   This option likely won’t work on most shared Minecraft hosting providers. For more details, refer to the Audio Download Options section.

10. (Optional) Download the ProtocolLib.jar plugin into your Minecraft server's plugins folder for custom "Now Playing" toasts, then restart your Minecraft server.

Support & Community

This plugin relies on a remote API and resource pack hosting maintained by me.
If you'd like to support the project and help cover server and storage costs, please consider contributing via Ko-fi. Thank you! ❤️

For any questions, help, or suggestions, feel free to join the Discord server!

Disclaimer

Please note that it is the sole responsibility of each user to comply with applicable copyright laws and the terms of service of any music provider when using this plugin. The developer of this plugin does not assume any liability for unauthorized use or violations of such laws and regulations.