> For the complete documentation index, see [llms.txt](https://wiki.auraplugins.eu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.auraplugins.eu/guides/sound-files.md). # Sound Files Explained Every sound lives in its own YAML file under `plugins/AuraSounds/sounds/` (or inside a scene folder). A file has up to four parts: ```yaml type: ambient # ambient | music | random enabled: true # toggle without deleting (also: /aurasounds toggle) playback: # WHAT plays and HOW source: # WHERE it plays (ambient: points+radius, music: zone) random: # CADENCE and placement (random type only) conditions: # WHEN it plays (optional — see the Conditions guide) ``` ## The three sound types | | `ambient` | `music` | `random` | | ----------- | ------------------------------------ | ------------------------------------------------- | ------------------------------------------- | | Bound to | **source points** + radius | a **zone** (WorldGuard region or built-in area) | **the player** — no location at all | | Positional | yes — volume falls off with distance | no — full volume while inside | yes — spawns around the player | | Playback | loops while in range | loops while in zone | **one-shot** at random intervals | | Stacking | several at once | **one music** per player, highest `priority` wins | several at once | | Typical use | fireplace, waterfall, frogs | dungeon theme, town music | distant roars, thunder rumbles, jump scares | ## The `random` type — atmosphere without coordinates Random sounds follow the player everywhere their conditions allow — no source points to place. Every so often, the sound plays **once**, positioned at a random spot around the player. Perfect for distant creature roars, far-off thunder, unsettling forest noises. ```yaml type: random playback: sound: ['mypack:distant_roar_1', 'mypack:distant_roar_2'] volume: 0.8 random: interval: '120s' # average wait between plays variance: '60s' # random +/- (here: one play every 60s to 180s) distance: 24 # played this many blocks away, random direction (0 = on the player) conditions: worlds: ['dinoworld'] time: ['night'] ``` `distance` gives the sound a *direction* — players instinctively look toward the roar. That, combined with a sound pool, is the cheapest dread you'll ever build. ## `playback` — what plays and how ```yaml playback: # A single key, or a pool (one variant picked at random per loop): sound: 'itemsadder:mypack:swamp_ambience' # sound: ['minecraft:ambient.cave', 'mypack:creak', 'mypack:drip'] category: AMBIENT # Minecraft sound category (respects client volume sliders) volume: 1.0 pitch: 1.0 pitch-variance: 0.1 # random +/- applied each play (volume-variance also exists) loop: enabled: true duration: '35s' # real length of the audio file interval: '0s' # silence between repetitions ('0s' = seamless chain) fade: stop: '2s' # delayed cut when the sound must stop # music only — real audible transition between two zone musics: transition: outro-sound: 'mypack:theme_outro' overlap: '1s' ``` **Accepted sound keys:** vanilla (`minecraft:...`), `itemsadder::`, `nexo:`, or any raw namespaced key from a manual resource pack (`mypack:`). **Durations** use a human format everywhere: `'500ms'`, `'2s'`, `'1m30s'`. {% hint style="warning" %} **About fades:** the vanilla protocol cannot lower the volume of a sound that is already playing. `fade.stop` is therefore a *delayed cut*, not a volume ramp. For music, use `transition.outro-sound` + `overlap` to get a true audible transition (the outro layers briefly over the next track's beginning). {% endhint %} ## `source` — where it plays (ambient) ```yaml source: radius: 16 # audible distance in blocks falloff: true # positional audio, quieter with distance points: - {world: world, x: 100, y: 64, z: -200} - {world: world, x: 112, y: 64, z: -190} ``` * Multiple points = the same ambience emitted from several spots (a riverbank, a row of torches…). * Manage points in game while standing at the right spot: `/aurasounds addloc ` and `/aurasounds remloc `. * `falloff: false` makes the sound non-positional — equally loud anywhere inside the radius. For **music**, `source` is replaced by the zone: a WorldGuard region name or a built-in area — see [Zone Music & WorldGuard](/guides/worldguard-music.md). ## `conditions` — when it plays Any sound can define conditions (time, weather, biome, altitude, light, permission, placeholders…). They are all covered with examples in [The Condition System](/guides/conditions.md). ## Defaults and validation * Anything you omit falls back to the `defaults` section of `config.yml` (volume, pitch, category). * An invalid file **never crashes the plugin**: it is skipped with a console message telling you *which file* and *which field* is wrong. Fix it and `/aurasounds reload`. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://wiki.auraplugins.eu/guides/sound-files.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.