Core

Core#

System#

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.

Typedefs

typedef float (*occlusionFunc)(const Pos &source, const Pos &listener)#

Signature of a user-supplied sound-occlusion callback.

Given the source and listener positions, return the occlusion amount in the range [0.0, 1.0]: 0 means no obstruction (full volume), 1 means fully occluded (silent). The engine applies it as a gain duck (finalGain *= 1 - occlusion). Typical implementations raycast through game-world geometry. See system::occlusionCallback for the threading contract — this runs on the control thread, not the audio callback.

Functions

system &System()#

Access the singleton system object.

< This macro is added to all public class declarations.

Variables

const std::string VERSION = "2.4.0"#

class system#

Engine lifecycle, audio device control, and global effect settings.

system is the top-level entry point for libYSE. Construct nothing directly — access the singleton through the System() free function. The typical lifecycle is:

System().init() once at startup.
System().update() every frame.
System().close() once at shutdown.

Between init and close, the engine manages an audio device, runs the DSP graph, and dispatches messages to playing sounds.

See also

YSE::System

See also

YSE::listener

Active device readouts

Live state of the currently open audio device.

Each returns 0 when no device is open (pre-init, after close(), or under initOffline()). Host applications use these to render device-info UI without having to re-enumerate YSE::device descriptors, and to survive device reconnects cleanly.

double getActiveSampleRate()#: Currently negotiated sample rate in Hz.

int getActiveBufferSize()#

Currently negotiated audio buffer size in frames.

This is the device’s frames-per-callback (PortAudio’s framesPerBuffer / Oboe’s framesPerBurst) — NOT the engine’s internal STANDARD_BUFFERSIZE, which may differ.

int getActiveOutputLatency()#

Currently negotiated output latency in samples.

Convert to milliseconds with (latency / sampleRate) * 1000.

Domain clocks (issue #249)

A set of named musical (beat) clocks, each a beat accumulator derived from the audio callback.

Every audio block a clock advances by blockSeconds × tempo / 60 at its current tempo, so beat position is the running integral of tempo — no absolute-time schedule. Because all clocks derive from the single sample clock, polytemporal relationships stay exact and deterministic. Tempo is a playable, rampable control.

Threading. createClock / destroyClock / setTempo are control-thread operations; beatPosition / currentTempo may be read from the UI thread at frame rate (e.g. for a playhead). None of them run on or block the audio callback.

bool createClock(const std::string &name, float initialTempo = 120.f)#

Create a domain clock.

Parameters:

name – Unique domain name. Empty names are rejected.
initialTempo – Starting tempo in BPM (default 120).

Returns:

true on success; false if the name is empty or a live clock already owns it (first registration wins).

void destroyClock(const std::string &name)#

Destroy a domain clock.

No-op for an unknown name.

The clock stops being visible to queries immediately; its beat/tempo advancement stops on the next audio callback.

bool clockExists(const std::string &name)#: Whether a live domain clock with name exists.

system &setTempo(const std::string &name, float bpm, float rampSeconds = 0.f)#

Ramp a domain clock’s tempo toward bpm over rampSeconds.

Instant when rampSeconds is 0; otherwise linear. Tempo is a played control signal — call it as often as you like. It is not clamped: 0 pauses the clock and a negative tempo runs it backwards. No-op for an unknown name.

double beatPosition(const std::string &name)#: Current beat position (running integral of tempo) of a clock, or 0 for an unknown name.

float currentTempo(const std::string &name)#: Current tempo in BPM of a clock, or 0 for an unknown name.

Public Functions

system()#

bool init()#

Initialise the engine and open the default audio device.

Note

Threading. This call runs on and defines the engine’s control thread. Call update() and close() from the same thread. The control-thread identity is captured here and never re-derived, so driving init() and update() from different threads silently loses the named-bus inline fast path — see the update() threading note (issue #290).

Returns:: true on success, false if no device could be opened.

bool initOffline()#

Initialise the engine without opening an audio device.

For benchmarks, automated tests, and headless tooling that need a fully-configured engine but no PortAudio stream — same channel tree, same DSP graph, no audio thread. Once initialised this way, drive the engine via System().renderOffline(blocks) rather than the audio callback.

Returns:: true on success.

void renderOffline(int blocks)#

Render N audio blocks synchronously on the calling thread.

Runs the same callback body the audio thread executes in production — manager update, channel-tree DSP, channel mixing, reverb — for blocks × STANDARD_BUFFERSIZE samples worth of output, which is discarded. Use only after initOffline(); driving this concurrently with a live audio thread would race the manager-update path.

void update()#

Pump engine state.

Call once per frame from the main thread. Drives message delivery, sound state transitions, virtualisation decisions, and listener velocity calculations.

Note

Threading. update() must be called from the same thread that called init() — the engine’s single control thread. That identity is frozen when the engine initialises (not re-derived per tick) and decides who may dispatch control-rate (T_GUI) named-bus publishes inline; a publish from any other thread is instead deferred to the next update() tick to keep the per-object message queues single-producer (issue #193). Driving init() and update() from different threads is unsupported: it stays functionally correct — every publish simply takes the deferred path and is dispatched on whichever thread runs update() — but permanently forfeits the inline fast path, because the control thread is captured at init() rather than followed from update() (issue #290).

void close()#: Shut down the engine and release the audio device.

void pause()#

Pause audio output.

The engine keeps running but the device is silent.

pause() closes the audio stream, so the audio tick stops draining the lock-free control-to-audio inboxes (per-object message queues and the managers’ toLoadInboxes). Interface setters and object creation called while paused keep enqueuing onto those queues; the messages are held and delivered in order on resume(), not dropped. This is intentional — the queues carry ordered discrete commands (play/stop, position, load-handoff pointers), so silently dropping them would corrupt state, unlike the latest-value-wins parameter queues (NamedBus, patcher) which do cap.

The consequence is unbounded memory growth if an app pushes a very large number of setter/creation calls while paused: lfQueue allocates doubling-size blocks on demand and never frees them, so the peak retained capacity persists for the queue’s lifetime even after the backlog drains. All allocation happens producer-side on the control thread, so this never violates audio-thread real-time discipline. Applications that drive a heavy control-rate workload should keep the engine running (leave the device open) rather than pausing, or simply avoid issuing large batches of setters while paused. See issue #289.

void resume()#: Resume audio output after pause().

int missedCallbacks()#

Number of audio callbacks that have failed to complete on time.

A non-zero value indicates the audio thread is starved or the device has disconnected. Useful as a watchdog signal for autoReconnect.

reverb &getGlobalReverb()#

Access the global reverb.

Disabled by default. When enabled, it acts as the fallback reverb at any position not covered by a positioned reverb zone. Partially rolled-off reverb zones are mixed against the global reverb.

const std::vector<device> &getDevices()#: All audio output devices visible to the engine.

Note

Only available when libYSE is linked as a static library. When linked dynamically, use getNumDevices / getDevice instead to avoid leaking the standard-library std::vector across the ABI boundary.

unsigned int getNumDevices()#: Number of audio output devices available.

const device &getDevice(unsigned int nr)#: Audio device at index nr.

void openDevice(const deviceSetup &object, CHANNEL_TYPE conf = CT_AUTO)#

Open an audio device.

Parameters:

object – Device + host + sample-rate configuration.
conf – Speaker layout. CT_AUTO picks stereo when possible.

void closeCurrentDevice()#: Close the currently open audio device.

const std::string &getDefaultDevice()#: Name of the platform default audio device.

const std::string &getDefaultHost()#

Name of the platform default audio host (e.g.

WASAPI, ALSA).

system &occlusionCallback(float (*func)(const YSE::Pos&, const YSE::Pos&))#

Install a sound-occlusion callback.

The engine calls the function for every occlusion-enabled sound to compute how much it should be attenuated by world geometry. The returned factor is applied as a gain duck (finalGain *= 1 - occlusion). Typical implementations issue a raycast through the game physics engine. Pass nullptr to disable.

See also

occlusionFunc

Note

Threading. The callback runs on the thread that calls System().update() (the application/control thread), once per occlusion-enabled sound per update tick — never on the audio callback thread. The result is delivered to the audio thread over the lock-free sound message queue. This means a raycast that takes locks or allocates cannot stall the audio callback (issue #209), but it also means the callback must not block update() for long.

occlusionFunc occlusionCallback()#: Current occlusion callback, or nullptr if none installed.

system &underWaterFX(const channel &target)#

Route a channel through the built-in under-water effect.

Since issue #327 the underwater treatment is an ordinary insert module (DSP::MODULES::underWater); this call places the engine’s default instance at the head of target's insert chain through the normal channel::setDSP message path. It therefore occupies the channel’s insert slot: a later setDSP on the same channel replaces it, and vice versa. Only one channel carries the stock effect at a time — calling this again with a different channel moves it. To combine the effect with other inserts, or to drive it from your own control logic, instantiate your own DSP::MODULES::underWater instead.

system &setUnderWaterDepth(float value)#

Set the listener’s depth below the water surface.

The default spatial driver of the underwater module: evaluate it at control rate on your update thread and the value is delivered to the audio thread as an ordinary wait-free parameter write.

Parameters:: value – Depth below the surface in world distance units. Zero or less disables the effect entirely; the low-passed, position-neutral treatment fades in above 1 and is fully position-neutral from 5 down. Any positive depth also enables the built-in underwater reverb zone at the listener’s position.

system &maxSounds(int value)#

Set the maximum number of concurrently audible sounds.

When this limit is exceeded, the engine virtualises the least significant sounds (typically furthest from the listener) instead of rendering them, freeing CPU for the audible ones.

int maxSounds()#: Current maxSounds limit.

system &AudioTest(bool on)#

Enable or disable the built-in audio test signal.

Outputs a steady tone through the audio device for verifying the output chain.

system &autoReconnect(bool on, int delay)#

Configure automatic device reconnection.

Parameters:

on – When true, the engine attempts to re-open the audio device after a disconnection (e.g. headphones unplugged).
delay – Milliseconds to wait between reconnection attempts.

float cpuLoad()#

Audio callback wall-clock load as a fraction of the buffer period.

Measured by YSE: timestamps taken at the entry/exit of each backend callback (PortAudio’s paCallback or Oboe’s onAudioReady) and divided by the buffer’s audio time. EMA-smoothed with a ~1 s time constant. Returns 0 when no device is open.

This is a dropout-risk indicator: 1.0 means the callback is taking as long as the buffer it produces, i.e. the next buffer will arrive late.

Distinct from the cost of update() on the main thread. Timed ourselves (rather than reading Pa_GetStreamCpuLoad) so the Oboe / Android backend can report a comparable number — that API doesn’t exist there.

double getSampleRate()#

Engine session sample rate in Hz.

The rate the engine locked to when init() / initOffline() ran. Stays constant across the entire session, including pause / resume cycles where getActiveSampleRate() transiently drops to 0. Returns 0 before the lock is established (pre-init).

Use this when scheduling sample-count-driven work that must outlive a pause; use getActiveSampleRate() for live device-state UI.

void sleep(unsigned int ms)#

Sleep the calling thread for ms milliseconds.

Convenience for console applications that don’t otherwise yield between calls to update().

inline std::string Version() const#: libYSE version string.

Private Members

std::atomic<occlusionFunc> occlusionPtr#

int currentlyMissedCallbacks#

bool doAutoReconnect#

int reconnectDelay#

Listener#

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.

Functions

listener &Listener()#

Access the singleton listener object.

< This macro is added to all public class declarations.

class listener#

Singleton representing the listener’s position and orientation in the virtual scene.

The Listener defines the reference point used by the engine to pan sounds across the available speakers, attenuate them by distance, and compute doppler shifts. Update its position every frame (typically alongside System().update()) so velocity and doppler stay coherent.

Access through the free function Listener().

See also

YSE::Listener

See also

YSE::Pos

Public Functions

Pos pos()#: Current listener position in world coordinates.

Pos vel()#

Current listener velocity in units per second.

Derived from successive calls to pos(const Pos&) — it cannot be set directly. Used internally for doppler calculations.

Pos forward()#: Forward-facing unit vector of the listener.

Pos upward()#: Upward unit vector of the listener.

listener &pos(const Pos &pos)#

Set the listener position.

Call once per frame to keep velocity-based effects (doppler, motion panning) accurate. Setting the position less frequently is fine for static scenes but will degrade the velocity estimate.

listener &orient(const Pos &forward, const Pos &up = Pos(0, 1, 0))#

Set the listener orientation.

Parameters:

forward – The direction the listener faces.
up – The upward axis. Defaults to (0, 1, 0), i.e. rotation confined to a horizontal plane.

Logging#

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.

Functions

log &Log()#

Access the singleton logging object.

< This macro is added to all public class declarations.

class log#

Singleton logging facility.

By default the engine writes messages to a text file in the working directory. Use setLogfile to redirect that file, or setHandler to bypass the file entirely and feed log lines into your own sink.

See also

YSE::Log

Note

Logging is only active between System().init() and System().close().

Public Functions

log &sendMessage(const char *msg)#

Send an application-level message to the YSE log.

The message is tagged app message and emitted at error log level so it survives filters set above EL_DEBUG.

log &setLevel(ERROR_LEVEL value)#

Set the active log level.

Defaults to EL_DEBUG in debug builds and EL_ERROR in release builds. Messages above the chosen level are dropped.

ERROR_LEVEL getLevel()#: Current log level.

log &setHandler(logHandler *handler)#

Install a custom log handler.

Replaces the default file-based sink. Pass nullptr to restore the default behaviour.

log &setLogfile(const char *path)#

Change the path of the default log file.

Defaults to YSElog.txt in the process working directory. Has no effect after a custom handler has been installed via setHandler.

const char *getLogfile()#: Current log file path.

class logHandler#

Base class for custom log sinks.

Subclass and override AddMessage to route log output somewhere other than the default log file — for example an in-game console or a third-party telemetry system. Register the instance with log::setHandler.

Public Functions

inline virtual void AddMessage(const std::string&)#

Called by the engine for every log message.

Default implementation discards it.

inline virtual ~logHandler()#

I/O#

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.

Functions

io &IO()#

Access the singleton custom-IO object.

< This macro is added to all public class declarations.

class io#

Custom file-system callbacks for asset loading.

Game engines and packed-asset workflows often need libYSE to read sound files through their own VFS instead of the host operating system. The io singleton lets you install C-style callbacks for each step of the file lifecycle (open / read / seek / close / exists / length / getPosition). Call setActive(true) to switch the engine over.

Access through the free function IO() — do not instantiate.

See also

YSE::IO

See also

YSE::BufferIO For an alternative that feeds sounds from in-memory buffers.

Public Functions

io()#

io &open(bool (*funcPtr)(const char *filename, long long *filesize, void **fileHandle))#

Install the open callback.

The callback opens the named file, writes its size into filesize, stores an implementation-defined handle in fileHandle, and returns true on success.

io &close(void (*funcPtr)(void *fileHandle))#: Install the close callback.

io &read(long long (*funcPtr)(void *destBuffer, long long maxBytesToRead, void *fileHandle))#

Install the read callback.

Reads up to maxBytesToRead bytes into destBuffer. Returns the number of bytes actually read, or 0 at end-of-file.

io &getPosition(long long (*funcPtr)(void *fileHandle))#

Install the get-position callback.

Returns the current read offset in bytes.

io &fileExists(bool (*funcPtr)(const char *filename))#: Install the file-exists callback.

io &length(long long (*funcPtr)(void *fileHandle))#

Install the length callback.

Returns the total size of the open file in bytes.

io &seek(long long (*funcPtr)(long long offset, int whence, void *fileHandle))#

Install the seek callback.

whence matches the FILEPOINT enum (FP_START, FP_CURRENT, FP_END). Returns the new absolute position.

io &setActive(bool value)#

Enable or disable the custom IO layer.

When inactive, libYSE falls back to its default platform file I/O.

Bool getActive()#: Whether the custom IO callbacks are currently active.

Private Members

aBool active#

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 BufferIO#

Feed sound files into the engine from in-memory byte buffers.

BufferIO is the simpler alternative to the callback-based YSE::io interface: register byte buffers under string IDs, then load sounds by passing those IDs as if they were file names. Typical use is bundling audio assets inside a game-engine resource pack or inside an Android APK where the regular file system is not accessible.

Construct one instance, call SetActive(true), add your buffers, then create sounds normally.

See also

YSE::io For full callback-based VFS integration.

Public Functions

BufferIO(bool storeCopy = false)#

Construct a BufferIO layer.

Parameters:: storeCopy – When true, AddBuffer copies the supplied bytes so the caller can free its buffer immediately. When false (default), the caller owns the memory and must keep it alive for as long as the buffer is registered.

void SetActive(bool value)#: Enable or disable this BufferIO layer.

bool GetActive()#: Whether this BufferIO layer is currently active.

bool BufferNameExists(const char *ID)#: Whether a buffer is registered under the given ID.

bool BufferExists(char *buffer)#: Whether the given byte buffer is currently registered.

bool AddBuffer(const char *ID, char *buffer, int length)#

Sounds can then be created by passing ID where a file name would normally go. length is the size of the buffer in bytes.

Returns:: true on success, false if the ID is already in use.

bool RemoveBufferByName(const char *ID)#: Unregister a buffer by its ID.

bool RemoveBuffer(char *buffer)#: Unregister a buffer by its address.

~BufferIO()#

Private Members

bool active#

bool storeCopy#

Reverb#

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.

namespace REVERB#

Enums

enum MESSAGE#

Values:

enumerator POSITION#

enumerator SIZE#

enumerator ROLLOFF#

enumerator ACTIVE#

enumerator ROOMSIZE#

enumerator DAMP#

enumerator DRY_WET#

enumerator MODULATION#

enumerator REFLECTION#

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 reverb#

A positioned reverb zone.

Each reverb object holds a set of parameters and a position in the scene. At the end of every DSP frame the engine looks at every reverb whose rolloff radius overlaps the listener and blends their parameters by proximity into the single shared reverb processor. The effect: you can drop multiple reverb zones around the world (cave, hall, bathroom) and the listener smoothly transitions between them as they move.

A “global” reverb is also available through System().getGlobalReverb(); it is mixed in as the fallback wherever no positioned reverb reaches.

See also

YSE::System

See also

YSE::REVERB_PRESET

Public Functions

reverb(bool global = false)#

Construct a reverb zone.

Parameters:: global – Reserved for the engine — leave as false in user code. true is used internally by System().getGlobalReverb().

~reverb()#

reverb &operator=(const reverb&) = delete#

Copy-assignment is deleted.

A reverb owns a raw pimpl that the engine tracks by interface identity. Copy-assigning would alias two interfaces onto a single implementation and turn that impl’s single-producer/single-consumer message queue into a dual-producer queue on the audio thread (issue #192). Copying a reverb is never valid — forbid it.

void create()#

Initialise the reverb.

Must be called after System().init() and before any other method on this object.

bool isValid()#: Whether this reverb has a live implementation.

reverb &setPosition(const Pos &value)#: Set the position of the reverb zone in the scene.

Pos getPosition()#: Current zone position.

reverb &setSize(float value)#

Radius within which the reverb is at full strength.

Inside this radius the zone is applied fully; beyond it, the strength fades over the rolloff distance (see setRollOff).

float getSize()#: Current full-strength radius.

reverb &setRollOff(float value)#

Distance over which the reverb fades out.

Measured from the edge of the full-strength radius. Outside size + rollOff from the center, this zone contributes nothing.

float getRollOff()#: Current rolloff distance.

reverb &setActive(bool value)#: Enable or disable this reverb zone.

bool getActive()#: Whether this reverb zone is currently active.

reverb &setRoomSize(float value)#

Set the simulated room size.

Larger values give longer tails.

float getRoomSize()#: Current room size.

reverb &setDamping(float value)#

Set the high-frequency damping.

Higher damping makes the reverb tail darken faster, simulating soft materials.

float getDamping()#: Current damping value.

reverb &setDryWetBalance(float dry, float wet)#

Set the dry/wet balance.

Note

dry + wet should usually be 1.0. Sums above 1.0 can clip.

Parameters:

dry – How much of the source signal passes through unprocessed.
wet – How much of the reverberated signal is mixed in.

float getWet()#: Current wet level.

float getDry()#: Current dry level.

reverb &setModulation(float frequency, float width)#

Modulate the reverb tail.

Adds a slow LFO to the reverb output to break up metallic resonances.

Parameters:

frequency – Modulation rate in Hz.
width – Modulation depth.

float getModulationFrequency()#: Current modulation frequency.

float getModulationWidth()#: Current modulation width.

reverb &setReflection(int reflection, int time, float gain)#

Configure one of the four early reflections.

Layered on top of the diffuse reverb tail to give the perception of nearby reflective surfaces.

Parameters:

reflection – Reflection index in [0, 3].
time – Delay time of this reflection.
gain – Gain of this reflection.

int getReflectionTime(int reflection)#

Delay time of the given reflection.

reflection is in [0, 3].

float getReflectionGain(int reflection)#

Gain of the given reflection.

reflection is in [0, 3].

reverb &setPreset(REVERB_PRESET value)#

Apply a named preset (cave, hall, bathroom, …).

See also

YSE::REVERB_PRESET

Private Members

REVERB::implementationObject *pimpl#

Bool connectedToManager#

Bool active#

Flt roomsize#

Flt damp#

Flt wet#

Flt dry#

Flt modFrequency#

Flt modWidth#

Int earlyPtr[4]#

Flt earlyGain[4]#

Pos position#

Flt size#

Flt rolloff#

REVERB_PRESET preset#

Bool global#

Core

Contents

Core#

System#

Listener#

Logging#

I/O#

Reverb#