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 ` - 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 ` 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 ` 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. ambient @a ~ ~ ~ 1 1` Vanilla command to stop a custom track: `/stopsound @a * minecraft:customdisc.` ## 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](https://github.com/TheoDgb/URLCustomDiscs). 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](https://github.com/TheoDgb/URLCustomDiscs/blob/main/SELF-HOSTED_AND_EDIT-ONLY_MODES_INSTALLATION.md) For more details, you may explore the API documentation, source code and architecture in the [URLCustomDiscsAPI GitHub repository](https://github.com/TheoDgb/URLCustomDiscsAPI). ## 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](https://notube.lol/fr/youtube-app-213) 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](https://www.protocollib.com/)]: 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](https://github.com/denoland/deno), licensed under the [MIT License](https://github.com/denoland/deno/blob/main/LICENSE.md) - **yt-dlp**, from the [yt-dlp GitHub repository](https://github.com/yt-dlp/yt-dlp), licensed under the [Unlicense](https://github.com/yt-dlp/yt-dlp/blob/master/LICENSE) - **FFmpeg**, from the [FFmpeg-Builds GitHub repository (Windows)](https://github.com/BtbN/FFmpeg-Builds) and the [FFmpeg Static Builds (Linux)](https://johnvansickle.com/ffmpeg/), licensed under the [GNU General Public License version 3 (GPLv3)](https://www.gnu.org/licenses/gpl-3.0.html) #### 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 ` 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](#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](https://ko-fi.com/mcallium). Thank you! ❤️ For any questions, help, or suggestions, feel free to join the [Discord server](https://discord.gg/tdWztKWzcm)! ## 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.