Patcher

Patcher#

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

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 "<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.

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.

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

Remove the connection from from’s outlet to to’s inlet.

std::string DumpJSON()#

Serialise the current graph to JSON.

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

Replace the current graph with the contents of a JSON dump.

unsigned int Objects()#

Number of objects in the patcher.

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.

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#

Friends

friend class YSE::sound
friend class YSE::DSP::patcherInsert
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 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.

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.

std::string GetName()#

Display name of this object (set in the patcher source).

std::string GetParams()#

Original creation argument string.

unsigned int GetID()#

Unique patcher-assigned ID.

unsigned int GetConnections(unsigned int outlet)#

Number of connections leaving outlet outlet.

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

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

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

Inlet on the target that this connection reaches.

std::string GetGuiValue()#

Current GUI display value for objects that have one (sliders, toggles, …).

Private Members

PATCHER::pObject *object#

Defines

DEFOBJ(name, tag)#
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.

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.

  • DSP filters: D_LOWPASS, D_HIGHPASS, D_BANDPASS, D_VCF.

  • I/O: D_DAC, D_ADC, D_LINE, D_OUT.

  • Control: G_INT, G_FLOAT, G_SLIDER, G_METRO, G_RANDOM.

  • Messaging: G_SEND, G_RECEIVE, G_ROUTE, G_GATE, G_SWITCH.

  • MIDI: M_OUT, M_NOTEON, M_NOTEOFF, M_CONTROL.

  • Conversion: MIDITOFREQUENCY, FREQUENCYTOMIDI.

Public Static Attributes

static constexpr char const *PATCHER = "patcher"#
static constexpr char const *D_DAC = "~dac"#
static constexpr char const *D_ADC = "~adc"#
static constexpr char const *G_RECEIVE = ".r"#
static constexpr char const *G_SEND = ".s"#
static constexpr char const *D_OUT = "~out"#
static constexpr char const *D_LINE = "~line"#
static constexpr char const *D_SINE = "~sine"#
static constexpr char const *D_SAW = "~saw"#
static constexpr char const *D_NOISE = "~noise"#
static constexpr char const *G_INT = ".i"#
static constexpr char const *G_FLOAT = ".f"#
static constexpr char const *G_SLIDER = ".slider"#
static constexpr char const *G_BUTTON = ".b"#
static constexpr char const *G_TOGGLE = ".t"#
static constexpr char const *G_MESSAGE = ".m"#
static constexpr char const *G_LIST = ".l"#
static constexpr char const *G_TEXT = ".text"#
static constexpr char const *G_COUNTER = ".counter"#
static constexpr char const *G_SWITCH = ".switch"#
static constexpr char const *G_GATE = ".gate"#
static constexpr char const *G_ROUTE = ".route"#
static constexpr char const *G_ADD = ".+"#
static constexpr char const *G_SUBSTRACT = ".-"#
static constexpr char const *G_MULTIPLY = ".*"#
static constexpr char const *G_DIVIDE = "./"#
static constexpr char const *G_RANDOM = ".random"#
static constexpr char const *G_METRO = ".metro"#
static constexpr char const *D_ADD = "~+"#
static constexpr char const *D_SUBSTRACT = "~-"#
static constexpr char const *D_MULTIPLY = "~*"#
static constexpr char const *D_DIVIDE = "~/"#
static constexpr char const *D_CLIP = "~clip"#
static constexpr char const *MIDITOFREQUENCY = ".mtof"#
static constexpr char const *FREQUENCYTOMIDI = ".ftom"#
static constexpr char const *D_LOWPASS = "~lp"#
static constexpr char const *D_HIGHPASS = "~hp"#
static constexpr char const *D_BANDPASS = "~bp"#
static constexpr char const *D_VCF = "~vcf"#
static constexpr char const *M_OUT = ".midiout"#
static constexpr char const *M_NOTEON = ".noteon"#
static constexpr char const *M_NOTEOFF = ".noteoff"#
static constexpr char const *M_CONTROL = ".controlchange"#
static constexpr char const *M_POLYPRESS = ".polypressure"#
static constexpr char const *M_CHANPRESS = ".channelpressure"#
static constexpr char const *M_PROGCHANGE = ".programchange"#

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.

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 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.

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#

Object reference