Table of Contents

Interface IAudioService

Namespace
BSGameLib.Game.Audio
Assembly
BSGameLib.Game.dll

Plays audio events that a game registers by id: sound effects and music, with volumes and fades.

public interface IAudioService : IUpdateable, IIdentifiable<Guid>, IEquatable<IUpdateable>, IDisposable
Inherited Members

Properties

ActiveSoundEvents

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

IReadOnlyCollection<string> ActiveSoundEvents { get; }

Property Value

IReadOnlyCollection<string>

CurrentMusicEventId

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

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.

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.

MusicPosition CurrentMusicPosition { get; }

Property Value

MusicPosition

EffectsVolume

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

float EffectsVolume { get; set; }

Property Value

float

MusicVolume

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

float MusicVolume { get; set; }

Property Value

float

RecentEvents

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

IReadOnlyList<AudioEventLogEntry> RecentEvents { get; }

Property Value

IReadOnlyList<AudioEventLogEntry>

Methods

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.

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).

bool HasAudio(string asset)

Parameters

asset string

Returns

bool

HasEvent(string)

Whether an event with this id is registered.

bool HasEvent(string eventId)

Parameters

eventId string

Returns

bool

PostEvent(string, AudioEventOptions?)

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

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.

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.

void RegisterEvent(AudioEventDefinition definition)

Parameters

definition AudioEventDefinition

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.

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.

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.

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.

void UnregisterAudio(string asset)

Parameters

asset string

UnregisterEvent(string)

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

void UnregisterEvent(string eventId)

Parameters

eventId string

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.

event Action<string> MusicFinished

Event Type

Action<string>