Sounds

Sounds#

namespace YSE

Public API of libYSE — sound playback, mixing, and 3D positional audio.

Entry points: YSE::System (lifecycle and audio device), YSE::Listener (3D origin), YSE::sound (a playable source), YSE::channel (mixing tree), YSE::reverb (positioned reverb zone), YSE::patcher (modular DSP graph), YSE::player (note sequencer). Sub-namespaces group domain-specific types: YSE::DSP for signal processing, YSE::MIDI for MIDI I/O, YSE::MUSIC for note / chord / motif primitives.

Note

Apart from their constructors, the oscillator and vcf classes must only be invoked from inside a DSP callback / process body.

namespace SOUND#

Enums

enum MESSAGE#

Values:

enumerator POSITION#

enumerator SPREAD#

enumerator VOLUME_VALUE#

enumerator VOLUME_TIME#

enumerator SPEED#

enumerator SIZE#

enumerator LOOP#

enumerator INTENT#

enumerator OCCLUSION#

enumerator DSP#

enumerator TIME#

enumerator RELATIVE#

enumerator DOPPLER#

enumerator PAN2D#

enumerator FADE_AND_STOP#

enumerator MOVE#

namespace YSE

Public API of libYSE — sound playback, mixing, and 3D positional audio.

Note

Apart from their constructors, the oscillator and vcf classes must only be invoked from inside a DSP callback / process body.

class sound#

A playable instance of an audio source.

Create one sound per voice you want in the scene. The audio source can be a file on disk (wav / ogg / flac and other formats depending on the platform), an in-memory buffer, a custom DSP source, or a patcher graph. Sounds can be mono, stereo, or multichannel.

Streaming sounds keep a dedicated buffer; non-streaming sounds share a buffer per file name — load the same file into multiple sounds and the underlying data is reused. Buffers without any remaining sound reference are flagged for deletion automatically.

See also

YSE::channel For grouping sounds.

See also

YSE::DSP::dspSourceObject For procedural audio sources.

See also

YSE::patcher For modular-graph sources.

Public Functions

sound()#

~sound()#

sound(const sound&) = delete#

Sounds are non-copyable.

The implementation holds a back-pointer to this interface object, so its address must not change. Move it through std::unique_ptr if you need transferable ownership.

void create(const char *fileName, channel *ch = nullptr, bool loop = false, float volume = 1.0f, bool streaming = false)#

Create a file-based sound.

Must be called before any other method on the sound. Calling twice on the same instance is a programming error.

Parameters:

fileName – Absolute path, or relative to the working directory.
ch – Channel to attach the sound to. nullptr routes through the global MainMix channel. Sounds can be moved later with moveTo.
loop – Loop continuously when true.
volume – Initial volume in the range [0.0, 1.0].
streaming – Stream from disk instead of loading the whole file. Use for large one-off assets; avoid for sounds played repeatedly.

void create(YSE::DSP::buffer &buffer, channel *ch = nullptr, bool loop = false, float volume = 1.f)#

Create a sound backed by an in-memory DSP buffer.

Useful when the audio data is generated or decoded by the application and also needs to be played back. The same buffer can back multiple sounds.

Parameters:

buffer – The audio data. The buffer must outlive the sound.
ch – Channel to attach to. nullptr uses MainMix.
loop – Loop continuously when true.
volume – Initial volume in the range [0.0, 1.0].

void create(std::vector<YSE::DSP::buffer> &buffer, channel *ch = nullptr, bool loop = false, float volume = 1.0f)#

Multichannel variant of the buffer-based create.

Identical to the single-buffer overload except that the source carries multiple channels (stereo or surround).

void create(YSE::DSP::dspSourceObject &dsp, channel *ch = nullptr, float volume = 1.0f)#

Create a sound driven by a custom DSP source.

Lets the application supply procedurally generated audio. Subclass YSE::DSP::dspSourceObject and pass the instance.

Warning

Lifetime contract. The caller owns dsp and must keep it alive until after the sound’s destructor has run AND the engine’s slow-pool delete tick has fired. The audio thread calls dsp.process(...) every callback while the sound is live. The implementation defensively nulls its pointer at the release transition, so destroying dsp slightly past release degrades to a silent nullptr read — but stack-local sources whose lifetime ends well before release can still cause a use-after-free. For tests or short-lived sources, allocate at file scope, hold via std::shared_ptr, or stop the sound and drain the manager before dsp goes out of scope.

Parameters:

dsp – The audio source. Must outlive the sound (see lifetime note).
ch – Channel to attach to. nullptr uses MainMix.
volume – Initial volume in the range [0.0, 1.0].

void create(YSE::patcher &patcher, channel *ch = nullptr, float volume = 1.0f)#

Create a sound driven by a patcher graph.

Parameters:

patcher – The patcher to run as an audio source. Must outlive the sound.
ch – Channel to attach to. nullptr uses MainMix.
volume – Initial volume in the range [0.0, 1.0].

bool isValid()#

Whether this interface has a live implementation.

Returns true for the entire lifetime of a successfully create-d sound. Primarily useful for debugging — callers don’t need to gate other methods on this.

void pos(const Pos &v)#: Set the position of this sound in the virtual scene.

Pos pos()#: Current position of this sound.

void spread(float value)#

Spread the channels of a multichannel sound across the stereo or surround field.

Has no audible effect on mono sources. value is the distance between individual channels in the listener’s space.

float spread()#: Current channel spread of a multichannel sound.

void speed(float value)#

Set the playback speed.

Alters pitch — playback at 2.0 is one octave up, 0.5 is one octave down. Doppler shift from listener/sound velocity is layered on top unless doppler(false) is set. Negative values play the sound backwards (not supported for streaming sounds, since that would thrash the disk).

Note

The internal value never reaches exactly zero — perfectly silent playback at static DC can damage speakers.

float speed()#: Current playback speed.

void size(float value)#

Set the audible radius of the sound.

value controls the rolloff distance: beyond this radius the sound fades out.

float size()#: Current audible radius.

void looping(bool value)#: Set whether the sound loops continuously.

bool looping()#: Whether the sound is currently set to loop.

void volume(float value, unsigned int time = 0)#

Set the volume of this sound, optionally with a fade.

Parameters:

value – Target volume in the range [0.0, 1.0].
time – Fade duration in milliseconds. 0 (default) sets the volume immediately.

float volume()#

Current volume.

May differ from the most recently requested target volume if a non-zero fade time was supplied and the fade is still in progress.

void fadeAndStop(unsigned int time)#: Fade out over time milliseconds, then stop.

void play()#: Start playback.

bool isPlaying()#: Whether the sound is currently playing.

void pause()#

Pause playback.

play() resumes from the current position.

bool isPaused()#: Whether the sound is currently paused.

void stop()#: Stop playback and rewind to the start of the source.

bool isStopped()#: Whether the sound is currently stopped.

void toggle()#

Cycle between playing / paused / stopped.

Playing → paused, paused → playing, stopped → playing.

void restart()#: Restart from the beginning regardless of current position.

void time(float value)#

Seek to a position in the source file.

Distinct from pos — that controls position in the virtual scene.

Parameters:: value – New playhead position in samples, in [0, length()].

float time()#: Current playhead position in samples.

unsigned int length()#: Length of the source in samples.

void relative(bool value)#

Make the sound relative to the listener.

Relative sounds move with the listener — libYSE’s idiomatic replacement for “2D” sounds. Typical for GUI clicks and background music. Relative sounds can still move within the listener’s frame.

bool relative()#: Whether the sound is relative to the listener.

void doppler(bool value)#

Enable or disable doppler shift for this sound.

See also

YSE::System For the global doppler scale.

bool doppler()#: Whether doppler is enabled for this sound.

void pan2D(bool value)#

Shorthand for relative + listener-origin position + no doppler.

Equivalent to relative(true); pos(Pos(0,0,0)); doppler(false);.

bool pan2D()#: Whether the sound is in 2D-pan mode.

bool isStreaming()#: Whether the sound is streamed from disk or network (vs loaded into memory).

bool isReady()#

Whether the sound is ready for playback.

Loading happens asynchronously so the audio callback isn’t blocked, so there is a brief window after create where the sound is not yet ready. Callers do not need to wait for this — calling play() on a not-yet-ready sound simply queues the start.

void occlusion(bool value)#

Enable sound occlusion for this sound.

Requires an occlusion callback installed via System().occlusionCallback(...).

bool occlusion()#: Whether sound occlusion is active for this sound.

void moveTo(channel &target)#

Move this sound to a different channel.

Parameters:: target – The new parent channel.

void setDSP(YSE::DSP::dspObject *value)#: Attach a DSP effect chain to this sound.

YSE::DSP::dspObject *getDSP()#: Currently attached DSP effect chain, or nullptr if none.

Private Members

SOUND::implementationObject *pimpl#

Pos _pos#

Flt _spread#

Flt _volume#

Flt _speed#

Flt _size#

Bool _loop#

Bool _relative#

Bool _doppler#

Bool _pan2D#

Bool _occlusion#

UInt _fadeAndStopTime#

DSP::dspObject *_dsp#

channel *_parent#

Sounds

Contents

Sounds#