Defining Custom Sounds in sound_definitions.json

Every resource pack that introduces new audio or overrides vanilla audio paths needs a sound_definitions.json file placed inside the RP/sounds/ directory. Unlike entity or block definitions where each asset gets its own file, all sound definitions for your pack live inside this single JSON file. If multiple resource packs are active on a world, Minecraft merges their sound_definitions.json files from lowest to highest priority.

Since Bedrock 1.14.0, this file uses format_version 1.14.0 and wraps all entries inside a top-level sound_definitions object. Each key inside that object is the custom identifier you will call from commands like /playsound, animation timelines, or RP/sounds.json event mappings. By convention, dot-separated names like mob.custom_goblin.ambient or custom.spell.cast are used rather than namespaces with colons, though colons are technically permitted.

{
  "format_version": "1.14.0",
  "sound_definitions": {
    "custom.magic.sparkle": {
      "category": "neutral",
      "max_distance": 24.0,
      "sounds": [
        "sounds/custom/magic/sparkle_1",
        "sounds/custom/magic/sparkle_2"
      ]
    }
  }
}

Each sound definition object accepts a small set of properties that govern the entire event regardless of which individual audio file is picked from its list. Setting a category is the most important of these, as it connects your sound to the corresponding volume slider in the player's audio settings menu.

Distance attenuation is handled primarily through max_distance. If you leave this out, the engine falls back to a default distance based on the category, which is usually 16 blocks for standard effects. Setting a larger number allows boss roars or thunderclaps to be heard from much further away, though you must still configure the individual sound weight and volume appropriately.

In the simplest setup, the sounds array just contains strings pointing to your audio files relative to the resource pack root, always omitting the .ogg or .wav file extension. When you need finer control over an individual variation, you can replace the string with a JSON object.

Using an object lets you alter the volume, pitch, and selection weight of each file independently. This is ideal when one variation in your pool is naturally louder than the others, or when you want a rare 'easter egg' voice line to play only once every twenty triggers by giving the common sounds a high weight and the rare sound a weight of 1.

{
  "format_version": "1.14.0",
  "sound_definitions": {
    "mob.forest_troll.say": {
      "category": "hostile",
      "max_distance": 32.0,
      "sounds": [
        {
          "name": "sounds/mob/troll/grunt1",
          "volume": 0.9,
          "pitch": 1.0,
          "weight": 10
        },
        {
          "name": "sounds/mob/troll/grunt2",
          "volume": 0.9,
          "pitch": 0.95,
          "weight": 10
        },
        {
          "name": "sounds/mob/troll/rare_laugh",
          "volume": 1.0,
          "pitch": 1.0,
          "weight": 1
        }
      ]
    }
  }
}

Minecraft handles short sound effects and long music tracks differently in memory. By default, any sound listed in sound_definitions.json is decoded and held in memory so it can play with zero latency when a mob attacks or a block breaks. If you do this with a three-minute music file, it consumes a huge amount of RAM and will often fail to play or crash the game on mobile devices and consoles.

For any file longer than a few seconds, set stream to true inside the sound object. Streaming reads the .ogg file off the drive in small chunks as it plays. Keep in mind that Bedrock limits the number of simultaneous audio streams, so avoid setting stream to true on rapid-fire sound effects like footsteps or weapon swings.

{
  "format_version": "1.14.0",
  "sound_definitions": {
    "record.custom_dungeon_theme": {
      "category": "record",
      "max_distance": 64.0,
      "sounds": [
        {
          "name": "sounds/music/dungeon_theme",
          "stream": true,
          "volume": 0.8
        }
      ]
    }
  }
}

Registering an identifier in sound_definitions.json makes it immediately available to the /playsound command, resource pack client entity animations, and particle effects. However, if you want a custom entity or block to use the sound automatically through built-in game events—such as playing a hurt sound when damaged or a step sound when walking—you also need to reference your definition key inside RP/sounds.json.

Think of sound_definitions.json as defining 'what the sound is and where the file lives', while RP/sounds.json defines 'which game event triggers that sound'. For simple scripted events using world.playSound() or animation controllers firing /playsound, editing sound_definitions.json is the only step required.

Format version 1.14.0 applies to Minecraft Bedrock 1.14.0 and all current releases (1.20 and 1.21+). No experimental toggles are required.

Read out of the game itself, so the ids match the version you are building for.