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 attenuation factor in the range [0.0, 1.0]: 0 means fully occluded, 1 means audible without obstruction. Typical implementations raycast through game-world geometry.

Functions

system &System()#

Access the singleton system object.

< This macro is added to all public class declarations.

Variables

const std::string VERSION = "2.2.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.

Public Functions

system()#

bool init()#

Initialise the engine and open the default audio device.

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.

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.

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 pair of (source, listener) positions to compute how much a sound should be attenuated by world geometry. Typical implementations issue a raycast through the game physics engine. Pass nullptr to disable.

See also

occlusionFunc

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

system &underWaterFX(const channel &target)#: Route a channel through the under-water effect.

system &setUnderWaterDepth(float value)#

Configure the depth (intensity) of the under-water effect.

Parameters:: value – Depth in the range [0.0, 1.0]. 0 is dry, 1 is the maximum low-pass / pitch-shift the effect applies.

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

float (*occlusionPtr)(const Pos &source, const Pos &listener)#

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()#

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#