A .sound stores one WAV/Ogg source and its playback defaults. A .soundscape is what a place sounds like: music, ambience and sounds around the listener, built from sound definitions. An .audiomix stores a complete configuration of the four audio groups and master effects. Both use the Windows effects runtime for effect processing. Loading them never starts playback, initializes effects, applies a mix or changes the selected audio world.
Select an object and click New... or Edit in its Sound section, whose list attaches a spatial sound or removes it, or choose File > New Resource > Sound.... Pick WAV/Ogg media, set loop, spatial mode, volume, pitch, group and sends, then choose Play. A spatial preview places the source to the right and four units ahead. Stop ends the preview and restores audio-world selection. Attach to the selected object saves the sound if needed and creates a sound-emitter on the object selected in Scene; save the world to retain the assignment.
Choose File > New Resource > Audio Mix, or File > Open Resource... for an .audiomix file, for mixer editing. Set group/master levels, limiter and reverb. Choose a test clip and Play: the clip loops with 50% reverb and 25% echo sends in the chosen group. Stop or Close restores the prior mixer. A failed restore keeps the preview session for retry and reports AudioLastError. Initialization remains enabled after preview.
Choose File > New Resource > Soundscape to make a soundscape; Soundscapes below describes its tab.
Each opens as a tab beside Scene, whose fields apply when you press Enter or move to another control. The tab's Source page exposes filters, EQ bands and echo delay/feedback. Hidden advanced values survive edits to the settings. Undo and Redo, in the tab or in the Edit menu, step through the draft. Save and Save as... validate a prepared snapshot; only a change to the resource's own record in the world asks for its tab to be opened again. Failed preparation retains the previous prepared preview; it never starts new playback.
{
"format": "blitz3d.sound", "version": 1, "id": "wind",
"assets": [{"id": "clip", "kind": "sound", "source": "wind.wav"}],
"definition": {"source": "clip", "loop": true, "spatial": true,
"volume": 0.6, "group": "ambience", "reverb": 0.4}
}
The world declares this descriptor as kind: "sound-definition". The existing raw sound kind remains WAV/Ogg media. WorldAssetSound accepts either kind and returns a new ordinary sound handle with independent defaults. FreeSound it when finished; playing channels keep their decoded media alive.
Supported defaults: loop/spatial false, volume 1, pitch 0 (native sample rate; authored Hz up to 192000), pan 0 (-1..1, nonspatial only), sfx group, bypass filter and zero sends. Sends and volume use 0..1. Filters have type 0..6, frequency 20..8000 Hz (up to 20000 for one-pole types 5/6), Q 0.667..10. Effects-dependent sources require InitAudioEffects before playback. Dry ordinary sources can use the direct playback path.
On Windows, macOS and iOS a sound definition's clip can stream: it is read from its file a quarter of a second at a time while it plays, instead of being decoded whole when the world loads. A three-minute stereo track then costs a few hundred kilobytes rather than about 30 MB, and loads at once. Set "stream": true or false in the definition to choose. Left out, sounds in the music group stream, and so does any other clip longer than 30 seconds; short sounds that start often stay decoded. Each playing channel reads the file on its own, so leave it in place while the world is loaded. On the web every clip is decoded whole.
"components": [{"type": "sound-emitter", "asset": "wind", "activation": "on-activate"}]
The asset must be required and spatial. Position comes from the entity transform. Activation is manual by default; on-activate still waits for an explicit ActivateWorldSounds call. Select its world with SetAudioWorld and provide a listener. PlaySoundEmitter replaces that emitter's channel; StopSoundEmitter stops it. Freeing the entity/world stops owned channels; copied entities begin silent.
A soundscape has three parts, each optional:
{
"format": "blitz3d.soundscape", "version": 1, "id": "meadow",
"assets": [
{"id": "theme", "kind": "sound-definition", "source": "theme.sound"},
{"id": "wind", "kind": "sound-definition", "source": "wind.sound"},
{"id": "bell", "kind": "sound-definition", "source": "bell.sound"}],
"definition": {
"music": {"track": "theme", "fadeIn": 3, "fadeOut": 4},
"beds": [{"sound": "wind", "volume": 0.35}],
"oneShots": [{"sounds": ["bell"], "every": [3, 7], "distance": [6, 14], "volume": [0.4, 0.8]}]}
}
Every sound is one of the soundscape's own sound definitions, named by its asset id. Music has volume 0..1 (1), fadeIn and fadeOut 0..600 seconds (2 each) and resume (true). A bed has a volume 0..1 (1). A set of one-shots plays a sound every every seconds, a random time between the two numbers (5 to 15, at least 0.05), distance units from the listener in a random direction (5 to 20) and up to 3 units above it, at a volume between the two (1). Each pair runs from low to high.
A world uses soundscapes in three places: its settings' "soundscape", heard outside every zone; a time of day's key, "soundscape" beside its environment, heard at that time; and a zone's "soundscape", heard inside the zone. See the world format's settings and zones. UpdateWorld mixes them for the listener as it mixes environments for a camera. Walking into a zone, its soundscape comes in across the zone's fade as the one outside goes out:
fadeOut as the new one fades in over its fadeIn. With resume, a track that comes back carries on where it stopped.Only the world chosen with SetAudioWorld plays its soundscapes, from its listener. Without a listener, the world's and the time of day's music and beds still play; zones and one-shots need the listener's position. A program can fade in a soundscape the place does not have, such as rain or a boss fight's music, with FadeWorldSoundscape: at weight 1 it replaces what the place sounds like, and at less the place is heard under it; ask how much of one is heard with ListenerSoundscapeWeight and whose music is playing with WorldSoundscapeMusic; and turn them all off and on, for a cutscene or the program's own PlayMusic, with WorldSoundscapeEnabled.
In the World Editor, a soundscape's tab has Music, Beds and One-shots sections whose lists offer the world's sound definitions; choosing one makes it part of the soundscape. Play plays the soundscape as heard from the middle of a zone, and Heard at fades it as if walking out. Use as the world's soundscape saves it and sets it in World settings; zones and times of day choose theirs in their own sections. Try the soundscapes sample: a meadow with music, wind and a bell, and a workshop whose machines take over as you walk into it.
Call InitAudioEffects before the first PCM playback, then explicitly ApplyAudioMix a ready asset. The definition is a complete replacement: omitted groups/settings return to neutral defaults. Groups are sfx=0, music=1, ui=2 and ambience=3. Each has volume, filter, echo delay/feedback, eqEnabled and exactly four optional EQ bands. Master volume/limiter and the existing 21 reverb presets plus off are supported.
Mixes prevalidate all settings and restore previous targets if native installation fails. Gain/filter ramps use 20 ms; reverb transitionMs is 0..5000. Echo delay is 1..2000 ms and feedback 0..0.95. EQ frequency is 20..20000 Hz, gainDb -18..18 and bandwidth 0.1..2. Meters, channels, device volume and effect tails are not document fields.
BeginAudioMixPreview returns an exclusive token and captures the previous configuration, including direct setter changes. Another mix, preview or group/master setter is rejected until EndAudioMixPreview restores it. Source/channel setters and meters remain usable. Stop preview channels before ending the session. Restore fades and clears wet tails using the existing 20 ms policy; it cannot replay old tails.
See the complete sound and mixer sample, its world, or the standalone mixer example. Validate descriptors with b3dworldc and the installed sound, soundscape and audiomix V1 schemas. See also reusable resources.
For editor steps and F1 help, see the World Editor User Guide.