RNBO Real-Time Audio Project

A cross-platform real-time audio application using RNBO (Cycling '74) and RtAudio.

Quick Start

# Build the project
./build.sh

# Run the application
cd build && ./RNBOCommandLine

# Press Ctrl+C to quit

Current Configuration

• Sample Rate: 44100 Hz
• Buffer Size: 64 samples (~1.45ms latency)
• Audio I/O: 1 input channel (mono), 2 output channels (stereo)
• RNBO Parameters: level (0-0.6), decouple (0-1)

Understanding Audio Glitches

What are "Output underflows"?

An output underflow occurs when the audio callback can't provide audio data fast enough. This causes:

• Clicks, pops, or dropouts in audio
• Interrupted sound playback
• Glitchy audio output

Should You Worry?

Underflow Count	Assessment	Action Needed
0	✓ Perfect!	None - enjoy your clean audio
1-5	⚠️ Minor	Likely startup glitches - monitor if it continues
5-20	⚠️ Moderate	Increase buffer size or optimize patch
20+	❌ Critical	System can't keep up - see solutions below

Common Causes

1. Startup initialization - First few buffers sometimes glitch (normal)
2. Buffer size too small - 64 samples = only 1.45ms processing time
3. CPU overload - Other apps competing for CPU
4. Debug build - Unoptimized code runs slower
5. Complex RNBO patch - Heavy DSP processing

Solutions for Audio Underflows

Solution 1: Increase Buffer Size (Recommended)

Trade latency for stability. Modify main.cpp:

// Current: 64 samples = 1.45ms latency
config.bufferFrames = 64;

// Try: 128 samples = 2.9ms latency (still good for guitar)
config.bufferFrames = 128;

// Or: 256 samples = 5.8ms latency (very stable)
config.bufferFrames = 256;

When to use:

• If you see frequent underflows
• If you're not concerned about ultra-low latency
• For complex RNBO patches

Solution 2: Release Build (if using Xcode/IDE)

Debug builds are much slower. Build in release mode:

cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make

Performance gain: 2-5x faster

Solution 3: Reduce System Load

• Close unnecessary applications
• Disable Wi-Fi/Bluetooth if not needed
• Check Activity Monitor for CPU hogs
• Quit browser tabs and other apps

Solution 4: Optimize RNBO Patch

In Max/MSP before exporting:

• Reduce poly~ voice count
• Remove unnecessary processing
• Use efficient objects (biquad~ vs multiple filtergraph~)
• Check CPU usage in Max before exporting

Solution 5: Use Different Audio Backend

On macOS, RtAudio uses CoreAudio. Some audio interfaces perform better than others:

# List devices and try different output devices
./RNBOCommandLine 129 129  # Use device 129 for both input/output
./RNBOCommandLine 0 1      # Try different device combinations

Monitoring Performance

The application now tracks underflows and reports statistics at shutdown:

Audio Statistics:
  Input overflows: 0
  Output underflows: 0
  ✓ Clean audio stream!

Run your application for a typical session, then check the stats when you quit (Ctrl+C).

Troubleshooting

Problem: Constant underflows even at 256 samples

Diagnosis: Your RNBO patch is too complex for real-time processing.

Solutions:

1. Simplify the Max patch
2. Reduce poly~ voice count
3. Use a faster computer
4. Profile the patch in Max before exporting

Problem: Underflows only at startup

Diagnosis: Normal - audio system initialization can cause brief glitches.

Solution: Ignore if it's just the first 1-5 underflows. Add a warmup period if needed.

Problem: No sound output

Check:

1. Correct audio device selected (check device list in output)
2. System volume not muted
3. RNBO patch has audio outputs connected
4. Parameter values (e.g., level is > 0)

Problem: Input not being processed

Diagnosis: Your RNBO patch was exported without audio inputs.

Solution:

1. Open rnbo_guitar.maxpat in Max/MSP
2. Add adc~ objects for input
3. Connect to your effects chain
4. Re-export C++ code from RNBO
5. Replace rnbo_source.cpp and description.json

Advanced Configuration

Custom Sample Rates

Modify main.cpp:

config.sampleRate = 48000;  // Higher quality
config.sampleRate = 22050;  // Lower CPU usage

Note: Your audio interface must support the sample rate.

Parameter Control

Parameters can be controlled from the command line (future enhancement) or by modifying main.cpp:

// Set parameter before starting audio
int levelIndex = rnboObject.getParameterIndexForID("level");
rnboObject.setParameterValue(levelIndex, 0.3);

Project Structure

RnboTest/
├── main.cpp              - Application entry point
├── AudioContext.h        - Real-time audio management
├── CMakeLists.txt        - Build configuration
├── build.sh              - Build automation script
├── rnbo_source.cpp       - RNBO exported code
├── description.json      - RNBO patch metadata
├── presets.json          - RNBO presets
└── rnbo/                 - RNBO C++ SDK

Performance Benchmarks

Buffer Size	Latency	CPU Headroom	Best For
32 samples	0.73ms	Very tight	Pro audio interfaces only
64 samples	1.45ms	Tight	Guitar processing, simple patches
128 samples	2.90ms	Comfortable	General use, moderate patches
256 samples	5.80ms	Lots	Complex patches, slower systems
512 samples	11.6ms	Maximum	Non-interactive processing

Building for Different Platforms

macOS (tested)

./build.sh

Linux

# Install ALSA development libraries
sudo apt-get install libasound2-dev

# Build
./build.sh

Windows

# Use Visual Studio or MinGW
mkdir build && cd build
cmake -G "Visual Studio 16 2019" ..
cmake --build .

Future Enhancements

• MIDI input support (RtMidi integration)
• Interactive parameter control via console
• Preset loading/saving
• Audio file recording
• GUI with JUCE
• Plugin versions (VST3/AU/AAX)

Resources

• RNBO Documentation
• RtAudio Documentation
• RNBO C++ API Reference

License

See individual component licenses:

• RNBO SDK: See rnbo/LICENSE
• RtAudio: MIT License