Class SoundEffect

Namespace

Microsoft.Xna.Framework.Audio

Assembly

MonoGame.Framework.dll

Represents a loaded sound resource.

public sealed class SoundEffect : IDisposable

Inheritance

object

SoundEffect

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

A SoundEffect represents the buffer used to hold audio data and metadata. SoundEffectInstances are used to play from SoundEffects. Multiple SoundEffectInstance objects can be created and played from the same SoundEffect object.

The only limit on the number of loaded SoundEffects is restricted by available memory. When a SoundEffect is disposed, all SoundEffectInstances created from it will become invalid.

SoundEffect.Play() can be used for 'fire and forget' sounds. If advanced playback controls like volume or pitch is required, use SoundEffect.CreateInstance().

Constructors

SoundEffect(byte[], int, AudioChannels)

Create a sound effect.

public SoundEffect(byte[] buffer, int sampleRate, AudioChannels channels)

Parameters

buffer byte[]

The buffer with the sound data.

sampleRate int

The sound data sample rate in hertz.

channels AudioChannels

The number of channels in the sound data.

Remarks

This only supports uncompressed 16bit PCM wav data.

SoundEffect(byte[], int, int, int, AudioChannels, int, int)

Create a sound effect.

public SoundEffect(byte[] buffer, int offset, int count, int sampleRate, AudioChannels channels, int loopStart, int loopLength)

Parameters

buffer byte[]

The buffer with the sound data.

offset int

The offset to the start of the sound data in bytes.

count int

The length of the sound data in bytes.

sampleRate int

The sound data sample rate in hertz.

channels AudioChannels

The number of channels in the sound data.

loopStart int

The position where the sound should begin looping in samples.

loopLength int

The duration of the sound data loop in samples.

Remarks

This only supports uncompressed 16bit PCM wav data.

Properties

DistanceScale

Gets or sets the scale of distance calculations.

public static float DistanceScale { get; set; }

Property Value

float

Remarks

DistanceScale defaults to 1.0 and must be greater than 0.0.

Higher values reduce the rate of falloff between the sound and listener.

DopplerScale

Gets or sets the scale of Doppler calculations applied to sounds.

public static float DopplerScale { get; set; }

Property Value

float

Remarks

DopplerScale defaults to 1.0 and must be greater or equal to 0.0

Affects the relative velocity of emitters and listeners.

Higher values more dramatically shift the pitch for the given relative velocity of the emitter and listener.

Duration

Gets the duration of the SoundEffect.

public TimeSpan Duration { get; }

Property Value

TimeSpan

IsDisposed

Indicates whether the object is disposed.

public bool IsDisposed { get; }

Property Value

bool

MasterVolume

Gets or sets the master volume scale applied to all SoundEffectInstances.

public static float MasterVolume { get; set; }

Property Value

float

Remarks

Each SoundEffectInstance has its own Volume property that is independent to SoundEffect.MasterVolume. During playback SoundEffectInstance.Volume is multiplied by SoundEffect.MasterVolume.

This property is used to adjust the volume on all current and newly created SoundEffectInstances. The volume of an individual SoundEffectInstance can be adjusted on its own.

Name

Gets or sets the asset name of the SoundEffect.

public string Name { get; set; }

Property Value

string

SpeedOfSound

Returns the speed of sound used when calculating the Doppler effect..

public static float SpeedOfSound { get; set; }

Property Value

float

Remarks

Defaults to 343.5. Value is measured in meters per second.

Has no effect on distance attenuation.

Methods

CreateInstance()

Creates a new SoundEffectInstance for this SoundEffect.

public SoundEffectInstance CreateInstance()

Returns

SoundEffectInstance

A new SoundEffectInstance for this SoundEffect.

Remarks

Creating a SoundEffectInstance before calling SoundEffectInstance.Play() allows you to access advanced playback features, such as volume, pitch, and 3D positioning.

Dispose()

Releases the resources held by this SoundEffect.

public void Dispose()

~SoundEffect()

Releases unmanaged resources and performs other cleanup operations before the SoundEffect is reclaimed by garbage collection.

protected ~SoundEffect()

FromFile(string)

Creates a new SoundEffect object based on the specified data stream. This internally calls FromStream(Stream).

public static SoundEffect FromFile(string path)

Parameters

path string

The path to the audio file.

Returns

SoundEffect

The SoundEffect loaded from the given file.

Remarks

The stream must point to the head of a valid wave file in the RIFF bitstream format. The formats supported are:

• 8-bit unsigned PCM16-bit signed PCM24-bit signed PCM32-bit IEEE float PCMMS-ADPCM 4-bit compressedIMA/ADPCM (IMA4) 4-bit compressed

FromStream(Stream)

Creates a new SoundEffect object based on the specified data stream.

public static SoundEffect FromStream(Stream stream)

Parameters

stream Stream

A stream containing the wave data.

Returns

SoundEffect

A new SoundEffect object.

Remarks

The stream must point to the head of a valid wave file in the RIFF bitstream format. The formats supported are:

• 8-bit unsigned PCM16-bit signed PCM24-bit signed PCM32-bit IEEE float PCMMS-ADPCM 4-bit compressedIMA/ADPCM (IMA4) 4-bit compressed

GetSampleDuration(int, int, AudioChannels)

Returns the duration for 16-bit PCM audio.

public static TimeSpan GetSampleDuration(int sizeInBytes, int sampleRate, AudioChannels channels)

Parameters

sizeInBytes int

The length of the audio data in bytes.

sampleRate int

Sample rate, in Hertz (Hz). Must be between 8000 Hz and 48000 Hz

channels AudioChannels

Number of channels in the audio data.

Returns

TimeSpan

The duration of the audio data.

GetSampleSizeInBytes(TimeSpan, int, AudioChannels)

Returns the data size in bytes for 16bit PCM audio.

public static int GetSampleSizeInBytes(TimeSpan duration, int sampleRate, AudioChannels channels)

Parameters

duration TimeSpan

The total duration of the audio data.

sampleRate int

Sample rate, in Hertz (Hz), of audio data. Must be between 8,000 and 48,000 Hz.

channels AudioChannels

Number of channels in the audio data.

Returns

int

The size in bytes of a single sample of audio data.

Initialize()

Initializes the sound system for SoundEffect support. This method is automatically called when a SoundEffect is loaded, a DynamicSoundEffectInstance is created, or Microphone.All is queried. You can however call this method manually (preferably in, or before the Game constructor) to catch any Exception that may occur during the sound system initialization (and act accordingly).

public static void Initialize()

Play()

Gets an internal SoundEffectInstance and plays it.

public bool Play()

Returns

bool

True if a SoundEffectInstance was successfully played, false if not.

Remarks

Play returns false if more SoundEffectInstances are currently playing then the platform allows.

To loop a sound or apply 3D effects, call SoundEffect.CreateInstance() and SoundEffectInstance.Play() instead.

SoundEffectInstances used by SoundEffect.Play() are pooled internally.

Play(float, float, float)

Gets an internal SoundEffectInstance and plays it with the specified volume, pitch, and panning.

public bool Play(float volume, float pitch, float pan)

Parameters

volume float

Volume, ranging from 0.0 (silence) to 1.0 (full volume). Volume during playback is scaled by SoundEffect.MasterVolume.

pitch float

Pitch adjustment, ranging from -1.0 (down an octave) to 0.0 (no change) to 1.0 (up an octave).

pan float

Panning, ranging from -1.0 (left speaker) to 0.0 (centered), 1.0 (right speaker).

Returns

bool

True if a SoundEffectInstance was successfully created and played, false if not.

Remarks

Play returns false if more SoundEffectInstances are currently playing then the platform allows.

To apply looping or simulate 3D audio, call SoundEffect.CreateInstance() and SoundEffectInstance.Play() instead.

SoundEffectInstances used by SoundEffect.Play() are pooled internally.