Minecraft Custom Sounds Resource Pack Guide

Written for Minecraft 26.3.

A minecraft custom sounds resource pack needs two things: your audio as .ogg files and a sounds.json file that gives each sound an event name. Once the pack is loaded, you play the event with /playsound.

Before you start

• A working resource pack. If you do not have one yet, read Pack basics first.

• Your audio converted to .ogg. Export mono for sounds that should fade with distance.

• A namespace for your pack, for example mypack. Use lowercase letters, numbers and underscores.

Add the sound files

1. Create the folder assets/mypack/sounds/custom/ in your pack.

2. Copy your file in, for example chime.ogg.

3. Create assets/mypack/sounds.json next to the sounds folder.

Mono files are positional: they get quieter the further the player is from the source. Stereo files keep the same volume everywhere, like music and ambience.

Write sounds.json

Each key in sounds.json is an event name that you choose. Its sounds array lists the files to pick from. The game picks one at random each time the event plays.

{
  "custom.chime": {
    "subtitle": "subtitles.mypack.chime",
    "sounds": [
      "mypack:custom/chime",
      {
        "name": "mypack:custom/chime_quiet",
        "volume": 0.5,
        "pitch": 1.0,
        "weight": 2
      }
    ]
  }
}

The name is the path from the sounds folder, with no .ogg and forward slashes only. A plain string is shorthand for an entry with default settings.

Entry options

• volume and pitch: decimals above 0. Both default to 1.0.

• weight: a whole number above 0. Higher means picked more often. Default 1.

• stream: set to true for long files such as music, so they play from disk instead of memory.

• preload: set to true to load the sound when the pack loads.

• replace: on the event, set to true to replace vanilla sounds on a vanilla event instead of adding to them.

• subtitle: a translation key shown in closed captions. Leave it out for no caption. See translations to define the text.

Play it

The event name is prefixed with your namespace. Run this in game or from the console:

/playsound mypack:custom.chime master @a ~ ~ ~ 1 1

The arguments after the sound are the source category, the targets, the position, the volume and the pitch. Only the sound is required. A volume above 1 does not make it louder: it widens the distance it can be heard from (16 blocks at volume 1).

A plugin can trigger the same sound by running that command from the console, or by playing the sound name through its own sound API.

Music discs

A custom disc also needs a jukebox song definition in a data pack, at data/<namespace>/jukebox_song/<name>.json. It has four keys: sound_event, description, length_in_seconds and comparator_output (0 to 15). The item that plays it needs the jukebox_playable component. This part is covered on the wiki for the 24w21a era onward; we have not tested it on 26.3.

Check it worked

1. Join with the pack loaded.

2. Run the /playsound command above. Type the namespace and the tab list should offer your event.

3. If the event is missing from tab completion, the pack did not load or the JSON is broken.

Common problems

Every vanilla sound stopped working

One bad entry makes the game ignore your whole sounds.json and fall back to the vanilla sounds. Check for trailing commas and spaces in names.

The event is not found

Use the full name with your namespace, for example mypack:custom.chime. Without a namespace the game looks in minecraft.

The sound is silent far away or only on one side

That is how mono positional audio behaves. Use a stereo file for ambience that should not fade.

Long tracks stutter

Set stream to true on the entry.

Keep file names lowercase. Names with capitals or spaces are the most common cause of a sound that never plays.

If nothing works, follow Debugging a pack.