bork~ is a unified system for percussive onset detection and sound classification. It features spectral analysis of sounds to discriminate onsets and classification according to a template.
Overview
Bork provides a complete workflow for interactive audio applications:
- Prototype & Analyze in Max/MSP using the
bork~object - Deploy & Run in Unreal Engine using the Bork Node
- Share Templates via portable template files
Part 1: bork~ for Max/MSP & Pd
The bork~ external provides spectral onset detection and template matching capabilities within Max/MSP and Pure Data
Installation & Basic Usage
// Basic bork~ object
bork~
// Configure analysis parameters
bork~ 512 128 11 // [npoints hop nfilters]
bork~ 256 64 11 // Faster response
bork~ 1024 256 11 // Higher frequency resolution
Object Structure
Inlets/Outlets:
- Inlet 1: Audio signal input
- Outlet 1: Template information
[template_index, power_increase] - Outlet 2: Raw spectral band energies (list of floats)
- Outlet 3: Bang on onset detection
Core Methods:
sensitivity 0.7 // Detection threshold (0-1, default 0.5)
learn 5 // Learn templates (5 samples per sound)
forget // Remove last template
write drums.txt // Save template library
read kicks.txt // Load templates
debug 1 // Enable debug output
print // Display current configuration
bang // Re-arm detector
Template Creation Workflow
-
Setup Analysis
bork~ 512 128 11 sensitivity 0.6 -
Learn Sound Templates
// Learn drum kit sounds learn 4 Play: kick drum 4 times // bork~ automatically advances to next template Play: snare drum 4 times etc -
Export Template Library
write my_sounds.txt
Part 2: Bork Metasound Node for Unreal Engine
The Bork Node brings real-time spectral analysis to Unreal Engine's Metasounds system, using the templates created in Max/MSP.
Input Configuration
| Parameter | Range | Description |
|---|---|---|
| Template File | File path | Location of .txt template file |
| Hi Thresh | 0.0001+ | High threshold for onset detection |
| Lo Thresh | 0.0001+ | Low threshold for re-arming |
| Min Vel | 0.0+ | Minimum velocity to output |
| Mask Time | 0+ ms | Mask time in milliseconds |
| Mask Decay | 0.0-1.0 | Mask decay factor |
| Debounce Decay | 0.0-1.0 | Prevents rapid re-triggering |
Output Data
| Output | Type | Use Case |
|---|---|---|
| Onset Trigger | Trigger | Precise timing for sound/events |
| Onset Counter | Integer | Sequential onset count |
| Instrument ID | Integer | Identifies which template matched |
| Velocity | Float | Attack intensity (onset detection) |
| RT Velocity | Float | Continuous energy stream (every frame) |
| Temperature | Float | Spectral brightness/centroid |
| Raw Spectrum | Float Array | Per-band energy values |
Gameplay Integration:
- Onset Trigger → Play impact sound
- Instrument ID → Select VFX system
- Velocity → Scale screen shake intensity
- RT Velocity → Dynamic hit marker opacity
- Onset Counter → Track total number of hits
Core Features
Spectral Analysis Engine
- Perceptual Frequency Bands: Optimized for percussive sounds
- Adaptive Thresholding: Automatic sensitivity to different sound levels
- Temporal Masking: Prevents double-detection on sustained sounds
- Envelope Following: Musical event detection separates real onsets from spectral artifacts
Template Matching System
- Multi-sample Learning: Average multiple performances for robust templates
- Real-time Correlation: Instant identification against template library
- Portable Format: Share templates between Max and Unreal
Performance Characteristics
- Low Latency: 5-20ms detection (configurable)
- High Accuracy: >95% on percussive sounds
- Efficient: ~2% CPU per instance on modern hardware
Template File Format
bork~ uses a simple text-based template format that's portable between Max and Unreal:
12.45 8.91 5.22 3.10 1.80 0.95 0.51 0.28 0.15 0.08 0.04
5.10 10.85 15.20 8.45 4.10 2.05 1.02 0.51 0.25 0.12 0.06
2.05 15.50 8.20 3.10 1.55 0.80 0.40 0.20 0.10 0.05 0.02
Each line represents one sound template with normalized spectral band values. The number of values per line must match the number of filters configured (default: 11).
Best Practices
Template Creation (Max/MSP)
- Use 3-5 samples per sound for reliable recognition
- Isolate sounds when possible for cleaner templates
- Adjust sensitivity (0.5-0.8 for most percussive sounds)
- Test with variations to ensure robust performance
Performance Tuning (Unreal Engine)
- Start with Hi Thresh 0.01-0.1 and adjust as needed
- Set Mask Time to 50-100ms for most percussive sounds
- Use Min Vel to filter weak detections or background noise
- Debounce Decay 0.7-0.95 prevents double-triggering
Real-time Applications
- Leverage RT Velocity for continuous parameter control (updated every frame)
- Use Instrument ID for context-aware responses
- Combine Temperature with visual/effect parameters for spectral brightness
- Monitor Onset Counter for gameplay metrics and statistics
Technical Specifications
Analysis Parameters
- Window Sizes: 256, 512, 1024 samples
- Hop Sizes: Configurable, typically 25-50% of window
- Frequency Bands: 5-40 perceptually-spaced filters (default: 11)
- Sample Rates: 44.1kHz, 48kHz, 96kHz supported
Max/MSP Configuration
- Default: 512-point window, 128-sample hop, 11 filters
- Arguments:
bork~ [npoints] [hop] [nfilters] - Sensitivity Range: 0.0-1.0 (0=less sensitive, 1=more sensitive)
Unreal Engine Implementation
- Based on: bonk~ algorithm by Miller Puckette
- Additional Features: Onset counter, continuous RT velocity output
- Template Compatibility: Reads standard bonk~/bork~ template files
System Requirements
- Max/MSP: Version 8+ recommended
- Unreal Engine: 5.6+ with Metasound support
- CPU: Modern multi-core processor
- Memory: 50MB+ for template libraries
Inspired by the real-time audio analysis techniques described in the article: Puckette, M. S., Apel, T., & Zicarelli, D. D. (1998). Real-time audio analysis tools for Pd and MSP. International Computer Music Conference, ICMC Proceedings.