footywhoops - MIDI Sequencer

A real-time audio pattern generator with advanced DSP effects, built in Go using PortAudio.

Example audio

sample.wav

Features

🎛️ Audio Processing

• Multiple Distortion Types: Tanh (smooth), Atan (warm), Hard clipping (aggressive)
• Schroeder Reverb: Professional-quality algorithmic reverb with room size and damping controls
• Tone Control: Low-pass filtering for frequency shaping
• Real-time Processing: Low-latency audio processing with configurable buffer sizes

🎵 Pattern Generation

• Musical Pattern Generator: Create drum patterns, basslines, arpeggios, and melodies
• Random Pattern Generation: Algorithmically generate patterns within musical scales
• Multiple Scales: Major, minor, dorian, pentatonic, blues, harmonic minor, and more
• Pattern Evolution: Real-time pattern modification for dynamic composition
• Bass Synthesis: Advanced bass sound generation with sub-oscillators and custom envelopes

🎚️ Advanced Controls

• Wet/Dry Mix: Blend processed and original signals
• Drive & Level: Independent pre-gain and post-gain controls
• Generator Mode: Use as standalone synthesizer without input
• WAV Recording: Record both dry input and processed output

Installation

Prerequisites

• Go 1.19 or later
• PortAudio development libraries

macOS

brew install portaudio

Ubuntu/Debian

sudo apt-get install portaudio19-dev

Build

git clone https://github.com/your-username/footywhoops
cd footywhoops
go mod tidy
go build .

Quick Start

List Audio Devices

./footywhoops --list

Basic Distortion Pedal

# Process microphone input with tanh distortion
./footywhoops --drive 15 --level -6 --mix 0.8

# Hard clipping with reverb
./footywhoops --mode hard --drive 20 --clip 0.6 --reverb-wet 0.3

Pattern Generation

# Generate a kick drum pattern
./footywhoops --no-mic --pattern --pattern-type kick --bpm 128

# Random melody in minor scale
./footywhoops --no-mic --pattern --pattern-type random-melody --scale minor --key 60

# Bass pattern with custom settings
./footywhoops --no-mic --pattern --pattern-type bass --key 40 \
--bass-wave square --bass-sub 0.4 --drive 12

Command Line Reference

Audio Processing

--sr 48000              Sample rate in Hz
--frames 256            Audio buffer size
--drive 20              Pre-gain in dB
--level -6              Output level in dB
--mix 1.0               Wet/dry mix [0..1]
--mode tanh             Distortion: tanh | atan | hard
--clip 0.8              Hard-clip threshold [0.1..1.0]
--tone 4000             Low-pass cutoff Hz (0=bypass)

Reverb

--reverb-room 0.5       Room size [0..1]
--reverb-damp 0.5       High-frequency damping [0..1]
--reverb-wet 0.3        Reverb level [0..1]

Pattern Generation

--pattern               Enable pattern generation
--pattern-type kick     Pattern: kick|snare|hihat|bass|arp-major|arp-minor|random-*
--bpm 120               Beats per minute
--key 60                MIDI root note (60=C4)
--pattern-mix 0.5       Pattern volume [0..1]
--no-mic                Disable microphone (generator only)

Random Patterns

--scale minor           Scale: major|minor|dorian|pentatonic|blues|chromatic
--density 0.6           Note density [0..1]
--seed 1337             Random seed (0=auto)
--evolve                Enable pattern evolution
--rhythm-style breakbeat Rhythm: four-on-floor|breakbeat|latin|shuffle

Bass Synthesis

--bass-wave square      Waveform: sine|square|saw|triangle
--bass-attack 0.01      Envelope attack time [0.001..5.0]
--bass-decay 0.3        Envelope decay time [0.001..5.0]
--bass-sustain 0.7      Envelope sustain level [0..1]
--bass-release 0.5      Envelope release time [0.001..5.0]
--bass-sub 0.3          Sub-oscillator level [0..1]

Ambient Generator

--ambient-gen           Enable atmospheric ambient music generator
--ambient-root 220.0    Root frequency for harmonic progression (Hz)
--ambient-density 0.7   Oscillator density/complexity [0..1]
--ambient-atmosphere 0.8 Atmosphere/effects intensity [0..1]
--ambient-evolution 0.6  Evolution speed of harmonics [0..1]

Recording & Devices

--rec-wet output.wav    Record processed audio
--rec-dry input.wav     Record raw input
--in "USB"              Input device name (substring)
--out "Speakers"        Output device name (substring)
--dur 30                Auto-stop after seconds (0=infinite)

Usage Examples

Electronic Music Production

Acid Bass

./footywhoops --no-mic --pattern --pattern-type random-bass \
--scale minor --key 36 --bass-wave saw --bass-sub 0.5 \
--drive 18 --tone 2000 --bpm 130 --evolve

Ambient Arpeggios

./footywhoops --no-mic --pattern --pattern-type random-arp \
--scale dorian --key 64 --density 0.4 \
--reverb-wet 0.6 --reverb-room 0.8 --drive 5

Breakbeat Drums

./footywhoops --no-mic --pattern --pattern-type random-rhythm \
--rhythm-style breakbeat --density 0.7 --bpm 140 \
--drive 15 --mode hard

Atmospheric Ambient Generator

# Ethereal ambient soundscapes with evolving harmonics
./footywhoops --no-mic --ambient-gen --ambient-root 110 \
--ambient-density 0.6 --ambient-atmosphere 0.9 \
--ambient-evolution 0.4 --drive 3 --reverb-wet 0.3

# Dense atmospheric layers
./footywhoops --no-mic --ambient-gen --ambient-root 220 \
--ambient-density 0.8 --ambient-atmosphere 0.95 \
--ambient-evolution 0.7 --tone 1500

# Minimal floating textures
./footywhoops --no-mic --ambient-gen --ambient-root 165 \
--ambient-density 0.3 --ambient-atmosphere 0.7 \
--ambient-evolution 0.2 --reverb-wet 0.5

Guitar Processing

Vintage Tube Amp

./footywhoops --mode tanh --drive 22 --level -4 --mix 0.9 \
--tone 3500 --reverb-wet 0.2 --reverb-room 0.4

Heavy Metal Distortion

./footywhoops --mode hard --drive 30 --clip 0.5 --level -8 \
--tone 5000 --mix 1.0

Clean with Reverb

./footywhoops --drive 0 --mix 0.3 --reverb-wet 0.4 \
--reverb-room 0.7 --reverb-damp 0.3

Creative Sound Design

Evolving Soundscape

./footywhoops --no-mic --pattern --pattern-type random-melody \
--scale harmonic-minor --density 0.3 --evolve \
--reverb-wet 0.7 --drive 8 --tone 2500 --seed 42

Generative Bass Music

./footywhoops --no-mic --pattern --pattern-type random-bass \
--scale blues --bass-wave square --bass-sub 0.6 \
--evolve --bpm 85 --drive 14 --rec-wet bass-jam.wav

Musical Scales

• major: Bright, happy (C-D-E-F-G-A-B)
• minor: Dark, sad (C-D-Eb-F-G-Ab-Bb)
• dorian: Modal, jazzy (C-D-Eb-F-G-A-Bb)
• pentatonic: World music (C-D-E-G-A)
• blues: Traditional blues (C-Eb-F-Gb-G-Bb)
• harmonic-minor: Dramatic, Middle Eastern
• chromatic: All 12 notes

Pattern Types

Fixed Patterns

• kick: 4/4 kick drum pattern
• snare: Snare on beats 2 and 4
• hihat: 16th note hi-hat pattern
• bass: Structured bassline
• arp-major/minor: Chord arpeggios

Random Patterns

• random-melody: Scale-aware melodies
• random-bass: Walking bass lines
• random-arp: Arpeggiated patterns
• random-rhythm: Algorithmic drum patterns

Performance Tips

Low Latency Setup

# Reduce buffer size for lower latency
./footywhoops --frames 128 --sr 44100

# Use specific audio devices
./footywhoops --in "Focusrite" --out "Focusrite"

CPU Optimization

# Disable effects when not needed
./footywhoops --reverb-wet 0 --tone 0 --mix 1.0

# Use simpler patterns
./footywhoops --pattern-type kick --density 0.4

Technical Details

Audio Processing Chain

1. Input gain (drive)
2. Waveshaping distortion
3. Tone control (low-pass filter)
4. Reverb processing
5. Wet/dry mixing
6. Output gain (level)
7. Soft limiting

Pattern Generation

• 16-step sequencer (16th note resolution)
• MIDI note mapping with proper frequency conversion
• ADSR envelope shaping
• Oscillator with sub-oscillator support
• Real-time pattern evolution algorithms

DSP Implementation

• Schroeder reverb with 6 comb filters and 3 allpass filters
• One-pole low-pass filters for tone control
• Multiple waveshaping algorithms
• Soft limiting for output protection

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Credits

Built with:

• PortAudio for cross-platform audio I/O
• Go standard library for high-performance audio processing
• Algorithmic reverb based on Schroeder’s classic design

---

footywhoops - Real-time audio processing and pattern generation for musicians, producers, and sound designers.

More examples:

./footywhoops --no-mic --pattern --pattern-type random-arp --scale dorian --key 52 -rhythm-style breakbeat -dur 12 -rec-wet test4.wav -density 0.99 -level 0.1 --reverb-wet 0.7 -reverb-room 0.1

./footywhoops --no-mic --pattern --pattern-type random-arp --scale dorian --key 52 -rhythm-style breakbeat -density 0.6 -volumes 0.6 --reverb-wet 0.7 -reverb-room 0.4 --reverb-damp 0.1

./footywhoops --no-mic --pattern --pattern-type random-arp --scale dorian --key 52 -rhythm-style breakbeat -density 0.99 -volumes 0.6 --reverb-wet 0.1 -reverb-room 0.1 -drive 10