# New sound API (easier to use, more versatile) and ability to set up sounds using CGE editor **URL:** https://forum.castle-engine.io/t/new-sound-api-easier-to-use-more-versatile-and-ability-to-set-up-sounds-using-cge-editor/423 **Category:** News **Created:** [September 24, 2021, 2:05pm UTC](https://forum.castle-engine.io/t/new-sound-api-easier-to-use-more-versatile-and-ability-to-set-up-sounds-using-cge-editor/423 "2021-09-24T14:05:04Z") **Posts on this page:** 1 **Page:** 1
### Author: ![michalis](https://forum.castle-engine.io/user_avatar/forum.castle-engine.io/michalis/32/3_2.png) [@michalis](https://forum.castle-engine.io/u/michalis) #### Post date: [September 24, 2021, 2:05pm UTC](https://forum.castle-engine.io/t/new-sound-api-easier-to-use-more-versatile-and-ability-to-set-up-sounds-using-cge-editor/423/1 "2021-09-24T14:05:05Z")
| [![Example 3D game with spatial sounds - TCastleSound](https://castle-engine.io/wp/wp-content/uploads/2021/09/example_3d_game_2-200x114.png)](https://castle-engine.io/wp/wp-content/uploads/2021/09/example_3d_game_2.png "Example 3D game with spatial sounds - TCastleSound") | | [![Example 3D game with spatial sounds - TCastleSoundSource](https://castle-engine.io/wp/wp-content/uploads/2021/09/example_3d_game-200x114.png)](https://castle-engine.io/wp/wp-content/uploads/2021/09/example_3d_game.png "Example 3D game with spatial sounds - TCastleSoundSource") | | [![Example audio player using LCL for UI and CGE for sound playing](https://castle-engine.io/wp/wp-content/uploads/2021/09/example_player-200x126.png)](https://castle-engine.io/wp/wp-content/uploads/2021/09/example_player.png "Example audio player using LCL for UI and CGE for sound playing") | | [![Example cross-platform testing of sound playback using CGE UI](https://castle-engine.io/wp/wp-content/uploads/2021/09/example_play_sounds-200x117.png)](https://castle-engine.io/wp/wp-content/uploads/2021/09/example_play_sounds.png "Example cross-platform testing of sound playback using CGE UI") | | [![Example showing Doppler effect](https://castle-engine.io/wp/wp-content/uploads/2021/09/example_doppler-200x114.png)](https://castle-engine.io/wp/wp-content/uploads/2021/09/example_doppler.png "Example showing Doppler effect") | | [![Editor Sound options](https://castle-engine.io/wp/wp-content/uploads/2021/09/editor_options_full-200x114.png)](https://castle-engine.io/wp/wp-content/uploads/2021/09/editor_options_full.png "Editor Sound options") | | [![Desining a collection of sounds](https://castle-engine.io/wp/wp-content/uploads/2021/09/sound_only-200x114.png)](https://castle-engine.io/wp/wp-content/uploads/2021/09/sound_only.png "Desining a collection of sounds") | We have a new shiny API to play sounds in _Castle Game Engine_! I think it’s a major improvement over the previous API (that revolved around `TSoundBuffer` and `TSound` classes). The new API is easier to use: - - The lifetime of instances is easier to grasp. You control the lifetime of everything, and there’s no need to deal with `TSound.OnRelease`. The new API is also perfect to visually set things up in the [CGE editor](https://castle-engine.io/manual_editor.php). It uses [behaviors](https://castle-engine.io/wp/2021/07/18/adding-behaviors-in-cge-editor-tcastlebillboard-tcastlesoundsource/) for spatial sounds. **The new classes, that you should use now for all sound loading and playing, are:** - [TCastleSound](https://castle-engine.io/apidoc-unstable/html/CastleSoundEngine.TCastleSound.html): The most important class, you should use this always when you want to play any sound. This is a new non-visual component that represents a sound file with some playback parameters. The most important properties are: - [URL](https://castle-engine.io/apidoc-unstable/html/CastleSoundEngine.TCastleSound.html#URL) — undoubtedly the most important property, set this to actually load the sound file. - [Stream](https://castle-engine.io/apidoc-unstable/html/CastleSoundEngine.TCastleSound.html#Stream) — optionally use “streaming”, which is an alternative loading method best suited for longer playing sounds (like music tracks). - [Volume](https://castle-engine.io/apidoc-unstable/html/CastleSoundEngine.TCastleSound.html#Volume) — how loud the sound is. This is multiplied by volume at `TCastlePlayingSound.Volume` and `TCastleSoundSource.Volume` and by spatial calculations. - [Pitch](https://castle-engine.io/apidoc-unstable/html/CastleSoundEngine.TCastleSound.html#Pitch) — sound playing speed. As with volume, the volume of `TCastleSound.Pitch` is multiplied by similar parameters controlled at `TCastlePlayingSound.Pitch` and `TCastleSoundSource.Pitch`. `TCastleSound` by itself doesn’t manage playing the sound. You have to use [SoundEngine.Play](https://castle-engine.io/apidoc-unstable/html/CastleSoundEngine.TSoundEngine.html#Play) to play the sound (the simplest way to play, for non-spatial sounds) or [TCastleSoundSource](https://castle-engine.io/apidoc-unstable/html/CastleBehaviors.TCastleSoundSource.html) (for sounds that can be spatial; assign to [TCastleSoundSource.Sound](https://castle-engine.io/apidoc-unstable/html/CastleBehaviors.TCastleSoundSource.html#Sound) for looping, use [TCastleSoundSource.Play](https://castle-engine.io/apidoc-unstable/html/CastleBehaviors.TCastleSoundSource.html#Play) for non-looping). `TCastleSound` also replaces previous `TSoundType` (`TSoundType` is now an alias of `TCastleSound`). So reading sounds from `sounds.xml` file and using [SoundEngine.SoundFromName](https://castle-engine.io/apidoc-unstable/html/CastleSoundEngine.TRepoSoundEngine.html#SoundFromName) just gives you ready `TCastleSound` instance. This XML file now becomes a new way to define _“a list of TCastleSound instances”_. Though you can also now ditch the manually-crafted XML files, and use a new approach we mention below — design a non-visual collection of components like `all_sounds.castle-component`. - [TCastleSoundSource](https://castle-engine.io/apidoc-unstable/html/CastleBehaviors.TCastleSoundSource.html): A way to play spatial (3D) sounds. - [TCastlePlayingSound](https://castle-engine.io/apidoc-unstable/html/CastleSoundEngine.TCastlePlayingSound.html): Optional, use if you need more control before and during the sound playback. Both `TCastleSoundSource` and `TCastleSound` can be created, configured and linked in the [CGE editor](https://castle-engine.io/manual_editor.php), e.g. when designing your state. You can hear the 3D sounds in the editor. You can also create and control them from code, as all CGE components. **All CGE examples have been upgraded to use the new approach for sounds.** - See all the examples in [examples/audio](https://github.com/castle-engine/castle-engine/tree/master/examples/audio) subdirectory. - In particular I recommend opening the [examples/audio/game\_3d\_sound](https://github.com/castle-engine/castle-engine/tree/master/examples/audio/game_3d_sound) demo. Aside from using new sound API, it has also been recently upgraded to use CGE editor and glTF intensively. - See also [examples/fixed\_camera\_game](https://github.com/castle-engine/castle-engine/tree/master/examples/fixed_camera_game) for a new approach to design a collection of sounds (a new, better approach than manually crafting XML files). In particular: **Editor sound features:** - - Drag-and-drop sound files on the viewport to automatically create a spatial sound: `TCastleTransform`, `TCastleSoundSource`, `TCastleSound`. - You can manage a collection of sounds independent of state/UI by simply using `TCastleComponent` as a design root and adding `TCastleSound` children. Save the resulting design to a file like `all_sounds.castle-component`. This is a great alternative to previous XML files to describe sounds which will soon be deprecated most likely. **Distance model changes:** - Our previous default [SoundEngine.DistanceModel](https://castle-engine.io/apidoc-unstable/html/CastleSoundEngine.TSoundEngine.html#DistanceModel) was poor (linear, which is not realistic). Now it is [dmInverse](https://castle-engine.io/apidoc-unstable/html/CastleSoundBase.html#dmInverse), and corresponds to FMOD default and OpenAL default. It’s the most natural model to play 3D spatial sounds. - Our default [MaxDistance](https://castle-engine.io/apidoc-unstable/html/CastleSoundEngine.TCastleSound.html#MaxDistance) was poor (1, equal `ReferenceDistance`, which means that there’s no attenuation with linear model at all). - Our possible [TSoundDistanceModel](https://castle-engine.io/apidoc-unstable/html/CastleSoundBase.html#TSoundDistanceModel) were not portable (they reflected OpenAL models closely, and did not reflect FMOD models). **Backward compatibility:** The sound API upgrade described here is _almost_ completely backward-compatible. Old classes still work, just make a warning about deprecation at compilation. The breaking changes are: - By default we use `dmInverse` model now, as it is much more natural for 3D sounds (and it is default in both OpenAL and FMOD too, for the same reason). If you want the same approach as in previous engine version, set `SoundEngine.DistanceModel := dmLinear`. Remember to adjust the `TCastleSound.MaxDistance` to sound good. - Our sounds XML file no longer supports “random aliases”. See the bottom of [upgrading wiki page](https://github.com/castle-engine/castle-engine/wiki/Upgrading-to-Castle-Game-Engine-7.0) for explanation. I suppose it was quite obscure feature, not used by many, and maintaining it is just too much cost in new API. If you miss this feature, I released a small unit that allows you to bring it back into your game: [use and adjust this in your projects](https://gist.github.com/michaliskambi/5f9e8df6021434a0dd47508a3cac1ec3). We also made a fix for [sounds defined in X3D files](https://castle-engine.io/x3d_implementation_sound.php): 3D sounds defined using X3D nodes are now correctly played in world coordinates, i.e. loading an X3D scene with sounds inside `TCastleScene`, and then transforming this `TCastleScene` makes a proper sound effect. Our [manual chapter about sound](https://castle-engine.io/manual_sound.php) has also been updated to reflect the information above. It’s admittedly very brief now, quite similar to this news post, but I hope to extend it into more tutorial-like description soon.