Compatibility
Minecraft: Java Edition
Platforms
Supported environments
Tags
Creators
Details
Minefy
Play Spotify tracks on Minecraft jukeboxes. Minefy is a server-authoritative Fabric mod: the server owns all track state, validates every submission, and decides what each player hears. Players with the mod get a URL input screen, synced playback state, positional audio hooks, and album-art disc overlays. Players without the mod hear a deterministic vanilla music-disc fallback sound, so unmodded clients can connect and play without crashes or kicks. The mod works in singleplayer (via the integrated server) and on dedicated servers.
What the mod does
- Right-click an empty jukebox with an empty hand to open a text screen where you paste a Spotify track or album link, URI, or ID (modded clients). Tracks are resolved to their real song names, artists, and cover art, then stored server-side on that jukebox. Right-clicking a jukebox that is already playing a Minefy track with an empty hand stops playback and ejects the Minefy Disc instead.
- Pasting an album link with
/minefy creategives you one disc per song on the album, each named after its real song title. If the blank-disc requirement is enabled, it consumes one vanilla music disc per song and tells you exactly how many you are missing. - Every Minefy Disc takes its song's main artwork color, extracted from the cover art, so discs are instantly recognizable. Discs show the real song title as their item name, with artist info in the tooltip.
- While a Minefy track is assigned, modded clients receive playback sync packets and play positional audio at the jukebox coordinates. Everyone else hears a vanilla disc fallback sound chosen deterministically from the track ID, so every track always has a sound.
- Right-click a playing jukebox with an empty hand to stop playback and eject a Minefy Disc item. The disc carries the track data and shows the song title as its item name, with artist info in the tooltip.
- Crafting-free disc creation through commands, with an optional requirement to consume a vanilla music disc from your inventory.
- All networking is guarded: custom packets are only sent to players that advertised the Minefy channels. Vanilla clients never receive unknown packets.
Requirements and installation
- Install Fabric Loader 0.19.5 or newer for your Minecraft version.
- Install Fabric API for the same Minecraft version (marked as a required dependency on each download).
- Use the correct Java version: Java 21 for the 1.21 builds, Java 25 for the 26.x builds.
- Download the Minefy file that matches your Minecraft version and put it in the
modsfolder. - For servers, install the same file on the server. Clients do not strictly need the mod, but only modded clients get the URL screen, synced state, and album art.
- For singleplayer, just put the mod (plus Fabric API) in
modsand open any world. The integrated server handles the server side automatically.
| Minefy file | Minecraft | Loader | Java |
|---|---|---|---|
| minefy-1.0.0+1.21.jar | 1.21 - 1.21.11 | Fabric | 21+ |
| minefy-1.0.0+26.1.jar | 26.1 - 26.1.2 | Fabric | 25+ |
| minefy-1.0.0+26.2.jar | 26.2 | Fabric | 25+ |
| minefy-1.0.0+26.3.jar | 26.3 | Fabric | 25+ |
Spotify metadata works out of the box for single tracks through a no-key lookup. For full album track lists and the richest metadata, optionally add Spotify API credentials to the config (see spotifyClientId below): create a free app in the Spotify developer dashboard and put its client id and secret in minefy-server.json (the secret can also come from the SPOTIFY_CLIENT_SECRET environment variable). Without credentials, single tracks still resolve with real names, and album links explain what is missing.
Note on Spotify audio: track metadata, syncing, fallback sounds, and album-art fetching are fully implemented. Actual Spotify stream decoding is an integration point (it requires Spotify API credentials and a streaming SDK): modded clients play positional audio through the provided handler hook, and everyone hears the vanilla fallback until a streaming backend is connected.
Configuration
Server config file: config/minefy-server.json (created with defaults on first run).
| Key | Default | Description |
|---|---|---|
| requireBlankDiscInInventory | false | When true, /minefy create consumes one vanilla music disc from your inventory. When false (default), the Minefy Disc is granted directly. |
| fallbackVolume | 1.0 | Volume of the vanilla-disc fallback sound heard by unmodded clients. |
| maxTrackUrlLength | 512 | Maximum accepted length for a submitted Spotify URL or track ID. |
| enableSpotifyStreaming | true | Master switch for modded-client Spotify audio streaming. |
| maxDistance | 24.0 - 64.0 | Audible radius in blocks for client-side distance attenuation (exact default depends on the Minecraft version). |
| enableFallbackForUnmodded / fallbackForUnmodded | true | When false, no vanilla fallback sound is played for unmodded clients. |
| enrichViaOEmbed | true | Enrich track titles and artists through the public Spotify oEmbed endpoint (no API key needed). |
| defaultVolume | 0.8 | Base volume for Spotify audio on modded clients. |
| spotifyClientId | (empty) | Optional Spotify application client ID. Enables full track and album lookups through the Spotify Web API. |
| spotifyClientSecret | (empty) | Optional Spotify application client secret (may also come from the SPOTIFY_CLIENT_SECRET environment variable). Required together with the client ID for album links. Never share this value. |
Not every key exists in every Minecraft version build; missing keys simply use the documented defaults above.
Commands
All commands are usable by every player (permission level 0).
| Command | Description |
|---|---|
| /minefy create <spotify_url> | Creates Minefy Discs bound to real song names. A track link gives one disc; an album link gives one disc per song (and consumes one vanilla music disc per song when requireBlankDiscInInventory is true, telling you the exact count if you are short). If your inventory is full, discs are dropped at your feet. |
| /minefy play <spotify_url> | Immediately starts playback on the jukebox you are looking at (within 8 blocks) using the real song name. An album link plays its first track and names the album. |
| /minefy stop | Stops playback on the jukebox you are looking at (available in the 26.1 and 26.3 builds). |
Accepted track formats: https://open.spotify.com/track/<id> and .../album/<id> links (query parameters are ignored), spotify:track:... and spotify:album:... URIs, and raw track IDs.
Compatibility notes
- Client: optional. Unmodded clients connect normally and hear vanilla fallback discs.
- Server: required. The server (or singleplayer integrated server) must have the mod for any Minefy feature to work.
- Singleplayer: fully supported. Install the mod and Fabric API in
modsand play any world.


