C++ API reference

C++ API reference#

The patcher’s public C++ classes, generated from the headers. For every object type, see Patcher object reference.

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

Base class for receiving OSC-style messages from a patcher.

Subclass and override the Send overloads to forward patcher output to an external system (OSC client, game logic, telemetry, …). Register the instance with patcher::SetOscHandler.

Public Functions

inline virtual void Send(const std::string&)#: Called when the patcher emits a bare bang (address only).

inline virtual void Send(const std::string&, int)#: Called when the patcher emits an integer value.

inline virtual void Send(const std::string&, float)#: Called when the patcher emits a float value.

inline virtual void Send(const std::string&, const std::string&)#: Called when the patcher emits a string value.

inline virtual ~oscHandler()#

class patcher#

Modular DSP / event graph (Max/MSP-style patcher).

Programmatically build a node graph, connect inlets to outlets, and optionally save/load it as JSON. A patcher can be used directly via the PassBang / PassData entry points, or wrapped into a YSE::sound via YSE::sound::create(patcher&, ...) to use it as an audio source.

Object type strings ("~sine", ".+", "~lp" etc.) are defined in YSE::OBJ — see patcher/pObjectList.hpp.

See also

YSE::OBJ

Public Functions

patcher()#

~patcher()#

void create(int mainOutputs)#: Initialise the patcher with mainOutputs audio outputs.

patcher &name(const std::string &n)#

Set the patcher’s name (used as the prefix on the global bus).

Every gSend inside this patcher publishes its value to the global NamedBus under "patcher.<patcherName>.<dataName>" (issue #122). Two patchers that share the same name route their sends/receives together; patchers with distinct names stay isolated even when their inner dataName values collide.

Calling this after creating gReceive objects transparently re-subscribes them under the new name. If create() has not yet been called the value is stashed and applied at create() time.

Default: an auto-generated identifier of the form "patcher_<N>" where N increments per process. Passing an empty name restores that auto-generated name (issue #896); before create() it drops any stashed name, so create() keeps the auto-name and name() reads back "" until then.

A name longer than 55 characters is refused — logged, and the current name kept — so the full "patcher.<patcherName>.<slot>" address, with a slot of up to 63 characters, always fits the bus’s fixed-size name on the audio-thread path (issue #921).

const std::string &name() const#

Current patcher name.

See name(const std::string&).

YSE::pHandle *CreateObject(const std::string &type, const std::string &args = std::string())#

Add an object to the patcher.

Parameters:

type – Type identifier (see YSE::OBJ).
args – Optional creation arguments, formatted as the object expects.

Returns:

Handle to the new object — owned by the patcher.

void DeleteObject(YSE::pHandle *obj)#: Remove an object from the patcher.

void Clear()#: Remove every object from the patcher.

void Connect(YSE::pHandle *from, int outlet, YSE::pHandle *to, int inlet)#

Connect from’s outlet to to’s inlet.

Both handles must be objects of this patcher. A nullptr handle or one from another patcher is refused: an error is logged and the graph is left unchanged. The same holds for Disconnect.

void Disconnect(YSE::pHandle *from, int outlet, YSE::pHandle *to, int inlet)#: Remove the connection from from’s outlet to to’s inlet.

void SetContainer(YSE::pHandle *obj, YSE::pHandle *container)#

Put obj inside the subpatcher container (issue #545).

container must be a "patcher" object in this patcher, or nullptr to move obj back out to the top level. A subpatcher cannot be placed inside itself or inside one of its own descendants. Anything else is refused with a log and no change.

Containment is addressing, not storage: a nested object is still an ordinary object in this patcher’s one flat graph, and this call publishes nothing because it changes no edge and no pin. What it changes is what Connect/Disconnect mean when handed the subpatcher — inlet N of a subpatcher is the boundary object inside it whose index is N, a ".inlet" for a message pin or a "~inlet" for a signal pin (issue #764) — and what DeleteObject takes with it.

YSE::pHandle *GetContainer(YSE::pHandle *obj)#: The subpatcher obj is inside, or nullptr at the top level.

int SubpatcherInlets(YSE::pHandle *container)#

How many inlets a subpatcher presents to its parent.

One past the highest index claimed by a boundary object among the subpatcher’s contents, so a sparsely numbered boundary reports the range a parent can address rather than the number of boundary objects. 0 for a handle that is not a subpatcher.

Both rates count towards the one total: a subpatcher has one set of inlet pins, and a ".inlet 0" beside a "~inlet 1" presents two inlets — a message pin and a signal pin — not one of each (issue #764).

A "patcher" object owns no pins of its own, so pHandle::GetInputs answers 0 for one; this is the question to ask instead.

int SubpatcherOutlets(YSE::pHandle *container)#

How many outlets a subpatcher presents.

See SubpatcherInlets.

std::string DumpJSON()#

Serialise the current graph to JSON.

A name set with name() is written as an optional top-level "name" key; the auto-generated "patcher_<N>" name is not written (issue #897).

void ParseJSON(const std::string &content)#

Add the contents of a JSON dump to the current graph.

Loading is additive: nothing already in the patcher is removed. The loaded objects are created next to the existing ones and get the smallest storage IDs those do not hold, so the IDs in the file are not kept. To replace the patch, call Clear() first (issue #939).

A top-level "name" key is applied only if this patcher still has its auto-generated name, so a name the host set before loading wins. It is applied before any object is created and before .loadbang fires, and is refused (logged, auto-name kept) like any over-long name() (issue #897).

Throws on a malformed file. A load is all-or-nothing: on a throw the patcher is left exactly as it was, with the objects the load had created removed and a name it applied taken back (issue #938).

unsigned int Objects()#

Number of objects in the patcher.

This and the two lookups below take the patcher’s lock like every edit, so they are safe against an edit on another thread (issue #937). Each call is answered on its own: an edit between two calls can change the count and the positions. Never call them from the audio callback.

Note

Most useful after ParseJSON to walk the loaded graph.

YSE::pHandle *GetHandleFromList(unsigned int obj)#: Object at position obj in the list (0-indexed).

YSE::pHandle *GetHandleFromID(unsigned int obj)#: Object whose ID is obj.

bool PassBang(const std::string &to)#

Send a bang to the named receive object.

Returns false if no such receiver exists.

bool PassData(int value, const std::string &to)#: Send an integer to the named receive object.

bool PassData(float value, const std::string &to)#: Send a float to the named receive object.

bool PassData(const std::string &value, const std::string &to)#: Send a string to the named receive object.

void SetOscHandler(oscHandler *handle)#

Install an OSC handler for outgoing messages; nullptr clears it.

The handler receives every message a PassBang / PassData — the host’s own calls, or a .s inside the patch — addresses to a name no .r in this patcher answers, and it makes those calls return true. It is called synchronously on the thread that emitted the message: the host’s own, or an engine worker such as the timer thread behind a millisecond .metro. Never the audio callback — a send made while rendering stays in the patch.

Returns once no other thread is still inside the handler it replaced, so that handler may be destroyed afterwards (issue #907). The patcher does not own the handler. Called before create(), the handler is kept and installed at create() time.

Public Static Functions

static bool IsValidObject(const char *type)#: Whether type is a known object type identifier.

Private Members

PATCHER::patcherImplementation *pimpl#

std::string pendingName#

oscHandler *pendingHandler = nullptr#

Friends

friend class YSE::sound

friend class YSE::DSP::patcherInsert

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

Handle to a single object inside a patcher.

Returned by patcher::CreateObject and the various lookup methods. Use it to feed external data into the object’s inlets, inspect its outlets, read or write GUI metadata, and walk the loaded graph after patcher::ParseJSON.

The patcher owns the underlying object — do not delete the handle directly; call patcher::DeleteObject instead.

Every call is for control threads, and every call is safe while another control thread edits the patch — including a SetParams on this same object that rebuilds it and swaps the rebuilt one in behind the handle (issue #968). GetParams, GetGuiProperty, SetGuiProperty and the three connection queries take the patcher’s lock. Type, GetName, GetID, GetInputs, GetOutputs and the GetGuiValue family take none, so GUI polling never waits on an edit. A call that races such a swap answers for the object before it or the one after it. Using a handle after DeleteObject has removed it is still the caller’s error.

Public Functions

pHandle(PATCHER::pObject *obj)#

Construct a handle around a patcher object.

Engine-internal.

const char *Type() const#: Type identifier of the underlying object (see YSE::OBJ).

void SetBang(unsigned int inlet)#: Send a bang to inlet inlet.

void SetIntData(unsigned int inlet, int value)#: Send an integer to inlet inlet.

void SetFloatData(unsigned int inlet, float value)#: Send a float to inlet inlet.

void SetListData(unsigned int inlet, const std::string &value)#: Send a string or list to inlet inlet.

void SetParams(const std::string &args)#: Reconfigure the object using a new argument string.

std::string GetGuiProperty(const std::string &key)#: Read a GUI property by key (used by patcher editors).

void SetGuiProperty(const std::string &key, const std::string &value)#: Write a GUI property.

int GetInputs()#: Number of inlets on this object.

int GetOutputs()#: Number of outlets on this object.

bool IsDSPInput(unsigned int inlet)#: Whether inlet inlet accepts an audio signal.

YSE::OUT_TYPE OutputDataType(unsigned int pin)#

Data type produced by outlet pin.

On a subpatcher this answers for the .outlet / ~outlet claiming index pin (ANY / BUFFER), and OUT_TYPE::INVALID when no boundary object claims it — the same resolution IsDSPInput makes on the inlet side.

std::string GetName()#: Display name of this object (set in the patcher source).

std::string GetParams()#: Original creation argument string.

unsigned int GetID()#

Storage ID, unique among the owning patcher’s live objects.

Assigned by the patcher when the object is created and stable for the object’s lifetime. This is the number patcher::DumpJSON writes for the object and that GetConnectionTarget reports for edges pointing at it. IDs are not unique across patchers — two patchers each number their own objects from 0 (issue #730) — so use patcher::GetHandleFromID on the patcher the object belongs to.

IDs are kept dense: the patcher issues the smallest number no live object holds, so a deleted object’s ID goes to the next object created and a long editing session does not push a small patch’s numbering up (issue #733). The consequence for a caller is that an ID names an object only while that object is alive — an ID cached across a delete may resolve to the object that inherited the number rather than to nothing. Hold the pHandle* for a lasting reference; use the ID for storage and for talking about a patch.

unsigned int GetConnections(unsigned int outlet)#

Number of connections leaving outlet outlet.

0 when the object has no such outlet — SetParams can shrink an object’s outlet count, so an outlet number cached across a re-parse may no longer name anything (issue #737). Compare against GetOutputs() to tell an absent outlet from an unconnected one.

This and the two queries below take the patcher’s lock (issue #966), so they are safe while another control thread edits the patch, but each answers on its own: a connection counted here can be gone by the next call, which then answers UINT_MAX. Control threads only.

unsigned int GetConnectionTarget(unsigned int outlet, unsigned int connection)#

ID of the target object of one connection from outlet outlet.

UINT_MAX when there is no such outlet or no such connection on it. Not 0: IDs start at 0 (issue #730), so 0 is a real target.

unsigned int GetConnectionTargetInlet(unsigned int outlet, unsigned int connection)#

Inlet on the target that this connection reaches.

UINT_MAX (pObject::kNoInletIndex) when there is no such outlet or no such connection on it. Not 0: inlet 0 is the leftmost inlet and the one most edges arrive at (issue #736).

std::string GetGuiValue()#

Current GUI state of this object, as one string.

For a scalar control (.slider, .t, .i, …) this is the value; for a structured one (.rslider, .multislider, .matrixctrl) it is every cell, space separated, in index order. Empty for an object with no GUI state.

Host thread, and it may be destructive: .b reports the press it is clearing. Poll an object through this call or through GetGuiValueAt once per frame, never both. See the GUI value protocol block in patcher/pObject.h for the full contract.

unsigned int GetGuiValueCount()#

How many cells this object’s GUI state has.

1 for a scalar control.

std::string GetGuiValueAt(unsigned int index)#

One cell of the GUI state, or “” past the end.

Cell 0 of a scalar control is exactly what GetGuiValue returns. Cells are sampled one call at a time and the read is not atomic across them — use GetGuiValue when a coherent snapshot matters.

bool GuiValueIsSettable()#

Whether this object accepts its own GUI state back on inlet 0.

True means the round trip holds: SetListData(0, GetGuiValue()) restores the state that was read, and SetListData(0, "set <index> <value>") writes a single cell. That is how a preset is restored — as ordinary messages on the control thread, never by writing another object’s state directly.

The round trip is the half a preset needs and it holds unconditionally. The cell form has one carve-out, stated in the protocol block: a one-cell control whose cell is free text (.textedit) takes its whole inlet verbatim, because a text cell can hold the word set. With one cell the two forms are the same write anyway.

True for every GUI control that holds state, including the scalar controls .slider, .i, .f, .dial, .incdec and .t (issue #846). False for .b, whose value is a consume-on-read press report that a restore could only replay; for .preset, whose value is its read-only active slot; for the message boxes .m and .l; and for the non-GUI objects that report a read-only value (.counter, .accum, …).

Private Functions

inline PATCHER::pObject *ObjectUnderLock() const#

Private Members

std::atomic<PATCHER::pObject*> object#

PATCHER::patcherImplementation *const owner#

Defines

DEFOBJ(name, tag)#

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.

struct OBJ#

Compile-time string identifiers for patcher object types.

Pass any of these constants to patcher::CreateObject instead of the raw string literal. The ~ prefix marks DSP / audio-rate objects, . marks control-rate objects.

DSP generators: D_SINE, D_SAW, D_NOISE.
DSP math: D_ADD, D_MULTIPLY, D_CLIP.
Control math: G_ADD, G_DIVIDE, G_REVERSESUBSTRACT, G_REVERSEDIVIDE, G_MODULO, G_INTDIVIDE.
Operand order: G_SWAP.
Elementary math: G_ABS, G_SQRT, G_POW, G_ROUND.
Range mapping: G_SCALE, G_ZMAP, G_LINEDRIVE.
Range limiting: G_CLIP, G_PONG.
Range routing: G_SPLIT.
Smoothing: G_SLIDE.
Expressions: G_EXPR, G_VEXPR.
Trigonometry / hyperbolics: G_SIN, G_COS, G_TAN, G_ASIN, G_ACOS, G_ATAN, G_ATAN2, G_SINH, G_COSH, G_TANH, G_ASINH, G_ACOSH, G_ATANH.
Comparison / logic: G_EQUAL, G_LESS, G_LOGICALAND, …
Running comparison: G_MAXIMUM, G_MINIMUM.
Running extremes: G_PEAK, G_TROUGH.
Threshold crossing: G_PAST.
Change detection: G_CHANGE.
Zero-crossing edges: G_TOGEDGE.
Bitwise: G_BITAND, G_BITOR, G_SHIFTLEFT, G_SHIFTRIGHT.
DSP filters: D_LOWPASS, D_HIGHPASS, D_BANDPASS, D_VCF.
I/O: D_DAC, D_ADC, D_LINE.
Control: G_INT, G_FLOAT, G_SLIDER, G_RSLIDER, G_XYSLIDER, G_MULTISLIDER, G_MATRIXCTRL, G_FUNCTION, G_KSLIDER, G_NSLIDER, G_DIAL, G_INCDEC, G_RANDOM.
Proximity fields: G_NODES.
Indexed selection: G_UMENU, G_RADIOGROUP, G_TAB.
Labelled switches: G_LED, G_TEXTBUTTON.
Text entry: G_TEXTEDIT.
Presets: G_PRESET.
Timing: G_METRO, G_DELAY, G_PIPE, G_TRANSPORT, G_SETCLOCK, G_WHEN, G_TRANSLATE, G_TIMEPOINT, G_TEMPO, G_CLOCKER, G_TIMER, G_SPEEDLIM, G_QLIM, G_THRESH, G_QUICKTHRESH, G_LINE, G_BLINE.
Registers: G_COUNTER, G_ACCUM.
Randomness: G_RANDOM, G_DRUNK, G_URN, G_DECIDE, G_PROB, G_ANAL, G_HISTO.
Statistics: G_ANAL, G_HISTO, G_MEAN.
Shared state: G_VALUE.
Collections: G_COLL, G_BAG, G_CAPTURE, G_FUNBUFF, G_TABLE, G_TEXTFILE, G_QLIST, G_MTR, G_SEQ.
Dictionaries: G_DICT, G_DICT_COMPARE, G_DICT_DESERIALIZE, G_DICT_GROUP, G_DICT_ITER, G_DICT_JOIN, G_DICT_PACK, G_DICT_PRINT, G_DICT_ROUTE, G_DICT_SERIALIZE, G_DICT_SLICE, G_DICT_STRIP, G_DICT_UNPACK.
Arrays: G_ARRAY, G_ARRAY_AT, G_ARRAY_LENGTH, G_ARRAY_PUSH, G_ARRAY_POP, G_ARRAY_SHIFT, G_ARRAY_UNSHIFT, G_ARRAY_INSERT, G_ARRAY_REMOVE, G_ARRAY_INDEXOF, G_ARRAY_INDEX, G_ARRAY_INDEXMAP, G_ARRAY_REVERSE, G_ARRAY_ROTATE, G_ARRAY_SCRAMBLE, G_ARRAY_SHUFFLE, G_ARRAY_SORT, G_ARRAY_MIN, G_ARRAY_MAX, G_ARRAY_MEAN, G_ARRAY_MEDIAN, G_ARRAY_MODE, G_ARRAY_STDDEV, G_ARRAY_SLICE, G_ARRAY_SUBARRAY, G_ARRAY_SUB, G_ARRAY_SPLIT, G_ARRAY_UNION, G_ARRAY_SECT, G_ARRAY_UNIQUE, G_ARRAY_CONCAT, G_ARRAY_JOIN, G_ARRAY_FILL, G_ARRAY_FLATTEN, G_ARRAY_TOLIST, G_ARRAY_TOSTRING, G_ARRAY_TOSYMBOL, G_ARRAY_DESERIALIZE, G_ARRAY_ITER, G_ARRAY_EXPR, G_ARRAY_MAP, G_ARRAY_FILTER, G_ARRAY_REDUCE, G_ARRAY_EVERY, G_ARRAY_SOME, G_ARRAY_FOREACH, G_ARRAY_CHANGE, G_ARRAY_COMPARE, G_ARRAY_GROUP, G_ARRAY_REPLACE, G_ARRAY_REGEXP, G_ARRAY_ROUTEPASS, G_ARRAY_RANDOM, G_ARRAY_STREAM, G_ARRAY_THIN, G_ARRAY_TUPLEWISE, G_ARRAY_WRAP.
Debugging: G_PRINT, G_DICT_PRINT.
Initialisation: G_LOADBANG, G_LOADMESS.
Encapsulation: PATCHER, G_INLET, G_OUTLET, D_INLET, D_OUTLET.
Messaging: G_SEND, G_RECEIVE, G_FORWARD, G_ROUTE, G_ROUTEPASS, G_SEL, G_TRIGGER, G_BANGBANG, G_ONEBANG, G_NEXT, G_MATCH, G_BONDO, G_BUDDY, G_CYCLE, G_BUCKET, G_SPRAY, G_FUNNEL, G_DECODE, G_GATE, G_SWITCH, G_ROUTER, G_MATRIX, G_IF, G_REGEXP.
Message construction: G_PREPEND, G_APPEND, G_SUBSTITUTE, G_SPRINTF, G_TOSYMBOL, G_FROMSYMBOL, G_COMBINE, G_SPELL, G_ATOI, G_ITOA, G_TOLOWER, G_TOUPPER.
List processing: G_ZL, G_PACK, G_PAK, G_UNPACK, G_JOIN, G_UNJOIN, G_LISTFUNNEL.
Iteration: G_UZI, G_ITER.
MIDI out: M_OUT, M_NOTEON, M_NOTEOFF, M_CONTROL, M_BENDOUT.
MIDI in: M_IN, M_NOTEIN, M_CTLIN, M_BENDIN, M_PGMIN, M_TOUCHIN, M_POLYIN, M_RTIN.
Extended-precision MIDI: M_XBENDIN, M_XBENDIN2, M_XCTLIN, M_XNOTEIN, M_XMIDIIN, M_XBENDOUT, M_XBENDOUT2, M_XCTLOUT, M_XNOTEOUT.
Parameter numbers: M_RPNIN, M_NRPNIN, M_RPNOUT, M_NRPNOUT.
MIDI polyphonic expression: M_MPECONFIG, M_MPEFORMAT, M_MPEPARSE.
MIDI codec: M_PARSE, M_FORMAT.
MIDI system exclusive: M_SYSEXIN, M_SXFORMAT.
MIDI devices: M_MIDIINFO.
MIDI hygiene: M_MIDIFLUSH, M_MAKENOTE, M_STRIPNOTE, M_FLUSH, M_SUSTAIN.
Voice allocation: M_POLY.
Note analysis: M_BORAX.
Note bookkeeping: M_OFFER.
Conversion: MIDITOFREQUENCY, FREQUENCYTOMIDI, G_ATODB, G_DBTOA, G_CARTOPOL, G_POLTOCAR.

Public Static Attributes

static char const *PATCHER = "patcher"#

static char const *G_INLET = ".inlet"#

static char const *G_OUTLET = ".outlet"#

static char const *D_INLET = "~inlet"#

static char const *D_OUTLET = "~outlet"#

static char const *D_DAC = "~dac"#

static char const *D_ADC = "~adc"#

static char const *G_RECEIVE = ".r"#

static char const *G_SEND = ".s"#

static char const *D_LINE = "~line"#

static char const *D_SINE = "~sine"#

static char const *D_SAW = "~saw"#

static char const *D_NOISE = "~noise"#

static char const *G_INT = ".i"#

static char const *G_FLOAT = ".f"#

static char const *G_SLIDER = ".slider"#

static char const *G_RSLIDER = ".rslider"#

static char const *G_XYSLIDER = ".xyslider"#

static char const *G_MULTISLIDER = ".multislider"#

static char const *G_MATRIXCTRL = ".matrixctrl"#

static char const *G_FUNCTION = ".function"#

static char const *G_KSLIDER = ".kslider"#

static char const *G_NSLIDER = ".nslider"#

static char const *G_NODES = ".nodes"#

static char const *G_UMENU = ".umenu"#

static char const *G_RADIOGROUP = ".radiogroup"#

static char const *G_TAB = ".tab"#

static char const *G_DIAL = ".dial"#

static char const *G_INCDEC = ".incdec"#

static char const *G_BUTTON = ".b"#

static char const *G_TOGGLE = ".t"#

static char const *G_LED = ".led"#

static char const *G_TEXTBUTTON = ".textbutton"#

static char const *G_MESSAGE = ".m"#

static char const *G_LIST = ".l"#

static char const *G_TEXT = ".text"#

static char const *G_TEXTEDIT = ".textedit"#

static char const *G_PRESET = ".preset"#

static char const *G_COUNTER = ".counter"#

static char const *G_ACCUM = ".accum"#

static char const *G_SWITCH = ".switch"#

static char const *G_GATE = ".gate"#

static char const *G_ROUTE = ".route"#

static char const *G_ROUTEPASS = ".routepass"#

static char const *G_ROUTER = ".router"#

static char const *G_MATRIX = ".matrix"#

static char const *G_FORWARD = ".forward"#

static char const *G_VALUE = ".value"#

static char const *G_SEL = ".sel"#

static char const *G_TRIGGER = ".trigger"#

static char const *G_BANGBANG = ".bangbang"#

static char const *G_ONEBANG = ".onebang"#

static char const *G_NEXT = ".next"#

static char const *G_MATCH = ".match"#

static char const *G_UZI = ".uzi"#

static char const *G_ITER = ".iter"#

static char const *G_BONDO = ".bondo"#

static char const *G_BUDDY = ".buddy"#

static char const *G_CYCLE = ".cycle"#

static char const *G_BUCKET = ".bucket"#

static char const *G_SPRAY = ".spray"#

static char const *G_FUNNEL = ".funnel"#

static char const *G_DECODE = ".decode"#

static char const *G_IF = ".if"#

static char const *G_REGEXP = ".regexp"#

static char const *G_PREPEND = ".prepend"#

static char const *G_APPEND = ".append"#

static char const *G_SUBSTITUTE = ".substitute"#

static char const *G_SPRINTF = ".sprintf"#

static char const *G_TOSYMBOL = ".tosymbol"#

static char const *G_FROMSYMBOL = ".fromsymbol"#

static char const *G_COMBINE = ".combine"#

static char const *G_SPELL = ".spell"#

static char const *G_ATOI = ".atoi"#

static char const *G_ITOA = ".itoa"#

static char const *G_TOLOWER = ".tolower"#

static char const *G_TOUPPER = ".toupper"#

static char const *G_ZL = ".zl"#

static char const *G_PACK = ".pack"#

static char const *G_PAK = ".pak"#

static char const *G_UNPACK = ".unpack"#

static char const *G_JOIN = ".join"#

static char const *G_UNJOIN = ".unjoin"#

static char const *G_LISTFUNNEL = ".listfunnel"#

static char const *G_COLL = ".coll"#

static char const *G_BAG = ".bag"#

static char const *G_CAPTURE = ".capture"#

static char const *G_FUNBUFF = ".funbuff"#

static char const *G_TABLE = ".table"#

static char const *G_TEXTFILE = ".textfile"#

static char const *G_QLIST = ".qlist"#

static char const *G_MTR = ".mtr"#

static char const *G_SEQ = ".seq"#

static char const *G_DICT = ".dict"#

static char const *G_DICT_COMPARE = ".dict.compare"#

static char const *G_DICT_DESERIALIZE = ".dict.deserialize"#

static char const *G_DICT_GROUP = ".dict.group"#

static char const *G_DICT_ITER = ".dict.iter"#

static char const *G_DICT_JOIN = ".dict.join"#

static char const *G_DICT_PACK = ".dict.pack"#

static char const *G_DICT_PRINT = ".dict.print"#

static char const *G_DICT_ROUTE = ".dict.route"#

static char const *G_DICT_SERIALIZE = ".dict.serialize"#

static char const *G_DICT_SLICE = ".dict.slice"#

static char const *G_DICT_STRIP = ".dict.strip"#

static char const *G_DICT_UNPACK = ".dict.unpack"#

static char const *G_ARRAY = ".array"#

static char const *G_ARRAY_AT = ".array.at"#

static char const *G_ARRAY_LENGTH = ".array.length"#

static char const *G_ARRAY_PUSH = ".array.push"#

static char const *G_ARRAY_POP = ".array.pop"#

static char const *G_ARRAY_SHIFT = ".array.shift"#

static char const *G_ARRAY_UNSHIFT = ".array.unshift"#

static char const *G_ARRAY_INSERT = ".array.insert"#

static char const *G_ARRAY_REMOVE = ".array.remove"#

static char const *G_ARRAY_INDEXOF = ".array.indexof"#

static char const *G_ARRAY_INDEX = ".array.index"#

static char const *G_ARRAY_INDEXMAP = ".array.indexmap"#

static char const *G_ARRAY_REVERSE = ".array.reverse"#

static char const *G_ARRAY_ROTATE = ".array.rotate"#

static char const *G_ARRAY_SCRAMBLE = ".array.scramble"#

static char const *G_ARRAY_SHUFFLE = ".array.shuffle"#

static char const *G_ARRAY_SORT = ".array.sort"#

static char const *G_ARRAY_MIN = ".array.min"#

static char const *G_ARRAY_MAX = ".array.max"#

static char const *G_ARRAY_MEAN = ".array.mean"#

static char const *G_ARRAY_MEDIAN = ".array.median"#

static char const *G_ARRAY_MODE = ".array.mode"#

static char const *G_ARRAY_STDDEV = ".array.stddev"#

static char const *G_ARRAY_SLICE = ".array.slice"#

static char const *G_ARRAY_SUBARRAY = ".array.subarray"#

static char const *G_ARRAY_SUB = ".array.sub"#

static char const *G_ARRAY_SPLIT = ".array.split"#

static char const *G_ARRAY_UNION = ".array.union"#

static char const *G_ARRAY_SECT = ".array.sect"#

static char const *G_ARRAY_UNIQUE = ".array.unique"#

static char const *G_ARRAY_CONCAT = ".array.concat"#

static char const *G_ARRAY_JOIN = ".array.join"#

static char const *G_ARRAY_FILL = ".array.fill"#

static char const *G_ARRAY_FLATTEN = ".array.flatten"#

static char const *G_ARRAY_TOLIST = ".array.tolist"#

static char const *G_ARRAY_TOSTRING = ".array.tostring"#

static char const *G_ARRAY_TOSYMBOL = ".array.tosymbol"#

static char const *G_ARRAY_DESERIALIZE = ".array.deserialize"#

static char const *G_ARRAY_ITER = ".array.iter"#

static char const *G_ARRAY_EXPR = ".array.expr"#

static char const *G_ARRAY_MAP = ".array.map"#

static char const *G_ARRAY_FILTER = ".array.filter"#

static char const *G_ARRAY_REDUCE = ".array.reduce"#

static char const *G_ARRAY_EVERY = ".array.every"#

static char const *G_ARRAY_SOME = ".array.some"#

static char const *G_ARRAY_FOREACH = ".array.foreach"#

static char const *G_ARRAY_CHANGE = ".array.change"#

static char const *G_ARRAY_COMPARE = ".array.compare"#

static char const *G_ARRAY_GROUP = ".array.group"#

static char const *G_ARRAY_REPLACE = ".array.replace"#

static char const *G_ARRAY_REGEXP = ".array.regexp"#

static char const *G_ARRAY_ROUTEPASS = ".array.routepass"#

static char const *G_ARRAY_RANDOM = ".array.random"#

static char const *G_ARRAY_STREAM = ".array.stream"#

static char const *G_ARRAY_THIN = ".array.thin"#

static char const *G_ARRAY_TUPLEWISE = ".array.tuplewise"#

static char const *G_ARRAY_WRAP = ".array.wrap"#

static char const *G_PRINT = ".print"#

static char const *G_LOADBANG = ".loadbang"#

static char const *G_LOADMESS = ".loadmess"#

static char const *G_ADD = ".+"#

static char const *G_SUBSTRACT = ".-"#

static char const *G_MULTIPLY = ".*"#

static char const *G_DIVIDE = "./"#

static char const *G_REVERSESUBSTRACT = ".!-"#

static char const *G_REVERSEDIVIDE = ".!/"#

static char const *G_SWAP = ".swap"#

static char const *G_MODULO = ".%"#

static char const *G_INTDIVIDE = ".div"#

static char const *G_SCALE = ".scale"#

static char const *G_ZMAP = ".zmap"#

static char const *G_LINEDRIVE = ".linedrive"#

static char const *G_CLIP = ".clip"#

static char const *G_PONG = ".pong"#

static char const *G_SPLIT = ".split"#

static char const *G_SLIDE = ".slide"#

static char const *G_EXPR = ".expr"#

static char const *G_VEXPR = ".vexpr"#

static char const *G_ABS = ".abs"#

static char const *G_SQRT = ".sqrt"#

static char const *G_POW = ".pow"#

static char const *G_ROUND = ".round"#

static char const *G_SIN = ".sin"#

static char const *G_COS = ".cos"#

static char const *G_TAN = ".tan"#

static char const *G_ASIN = ".asin"#

static char const *G_ACOS = ".acos"#

static char const *G_ATAN = ".atan"#

static char const *G_ATAN2 = ".atan2"#

static char const *G_SINH = ".sinh"#

static char const *G_COSH = ".cosh"#

static char const *G_TANH = ".tanh"#

static char const *G_ASINH = ".asinh"#

static char const *G_ACOSH = ".acosh"#

static char const *G_ATANH = ".atanh"#

static char const *G_EQUAL = ".=="#

static char const *G_NOTEQUAL = ".!="#

static char const *G_LESS = ".<"#

static char const *G_LESSEQUAL = ".<="#

static char const *G_GREATER = ".>"#

static char const *G_GREATEREQUAL = ".>="#

static char const *G_LOGICALAND = ".&&"#

static char const *G_LOGICALOR = ".||"#

static char const *G_MAXIMUM = ".maximum"#

static char const *G_MINIMUM = ".minimum"#

static char const *G_PEAK = ".peak"#

static char const *G_TROUGH = ".trough"#

static char const *G_PAST = ".past"#

static char const *G_CHANGE = ".change"#

static char const *G_TOGEDGE = ".togedge"#

static char const *G_BITAND = ".&"#

static char const *G_BITOR = ".|"#

static char const *G_SHIFTLEFT = ".<<"#

static char const *G_SHIFTRIGHT = ".>>"#

static char const *G_RANDOM = ".random"#

static char const *G_DRUNK = ".drunk"#

static char const *G_URN = ".urn"#

static char const *G_DECIDE = ".decide"#

static char const *G_PROB = ".prob"#

static char const *G_ANAL = ".anal"#

static char const *G_HISTO = ".histo"#

static char const *G_MEAN = ".mean"#

static char const *G_METRO = ".metro"#

static char const *G_DELAY = ".delay"#

static char const *G_TRANSPORT = ".transport"#

static char const *G_SETCLOCK = ".setclock"#

static char const *G_WHEN = ".when"#

static char const *G_TRANSLATE = ".translate"#

static char const *G_TIMEPOINT = ".timepoint"#

static char const *G_TEMPO = ".tempo"#

static char const *G_CLOCKER = ".clocker"#

static char const *G_TIMER = ".timer"#

static char const *G_PIPE = ".pipe"#

static char const *G_SPEEDLIM = ".speedlim"#

static char const *G_QLIM = ".qlim"#

static char const *G_THRESH = ".thresh"#

static char const *G_QUICKTHRESH = ".quickthresh"#

static char const *G_LINE = ".line"#

static char const *G_BLINE = ".bline"#

static char const *D_ADD = "~+"#

static char const *D_SUBSTRACT = "~-"#

static char const *D_MULTIPLY = "~*"#

static char const *D_DIVIDE = "~/"#

static char const *D_CLIP = "~clip"#

static char const *MIDITOFREQUENCY = ".mtof"#

static char const *FREQUENCYTOMIDI = ".ftom"#

static char const *G_ATODB = ".atodb"#

static char const *G_DBTOA = ".dbtoa"#

static char const *G_CARTOPOL = ".cartopol"#

static char const *G_POLTOCAR = ".poltocar"#

static char const *D_LOWPASS = "~lp"#

static char const *D_HIGHPASS = "~hp"#

static char const *D_BANDPASS = "~bp"#

static char const *D_VCF = "~vcf"#

static char const *M_OUT = ".midiout"#

static char const *M_IN = ".midiin"#

static char const *M_NOTEIN = ".notein"#

static char const *M_CTLIN = ".ctlin"#

static char const *M_BENDIN = ".bendin"#

static char const *M_PGMIN = ".pgmin"#

static char const *M_TOUCHIN = ".touchin"#

static char const *M_POLYIN = ".polyin"#

static char const *M_RTIN = ".rtin"#

static char const *M_NOTEON = ".noteon"#

static char const *M_NOTEOFF = ".noteoff"#

static char const *M_CONTROL = ".controlchange"#

static char const *M_POLYPRESS = ".polypressure"#

static char const *M_CHANPRESS = ".channelpressure"#

static char const *M_PROGCHANGE = ".programchange"#

static char const *M_BENDOUT = ".bendout"#

static char const *M_PARSE = ".midiparse"#

static char const *M_FORMAT = ".midiformat"#

static char const *M_SYSEXIN = ".sysexin"#

static char const *M_SXFORMAT = ".sxformat"#

static char const *M_XBENDIN = ".xbendin"#

static char const *M_XBENDIN2 = ".xbendin2"#

static char const *M_XCTLIN = ".xctlin"#

static char const *M_XNOTEIN = ".xnotein"#

static char const *M_XMIDIIN = ".xmidiin"#

static char const *M_XBENDOUT = ".xbendout"#

static char const *M_XBENDOUT2 = ".xbendout2"#

static char const *M_XCTLOUT = ".xctlout"#

static char const *M_XNOTEOUT = ".xnoteout"#

static char const *M_RPNIN = ".rpnin"#

static char const *M_NRPNIN = ".nrpnin"#

static char const *M_RPNOUT = ".rpnout"#

static char const *M_NRPNOUT = ".nrpnout"#

static char const *M_MPECONFIG = ".mpeconfig"#

static char const *M_MPEFORMAT = ".mpeformat"#

static char const *M_MPEPARSE = ".mpeparse"#

static char const *M_MIDIINFO = ".midiinfo"#

static char const *M_MIDIFLUSH = ".midiflush"#

static char const *M_MAKENOTE = ".makenote"#

static char const *M_STRIPNOTE = ".stripnote"#

static char const *M_FLUSH = ".flush"#

static char const *M_SUSTAIN = ".sustain"#

static char const *M_POLY = ".poly"#

static char const *M_BORAX = ".borax"#

static char const *M_OFFER = ".offer"#

Running a patcher as an insert#

Wrap a built patcher graph in a DSP::patcherInsert to attach it anywhere a DSP::dspObject chain goes — a channel or per-sound insert.

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 DSP

Audio buffers, oscillators, filters, envelopes, and effect modules.

Build chains of DSP::dspObject to process a sound, DSP::dspSourceObject to feed one. Single-channel audio data lives in DSP::buffer and its drawing / file / wavetable subclasses.

class patcherInsert : public YSE::DSP::dspObject #

Runs a YSE::patcher graph as an insert effect.

A patcherInsert wraps a patcher so it can be attached anywhere a DSP::dspObject chain goes — YSE::sound::setDSP or YSE::channel::setDSP (issue #167). Each process call feeds the host’s incoming audio to the graph’s ~adc objects, renders the graph, and copies the summed ~dac output back over the host buffer in place. This turns a hand-patched network (a filter-delay, a custom EQ, …) into a channel or per-sound insert.

Build the patcher (with at least one ~adc and one ~dac) before attaching the insert, and keep it alive for as long as the insert is attached — the insert borrows the patcher, it does not own it.

Channel-count behaviour#

The graph is created with a fixed channel count (patcher::create). When the host buffer has a different channel count than the graph:

fewer host channels than graph inputs: the extra ~adc channels get no input (silent);
fewer graph outputs than host channels: the extra host channels pass through unchanged (dry) — only the channels the graph produces are replaced.

Public Functions

explicit patcherInsert(YSE::patcher &patch)#

Wrap patch as an insert.

patch must outlive this object.

virtual void create() override#: No-op: the wrapped patcher owns its own graph and buffers.

virtual void process(std::vector<YSE::DSP::buffer> &buffer) override#

Render the patcher over buffer in place.

Audio thread.

Private Members

YSE::patcher *patch#

C++ API reference

Contents

C++ API reference#

Running a patcher as an insert#

Channel-count behaviour#