Class SdlAudioService

Namespace

BSGameLib.Game.Audio

Assembly

BSGameLib.Game.dll

The default audio service, built on SDL3_mixer. It opens the audio device when the first sound plays.

public sealed class SdlAudioService : Component, IAudioService, IUpdateable, IIdentifiable<Guid>, IEquatable<IUpdateable>, IDisposable, IAttachOnGameStart

Inheritance

object

Component

SdlAudioService

Implements

IAudioService

IUpdateable

IIdentifiable<Guid>

IEquatable<IUpdateable>

IDisposable

IAttachOnGameStart

Inherited Members

Component.Id

Component.Equals(IUpdateable)

Component.Equals(object)

Component.GetHashCode()

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

SdlAudioService(ILogger<SdlAudioService>)

Created by dependency injection.

public SdlAudioService(ILogger<SdlAudioService> logger)

Parameters

logger ILogger<SdlAudioService>

Properties

ActiveSoundEvents

The ids of the sound effect, ambience and voice events that have a track still playing. Music is not listed.

public IReadOnlyCollection<string> ActiveSoundEvents { get; }

Property Value

IReadOnlyCollection<string>

CurrentMusicEventId

The id of the music event playing, or null when no music is playing.

public string CurrentMusicEventId { get; }

Property Value

string

CurrentMusicPhase

Which part of the music is playing: its intro, its body (Loop, also for music that is one file) or its ending. None without music. It changes when the next part is queued to the audio device, a few tens of milliseconds before it is heard.

public MusicPhase CurrentMusicPhase { get; }

Property Value

MusicPhase

CurrentMusicPosition

Which part of the music is playing, how far into it, and how long it is, for a progress bar. Approximate: it runs a few tens of milliseconds ahead of what is heard. For the body, how far into the current pass. None and zeros without music.

public MusicPosition CurrentMusicPosition { get; }

Property Value

MusicPosition

EffectsVolume

The effects volume, from 0 to 1. It applies to effects started after the change.

public float EffectsVolume { get; set; }

Property Value

float

MusicVolume

The music volume, from 0 to 1. Changing it adjusts the music playing now.

public float MusicVolume { get; set; }

Property Value

float

RecentEvents

The latest changes to events, oldest first. Only the most recent are kept.

public IReadOnlyList<AudioEventLogEntry> RecentEvents { get; }

Property Value

IReadOnlyList<AudioEventLogEntry>

Methods

Attach(IGame)

Adds the service to the game as a component, so that Update(IGameTime) runs each frame.

public void Attach(IGame game)

Parameters

game IGame

Dispose()

Stops all playback, frees the cached audio and closes the device. Safe to call more than once.

public void Dispose()

FinishMusic(int)

Ends the music the way it was written to end. Music with an EndingAsset plays on to the end of the current pass of its body, or of its intro, then plays the ending, with no gap, and stops. Music without one fades out over fadeOutMilliseconds, or stops at once for 0. Posting the same music again while its ending plays starts it again from its intro.

public void FinishMusic(int fadeOutMilliseconds = 0)

Parameters

fadeOutMilliseconds int

HasAudio(string)

Whether sound is registered under this asset name by RegisterAudio(string, ReadOnlyMemory<float>, int, int).

public bool HasAudio(string asset)

Parameters

asset string

Returns

bool

HasEvent(string)

Whether an event with this id is registered.

public bool HasEvent(string eventId)

Parameters

eventId string

Returns

bool

PostEvent(string, AudioEventOptions?)

Starts an event playing. An unknown id is logged and does nothing.

public void PostEvent(string eventId, AudioEventOptions? options = null)

Parameters

eventId string

options AudioEventOptions?

RegisterAudio(string, ReadOnlyMemory<float>, int, int)

Registers sound the game made itself (synthesised, generated, recorded or decoded) as an audio asset called asset. An event whose Asset is that name then plays it as it would a file, with the same volumes, categories and ducking. Registering again under the same name replaces the sound; anything already playing the old one finishes it. The samples are copied.

public void RegisterAudio(string asset, ReadOnlyMemory<float> samples, int sampleRate, int channels = 1)

Parameters

asset string

The name events use for it. Checked before files of the same name.

samples ReadOnlyMemory<float>

Samples from -1 to 1, interleaved when there is more than one channel.

sampleRate int

Frames per second, such as 44100.

channels int

1 for mono, 2 for stereo.

Remarks

Memory rather than a span so the interface can be mocked: proxies can't take spans.

RegisterEvent(AudioEventDefinition)

Registers an event, replacing any registered under the same id.

public void RegisterEvent(AudioEventDefinition definition)

Parameters

definition AudioEventDefinition

Exceptions

ArgumentException

The id or the asset is blank, an event that isn't music has an intro or an ending, or a duck is positive or set on music.

SeekMusic(MusicPhase, TimeSpan)

Continues the music from position into part, clamped to that part, with no fade: for scrubbing in an editor, such as to just before the end of the loop to check its join. Music that is one file can seek only within its Loop. An ending asked for with FinishMusic(int) stays asked for. Returns false without music, for a part the music doesn't have, or when the file can't seek.

public bool SeekMusic(MusicPhase part, TimeSpan position)

Parameters

part MusicPhase

position TimeSpan

Returns

bool

StopAll(AudioEventCategory?, int)

Stops the events in category, or all events when it is null. The fade-out applies to each.

public void StopAll(AudioEventCategory? category = null, int fadeOutMilliseconds = 0)

Parameters

category AudioEventCategory?

fadeOutMilliseconds int

StopEvent(string, int)

Stops an event. A fade-out time in milliseconds makes it stop over that time; 0 stops it at once.

public void StopEvent(string eventId, int fadeOutMilliseconds = 0)

Parameters

eventId string

fadeOutMilliseconds int

UnregisterAudio(string)

Removes sound registered by RegisterAudio(string, ReadOnlyMemory<float>, int, int). Anything playing it finishes; events that name it look for a file again. An unknown name does nothing.

public void UnregisterAudio(string asset)

Parameters

asset string

UnregisterEvent(string)

Removes an event. Anything playing it is stopped. An unknown id does nothing.

public void UnregisterEvent(string eventId)

Parameters

eventId string

Update(IGameTime)

Destroys the tracks that finished on the audio thread, which cannot free them itself, opens the files music with an intro or ending will need next, logs an ending starting, and raises MusicFinished.

public override void Update(IGameTime gameTime)

Parameters

gameTime IGameTime

Events

MusicFinished

Raised, with the event's id, when music ends by itself: its ending has played, or music that doesn't loop has run out. A stop, or other music replacing it, doesn't raise it. Raised during Update(IGameTime), on the game's thread.

public event Action<string> MusicFinished

Event Type

Action<string>