audio
Loading and playing sounds.
One mixer opens against the default playback device when the engine starts. A
Source is a loaded sound bound to its own track, static when it decodes
fully into memory for short effects, streaming when it decodes as it plays for
music. Sources carry the usual controls: play, pause, resume, stop, rewind,
seek and tell, volume, pitch, looping, and a 3D position for panning and
distance.
Pitch and speed move together through the track's frequency ratio; there is no independent time stretch. SDL_mixer keeps its listener at the origin, so a movable listener is emulated by offsetting each positioned source by the stored listener position.
If no audio device opens (a headless or CI machine), the mixer stays off and every call here becomes a safe no-op, so a game still builds and runs.
type SourceType = enum
Static decodes fully into memory for short sounds; stream decodes as it
plays for music.
Values
-
stStatic -
stStream
type Source = ref object
A playable sound: a loaded MIX_Audio bound to its own MIX_Track.
initAudio ¶
proc initAudio(nim2d: Nim2d)
Open the audio device and the mixer. Called once by newNim2d. If no device
is available it leaves audio off rather than failing, and it is safe to call
again as a no-op. Audio reopens cleanly after shutdownAudio.
Parameters
-
nim2d(Nim2d)
shutdownAudio ¶
proc shutdownAudio(nim2d: Nim2d)
Stop all sound, destroy the mixer and close the device. Called from the
play teardown. Destroying the mixer also frees every track and sound, so
the handles outstanding sources hold are dropped here to keep later calls
on them, and destroy, safe no-ops.
Parameters
-
nim2d(Nim2d)
audioAvailable ¶
proc audioAvailable(nim2d: Nim2d): bool
Whether an audio device opened. False on machines with no sound output.
Parameters
-
nim2d(Nim2d)
Returns
bool
newSource ¶
proc newSource(nim2d: Nim2d; filename: string; kind: SourceType = stStatic): Source
Load a sound from a file. WAV, OGG, MP3, FLAC and tracker formats decode
through SDL_mixer. With audio off this returns a source whose controls do nothing.
Parameters
-
nim2d(Nim2d) -
filename(string) -
kind(SourceType)
Returns
Source
play ¶
proc play(src: Source)
Start the source from the beginning, or restart it if already playing.
The loop count is set through the play options, because setting it on a stopped track has no lasting effect.
Parameters
-
src(Source)
pause ¶
proc pause(src: Source)
Pause playback, keeping the current position.
Parameters
-
src(Source)
resume ¶
proc resume(src: Source)
Resume a paused source from where it stopped.
Parameters
-
src(Source)
stop ¶
proc stop(src: Source)
Stop playback and reset the position to the start.
Parameters
-
src(Source)
rewind ¶
proc rewind(src: Source)
seek ¶
proc seek(src: Source; seconds: float)
Jump to a position in seconds.
Parameters
-
src(Source) -
seconds(float)
tell ¶
proc tell(src: Source): float
The current playback position in seconds.
Parameters
-
src(Source)
Returns
float
isPlaying ¶
proc isPlaying(src: Source): bool
True while the source is actively mixing (not stopped, not paused).
Parameters
-
src(Source)
Returns
bool
isPaused ¶
proc isPaused(src: Source): bool
True while the source is paused.
Parameters
-
src(Source)
Returns
bool
setVolume ¶
proc setVolume(src: Source; volume: float)
Set per-source gain, 0.0 silent to 1.0 full; values above 1.0 amplify.
Parameters
-
src(Source) -
volume(float)
getVolume ¶
proc getVolume(src: Source): float
setPitch ¶
proc setPitch(src: Source; pitch: float)
Set the playback speed and pitch together, 1.0 is normal. There is no
independent time stretch.
Parameters
-
src(Source) -
pitch(float)
getPitch ¶
proc getPitch(src: Source): float
The source's current pitch/speed ratio.
Parameters
-
src(Source)
Returns
float
setLooping ¶
proc setLooping(src: Source; loop: bool)
Loop forever when true, play once when false.
Parameters
-
src(Source) -
loop(bool)
isLooping ¶
proc isLooping(src: Source): bool
duration ¶
proc duration(src: Source): float
Length of the sound in seconds, or -1 if unknown or infinite.
Parameters
-
src(Source)
Returns
float
listenerRelative ¶
func listenerRelative(wx, wy, wz, lx, ly, lz: float): tuple[x, y, z: float]
A source's position relative to the listener, with screen y (down) flipped
to the mixer's y (up). Used to emulate a movable listener.
Parameters
-
wx(float) -
wy(float) -
wz(float) -
lx(float) -
ly(float) -
lz(float)
Returns
tuple[x, y, z: float]
setPosition ¶
proc setPosition(src: Source; x, y: float; z: float = 0)
Place the source in space for distance attenuation and stereo panning,
relative to the listener.
Parameters
-
src(Source) -
x(float) -
y(float) -
z(float)
clearPosition ¶
proc clearPosition(src: Source)
destroy ¶
proc destroy(src: Source)
Stop the source and free its track and audio data.
Parameters
-
src(Source)
setVolume ¶
proc setVolume(nim2d: Nim2d; volume: float)
Master gain applied to everything the mixer outputs.
Parameters
-
nim2d(Nim2d) -
volume(float)
getVolume ¶
proc getVolume(nim2d: Nim2d): float
stopAll ¶
proc stopAll(nim2d: Nim2d)
setListenerPosition ¶
proc setListenerPosition(nim2d: Nim2d; x, y: float; z: float = 0)
Move the listener. Every positioned source is re-offset so panning follows.
Parameters
-
nim2d(Nim2d) -
x(float) -
y(float) -
z(float)
getListenerPosition ¶
proc getListenerPosition(nim2d: Nim2d): tuple[x, y, z: float]
The current listener position.
Parameters
-
nim2d(Nim2d)
Returns
tuple[x, y, z: float]