Chiller~ Max/MSP External Builder

Build and develop chiller~, a Max/MSP external that performs real-time spectral freezing of audio buffer content, creating evolving drones and textural sounds through FFT-based granular synthesis.

What This Skill Does

This skill helps you build, debug, and extend the chiller~ Max/MSP external. It handles CMake configuration for universal binaries (Intel + Apple Silicon), implements FFT-based audio processing, manages buffer~ integration, and provides comprehensive debugging for spectral analysis issues.

Instructions

When the user asks you to work with the chiller~ external, follow these steps:

1. Understand the Project Architecture

The chiller~ external is a Max/MSP audio object (`t_pxobject`) that:

Extracts spectral content from audio buffers using FFT analysis

Preserves magnitude spectrum while randomizing phase for evolving textures

Uses overlap-add synthesis for continuous audio output

Supports configurable FFT sizes (512, 1024, 2048, 4096, 8192)

**Key files:**

`chiller.c` - Main external implementation

`CMakeLists.txt` - Build configuration

`chiller.maxhelp` - Interactive documentation patch

`README.md` - User documentation

`CLAUDE.md` - Technical developer documentation

2. Building the External

When building or rebuilding:

```bash

Navigate to project directory

cd "/Users/a1106632/Documents/Max 8/Packages/max-sdk-main/projects/chiller"

Create and configure build for universal binary

mkdir -p build && cd build

cmake -DCMAKE_OSX_ARCHITECTURES="x86_64;arm64" ..

Build the external

cmake --build .

Verify output location

ls "/Users/a1106632/Documents/Max 8/Packages/externals/chiller.mxo"

```

**Verification:**

```bash

file "/Users/a1106632/Documents/Max 8/Packages/externals/chiller.mxo/Contents/MacOS/chiller"

Should show: Mach-O universal binary with 2 architectures

```

3. Critical Implementation Details

**Spectrum Normalization (CRITICAL):**

The external previously suffered from magnitude explosion. Always ensure energy-based normalization in the capture phase:

```cpp

double target_energy = x->fft_size * 0.1;

double normalization_factor = sqrt(target_energy / spectrum_energy);

```

**Rate Limiting:**

Position changes must be rate-limited to prevent noise artifacts:

```cpp

if (current_time - x->last_position_change_time < 500.0) return;

```

**Processing Pipeline:**

```

Buffer Audio → Windowed FFT → Magnitude Extraction → Phase Randomization → IFFT → Overlap-Add → Output

```

4. Debugging Issues

When diagnosing audio problems, use the debug system:

**Send `bang` message to output:**

Configuration (FFT size, sample rate, buffer info)

Analysis state (position, spectrum capture status)

Timing intervals (watch for position change frequency)

**Spectrum energy levels** (watch for magnitude explosion)

Overlap buffer states

**Healthy spectrum energy:**

```

Spectrum Energy: 88633.919625

Max Magnitude: 94.018975

```

**Problem indicators:**

```

Spectrum Energy: 871190700897.731689 ← MAGNITUDE EXPLOSION

Max Magnitude: 334635.621325

```

5. Parameter System

**Core functions:**

`set <buffername>` - Set buffer to analyze

`position <0.0-1.0>` - Set analysis position (auto-captures spectrum)

`freeze` - Manually capture spectrum at current position

`bang` - Output debug information

**Synthesis parameters:**

`rate <0.1-4.0>` - Grain generation rate (default: 1.0)

`phaserand <0.0-1.0>` - Phase randomization (default: 0.1)

`ampvar <0.0-0.5>` - Amplitude variation (default: 0.1)

`overlap <1.0-8.0>` - Overlap factor (default: 4.0)

**Object instantiation:**

`chiller~ 2048` - Set FFT size

`chiller~ mybuffer` - Set buffer name

`chiller~ 2048 mybuffer` - Both

6. Performance Considerations

**FFT Size Trade-offs:**

**512**: Very low CPU, basic frequency resolution

**1024**: Low CPU, good for multiple instances

**2048**: Moderate CPU, **recommended default**

**4096**: High CPU, detailed analysis

**8192**: Very high CPU, maximum detail

**Memory usage per instance:**

2048 FFT: ~98KB

4096 FFT: ~196KB

7. Common Development Tasks

**Adding new parameters:**

1. Add attribute in struct definition

2. Implement setter method with `METHOD_ATTRIBUTE`

3. Register in `ext_main()`

4. Document in help patch and README

**Modifying FFT processing:**

1. Update `chiller_capture_spectrum()` for analysis changes

2. Update `chiller_generate_grain()` for synthesis changes

3. Test with debug `bang` to verify spectrum energy

4. Validate with multiple FFT sizes

**Fixing audio artifacts:**

1. Use `bang` to check spectrum energy (watch for explosion)

2. Verify rate limiting is active (check timing intervals)

3. Check overlap buffer states for discontinuities

4. Test with different buffer content types

8. Testing Protocol

After any code changes:

1. **Build verification:** Check universal binary architecture

2. **Load test:** Open help patch, verify object loads without errors

3. **Audio test:** Load buffer, set position, verify clean output

4. **Debug test:** Send `bang`, verify spectrum energy is reasonable

5. **Parameter test:** Sweep each parameter, verify smooth transitions

6. **Performance test:** Monitor CPU with Max performance monitor

9. Documentation Updates

When modifying functionality:

1. Update inline code comments

2. Update `README.md` for user-facing changes

3. Update `CLAUDE.md` for technical details

4. Update help patch with new examples

5. Document any new parameters or messages

Examples

**Building after code changes:**

```bash

cd "/Users/a1106632/Documents/Max 8/Packages/max-sdk-main/projects/chiller"

cd build

cmake --build .

Restart Max to reload external

```

**Diagnosing noisy output:**

1. Send `bang` to chiller~ object

2. Check Max console for "Spectrum Energy" value

3. If > 1,000,000: magnitude explosion issue

4. Verify normalization code is active in `chiller_capture_spectrum()`

**Adding a new synthesis parameter:**

1. Add `t_atom_float new_param;` to struct

2. Create `chiller_new_param(t_chiller *x, double f)` setter

3. Register in `ext_main()` with `CLASS_ATTR_DOUBLE`

4. Use in `chiller_generate_grain()` processing

5. Update help patch with example usage

Important Notes

**Critical:** Always maintain energy-based spectrum normalization to prevent magnitude explosion

**Performance:** Large FFT sizes (4096+) can cause high CPU usage; document trade-offs

**Threading:** External is single-threaded; rate limiting prevents concurrent capture issues

**Buffer Safety:** Always check buffer validity before accessing (`buffer_ref_getobject()`)

**Universal Binary:** Always build with `-DCMAKE_OSX_ARCHITECTURES="x86_64;arm64"`

Constraints

FFT sizes must be powers of 2 (512, 1024, 2048, 4096, 8192)

Position changes rate-limited to 500ms minimum interval

Single buffer support (no crossfading between buffers)

Requires Max SDK 8.0+ and CMake 3.19+

Output location hardcoded to Max 8 Packages directory

Chiller~ Max/MSP External Builder

Chiller~ Max/MSP External Builder

What This Skill Does

Instructions

1. Understand the Project Architecture

2. Building the External

Navigate to project directory

Create and configure build for universal binary

Build the external

Verify output location

Should show: Mach-O universal binary with 2 architectures

3. Critical Implementation Details

4. Debugging Issues

5. Parameter System

6. Performance Considerations

7. Common Development Tasks

8. Testing Protocol

9. Documentation Updates

Examples

Restart Max to reload external

Important Notes

Constraints

Reviews (0)