Types, enums and constants

yse.hpp pulls in three small headers that the rest of the API is written in terms of:

• headers/types.hpp: the fixed-size aliases (Flt, Dbl, Int, UInt …) and their atomic versions. They are in the global namespace.

• headers/enums.hpp: the public enumerations, such as CHANNEL_TYPE, REVERB_PRESET, ERROR_LEVEL and the MIDI pitch and channel names.

• headers/constants.hpp: the block size (STANDARD_BUFFERSIZE, 128 samples) and the active sample rate (SAMPLERATE).

headers/defines.hpp is also included but left out of this reference on purpose. It holds the platform-detection macros (YSE_WINDOWS, YSE_LINUX …) and the API export macro, which the build sets up for you.

Types

Fixed-size type aliases used throughout the public API.

They live in the global namespace. Flt (float), Dbl (double), Int and UInt (32-bit) appear in most signatures.

Typedefs

typedef bool Bool

bool.

typedef char Char8

char.

typedef float Flt

32-bit float.

typedef double Dbl

64-bit float.

typedef int8_t I8

Signed 8-bit integer.

typedef uint8_t U8

typedef uint8_t Byte

Unsigned 8-bit integer.

typedef int16_t I16

typedef int16_t Short

Signed 16-bit integer.

typedef uint16_t U16

typedef uint16_t UShort

Unsigned 16-bit integer.

typedef int32_t I32

typedef int32_t Int

Signed 32-bit integer.

typedef uint32_t U32

typedef uint32_t UInt

Unsigned 32-bit integer.

typedef long long I64

typedef long long Long

Signed 64-bit integer.

typedef uint64_t U64

typedef uint64_t ULong

Unsigned 64-bit integer.

typedef std::atomic<Bool> aBool

Atomic Bool.

typedef std::atomic<Int> aInt

Atomic Int.

typedef std::atomic<UInt> aUInt

Atomic UInt.

typedef std::atomic<Flt> aFlt

Atomic Flt.

typedef std::atomic<Byte> aByte

Atomic Byte.

Enums

Public enumerations of the YSE namespace.

Only the enums a host passes to or receives from the public API are documented here. The object-lifecycle states and the log message codes in this header are engine internals.

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.

Enums

enum CHANNEL_TYPE

Speaker layout of the output.

Passed to System().openDevice and System().setChannelConfiguration.

Values:

enumerator CT_AUTO

Stereo when the device allows it.

enumerator CT_MONO

One speaker.

enumerator CT_STEREO

Left and right.

enumerator CT_QUAD

Four speakers.

enumerator CT_51

5.1 surround.

enumerator CT_51SIDE

5.1 surround with side instead of rear speakers.

enumerator CT_61

6.1 surround.

enumerator CT_71

7.1 surround.

enumerator CT_CUSTOM

Custom layout: set the speaker positions yourself.

enumerator CT_COUNT_

Sentinel: the number of layouts, not a valid value.

enum RECONNECT_STATE

What the autoReconnect watchdog last did, read with System().reconnectState() (issue #1027).

Values:

enumerator RS_NONE

No attempt since the session started, a device was opened, or autoReconnect() was last called.

enumerator RS_RECONNECTING

The last attempt opened nothing; the watchdog tries again.

enumerator RS_RESTORED

The last attempt reopened the device the session had.

enumerator RS_FELL_BACK_TO_DEFAULT

The session’s device could not be reopened, so the default output device was opened instead.

enumerator RS_FAILED

The attempt limit was reached; the watchdog stopped trying.

enumerator RS_COUNT_

Sentinel: the number of states, not a valid value.

enum REVERB_PRESET

Named reverb presets, applied with reverb::setPreset.

Values:

enumerator REVERB_OFF

enumerator REVERB_GENERIC

enumerator REVERB_PADDED

enumerator REVERB_ROOM

enumerator REVERB_BATHROOM

enumerator REVERB_STONEROOM

enumerator REVERB_LARGEROOM

enumerator REVERB_HALL

enumerator REVERB_CAVE

enumerator REVERB_SEWERPIPE

enumerator REVERB_UNDERWATER

enumerator REVERB_COUNT_

Sentinel: the number of presets, not a valid value.

enum SOUND_STATUS

Playback state and intent.

A DSP::dspSourceObject receives it in process to drive its envelopes: the SS_WANTSTO… values ask for a transition, the others describe the current state.

Values:

enumerator SS_STOPPED

enumerator SS_PAUSED

enumerator SS_PLAYING

enumerator SS_PLAYING_FULL_VOLUME

enumerator SS_WANTSTOPLAY

enumerator SS_WANTSTOPAUSE

enumerator SS_WANTSTOSTOP

enumerator SS_WANTSTORESTART

enum OUT_TYPE

Data type a patcher outlet sends (see pHandle::OutputDataType).

Values:

enumerator INVALID

No such outlet.

enumerator BANG

A bang.

enumerator FLOAT

A float.

enumerator INT

An integer.

enumerator BUFFER

An audio signal.

enumerator LIST

A list message.

enumerator ANY

Any message type.

enumerator OUT_TYPE_COUNT_

Sentinel: the number of types, not a valid value.

enum THREAD

The thread a patcher object is called on: the audio thread (T_DSP) or a control thread (T_GUI).

Values:

enumerator T_DSP

The audio thread.

enumerator T_GUI

A control thread.

enum ERROR_LEVEL

Log verbosity, set with Log().setLevel.

Each level includes the ones before it.

Values:

enumerator EL_NONE

Log nothing.

enumerator EL_ERROR

Errors only.

enumerator EL_WARNING

Errors and warnings.

enumerator EL_DEBUG

Everything, including debug messages.

enumerator EL_COUNT_

Sentinel: the number of levels, not a valid value.

enum FILEPOINT

Seek origin for custom file I/O callbacks (see io.hpp).

Values:

enumerator FP_CURRENT

From the current position.

enumerator FP_START

From the start of the file.

enumerator FP_END

From the end of the file.

enum BQ_TYPE

Filter response of DSP::biQuad.

Values:

enumerator BQ_LOWPASS

Low-pass.

enumerator BQ_HIGHPASS

High-pass.

enumerator BQ_BANDPASS

Band-pass.

enumerator BQ_NOTCH

Notch (band-reject).

enumerator BQ_PEAK

Peaking EQ.

enumerator BQ_LOWSHELF

Low shelf.

enumerator BQ_HIGHSHELF

High shelf.

namespace MIDI

MIDI file playback and external device I/O.

MIDI::file plays back standard MIDI files; midiOut (Windows / Linux only) sends messages to a MIDI port. The MIDI::midiMessage / midiNote types wrap raw byte sequences.

Enums

enum M_PITCH

MIDI note numbers by name, for midiOut.

C4 is note 60; S means sharp and F flat, so CS4 and DF4 are both

1. The octave below C0 is spelled with M1 (minus one).

Values:

enumerator CM1

enumerator CSM1

enumerator DFM1

enumerator DM1

enumerator DSM1

enumerator EFM1

enumerator EM1

enumerator FM1

enumerator FSM1

enumerator GFM1

enumerator GM1

enumerator GSM1

enumerator AFM1

enumerator AM1

enumerator ASM1

enumerator BFM1

enumerator BM1

enumerator C0

enumerator CS0

enumerator DF0

enumerator D0

enumerator DS0

enumerator EF0

enumerator E0

enumerator F0

enumerator FS0

enumerator GF0

enumerator G0

enumerator GS0

enumerator AF0

enumerator A0

enumerator AS0

enumerator BF0

enumerator B0

enumerator C1

enumerator CS1

enumerator DF1

enumerator D1

enumerator DS1

enumerator EF1

enumerator E1

enumerator F1

enumerator FS1

enumerator GF1

enumerator G1

enumerator GS1

enumerator AF1

enumerator A1

enumerator AS1

enumerator BF1

enumerator B1

enumerator C2

enumerator CS2

enumerator DF2

enumerator D2

enumerator DS2

enumerator EF2

enumerator E2

enumerator F2

enumerator FS2

enumerator GF2

enumerator G2

enumerator GS2

enumerator AF2

enumerator A2

enumerator AS2

enumerator BF2

enumerator B2

enumerator C3

enumerator CS3

enumerator DF3

enumerator D3

enumerator DS3

enumerator EF3

enumerator E3

enumerator F3

enumerator FS3

enumerator GF3

enumerator G3

enumerator GS3

enumerator AF3

enumerator A3

enumerator AS3

enumerator BF3

enumerator B3

enumerator C4

enumerator CS4

enumerator DF4

enumerator D4

enumerator DS4

enumerator EF4

enumerator E4

enumerator F4

enumerator FS4

enumerator GF4

enumerator G4

enumerator GS4

enumerator AF4

enumerator A4

enumerator AS4

enumerator BF4

enumerator B4

enumerator C5

enumerator CS5

enumerator DF5

enumerator D5

enumerator DS5

enumerator EF5

enumerator E5

enumerator F5

enumerator FS5

enumerator GF5

enumerator G5

enumerator GS5

enumerator AF5

enumerator A5

enumerator AS5

enumerator BF5

enumerator B5

enumerator C6

enumerator CS6

enumerator DF6

enumerator D6

enumerator DS6

enumerator EF6

enumerator E6

enumerator F6

enumerator FS6

enumerator GF6

enumerator G6

enumerator GS6

enumerator AF6

enumerator A6

enumerator AS6

enumerator BF6

enumerator B6

enumerator C7

enumerator CS7

enumerator DF7

enumerator D7

enumerator DS7

enumerator EF7

enumerator E7

enumerator F7

enumerator FS7

enumerator GF7

enumerator G7

enumerator GS7

enumerator AF7

enumerator A7

enumerator AS7

enumerator BF7

enumerator B7

enumerator C8

enumerator CS8

enumerator DF8

enumerator D8

enumerator DS8

enumerator EF8

enumerator E8

enumerator F8

enumerator FS8

enumerator GF8

enumerator G8

enumerator GS8

enumerator AF8

enumerator A8

enumerator AS8

enumerator BF8

enumerator B8

enumerator C9

enumerator CS9

enumerator DF9

enumerator D9

enumerator DS9

enumerator EF9

enumerator E9

enumerator F9

enumerator FS9

enumerator GF9

enumerator G9

enum M_CHANNEL

MIDI channel for midiOut.

CH_01 is channel 1 (wire value 0).

Values:

enumerator CH_01

enumerator CH_02

enumerator CH_03

enumerator CH_04

enumerator CH_05

enumerator CH_06

enumerator CH_07

enumerator CH_08

enumerator CH_09

enumerator CH_10

enumerator CH_11

enumerator CH_12

enumerator CH_13

enumerator CH_14

enumerator CH_15

enumerator CH_16

Constants

Engine-wide constants: the block size and the active sample rate.

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.

Variables

const UInt STANDARD_BUFFERSIZE = 128

Samples per audio block.

The engine renders, and advances its clocks, in blocks of this size whatever the device buffer size.

const UInt STREAM_BUFFERSIZE = 44100

Streaming chunk size in samples.

About 1 s of audio at 44.1 kHz; at other sample rates the wall-clock length scales (about 0.92 s at 48 kHz, 0.46 s at 96 kHz). A fixed sample count used by the file and streaming code; it does not follow SAMPLERATE.

UInt SAMPLERATE

The active engine sample rate, in Hz.

48000 until a session starts. The audio backend writes it once per session, while the session starts: the rate the application requested (System().requestSampleRate) or the device default on desktop, the rate Oboe negotiated on Android. Read it, never write it, and treat it as fixed for the rest of the session. < This macro is added to all public class declarations.