0
# Sound System
1

2
Sound playback and management with support for different sources, volumes, positional audio, and sound stopping. Adventure's sound system provides comprehensive audio control for Minecraft servers.
3

4
## Capabilities
5

6
### Sound Interface
7

8
Core interface for representing and playing sounds with configurable properties.
9

10
```java { .api }
11
/**
12
 * Represents a sound with key, source, volume, and pitch
13
 */
14
interface Sound extends Examinable {
15
    /**
16
     * Gets the sound key (identifier)
17
     * @return the sound key
18
     */
19
    Key name();
20
    
21
    /**
22
     * Gets the sound source category
23
     * @return the sound source
24
     */
25
    Source source();
26
    
27
    /**
28
     * Gets the sound volume (0.0 to Integer.MAX_VALUE)
29
     * @return the volume
30
     */
31
    float volume();
32
    
33
    /**
34
     * Gets the sound pitch (-1.0 to 1.0)
35
     * @return the pitch
36
     */
37
    float pitch();
38
    
39
    /**
40
     * Gets the random seed for sound variation
41
     * @return optional containing the seed
42
     */
43
    OptionalLong seed();
44
    
45
    /**
46
     * Creates a sound with specified properties
47
     * @param name the sound key
48
     * @param source the sound source
49
     * @param volume the volume (0.0 to Integer.MAX_VALUE)
50
     * @param pitch the pitch (-1.0 to 1.0)
51
     * @return new sound
52
     */
53
    static Sound sound(Key name, Source source, float volume, float pitch);
54
    
55
    /**
56
     * Creates a sound with seed
57
     * @param name the sound key
58
     * @param source the sound source
59
     * @param volume the volume
60
     * @param pitch the pitch
61
     * @param seed the random seed
62
     * @return new sound
63
     */
64
    static Sound sound(Key name, Source source, float volume, float pitch, long seed);
65
    
66
    /**
67
     * Creates a sound builder
68
     * @return new sound builder
69
     */
70
    static Builder sound();
71
    
72
    /**
73
     * Sound source categories affecting volume controls
74
     */
75
    enum Source {
76
        /**
77
         * Master volume category
78
         */
79
        MASTER("master"),
80
        
81
        /**
82
         * Music volume category
83
         */
84
        MUSIC("music"),
85
        
86
        /**
87
         * Record/note block volume category
88
         */
89
        RECORD("record"),
90
        
91
        /**
92
         * Weather sounds category
93
         */
94
        WEATHER("weather"),
95
        
96
        /**
97
         * Block interaction sounds category
98
         */
99
        BLOCK("block"),
100
        
101
        /**
102
         * Hostile mob sounds category
103
         */
104
        HOSTILE("hostile"),
105
        
106
        /**
107
         * Neutral/friendly mob sounds category
108
         */
109
        NEUTRAL("neutral"),
110
        
111
        /**
112
         * Player-generated sounds category
113
         */
114
        PLAYER("player"),
115
        
116
        /**
117
         * Ambient environment sounds category
118
         */
119
        AMBIENT("ambient"),
120
        
121
        /**
122
         * Voice/speech sounds category
123
         */
124
        VOICE("voice"),
125
        
126
        /**
127
         * User interface sounds category (since 4.22.0, Minecraft 1.21.6)
128
         */
129
        UI("ui");
130
        
131
        /**
132
         * Gets source by name
133
         * @param name the source name
134
         * @return the source or null
135
         */
136
        static @Nullable Source byName(String name);
137
    }
138
    
139
    /**
140
     * Builder for creating sounds
141
     */
142
    interface Builder extends AbstractBuilder<Sound> {
143
        /**
144
         * Sets the sound key
145
         * @param name the sound key
146
         * @return this builder
147
         */
148
        Builder type(Key name);
149
        
150
        /**
151
         * Sets the sound source category
152
         * @param source the source
153
         * @return this builder
154
         */
155
        Builder source(Source source);
156
        
157
        /**
158
         * Sets the sound volume
159
         * @param volume the volume (0.0 to Integer.MAX_VALUE)
160
         * @return this builder
161
         */
162
        Builder volume(float volume);
163
        
164
        /**
165
         * Sets the sound pitch
166
         * @param pitch the pitch (-1.0 to 1.0)
167
         * @return this builder
168
         */
169
        Builder pitch(float pitch);
170
        
171
        /**
172
         * Sets the random seed
173
         * @param seed the seed
174
         * @return this builder
175
         */
176
        Builder seed(long seed);
177
    }
178
    
179
    /**
180
     * Sound emitter for positional audio
181
     */
182
    interface Emitter {
183
        // Marker interface for sound emitters (entities, locations, etc.)
184
    }
185
}
186
```
187

188
**Usage Examples:**
189

190
```java
191
import net.kyori.adventure.sound.Sound;
192
import net.kyori.adventure.key.Key;
193

194
// Basic sound playback
195
Sound levelUp = Sound.sound(
196
    Key.key("entity.player.levelup"),
197
    Sound.Source.PLAYER,
198
    1.0f,  // volume (0.0 to Integer.MAX_VALUE)
199
    0.0f   // normal pitch (-1.0 to 1.0)
200
);
201
audience.playSound(levelUp);
202

203
// Custom sound with different properties
204
Sound lowPitchBell = Sound.sound()
205
    .type(Key.key("block.note_block.bell"))
206
    .source(Sound.Source.BLOCK)
207
    .volume(0.7f)
208
    .pitch(0.5f)  // lower pitch
209
    .build();
210

211
// Play sound at specific location
212
audience.playSound(levelUp, x, y, z);
213

214
// High-pitched notification
215
Sound notification = Sound.sound(
216
    Key.key("entity.experience_orb.pickup"),
217
    Sound.Source.PLAYER,
218
    0.5f,  // quieter
219
    1.5f   // higher pitch
220
);
221
```
222

223
### Sound Stop Interface
224

225
Interface for stopping sound playback with various filtering options.
226

227
```java { .api }
228
/**
229
 * Represents a request to stop playing sounds
230
 */
231
interface SoundStop extends Examinable {
232
    /**
233
     * Gets the specific sound to stop (null for any)
234
     * @return the sound key or null
235
     */
236
    @Nullable Key sound();
237
    
238
    /**
239
     * Gets the source category to stop (null for any)
240
     * @return the source or null
241
     */
242
    @Nullable Sound.Source source();
243
    
244
    /**
245
     * Stops all sounds
246
     * @return sound stop for all sounds
247
     */
248
    static SoundStop all();
249
    
250
    /**
251
     * Stops a specific sound by key
252
     * @param sound the sound key to stop
253
     * @return sound stop for specific sound
254
     */
255
    static SoundStop named(Key sound);
256
    
257
    /**
258
     * Stops sounds from a specific source category
259
     * @param source the source category
260
     * @return sound stop for source category
261
     */
262
    static SoundStop source(Sound.Source source);
263
    
264
    /**
265
     * Stops a specific sound from a specific source
266
     * @param sound the sound key
267
     * @param source the source category
268
     * @return sound stop for sound and source
269
     */
270
    static SoundStop namedOnSource(Key sound, Sound.Source source);
271
    
272
    /**
273
     * Creates a sound stop builder
274
     * @return new builder
275
     */
276
    static Builder builder();
277
    
278
    /**
279
     * Builder for creating sound stop requests
280
     */
281
    interface Builder extends AbstractBuilder<SoundStop> {
282
        /**
283
         * Sets the sound to stop
284
         * @param sound the sound key or null for any
285
         * @return this builder
286
         */
287
        Builder sound(@Nullable Key sound);
288
        
289
        /**
290
         * Sets the source category to stop
291
         * @param source the source or null for any
292
         * @return this builder
293
         */
294
        Builder source(@Nullable Sound.Source source);
295
    }
296
}
297
```
298

299
**Usage Examples:**
300

301
```java
302
import net.kyori.adventure.sound.SoundStop;
303

304
// Stop all sounds
305
audience.stopSound(SoundStop.all());
306

307
// Stop specific sound
308
audience.stopSound(SoundStop.named(Key.key("entity.player.levelup")));
309

310
// Stop all music
311
audience.stopSound(SoundStop.source(Sound.Source.MUSIC));
312

313
// Stop specific sound from specific source
314
audience.stopSound(SoundStop.namedOnSource(
315
    Key.key("music.overworld"), 
316
    Sound.Source.MUSIC
317
));
318

319
// Using builder for complex stop requests
320
SoundStop complexStop = SoundStop.builder()
321
    .sound(Key.key("ambient.cave"))
322
    .source(Sound.Source.AMBIENT)
323
    .build();
324
```
325

326
## Common Sound Patterns
327

328
### Sound Effect Library
329

330
```java
331
public class SoundEffects {
332
    // UI Sounds
333
    public static final Sound BUTTON_CLICK = Sound.sound(
334
        Key.key("ui.button.click"), Sound.Source.MASTER, 0.5f, 1.0f);
335
    
336
    public static final Sound SUCCESS = Sound.sound(
337
        Key.key("entity.experience_orb.pickup"), Sound.Source.PLAYER, 0.7f, 1.2f);
338
    
339
    public static final Sound ERROR = Sound.sound(
340
        Key.key("block.note_block.bass"), Sound.Source.PLAYER, 0.8f, 0.5f);
341
    
342
    // Game Events
343
    public static final Sound LEVEL_UP = Sound.sound(
344
        Key.key("entity.player.levelup"), Sound.Source.PLAYER, 1.0f, 1.0f);
345
    
346
    public static final Sound DEATH = Sound.sound(
347
        Key.key("entity.player.death"), Sound.Source.PLAYER, 1.0f, 1.0f);
348
    
349
    // Environmental
350
    public static final Sound THUNDER = Sound.sound(
351
        Key.key("entity.lightning_bolt.thunder"), Sound.Source.WEATHER, 0.8f, 1.0f);
352
    
353
    public static final Sound RAIN = Sound.sound(
354
        Key.key("weather.rain"), Sound.Source.WEATHER, 0.3f, 1.0f);
355
}
356
```
357

358
### Positional Audio
359

360
```java
361
// Play sound at entity location
362
public void playSoundAtEntity(Audience audience, Sound sound, Entity entity) {
363
    Location loc = entity.getLocation();
364
    audience.playSound(sound, loc.getX(), loc.getY(), loc.getZ());
365
}
366

367
// Play sound following an entity
368
public void playSoundFollowingEntity(Audience audience, Sound sound, Entity entity) {
369
    audience.playSound(sound, entity); // Assuming entity implements Sound.Emitter
370
}
371

372
// Distance-based volume adjustment
373
public Sound adjustVolumeByDistance(Sound baseSound, double distance, double maxDistance) {
374
    float volume = Math.max(0.0f, Math.min(1.0f, (float)(1.0 - distance / maxDistance)));
375
    return Sound.sound()
376
        .type(baseSound.name())
377
        .source(baseSound.source())
378
        .volume(baseSound.volume() * volume)
379
        .pitch(baseSound.pitch())
380
        .build();
381
}
382
```
383

384
### Dynamic Sound Effects
385

386
```java
387
// Random pitch variation
388
public Sound withRandomPitch(Sound baseSound, float variation) {
389
    Random random = new Random();
390
    float pitchOffset = (random.nextFloat() - 0.5f) * variation;
391
    float newPitch = Math.max(0.5f, Math.min(2.0f, baseSound.pitch() + pitchOffset));
392
    
393
    return Sound.sound(baseSound.name(), baseSound.source(), baseSound.volume(), newPitch);
394
}
395

396
// Volume fade effect (requires multiple sound calls)
397
public void fadeInSound(Audience audience, Sound baseSound, int steps, long delayMs) {
398
    for (int i = 0; i <= steps; i++) {
399
        float volume = (float) i / steps * baseSound.volume();
400
        Sound fadedSound = Sound.sound(
401
            baseSound.name(), 
402
            baseSound.source(), 
403
            volume, 
404
            baseSound.pitch()
405
        );
406
        
407
        // Schedule sound with delay (implementation-specific)
408
        scheduleSound(audience, fadedSound, delayMs * i);
409
    }
410
}
411

412
// Sound sequence/chain
413
public void playSoundSequence(Audience audience, Sound... sounds) {
414
    for (int i = 0; i < sounds.length; i++) {
415
        // Schedule each sound with delay (implementation-specific)
416
        scheduleSound(audience, sounds[i], i * 500L); // 500ms between sounds
417
    }
418
}
419
```
420

421
### Category-Based Sound Management
422

423
```java
424
// Sound manager for different categories
425
public class SoundManager {
426
    public void playUISound(Audience audience, Key soundKey) {
427
        Sound sound = Sound.sound(soundKey, Sound.Source.MASTER, 0.5f, 1.0f);
428
        audience.playSound(sound);
429
    }
430
    
431
    public void playGameSound(Audience audience, Key soundKey, float volume) {
432
        Sound sound = Sound.sound(soundKey, Sound.Source.PLAYER, volume, 1.0f);
433
        audience.playSound(sound);
434
    }
435
    
436
    public void playAmbientSound(Audience audience, Key soundKey, float volume, float pitch) {
437
        Sound sound = Sound.sound(soundKey, Sound.Source.AMBIENT, volume, pitch);
438
        audience.playSound(sound);
439
    }
440
    
441
    // Stop sounds by category
442
    public void stopAllMusic(Audience audience) {
443
        audience.stopSound(SoundStop.source(Sound.Source.MUSIC));
444
    }
445
    
446
    public void stopAllAmbient(Audience audience) {
447
        audience.stopSound(SoundStop.source(Sound.Source.AMBIENT));
448
    }
449
    
450
    public void mutePlayer(Audience audience) {
451
        audience.stopSound(SoundStop.source(Sound.Source.PLAYER));
452
    }
453
}
454
```
455

456
## Sound Keys and Registry
457

458
### Common Minecraft Sound Keys
459

460
```java
461
// Entity sounds
462
Key.key("entity.player.levelup")
463
Key.key("entity.player.death")
464
Key.key("entity.experience_orb.pickup")
465
Key.key("entity.villager.yes")
466
Key.key("entity.villager.no")
467

468
// Block sounds
469
Key.key("block.note_block.bell")
470
Key.key("block.note_block.bass")
471
Key.key("block.chest.open")
472
Key.key("block.chest.close")
473
Key.key("block.anvil.use")
474

475
// UI sounds
476
Key.key("ui.button.click")
477
Key.key("ui.toast.challenge_complete")
478
Key.key("ui.toast.in")
479
Key.key("ui.toast.out")
480

481
// Weather and environment
482
Key.key("weather.rain")
483
Key.key("weather.rain.above")
484
Key.key("entity.lightning_bolt.thunder")
485
Key.key("ambient.cave")
486

487
// Music
488
Key.key("music.overworld")
489
Key.key("music.nether")
490
Key.key("music.end")
491
Key.key("music.creative")
492
```
493

494
### Custom Sound Registration
495

496
```java
497
// For custom resource packs or plugins
498
public class CustomSounds {
499
    public static final Key CUSTOM_NOTIFICATION = Key.key("myserver", "notification");
500
    public static final Key CUSTOM_SUCCESS = Key.key("myserver", "success");
501
    public static final Key CUSTOM_ERROR = Key.key("myserver", "error");
502
    
503
    public static Sound customNotification() {
504
        return Sound.sound(CUSTOM_NOTIFICATION, Sound.Source.MASTER, 0.7f, 1.0f);
505
    }
506
    
507
    public static Sound customSuccess() {
508
        return Sound.sound(CUSTOM_SUCCESS, Sound.Source.PLAYER, 0.8f, 1.1f);
509
    }
510
    
511
    public static Sound customError() {
512
        return Sound.sound(CUSTOM_ERROR, Sound.Source.PLAYER, 0.6f, 0.8f);
513
    }
514
}
515
```
516

517
## Best Practices
518

519
### Volume and Pitch Guidelines
520
- **Volume**: 0.0-1.0 range, with 0.5-0.8 being good for most UI sounds
521
- **Pitch**: 0.5-2.0 range, with 1.0 being normal pitch
522
- Use volume < 0.5 for ambient/background sounds
523
- Use volume > 0.8 for important notifications
524

525
### Source Category Usage
526
- **MASTER**: Universal sounds that should respect master volume
527
- **PLAYER**: Player action sounds (walking, attacking, etc.)
528
- **BLOCK**: Block interaction sounds (breaking, placing)
529
- **AMBIENT**: Background environmental sounds
530
- **MUSIC**: Background music tracks
531
- **UI**: Interface sounds (usually MASTER category)
532

533
### Performance Considerations
534
- Don't spam sounds - limit frequency of sound playback
535
- Use sound stopping to prevent audio overlap
536
- Consider client-side performance with many simultaneous sounds
537
- Cache frequently used Sound objects rather than creating new ones
538

539
### User Experience
540
- Provide audio cues for important events
541
- Use consistent sound themes for similar actions
542
- Respect player audio preferences through source categories
543
- Test sounds across different client settings and hardware