Processing Expression

NodeBuffer connects the node system (sample-by-sample evaluation) to the buffer system (block-based processing).

Default processor: NodeSourceProcessor

Each cycle:

1. Node is evaluated 512 times: node->process_sample()
2. Results fill the buffer
3. Processing chain runs (your custom processors)
4. Buffer outputs to speakers

Why this matters:

Nodes are mathematical expressions—infinite generators. Buffers are temporal accumulators—finite chunks.

NodeBuffer bridges the two: continuous expression → discrete blocks.

Without NodeBuffer, you'd manually call node->process_sample() 512 times and copy results into a buffer. NodeBuffer automates this.

NodeBuffer has a flag: clear_before_process

auto node_buffer = vega.NodeBuffer(0, 512, sine, true);  // Clear first (default)
      

true (default): Buffer is zeroed, then filled with node output

• Result: pure node output

false: Node output is added to existing buffer content

• Result: node output + previous buffer state

Why use false?

• Layering: Multiple nodes contributing to the same buffer
• Feedback: Previous cycle's output influences current cycle
• Additive synthesis: Mix multiple generators

Example (layering):

auto sine = vega.Sine(440.0);
auto buffer = vega.NodeBuffer(0, 512, sine, true)[0] | Audio;  // First node clears

auto noise = vega.Random();
auto noise_buffer = vega.NodeBuffer(0, 512, noise, false)[0] | Audio;  // Adds to sine
      

Result: sine + noise.

NodeSourceProcessor has a mix parameter (default: 0.5):

auto processor = std::make_shared<NodeSourceProcessor>(node, 0.7f);
      

Mix = 0.0: Preserve existing buffer content (node output ignored)
Mix = 0.5: Equal blend of existing + node output
Mix = 1.0: Replace with node output (existing content overwritten)

This is a cross-fade between what's in the buffer and what the node generates.

Use case: Smoothly transition between sources, or create feedback loops where node output gradually replaces decaying buffer content.

Most of the time, you'll use the default (1.0 via clear_before_process=true). But for creative effects, mix is powerful.

Default processor: FeedbackProcessor

Each cycle:

1. Current buffer content: buffer[n]
2. Previous buffer content: previous_buffer[n-1]
3. Output: buffer[n] + (feedback_amount * previous_buffer[n-1])
4. Store output as next cycle's "previous"

This is a simple delay line with feedback.

Parameters:

• feedback_amount: 0.0–1.0 (how much previous state contributes)
• feed_samples: Delay length in samples

Example: FeedbackBuffer(0, 512, 0.7, 512) creates:

• 512-sample delay (~10.6 ms at 48 kHz)
• 70% feedback (echoes decay to 0.7 → 0.49 → 0.343 → ...)

Stability: Keep feedback_amount < 1.0 or output will grow unbounded.

FeedbackBuffer is simple—intentionally. It implements one specific recursive algorithm: linear feedback delay.

Limitations:

1. Fixed feedback coefficient: Can't modulate feedback amount per sample (it's buffer-wide)
2. No filtering in loop: Can't insert lowpass/highpass in the feedback path
3. No cross-channel feedback: Single-channel only
4. No time-varying delay: Delay length is fixed at creation

Why these limitations?

FeedbackBuffer is a building block, not a complete reverb/delay effect.

For complex feedback systems:

• Use PolynomialProcessor in RECURSIVE mode (per-sample nonlinear feedback)
• Use BufferPipeline to route buffers back to themselves with processing
• Build custom feedback networks with multiple buffers

FeedbackBuffer is for simple echoes and resonances—quick and efficient.

Use FeedbackBuffer when:

• You need a simple delay line with fixed feedback
• Building Karplus-Strong string synthesis
• Creating rhythmic echoes
• Implementing comb filters

Use PolynomialProcessor(RECURSIVE) when:

• You need nonlinear feedback (saturation, distortion in loop)
• Feedback amount varies per sample
• Building filters with arbitrary feedback functions

Use BufferPipeline when:

• You need complex routing (buffer A → process → buffer B → back to A)
• Multi-buffer feedback networks
• Cross-channel feedback

Example: Filtered feedback (requires multiple approaches):

// FeedbackBuffer can't do this alone:
// current + lowpass(feedback * previous)

// Solution: Use PolynomialProcessor RECURSIVE mode with filtering
auto filtered_feedback = vega.Polynomial(
    [](std::span<double> amp; history) {
        double fb = 0.7 * history[0];
        return fb * 0.5 + history[1] * 0.5;  // Simple lowpass
    },
    PolynomialMode::RECURSIVE,
    2
);
      

SoundStreamWriter is the inverse of SoundContainerBuffer:

• SoundContainerBuffer: reads from container → fills buffer (source)
• SoundStreamWriter: reads from buffer → writes to container (sink)

Each cycle:

1. Extract 512 samples from the buffer
2. Write them to the DynamicSoundStream at the current write position
3. Increment write position by 512

The stream grows dynamically as data arrives. No pre-allocation needed (though you can for performance).

Use cases:

• Record processed audio to memory
• Capture intermediate processing stages for analysis
• Build delay lines / loopers
• Create feedback paths (buffer → stream → buffer)

SoundStreamWriter respects buffer channel IDs:

auto left_buffer = buffers[0];   // channel 0
auto right_buffer = buffers[1];  // channel 1

auto stream = std::make_shared<DynamicSoundStream>(48000, 2);  // stereo

auto writer_L = std::make_shared<SoundStreamWriter>(stream);
auto writer_R = std::make_shared<SoundStreamWriter>(stream);

// Add to respective buffers
left_buffer->get_processing_chain()->add_processor(writer_L);
right_buffer->get_processing_chain()->add_processor(writer_R);
      

Result: Stereo file captured to stereo stream—channels preserved.

Critical: Buffer's channel_id determines which stream channel receives data. Mismatch = warning + skip.

SoundStreamWriter tracks where it's writing:

writer->set_write_position(0);        // Write from start
writer->set_write_position(48000);    // Write from 1-second mark
writer->reset_position();             // Reset to 0

// Time-based positioning
writer->set_write_position_time(2.5); // Write from 2.5 seconds

uint64_t pos = writer->get_write_position();           // Get current frame position
double time = writer->get_write_position_time();       // Get current time position
      

Why control position?

• Overdubbing: Write new audio over existing content
• Looping: Reset position to create cyclic recording
• Multi-pass recording: Capture different takes at different positions

Default behavior: append at end. Position auto-increments.

DynamicSoundStream can operate in circular mode:

auto stream = std::make_shared<DynamicSoundStream>(48000, 2);
stream->enable_circular_buffer(48000);  // 1 second capacity

auto writer = std::make_shared<SoundStreamWriter>(stream);
      

Behavior:

When write position reaches capacity, it wraps to 0. Old data is overwritten.

Use cases:

• Delay lines: Fixed-length delays for effects
• Loopers: Record N seconds, then loop
• Rolling analysis: Keep only the most recent N seconds

Without circular mode, the stream grows unbounded—useful for full recording, problematic for long-running systems.

MayaFlux has a dedicated input subsystem parallel to the output system.

Architecture:

Hardware (Microphone)
    ↓
Audio Driver (RtAudio)
    ↓
BufferManager::process_input()
    ↓
InputAudioBuffer (per input channel)
    ↓
InputAccessProcessor (dispatches to listeners)
    ↓
Your listener buffers
      

When you call create_input_listener_buffer(channel, add_to_output):

1. Creates a new AudioBuffer
2. Registers it with InputAudioBuffer[channel] as a listener
3. If add_to_output=true: Also registers it with output channel (so it plays back)

Each audio cycle:

• Driver captures microphone data
• InputAudioBuffer receives it
• InputAccessProcessor copies data to all registered listeners
• Your buffer gets fresh input every cycle

Key insight: InputAudioBuffer is a hub. Multiple buffers can listen to the same input channel simultaneously.

create_input_listener_buffer() is convenience. You can do it manually:

// Create your own buffer
auto buffer = vega.AudioBuffer()[0] | Audio;

// Register it as input listener
MayaFlux::read_from_audio_input(buffer, 0);  // Listen to input channel 0

// Later, stop listening:
MayaFlux::detach_from_audio_input(buffer, 0);
      

When to use manual registration:

• You already have a buffer (don't want to create a new one)
• You want to dynamically start/stop listening (e.g., record button)
• You need finer control over buffer lifecycle

Example: Record button

auto recorder = vega.AudioBuffer()[0] | Audio;

// Start recording
MayaFlux::read_from_audio_input(recorder, 0);

// Stop recording (after some time)
MayaFlux::detach_from_audio_input(recorder, 0);
      

The buffer continues to exist and process, but stops receiving new input.

Often you want to capture input without playing it back:

// Create listener but don't add to output
auto mic_capture = MayaFlux::create_input_listener_buffer(0, false);  // false = silent

// Capture to a stream for analysis
auto stream = std::make_shared<DynamicSoundStream>(48000, 1);
auto writer = std::make_shared<SoundStreamWriter>(stream);
mic_capture->get_processing_chain()->add_processor(writer);
      

Result: Microphone data is captured to stream, but you don't hear it.

Use cases:

• Recording without monitoring
• Voice analysis (pitch detection, speech recognition)
• Trigger detection (clap to start/stop)
• Level metering / VU display

Registration (vega.AudioBuffer()[0] | Audio):

• Adds buffer as a child of RootAudioBuffer[0]
• Buffer processes during channel 0's cycle
• Output accumulates into channel 0

Supply (supply_buffer_to_channels):

• Adds buffer's output to other channels
• Buffer still processes in its original channel
• Output is copied to supplied channels

Analogy:

• Registration = "This buffer lives in channel 0"
• Supply = "After processing in channel 0, send copies to channels 1 and 2"

Architecture:

Buffer processes in channel 0
    ↓
Output goes to RootAudioBuffer[0]
    ↓
MixProcessor copies output to RootAudioBuffer[1]
    ↓
MixProcessor copies output to RootAudioBuffer[2]
      

Key: The buffer only processes once. Supply is a routing operation, not a duplication of processing.

The mix parameter controls how much of the buffer's output is sent:

MayaFlux::supply_buffer_to_channel(buffer, 1, 1.0);  // 100% (unity gain)
MayaFlux::supply_buffer_to_channel(buffer, 2, 0.5);  // 50% (half amplitude)
MayaFlux::supply_buffer_to_channel(buffer, 3, 0.1);  // 10% (quiet)
      

Use case: Stereo width control

auto mono_source = vega.Sine(440.0);
auto buffer = vega.NodeBuffer(0, 512, mono_source)[0] | Audio;

// Send to left (full) and right (half) for asymmetric stereo
MayaFlux::supply_buffer_to_channel(buffer, 0, 1.0);  // Left
MayaFlux::supply_buffer_to_channel(buffer, 1, 0.5);  // Right (quieter)
      

Use case: Send effects

auto dry = vega.NodeBuffer(0, 512, sine)[0] | Audio;  // Dry signal, channel 0

// Send 30% to reverb channel
MayaFlux::supply_buffer_to_channel(dry, 2, 0.3);  // Channel 2 = reverb bus
      

Mix is additive. If channel already has content, supply adds to it.

You can remove supply relationships:

auto buffer = vega.NodeBuffer(0, 512, sine)[0] | Audio;
MayaFlux::supply_buffer_to_channel(buffer, 1);

// Later: stop sending to channel 1
MayaFlux::remove_supplied_buffer_from_channel(buffer, 1);

// Or remove from multiple channels at once
MayaFlux::remove_supplied_buffer_from_channels(buffer, {1, 2, 3});
      

Use case: Mute individual sends

• Buffer still processes
• Output still goes to its registered channel
• Supplied channels no longer receive it

Use case: Dynamic routing matrices

if (user_pressed_button_A) {
    MayaFlux::supply_buffer_to_channel(buffer, 1);
} else {
    MayaFlux::remove_supplied_buffer_from_channel(buffer, 1);
}
      

Supply:

• One buffer processes once
• Output is copied to multiple channels
• Processing cost: 1× processing
• Memory: One buffer
• Use when: Same signal needs to go to multiple places

Clone:

• Multiple buffers process independently
• Each has its own data, state, processing chain
• Processing cost: N× processing (N = number of clones)
• Memory: N buffers
• Use when: Similar buffers need independent processing

Example: Supply use case

// One reverb output to stereo speakers
auto reverb = vega.FeedbackBuffer(0, 512, 0.8f, 4800)[0] | Audio;
MayaFlux::supply_buffer_to_channel(reverb, 1);  // Copy to right channel
// Cost: 1× reverb processing
      

Example: Clone use case

// Independent noise generators per channel
auto noise_template = vega.NodeBuffer(0, 512, vega.Random(-1.0, 1.0));
MayaFlux::clone_buffer_to_channels(noise_template, {0, 1, 2, 3});
// Cost: 4× noise processing (each with different random seed/state)
// Result: Decorrelated noise on each channel
      

When you clone a buffer, each clone receives:

• Same buffer type (NodeBuffer, FeedbackBuffer, etc.)
• Same default processor configuration
• Same processing chain (all added processors)
• Independent data (not shared—each clone has its own samples)
• Independent state (feedback buffers have separate history)

Example: Clone a processed buffer

auto sine = vega.Sine(440.0);
auto buffer = vega.NodeBuffer(0, 512, sine);

// Add processing before cloning
auto distortion = vega.Polynomial([](double x) { return std::tanh(x * 2.0); });
MayaFlux::create_processor<PolynomialProcessor>(buffer, distortion);

// Now clone
MayaFlux::clone_buffer_to_channels(buffer, {0, 1, 2});

// Result: Each channel gets sine → distortion (independently processed)
      

Each clone has its own instance of the distortion processor. They don't share state.

After cloning, you can modify individual clones:

auto buffer = vega.NodeBuffer(0, 512, vega.Sine(440.0));
// Store cloned buffers for later reference
auto cloned_buffers = MayaFlux::clone_buffer_to_channels(buffer, { 0, 1, 2 });


// Add different processing to each
std::vector<double> coeffs_a_2 = { 0.2, 0.3, 0.2 };
std::vector<double> coeffs_b_2 = { 1.0, -0.7 };
auto filter1 = vega.IIR(coeffs_a_1, coeffs_b_1);
auto filter2 = vega.IIR(coeffs_a_2, coeffs_b_2);

MayaFlux::create_processor<FilterProcessor>(cloned_buffers[0], filter1);
MayaFlux::create_processor<FilterProcessor>(cloned_buffers[1], filter2);

// Now channel 0 has one filter, channel 1 has a different filter
      

Use case: Stereo decorrelation (same source, slightly different processing per channel)