rhythm_pattern_explorer

Rhythm Pattern Explorer

Mathematical Rhythm Pattern Generator and Analyzer

A comprehensive system for generating, analyzing, and manipulating rhythmic patterns using advanced mathematical algorithms including Euclidean rhythms, Barlow’s indispensability theory, and progressive transformations.

Project Structure

This repository is organized into two main components:

Note: For backward compatibility, app/ in the project root is a symbolic link to WebApp/app/

🎛️ Plugin/ - Audio Plugin Implementation

Plugin/
├── Source/                  # C++ plugin source code
├── RhythmPatternExplorer.jucer  # JUCE project file
├── Builds/                  # Xcode build files
├── Tests/                   # Comprehensive test suites
├── Documentation/           # Plugin-specific docs
└── README.md               # Plugin development guide

Formats: Audio Unit (AU), VST3, Standalone
Platform: macOS (iOS experimental)
Status: ✅ Production ready

🌐 WebApp/ - Web Application (Reference Implementation)

WebApp/
├── app/                     # Web application files
├── serve-app.py            # Development server
├── minimal-midi-bridge.py  # MIDI bridge utility
├── *.md                    # Shared documentation
└── WEBAPP_README.md        # WebApp guide

Platform: Any modern web browser
Features: Full algorithm reference, interactive UI
Status: ✅ Stable reference implementation

Quick Start

# Navigate to plugin directory
cd Plugin/

# Open JUCE project
open RhythmPatternExplorer.jucer

# Build and install (see Plugin/README.md for details)

Using the Web App (For Development/Reference)

# Option 1: Use WebApp directory (recommended)
cd WebApp/
python3 serve-app.py

# Option 2: Use legacy app/ link (backward compatibility)
cd app/
python3 -m http.server 8000

# Open browser to http://localhost:8080 or http://localhost:8000

Core Features

Pattern Generation Algorithms

Preset Management System (v0.03g)

Enhanced User Interface (v0.03g)

Progressive Transformations

Accent Pattern System (v0.03c+)

Pattern Timing Modes (v0.03e+)

Three distinct modes for controlling pattern timing and duration:

Steps Mode (Microrhythm Control)

Examples:

8 steps × 16th notes = 8 × 0.25 = 2 beats (half note duration)
9 steps × 8th notes = 9 × 0.5 = 4.5 beats total
9 steps × 8th triplets = 9 × (1/3) = 3 beats total

Use Case: Create microrhythmic variations by changing subdivision while keeping the same pattern.

Beats Mode (Divisive Timing)

Bars Mode (Metric Timing)

UPI (Universal Pattern Input) Notation

Basic Pattern Generation

E(3,8)                    # Euclidean: 3 onsets in 8 steps → 10010010
B(3,8)                    # Barlow indispensability: 3 onsets in 8 steps → 10001010
W(3,8)                    # Wolrab (anti-Barlow): 3 onsets in 8 steps → 01100100
D(3,8)                    # Dilcue (anti-Euclidean): 3 onsets in 8 steps → 01101001
P(5,12,0)                 # Pentagon rhythm: 5 vertices in 12 steps with 0 offset
R(4,8,42)                 # Random: 4 onsets in 8 steps with seed 42

Numeric Pattern Input (Strict Left-to-Right Notation)

# Binary patterns
10010010                  # Direct binary: tresillo pattern
101010                    # Binary: alternating pattern

# Hex patterns (LSB-first, digit-reversed input)
0x94:8                    # Hex: 10010010 (tresillo)
0x1:4                     # Hex: 1000 (leftmost bit = LSB)
0x8:4                     # Hex: 0001 (rightmost bit = MSB)

# Octal patterns (same LSB-first principle)
o12:6                     # Octal: 100010 (using 3-bit groups)
o7:3                      # Octal: 111 (all bits set)

# Decimal patterns  
d73:8                     # Decimal: 10010010 (same as 0x94:8)
d85:8                     # Decimal: 10101010 (alternating)

Important: Hex and octal use reversed digit order during input parsing to maintain strict left-to-right bit ordering where the leftmost position represents the least significant bit (LSB).

Progressive Transformations

E(1,8)E>8                 # Progressive Euclidean: 1→8 onsets (manual trigger)
E(8,8)B>1                 # Progressive Barlow dilution: 8→1 onsets (manual trigger)
B(3,13)W>11               # Progressive Barlow to Wolrab: 3→11 onsets
E(1,8)@3                  # Progressive offset: rotation by 3 steps per trigger
E(1,8)@#5                 # Auto-advancing offset: rotation by 5 steps per beat

Scene Cycling

E(3,8)|P(5,12)           # Scene cycling: alternate between tresillo and pentagon
100|110|101              # Scene cycling: alternate between binary patterns
{100}E(3,8)|{010}B(5,13) # Scene cycling with different accent patterns

Accent Patterns (v0.03c+)

{100}E(3,8)              # Accented tresillo: accent on first onset
{10010}E(5,8)            # Quintillo with accents on 1st and 4th onsets
{10}E(4,8)               # Alternating strong/weak accents (polyrhythmic)
{E(2,5)}E(3,8)           # Euclidean accent pattern over Euclidean rhythm
{P(3,0)}B(5,13)          # All-accent pattern cycling over Barlow rhythm
{101}E(1,8)B>8           # Progressive transformation with accents

Pattern Combinations

E(3,8)+P(5,12)           # Pattern combination: union of onsets
E(3,8)-P(5,12)           # Pattern subtraction: remove overlapping onsets
P(3,0)+P(5,0)-P(2,0)     # Complex combination for perfect balance

Binary and Numeric Patterns

101010                   # Binary pattern: direct onset specification
0x2A:8                   # Hexadecimal: 42 in hex spread over 8 steps
0o52:8                   # Octal: 42 in octal spread over 8 steps
42:8                     # Decimal: 42 spread over 8 steps
[0,2,4,6]:8              # Onset array: specific positions in 8 steps

Implementation Relationship

WebApp (JavaScript)          Plugin (C++)
      ↓                          ↑
 Reference Algorithms    ←    Ported Algorithms
      ↓                          ↑
   Browser Testing       ←    DAW Integration
      ↓                          ↑
 Algorithm Validation    ←    Performance Testing

The WebApp serves as the reference implementation - all algorithms are first developed and validated in the browser, then ported to the Plugin for professional music production use.

Documentation

Shared Documentation (in WebApp/)

Plugin-Specific (in Plugin/)

WebApp-Specific (in WebApp/)

Development Workflow

Algorithm Development

  1. Prototype in WebApp (JavaScript)
  2. Validate algorithms and edge cases
  3. Port to Plugin (C++)
  4. Cross-validate outputs match
  5. Test in production environments

Testing Strategy

  1. WebApp: Browser-based algorithm validation
  2. Plugin: DAW integration testing
  3. Cross-validation: Ensure identical outputs
  4. Performance: Stress testing and benchmarks

Version History

Current: v0.03g (July 2025) - Preset Browser & Enhanced UI Release

Previous: v0.03d (January 2025) - Complete Documentation & Bug Fixes Release

Key Milestones

Requirements

Plugin Development

WebApp Development

Installation

For Music Producers (Plugin)

# Quick install (if already built)
cp -R "Plugin/Builds/MacOSX/build/Release/Rhythm Pattern Explorer.component" ~/Library/Audio/Plug-Ins/Components/
cp -R "Plugin/Builds/MacOSX/build/Release/Rhythm Pattern Explorer.vst3" ~/Library/Audio/Plug-Ins/VST3/

For Developers (WebApp)

cd WebApp/app/
python3 -m http.server 8000
# Open http://localhost:8000

Compatibility

Plugin Hosts (Tested)

Browsers (WebApp)

Contributing

Code Organization

Algorithm Development

  1. Implement in WebApp first (easier debugging)
  2. Validate with comprehensive test cases
  3. Port to Plugin with identical behavior
  4. Cross-validate outputs between implementations

Research Foundation

Based on extensive research in:

Contact

License

[License information to be added]

Choose Your Platform:

This site is open source. Improve this page.