Adding sounds to a YSM model
Since version 2.3.0, Yes Steve Model (YSM) allows you to trigger custom or vanilla Minecraft audio directly inside your animations. This guide explains how to prepare audio files, link them in Blockbench, and control playback using Molang and playback contexts introduced in 2.5.3.
Audio Requirements and Limitations
Your model must use the modern YSM file structure (ysm.json) to support audio; legacy model structures cannot play sounds. You can either bundle custom audio files inside your model pack or reference built-in vanilla Minecraft sound events.
All custom audio files must be in .ogg format, and each individual file cannot exceed 4 MB (with the total model pack capped at 66 MB). Using mono (single-channel) audio is strongly recommended so that Minecraft can properly calculate 3D directional stereo effects in-game. Since version 2.5.3, YSM also features an improved Opus decoder, meaning you can encode .ogg files with the Opus codec for better audio quality at smaller file sizes compared to standard Vorbis.
.mp3 or .wav files into mono .ogg files using free tools like Audacity, FFmpeg, Format Factory, or Adobe Audition.How to Add Built-in Audio Files
By default, YSM looks for custom audio files inside a folder named sounds in the root directory of your model pack. When referencing a file in Blockbench, you only write the file name without the folder prefix or the .ogg extension. For example, if your file is located at sounds/laugh.ogg, you simply enter laugh into the Blockbench sound keyframe.
- Create a folder named
soundsinside your model pack directory. - Convert your audio into
.oggformat and place it inside thesoundsfolder. - Open your animation in Blockbench, add a sound effect keyframe, and type the file name without
sounds/or.ogg.
Customizing the Sound Folder and Using Vanilla Sounds
If you want to store your audio files in a folder other than sounds, you can define a custom path using the sound_path key inside ysm.json. Even with a custom folder, you still omit the folder name and .ogg extension when writing the sound name in Blockbench.
You can also trigger vanilla Minecraft sounds or resource pack sounds by entering their full sound event ID (such as minecraft:block.anvil.hit) in the sound keyframe. Using a separate vanilla resource pack for audio is highly recommended when you want to keep your YSM model file size small, use random sound weights, or avoid bundling copyrighted audio directly inside the model.
{
"files": {
"sound_path": "custom_audio_folder"
}
}Animation Controller Sounds and Playback Contexts (Since 2.5.3)
Starting in version 2.5.3, you can attach sound effects directly to states inside Blockbench Animation Controllers. When a state is entered, YSM first executes the state's on-entry Molang expressions and then plays the attached sound.
Every sound played in 2.5.3+ is assigned to one of three Playback Contexts, which determines when the sound automatically stops:
1. Animation Context: Includes animation sound keyframes, animation command keyframe Molang, and script controller Molang. Sounds in this context automatically stop when the animation ends or loops to the next cycle.
2. Animation Controller Context: Includes sounds configured directly on controller states and sounds created via controller on-entry/on-exit Molang. These automatically stop when the controller transitions to a different state.
3. Global Context: Includes sounds triggered by action wheel Molang, in-game commands, ysm.sync events, or other Molang events. These do not stop automatically when animations change; they only force-stop if the player switches models, the entity is removed, or the entity teleports to another dimension.
ysm.play_sound AFTER calling set_animation or reset, otherwise your sound instance will be immediately wiped out by the reset.Playing Sounds with Molang and Bitwise Flags
You can play sounds dynamically using ysm.play_sound(id, 'sound_name', flags, volume, pitch), where the third parameter acts as an integer bitflag since version 2.5.3. In older versions, the third parameter was a simple boolean (0 or 1), which remains backward-compatible.
You can combine the following flag values by adding them together: +1 forces a replay (stops any existing instance with the same id and starts a new one), +2 assigns the sound to the Global Context (ignoring the current animation or controller context), and +4 loops the audio continuously.
ysm.play_sound('fx', 'sample', 1) // Force replay (+1)
ysm.play_sound('fx', 'sample', 2) // Global context (+2)
ysm.play_sound('fx', 'sample', 4) // Loop playback (+4)
ysm.play_sound('fx', 'sample', 7) // 1+2+4: Force replay + Global + LoopNumeric IDs and Anonymous Sound Instances (Since 2.5.3)
In version 2.5.3 and later, the id parameter in ysm.play_sound and ysm.stop_sound can be either a string or a non-negative number (>= 0). Using numbers makes it easier to manage sound channels dynamically with Molang math.
Setting id = 0 creates an anonymous playback instance, which allows multiple copies of the same sound to overlap and play simultaneously. Note that force-replay (+1) has no effect on anonymous instances, and all Blockbench sound keyframes and controller sounds are automatically created as anonymous instances. You cannot stop an anonymous sound with ysm.stop_sound, though it still obeys its Playback Context and can be stopped via ysm.stop_all_sounds.
ysm.play_sound(1, 'sample') // Create sound with numeric ID 1
ysm.stop_sound(1) // Stop sound with numeric ID 1
ysm.play_sound(0, 'sample') // Anonymous instance (can overlap)Stopping Sounds Manually with Molang
You can manually stop playing audio at any time using ysm.stop_sound(id, global?) or ysm.stop_all_sounds(global?). By default (since 2.5.3), these functions only stop sounds that belong to the same Playback Context where the stop function is called.
To stop sounds running in the Global Context, pass 1 as the optional global parameter. Leaving the global parameter empty or setting it to 0 targets only the current context.
ysm.stop_sound('fx', 1) // Stop 'fx' in the Global Context
ysm.stop_all_sounds(0) // Stop all sounds in the current context
ysm.stop_all_sounds // Stop all sounds in the current contextQuestions
Why does my custom sound sound flat or play at the same volume everywhere?
Your .ogg file is likely exported in stereo (two channels). Convert your audio file to mono (single channel) so Minecraft's sound engine can apply 3D positional audio and distance attenuation.
How do I stop a sound from cutting off when my animation finishes?
In YSM 2.5.3+, sounds triggered inside an animation belong to the Animation Context and stop when the animation ends. To keep it playing after the animation finishes, trigger it via Molang using ysm.play_sound('id', 'sound_name', 2) so the +2 flag places it in the Global Context.
Why can't I stop a sound that I created with `ysm.play_sound(0, 'sample')` using `ysm.stop_sound(0)`?
Passing 0 as the ID creates an anonymous sound instance. Anonymous instances cannot be targeted by ysm.stop_sound; you must use ysm.stop_all_sounds or wait for their playback context to end.
Do I write `sounds/my_audio.ogg` inside the Blockbench sound keyframe?
No. Exclude both the folder path and the .ogg file extension. Simply write my_audio.