Audio devices

YSE::device describes an audio device the engine found, and YSE::deviceSetup names the device to open with System().openDevice(). Sessions and devices covers listing and opening devices, the -1 device ID and 0 buffer size values, and what happens when an open is refused.

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 DEVICE

Functions

managerObject &Manager()

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.

class device

Read-only descriptor of an audio device on the host system.

Enumerated and populated by the engine — applications retrieve instances through System().getDevices() (or the indexed getNumDevices / getDevice pair when libYSE is linked dynamically). Use the device to inspect its name, host (ASIO / WASAPI / ALSA / …), available channel layouts, sample rates, and buffer sizes; then pass a deviceSetup derived from that info to System().openDevice.

See also

YSE::deviceSetup

See also

YSE::system::openDevice

Note

Do not construct directly — instances handed out by the engine are the only valid ones.

Public Functions

device()

Default constructor used internally by the device enumerator.

device &setName(const std::string &name)

Set the device name.

Used by the engine when populating the device list.

const std::string &getName() const

Device name as reported by the host.

device &setTypeName(const std::string &name)

Set the host (driver) name.

Used internally.

const std::string &getTypeName() const

Host (driver) name, e.g.

ASIO, WASAPI, ALSA, JACK.

device &addInputChannelName(const std::string &name)

Internal: append an input channel name to the descriptor.

device &addOutputChannelName(const std::string &name)

Internal: append an output channel name to the descriptor.

device &addAvailableSampleRate(double sr)

Internal: register an available sample rate.

device &addAvailableBufferSize(int bs)

Internal: register an available buffer size.

const std::vector<std::string> &getOutputChannelNames() const

All output channel names.

Note

Not usable across DLL boundaries — use the indexed getNumOutputChannelNames / getOutputChannelName pair when libYSE is linked dynamically.

const std::vector<std::string> &getInputChannelNames() const

All input channel names.

Same DLL caveat as getOutputChannelNames.

const std::vector<double> &getAvailableSampleRates() const

All available sample rates.

Same DLL caveat.

const std::vector<int> &getAvailableBufferSizes() const

All available buffer sizes.

Same DLL caveat.

unsigned int getNumOutputChannelNames() const

Number of output channels.

const std::string &getOutputChannelName(unsigned int nr) const

Name of output channel nr.

Throws:

std::out_of_range – if nr >= getNumOutputChannelNames().

unsigned int getNumInputChannelNames() const

Number of input channels.

const std::string &getInputChannelName(unsigned int nr) const

Name of input channel nr.

Throws:

std::out_of_range – if nr >= getNumInputChannelNames().

unsigned int getNumAvailableSampleRates() const

Number of supported sample rates.

double getAvailableSampleRate(unsigned int nr) const

Supported sample rate at index nr.

Throws:

std::out_of_range – if nr >= getNumAvailableSampleRates().

unsigned int getNumAvailableBufferSizes() const

Number of supported buffer sizes.

int getAvailableBufferSize(unsigned int nr) const

Supported buffer size at index nr.

Throws:

std::out_of_range – if nr >= getNumAvailableBufferSizes().

device &setDefaultBufferSize(int value)

Set the default buffer size to use when this device is opened.

int getDefaultBufferSize() const

Default buffer size for this device, or 0 when the host does not advertise one.

0 means unspecified, not zero frames: fed to deviceSetup::setBufferSize it asks the backend to pick the size itself (PortAudio’s paFramesPerBufferUnspecified). The PortAudio enumerator leaves it at 0 for every device it reports, because PaDeviceInfo carries no equivalent field and inventing a number would be worse than saying nothing (issue #569). Read System().getActiveBufferSize() after the device is open for the size actually negotiated.

device &setOutputLatency(int value)

Set the reported output latency in samples.

int getOutputLatency() const

Reported output latency in samples.

device &setInputLatency(int value)

Set the reported input latency in samples.

int getInputLatency() const

Reported input latency in samples.

device &setID(int value)

Set the host-assigned ID for this device.

int getID() const

Host-assigned ID for this device, or -1 when no device has been assigned.

-1 is PortAudio’s paNoDevice sentinel and the value a descriptor starts at: it means no device, not device index -1, and is what a descriptor built by hand rather than taken from System().getDevices() reports until setID is called (issue #666). Passing such a descriptor to System().openDevice is refused with an E_AUDIODEVICE log line and leaves the running stream alone, the same as any other index no host API resolves (issue #661). Every enumerated device carries a real, non-negative index.

Private Members

std::string name

std::string typeName

std::vector<std::string> outputChannelNames

std::vector<std::string> inputChannelNames

std::vector<double> sampleRates

std::vector<int> bufferSizes

int defaultBufferSize = 0

int inputLatency = 0

int outputLatency = 0

int ID = -1

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.

class deviceSetup

Public Functions

deviceSetup()

deviceSetup &setInput(const device &in)

deviceSetup &setOutput(const device &out)

deviceSetup &setSampleRate(double value)

Sample rate to open the device at, in Hz.

0 (the default) means no request.

The sample rate is fixed for a whole session. When this rate differs from the session rate, System().openDevice() logs a warning and opens the stream at the session rate (issue #971). To run at a different rate, call System().requestSampleRate() before init().

deviceSetup &setBufferSize(int value)

int getOutputChannels() const

Private Members

const device *in

const device *out

double sampleRate

int bufferSize