Chroma

A SuperCollider-based audio effects engine providing real-time audio processing with multiple configurable effects, spectral analysis, and flexible parameter control via Open Sound Control (OSC).

Note: This repository contains the SuperCollider audio engine only. For a terminal user interface, see chroma-tui.

Features

Audio Effects

• Multi-mode Filter - Cutoff, resonance, and amount control
• Overdrive - Saturation/distortion with drive, tone, bias, and mix parameters
• Bitcrush - Bit reduction and sample rate manipulation
• Granular Processor - Density, size, and scatter controls with freeze capability
• Reverb - Algorithmic reverb with decay time control
• Modulated Delay - Delay time, decay, and modulation parameters
• Input Freeze - Adjustable loop length for sustained tones
• Blend Modes - Mirror, complement, and transform modes for effect combination

Control Interface

• OSC Control - Full parameter control via OSC messages
• Headless Operation - No GUI dependency
• Effects Chain Reordering - Dynamic effects processing order
• Real-time Parameters - All audio parameters controllable in real-time

Audio Processing

• Sample Rate - 44.1 kHz (configurable)
• Buffer Management - Circular buffers for granular and freeze effects
• Spectral Analysis - 8-band spectrum analysis for real-time effect modulation
• Cross-platform - Works on Linux, macOS, and Windows

Installation

Prerequisites

• SuperCollider 3.11+ with sc3-plugins
• JACK Audio Connection Kit (Linux) or CoreAudio (macOS)
• OSC client for control (see chroma-tui)

Install SuperCollider

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install supercollider sc3-plugins jackd2

macOS (Homebrew):

brew install supercollider

Windows: Download from SuperCollider website

Setup Chroma

1. Clone this repository:

git clone https://github.com/renderorange/chroma.git
cd chroma

2. Copy Chroma.sc to SuperCollider Extensions:

# Linux
sudo cp Chroma.sc /usr/share/SuperCollider/Extensions/

# macOS  
sudo cp Chroma.sc ~/Library/Application\ Support/SuperCollider/Extensions/

# Or copy to user extensions directory:
mkdir -p ~/.local/share/SuperCollider/Extensions/
cp Chroma.sc ~/.local/share/SuperCollider/Extensions/

Usage

Starting Chroma

Basic Startup:

./run.sh

With Specific Audio Device:

./run.sh --device 1
./run.sh --list  # List available devices

Manual SuperCollider Startup:

sclang startup.scd

OSC Control

Chroma listens for OSC messages on port 57120. All parameters can be controlled via OSC:

Basic Control Examples:

// Connect to Chroma
n = NetAddr("127.0.0.1", 57120);

// Control parameters
n.sendMsg("/chroma/gain", 0.8);
n.sendMsg("/chroma/filterEnabled", 1);
n.sendMsg("/chroma/filterCutoff", 2000);
n.sendMsg("/chroma/overdriveDrive", 0.5);
n.sendMsg("/chroma/dryWet", 0.7);

Complete OSC Parameter Reference:

Parameter	OSC Path	Range	Description
Input Gain	/chroma/gain	0.0-2.0	Master input gain
Input Freeze	/chroma/inputFreeze	0/1	Enable input freeze
Freeze Length	/chroma/inputFreezeLength	0.05-0.5	Freeze loop length (seconds)
Filter Enable	/chroma/filterEnabled	0/1	Enable filter effect
Filter Amount	/chroma/filterAmount	0.0-1.0	Filter effect amount
Filter Cutoff	/chroma/filterCutoff	200-8000	Filter frequency (Hz)
Filter Resonance	/chroma/filterResonance	0.0-1.0	Filter resonance
Overdrive Enable	/chroma/overdriveEnabled	0/1	Enable overdrive
Overdrive Drive	/chroma/overdriveDrive	0.0-1.0	Overdrive intensity
Overdrive Tone	/chroma/overdriveTone	0.0-1.0	Overdrive tone control
Overdrive Mix	/chroma/overdriveMix	0.0-1.0	Overdrive wet/dry mix
Granular Enable	/chroma/granularEnabled	0/1	Enable granular effect
Granular Density	/chroma/granularDensity	1-50	Grains per second
Granular Size	/chroma/granularSize	0.05-2.0	Grain size (seconds)
Granular Pitch Scatter	/chroma/granularPitchScatter	0.0-1.0	Pitch variation
Granular Position Scatter	/chroma/granularPosScatter	0.0-1.0	Position variation
Granular Mix	/chroma/granularMix	0.0-1.0	Granular wet/dry mix
Granular Freeze	/chroma/granularFreeze	0/1	Freeze granular buffer
Grain Intensity	/chroma/grainIntensity	subtle/pronounced/extreme	Granular intensity mode
Bitcrush Enable	/chroma/bitcrushEnabled	0/1	Enable bitcrush
Bit Depth	/chroma/bitDepth	4-16	Bit reduction depth
Sample Rate	/chroma/bitcrushSampleRate	1000-44100	Sample rate reduction
Bitcrush Drive	/chroma/bitcrushDrive	0.0-1.0	Bitcrush intensity
Bitcrush Mix	/chroma/bitcrushMix	0.0-1.0	Bitcrush wet/dry mix
Reverb Enable	/chroma/reverbEnabled	0/1	Enable reverb
Reverb Decay	/chroma/reverbDecayTime	0.1-10.0	Reverb decay (seconds)
Reverb Mix	/chroma/reverbMix	0.0-1.0	Reverb wet/dry mix
Delay Enable	/chroma/delayEnabled	0/1	Enable delay
Delay Time	/chroma/delayTime	0.01-2.0	Delay time (seconds)
Delay Decay	/chroma/delayDecayTime	0.1-5.0	Delay feedback
Modulation Rate	/chroma/modRate	0.1-10.0	Modulation frequency (Hz)
Modulation Depth	/chroma/modDepth	0.0-1.0	Modulation amount
Delay Mix	/chroma/delayMix	0.0-1.0	Delay wet/dry mix
Blend Mode	/chroma/blendMode	0-2	Blend mode (0=mirror, 1=complement, 2=transform)
Dry/Wet Mix	/chroma/dryWet	0.0-1.0	Overall effects mix

Effects Ordering:

// Set effects processing order
n.sendMsg("/chroma/effectsOrder", "filter", "overdrive", "granular", "bitcrush", "reverb", "delay");

// Get current effects order
n.sendMsg("/chroma/getEffectsOrder");

Testing

Headless Tests (No Audio Hardware Required)

Run the test suite that validates code structure, syntax, and component definitions without requiring audio hardware:

./test/run_lint_tests.sh    # Run lint tests

This test suite checks:

• File structure validation
• Syntax validation (braces, parentheses, brackets balanced)
• Required methods present
• OSC handlers defined
• SynthDef definitions
• Audio effect parameters
• Bus allocation
• Documentation files
• Code quality checks

Full Test Suite (Requires Audio Hardware)

Interactive Test Runner:

./test/run_full_tests.sh    # Interactive test runner (requires JACK audio)

Manual Testing

Start SuperCollider and test basic functionality:

// Start Chroma
Chroma.start;

// Test basic parameters
Chroma.setGain(0.8);
Chroma.setFilterEnabled(true);
Chroma.setFilterCutoff(1000);

// Test effects
Chroma.setOverdriveEnabled(true);
Chroma.setGranularEnabled(true);
Chroma.setReverbEnabled(true);

// Test freeze functionality
Chroma.setInputFreeze(true);
Chroma.setGranularFreeze(true);

// Stop Chroma
Chroma.stop;

Audio Routing

Chroma processes audio from the default input device and outputs to the default output device. With JACK, you can route audio flexibly:

# List JACK ports
jack_lsp -c

# Connect inputs
jack_connect system:capture_1 Chroma:in
jack_connect system:capture_2 Chroma:in

# Connect outputs  
jack_connect Chroma:out system:playback_1
jack_connect Chroma:out system:playback_2

TUI Control

For a complete terminal interface see chroma-tui.

Architecture

Chroma follows a modular architecture:

Audio Input → Analysis → Effects Chain → Audio Output
                 ↓
            Parameter Control (OSC)
                 ↓
            Real-time Processing

Connection Model

Chroma uses stateless OSC over UDP for parameter control.

• No Connection State: UDP is connectionless - there is no persistent connection to maintain
• Server Independence: The SuperCollider audio server continues processing audio with last-known parameters regardless of client connectivity
• Simple Integration: OSC clients simply send messages to control parameters; no handshake or connection management needed

Note: There is no automatic reconnection logic by design. If your client disconnects, simply start sending OSC messages again when ready. The server maintains the last-known parameter state.

Effects Chain Order (configurable):

1. Input Analysis & Freeze
2. Multi-mode Filter
3. Overdrive/Saturation
4. Granular Processing
5. Bitcrush
6. Reverb
7. Modulated Delay
8. Output Mixer

Development

To verify your changes:

# Run lint tests to validate code structure and syntax
./test/run_lint_tests.sh

# All tests should pass before submitting changes

Project Structure

chroma/
├── Chroma.sc      # Main SuperCollider class
├── startup.scd    # SuperCollider startup script
├── run.sh         # Launch script with JACK setup
├── test/          # Test suite
└── README.md      # This file

Modifying Chroma

Adding New Effects:

1. Create SynthDef in Chroma.sc
2. Add parameters to appropriate parameter dictionary
3. Add OSC responders in setupOSC method
4. Update createSynths and connectSynths methods
5. Add test cases

Modifying OSC Interface:

• OSC responders are defined in the setupOSC method
• Each parameter has a corresponding OSCdef
• All OSC messages use the /chroma/ namespace

Troubleshooting

Common Issues

SuperCollider Can't Find Chroma Class:

• Ensure Chroma.sc is in the Extensions directory
• Restart SuperCollider after copying files
• Check Extensions path in SuperCollider preferences

Audio Not Working:

• Verify JACK is running: ps aux | grep jackd
• Check audio device permissions: sudo usermod -a -G audio $USER
• Try specific device: ./run.sh --device 0

OSC Control Not Responding:

• Verify SuperCollider server is running: Server.local.boot
• Check port 57120 is available: netstat -an | grep 57120
• Test OSC connection with simple message

Performance Issues:

• Reduce granular density for CPU relief
• Check JACK buffer size settings
• Monitor CPU usage in SuperCollider: s.avgCPU

Getting Help

• Issues: GitHub Issues
• TUI Project: chroma-tui
• SuperCollider: SuperCollider Documentation

License

This project is licensed under the MIT License - see the LICENSE file for details.