Class TCastleSound

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description. Showing description inherited from TCastleComponent.PropertySections.

Section where to show property in the editor.

Load sound contents from given TStream.

Parameters

AStream

Stream to load. When loading, we rewind stream positon 0 zero, and read the whole stream.

MimeType

Valid MIME type that indicates a sound file type, like audio/wav or audio/ogg. See TUrlFile.MimeType implementation for currently supported MIME file types.

Duration of the sound, in seconds. -1 if not loaded yet. The sound is loaded once you set Url and don't get any loading exceptions.

Sound data format (disregarding compression on top of it), for informational purposes. Undefined if not loaded yet. The sound is loaded once you set Url and don't get any loading exceptions.

Frequency (sample rate) of the loaded sound file. 0 if not loaded yet. The sound is loaded once you set Url and don't get any loading exceptions.

Warning: this symbol is specific to some platform.

Force a minimum sound loudness, despite what volume would be calculated by the spatialization. This can be used to force sound to be audible, even when it's far away from the listener.

It must be in [0, 1] range. By default it is 0.

Warning: this symbol is specific to some platform.

Force a maximum sound loudness, despite what volume would be calculated by the spatialization. This can be used to limit sound volume, regardless of the distance attenuation calculation.

It must be in [0, 1] range. By default it is 1.

URL of the sound file. Set this to load a new sound buffer, you can set to '' to clear the sound buffer.

If you plan to change Stream, note that it is best to do it before setting Url. Changing Stream while Url is already set means that the sound is reloaded.

Play sound using streaming. This means that the sound is gradually decompressed in memory, which means that loading time is much smaller, although there may be a small overhead on CPU during playback. Streaming is usually a good idea for longer sounds, e.g. music tracks.

See also TSoundLoading for details.

If you plan to change Stream, note that it is best to do it before setting Url. Changing Stream while Url is already set means that the sound is reloaded.

Volume (how loud the sound is).

Use this to indicate that e.g. a plane engine is louder than a mouse squeak (when heard from the same distance). Note: Do not make the actual sound data (in sound files) louder/more silent to express that something is louder/more silent in reality. This would usually lower the sound quality. Instead, keep your sound file data at max loudness ("normalized"), and use this property to adjust the volume associated with the sound.

The effective sound volume is a multiplication of TCastleSound.Volume, TCastlePlayingSound.Volume and TCastleSoundSource.Volume (if the sound is played through TCastleSoundSource). It is also affected by spatial calculations (if the sound is played through TCastleSoundSource with TCastleSoundSource.Spatial = True) and finally by a master SoundEngine.Volume.

Any value > 0 is allowed. The default is 1. Note that, while values > 1 are allowed, but some sound backends (like OpenAL) may clip the resulting sound volume (after all volume influences, including spatial calculations are done) to 1.0.

Sound playing speed.

The effective sound pitch is a multiplication of TCastleSound.Pitch, TCastlePlayingSound.Pitch and TCastleSoundSource.Pitch (if the sound is played through TCastleSoundSource).

Changing this naturally also changes the audible sound. Each reduction by 50 percent equals a pitchshift of -12 semitones (one octave reduction). Each doubling equals a pitch shift of 12 semitones (one octave increase).

Any value > 0 is allowed.

How important is the sound, between 0.0 (least important) to 1.0 (most important).

The sound engine sometimes has to interrupt (or even not start at all) playback of some non-important sound, to have a good performance of audio mixing. In these cases, the sound with higher priority always "wins" over sound with lower priority. That is, sound with lower priority will be interrupted (the slot will be "stolen") to make room for sound with higher priority.

Note: Many sound APIs (Unity, FMOD, Wwise, X3D...) have a similar property, with inconsistent range (minimum, maximum) and inconsistent meaning (some say "lower is more important", some say "higher is more important"). Our treatment of this property is similar to X3D, as it satisfies a number of important points: it defines easy to remember min/max (0 and 1), it is agnostic to the underlying precision (e.g. it has to map to 257 levels in FMOD, 100 levels in Wwise). Also, "higher is more important" seems just more natural.

Spatial sound is fully audible (with Volume) at this distance. See TSoundDistanceModel for a description how distance affects the sound volume.

Distance at which sound volume stops attenuating. For the linear distance model (SoundEngine.DistanceModel = dmLinear) this is also a distance at which sound volume drops to zero (completely silent). See TSoundDistanceModel for a description how distance affects the sound volume.