Sound Definition JSON Format Reference

The Minecraft Sound Definition JSON Format is the critical backbone for custom audio within the game, empowering resource pack creators and mod developers to meticulously define how sound events are processed and played. This `sounds.json` file dictates everything from which audio files correspond to specific in-game actions to how those sounds behave in the game world, including their volume, pitch, and spatial properties.

Understanding the Core Mechanism

At its heart, the system relies on the sounds.json file to act as a central registry. In Java Edition, this file is typically nestled within your resource pack or mod at assets/<namespace>/sounds.json. For Bedrock Edition, while also using sounds.json, it often works in conjunction with sound_definitions.json. This JSON file doesn’t contain the audio data itself, but rather maps abstract sound event names to actual audio files and a rich set of properties that govern their playback.

• Sound Events: These are the in-game triggers. Whenever an action occurs in Minecraft that is designed to produce sound (e.g., a block breaking, a player taking damage, a mob spawning), it calls a specific sound event. Each event is identified by a unique ID, known as a ResourceLocation, which then looks up its definition in sounds.json to determine what audio to play.
• Supported Audio Formats: It’s crucial to use the correct audio format for your target edition. For Minecraft Java Edition, the only natively supported format is Ogg Vorbis (.ogg). This format is widely used for its balance of compression and quality. Minecraft Bedrock Edition offers more flexibility, supporting .wav, .ogg, and .fsb files. Always convert your audio files to the appropriate format before including them in your pack.
• Sound Categories: Minecraft neatly organizes sounds into categories such as “block,” “player,” “weather,” “ambient,” and “music.” These categories are directly linked to the volume sliders found in the game’s audio settings. By assigning your custom sounds to existing categories, you ensure players can adjust their volume independently, providing a consistent and user-friendly audio experience.

Deep Dive into Sound Object Properties

Within each sound event definition in sounds.json, you’ll find a list of sound objects. These objects are where the magic happens, allowing for granular control over every aspect of playback. Here are the key properties you can define:

• name: This is arguably the most fundamental property, specifying the file path to your audio file. The path is relative to the assets/<namespace>/sounds/ directory. For example, if your .ogg file is at assets/my_pack/sounds/custom/my_sound.ogg, the name property would be "custom/my_sound".
• volume: Controls the base loudness of the sound. This can be a single floating-point number (e.g., 1.0 for full volume, 0.5 for half) or a [min, max] array. Using an array, like [0.8, 1.2], introduces randomization, making the sound play at a slightly different volume each time, adding natural variation.
• pitch: Determines the playback speed and perceived pitch of the sound. Similar to volume, it can be a single float (e.g., 1.0 for normal pitch) or a [min, max] array (e.g., [0.9, 1.1]). Randomizing pitch can make repeated sounds less monotonous, mimicking natural imperfections.
• weight: When multiple sound objects are listed for a single sound event, weight determines the likelihood of each sound being chosen. A sound with a higher weight is more likely to play. For example, if you have two sounds with weights 1 and 2, the second sound is twice as likely to be chosen.
• stream: A boolean property (true or false). Setting stream to true is essential for long audio files, such as background music or extensive ambient loops. Instead of loading the entire file into memory at once, which can cause lag or memory issues, streaming plays the audio directly from disk as needed. For shorter sound effects, it’s generally left as false.
• attenuation_distance, min_distance, max_distance: These properties control how a sound’s volume diminishes with distance from the player, crucial for spatial audio.
  • min_distance defines the radius around the sound source where the sound plays at its full, specified volume. Beyond this radius, attenuation begins.
  • max_distance defines the maximum audible radius. Once the player moves beyond this distance, the sound becomes completely inaudible.
  • attenuation_distance (Java Edition specific, often used in conjunction with min/max distance for more complex attenuation models) can sometimes dictate how quickly the sound fades. The game’s engine uses these values to calculate the falloff curve.
• subtitle: This property accepts a localization key (e.g., "subtitles.entity.cow.ambient"). When the sound plays, if subtitles are enabled in the game settings, the localized text corresponding to this key will appear on screen, providing accessibility for players who are hearing impaired or playing without sound.

The Critical Role of Mono vs. Stereo Audio

A frequently overlooked but vital detail when preparing audio for Minecraft is the difference between mono and stereo. Sounds that are intended to attenuate, meaning their volume should decrease as the player moves away from the source, must be mono audio files. The game’s engine uses the single channel of a mono file to correctly calculate and apply spatial positioning and distance-based volume changes. If you use a stereo file for an attenuating sound, it will likely play at full volume directly at the player’s location, regardless of the source’s actual position, breaking immersion.

Conversely, stereo sounds are ideal for ambient music or non-diegetic (non-world-based) audio. Since they are not meant to originate from a specific point in the game world, playing them in stereo ensures a rich, full soundscape that always feels present around the player, irrespective of their in-game coordinates.

Step-by-Step Implementation for Java Edition Resource Packs

Creating custom sounds for Java Edition involves a straightforward, albeit precise, process:

1. Prepare Your Audio Files: The absolute first step is to convert all your desired sound files to the Ogg Vorbis (.ogg) format. This can be done using various audio editing software like Audacity. During this process, ensure that any sounds intended to attenuate (like mob noises, block sounds, etc.) are converted to mono. Music or global ambient sounds can remain stereo if desired.
2. Organize Your Files: Within your resource pack or mod structure, create a namespace folder (e.g., assets/my_pack/). Inside this, create a sounds directory: assets/my_pack/sounds/. Place all your converted .ogg files into this directory, often organizing them further into subfolders (e.g., assets/my_pack/sounds/custom_mobs/my_creeper_hiss.ogg). Use clear, lowercase naming conventions for easy reference.
3. Create sounds.json: This critical file must be placed directly inside your namespace folder, not inside the sounds subfolder. So, its path should be assets/my_pack/sounds.json. This file serves as the main index that the game will read.
4. Define Sound Events: Open your newly created sounds.json file. Inside, you will define your sound events. Each event is a JSON object with a unique key (your sound event ID) and contains properties that dictate how the sound behaves. For instance, to define a custom sound for a creeper hissing, you might create an entry like this (simplified):

   {
     "entity.creeper.prime": {
       "sounds": [
         {
           "name": "custom_mobs/my_creeper_hiss",
           "volume": 0.8,
           "pitch": [0.9, 1.1],
           "attenuation_distance": 16
         }
       ]
     }
   }
   

   This example maps the vanilla creeper priming sound event to your custom audio file, adjusting its volume, adding pitch variation, and defining its audible distance.

By mastering the sounds.json format and its various properties, you gain unparalleled control over Minecraft’s audio landscape, allowing for truly unique and immersive custom content. Experiment with different values for volume, pitch, and attenuation to find the perfect auditory experience for your creations.