Webarmonium - Technical Documentation

1. Landing Page: Virtual User Mapping

The landing page generates music from three web activity sources, each mapped to a distinct tessitura (frequency range) and oscillator type. Cursor positions use a golden ratio distribution system—X and Y coordinates are calculated independently using φ (phi) and φ² sequences, modulated by metrics, ensuring optimal spacing across the canvas while maintaining data-driven coherence.

Source	Tessitura	Frequency Range	Oscillator	Character
Wikipedia	Bass	110-220Hz (A2-A3)	Sawtooth (rich harmonics)	Deep, warm foundation
HackerNews	Tenor	196-392Hz (G3-G4)	Sine (pure tone)	Pure, mellow mid-range
GitHub	Soprano	523-1047Hz (C5-C6)	Triangle (hollow, flute-like)	Ethereal, airy highs

Metrics Monitored

Source	Primary Metric	Secondary Metrics
Wikipedia	editsPerMinute	avgEditSize, newArticles
HackerNews	postsPerMinute	avgUpvotes, commentCount
GitHub	commitsPerMinute	createsPerMinute, deletesPerMinute

2. Collaborative Rooms: Gesture Processing

Gesture Types

Gesture	Trigger	Audio Result	Visual Feedback
Tap	Click/touch <100ms	Single percussive note (10-110ms attack)	Pulse emission
Long Tap (Hold)	Click/touch held without motion	Sustained note (gate opens on hold, closes on release)	Growing pulse
Drag	Continuous motion	Multi-note melodic phrase (50-250ms attack based on Y position)	Particle trail

3. Multi-User Composition Engine

Parameter	Value	Description
Max users	4	Each user receives a unique timbre/patch
Timbre assignment	Sequential (slots 0-3)	Retro Square, Nasal Reed, Warm Chorus, Bell Chime
Color assignment	From 7-color pool	Visual differentiation between users

Virtual User Activation: When only 1 real user is in a room, 2 virtual users (from Wikipedia and HackerNews metrics) automatically join to provide accompaniment. They deactivate when a second real user joins.

4. Environmental Memory System

Phase	Trigger	Learning Rate	Max Patterns
Initial	< 10 gestures	1.5× (fast learning)	2
Learning	10-50 gestures	1.0× (normal)	4
Mature	> 200 gestures	0.8× (slow evolution)	8

Pattern Compatibility

Gestures influence existing patterns based on these compatibility criteria:

Smooth: Low intensity, non-touch input
Rhythmic: High intensity, touch input
Melodic: X coordinate in center range (0.3-0.7)
Intense: Intensity > 0.8

Deterministic Pattern Thresholds

Pattern creation and evolution use deterministic thresholds derived from gesture characteristics:

Pattern Creation (mature phase):
creationScore = (intensity × 0.7) + (positionUniqueness × 0.3)
positionUniqueness = |x - 0.5| + |y - 0.5|
Create new pattern when creationScore > 0.85

Pattern Evolution:
Dormant patterns → evolve when gesture.intensity > 0.4
Emerging patterns → evolve when gesture.intensity > 0.3

Pattern Retention: 24 hours. Rooms develop a unique "personality" from accumulated gestures. Pattern creation favors high-intensity gestures at unique positions (far from center), while evolution thresholds ensure moderate-intensity gestures contribute to existing patterns.

5. Composition System

Webarmonium uses a fully deterministic composition architecture. Every musical decision—from form selection to individual note dynamics—derives directly from input data. Given the same gesture sequence, the system produces identical compositions.

Core Components

Component	Role	How Input Data Maps to Music
CompositionEngine	Musical form selection	Energy level → form (low=contemplative, high=energetic)
PhraseMorphology	Melodic generation	Acceleration → rhythm; Curvature → syncopation; Intensity → phrase length
HarmonicEngine	Tonal management	Harmonic complexity → progression (simple to complex)
CounterpointEngine	Voice leading	Note position → velocity contour, duration, gap patterns
StyleAnalyzer	Pattern recognition	Extracts tempo, energy, density from gesture history
MaterialLibrary	Musical material storage	Organizes motifs, themes by function and character

Form Selection by Genre and Energy

Forms within each genre are ordered by energy level. The style's energy value (0.0-1.0) directly selects the form: low energy chooses contemplative forms (first in array), high energy chooses energetic forms (last in array).

Genre Weight	Forms (Low Energy → High Energy)
Classical (>0.7)	theme_and_variations → ABA → rondo → sonata
Electronic (>0.7)	through_composed → strophic → verse_chorus → build_drop
Jazz (>0.7)	modal → AABA → blues → rhythm_changes
Rock (>0.7)	strophic → AABA → verse_chorus → intro_verse_chorus_bridge_outro
Mixed/Default	strophic → ABA → verse_chorus

temporalOffset = (compositionCount × φ) mod 1
historyVariation = (historyLength × φ) mod 1
combinedIndex = (energy × 0.4) + (temporalOffset × 0.4) + (historyVariation × 0.2)
selectedForm = genreForms[floor(combinedIndex × formCount)]

Golden Ratio (φ) Stepping: All composition parameters use φ (1.618...) to create low-discrepancy sequences that avoid predictable repetition. Form selection combines energy (40%), temporal offset (40%), and history variation (20%). Note-level details (velocity, duration, articulation) derive from position within the phrase using sine-wave contours.

5b. Data-to-Music Derivation Table

Every musical parameter derives from a specific input data source. This table documents the complete mapping from gesture/metric data to musical output.

Macro-Level Derivations

Musical Parameter	Input Data	Derivation Formula
Form selection	style.energy	forms[floor(energy × formCount)]
Chord progression	harmonicComplexity	progressions[floor(complexity × progCount)]
Phrase length	velocity + intensity	rangeMin + intensity × (rangeMax - rangeMin)
Composition timing	energy + compositionCount	baseBeats[count % 5] × (1 - energy × 0.3)
Scale selection	mood (from gesture)	scaleMap[mood].primary or secondary based on curvature
Contour type	trajectory.angle + curvature	angle → ascending/descending; curvature → arch/wave

Note-Level Derivations

Musical Parameter	Input Data	Derivation Formula
Rhythm variation	acceleration	baseDuration × (1 + (acceleration/100) × position × 0.4)
Syncopation	curvature	Apply rhythmic device when phrasePosition > (1 - curvature)
Velocity contour	notePosition	baseVel + sin(position × π) × range (arch shape)
Note duration	role + noteIndex	durationOptions[role][index % optionCount]
Inter-note gaps	role + notePosition	baseGap + sin(position × 2π) × gapRange
Interval type	phrasePosition	Edges (<0.2, >0.8) prefer steps; center allows skips/leaps
Articulation	role + noteIndex	Pattern-based: melody=staccato on 3/4 notes, bass=legato
Ornaments	pitchClass + phrasePosition	Style-specific placement based on pitch%12 and position

Environmental Memory Derivations

Decision	Input Data	Derivation Formula
Pattern creation	intensity + position	Create when (intensity × 0.7) + (positionUniqueness × 0.3) > 0.85
Pattern evolution	gesture.intensity	Evolve dormant patterns when intensity > 0.4
Position uniqueness	coordinates	\|x - 0.5\| + \|y - 0.5\| (distance from center)

Position-Based Variation: Note-level parameters use sine-wave functions based on position within the phrase (sin(position × π)) to create natural musical contours. This produces arch-like dynamics (louder in middle), voice-leading preference at phrase edges, and organic duration/gap variations—all without random number generation.

6. Dynamic Normalization

Webarmonium uses no hardcoded thresholds. All parameters are normalized dynamically based on observed data ranges.

Normalization Method

normalizedValue = (rawValue - observedMin) / (observedMax - observedMin)

Key Principles

Min/Max Tracking: Rolling window over gesture/metric history
Gesture Classification: Relative comparison only (stability vs density vs periodicity)
Frequency Mapping: Percentile-based (P10-P90) rather than fixed ranges
Velocity Calculation: Rate of change (positive = increasing, negative = decreasing)

7. Audio Architecture

Unified Audio Chain

All audio sources share a common routing architecture with independent volume control and stereo panning. Each source connects to a master bus with optional effects sends.

Source	Synth Type	Routing
Local gestures	MonoSynth (gestureSynth)	synth → pan → volume → master + FX
Remote users	Per-user PolySynth (UserSynthManager)	synth → pan → volume → master + FX
Background	Ambient layers (bass, pad, chords)	layer → filter → volume → master + FX

Real User Patches (4 slots)

Slot	Name	Oscillator	Character
0	Retro Square	Square	Buzzy, 8-bit
1	Nasal Reed	Pulse (20% width)	Nasal, oboe-like
2	Warm Chorus	Fat Sawtooth (3 voices)	Lush, detuned
3	Bell Chime	FM Sine	Bell-like, metallic

8. Background Composition System

GenerativeMusicEngine: Three-Layer Architecture

The landing page generates continuous background music through three independent layers, each with its own rhythm cycle and pattern system. The layers operate autonomously but share a common harmonic context (current chord, scale, tonic).

Layer	Rhythm Cycle	Role	Pattern Count
Bass	2000ms	Low frequency foundation	12 patterns
Pad	16000ms	Ethereal sustained tones	12 patterns
Chords	4000ms	Harmonic movement	12 patterns

Harmonic Progressions

Seven chord progressions are available, each with a distinct mood. Progressions change automatically after 3-7 cycles based on complexity level.

Progression	Degrees	Mood
I-V-vi-IV	0, 4, 5, 3	Uplifting
I-IV-V-IV	0, 3, 4, 3	Driving
i-VI-III-VII	0, 5, 2, 6	Dramatic
I-vi-IV-V	0, 5, 3, 4	Circular
I-V-vi-iii-IV	0, 4, 5, 2, 3	Flowing
I-iii-vi-IV	0, 2, 5, 3	Melancholic
I-VII-IV-V	0, 6, 3, 4	Mysterious

Chord Changes: Current chord changes every 8 seconds, cycling through the active progression. Progression selection is influenced by room complexity: high complexity favors driving/uplifting progressions, low complexity favors melancholic/mysterious moods.

9. Drone & Void Detection

The DroneVoidController makes the ambient drone "emerge during activity voids"—filling silence with atmospheric sound while fading out during active musical events.

DroneVoidController Parameters

Parameter	Value	Purpose
voidTimeoutMin	5000ms	Minimum silence before drone emerges
voidTimeoutMax	10000ms	Full drone emergence time
fadeInTime	2.0s	Quick fade in to fill void
fadeOutTime	20.0s	Gradual fade out on activity
droneNominalDb	-3dB	Full drone level
droneSilentDb	-60dB	Effectively silent
updateInterval	100ms	Check frequency for smooth transitions

Void Score Calculation

Three factors are combined multiplicatively—any single factor can suppress the drone:

voidScore = timeScore × influenceVoidScore × noteVoidScore

timeScore = (timeSinceActivity - 5000) / (10000 - 5000) [clamped 0-1]
influenceVoidScore = 1 - userInfluence
noteVoidScore = activeNotes > 0 ? 0 : 1

LFO Modulation (Organic Breathing)

Two LFOs add subtle organic movement to the drone sound, with randomized phases to prevent synchronized modulation patterns.

LFO	Frequency	Cycle	Range	Effect
Amplitude	0.03 Hz	~33s	-6dB to 0dB	Very slow volume breathing
Pitch	0.05 Hz	~20s	±8 cents	Subtle organic detuning

Dual Control: The DroneVoidController uses a dedicated gain node (droneAmplitudeGain) for overall presence control, allowing the amplitude LFO to continue providing subtle breathing modulation even while the drone fades in/out.

10. Musical Scheduler

The MusicalScheduler prioritizes clock consistency over low latency, ensuring perfect synchronization between local and remote gestures. Remote events may wait but will always be scheduled in sync with the local clock.

Clock Synchronization

Parameter	Value	Purpose
Tick interval	25ms (40Hz)	Web Worker precision timer
Local lookahead	100ms	Immediate scheduling for local events
Remote lookahead	250ms	Schedule ahead for jitter tolerance
Default tempo	120 BPM	Base tempo (range: 60-140 BPM)
Time signature	4/4	Standard time signature
Grid resolution	16th note	Remote event quantization

Beat Grid Assignment (Landing Page)

Virtual user notes are distributed across the beat grid to create rhythmic variety:

Wikipedia notes: ticks 0, 4, 8, 12 (downbeats)
HackerNews notes: ticks 2, 6, 10, 14 (off-beats)
GitHub notes: ticks 1, 5, 9, 13 (upbeats)

Local vs Remote: Local events have 100ms lookahead for immediacy. Remote events use 250ms lookahead and snap to the nearest sixteenth-note boundary for global synchronization despite network jitter.

11. Harmonic Engine & Voice Leading

Available Scales

Nine scales are available for melodic generation, with pentatonic as the default (safest for improvisation):

Scale	Intervals (semitones)	Character
Pentatonic (default)	0, 2, 4, 7, 9	Safe, no dissonance
Major (Ionian)	0, 2, 4, 5, 7, 9, 11	Bright, happy
Minor (Aeolian)	0, 2, 3, 5, 7, 8, 10	Sad, introspective
Dorian	0, 2, 3, 5, 7, 9, 10	Jazz, modal
Mixolydian	0, 2, 4, 5, 7, 9, 10	Bluesy, rock
Blues	0, 3, 5, 6, 7, 10	Expressive, bent
Phrygian	0, 1, 3, 5, 7, 8, 10	Spanish, exotic
Lydian	0, 2, 4, 6, 7, 9, 11	Dreamy, floating
Chromatic	0-11 (all semitones)	Full spectrum

SATB Voice Ranges (Background Composition)

Background composition uses traditional SATB voice ranges for proper voice leading:

Voice	MIDI Range	Notes	Character
Soprano	60-79	C4-G5	High density, staccato
Alto	55-72	G3-C5	Medium density
Tenor	48-67	C3-G4	Sparse, long sustain
Bass	36-55	C2-G3	Low density, legato

Voice Leading Rules

The CounterpointEngine validates voice leading to ensure musical coherence:

No parallel fifths/octaves: Consecutive voices cannot move in parallel perfect intervals
No voice crossing: Lower voices must stay below upper voices
Maximum spacing: Adjacent voices within one octave (12 semitones)
Stepwise motion preferred: Leaps > 5 semitones trigger octave alternatives

Consonant Intervals

Allowed intervals: Unison (0), Minor 3rd (3), Major 3rd (4), Perfect 5th (7), Major 6th (9), Octave (12)

12. Metric-to-Gesture Classification

Virtual user gestures are classified based on which metric characteristic is dominant. This uses purely relative comparison—no hardcoded thresholds.

Classification Metrics

Metric	Formula / Source	Gesture	Audio Result
Stability	1 - normalizedVelocity	TAP	Single note (50-300ms)
Density	Wiki: avgEditSize HN: avgUpvotes GH: createsPerMinute	DRAG	Phrase (3-8 notes, 300-3000ms)

Gesture Selection

gestureType = stability > density ? TAP : DRAG
// Higher stability produces single notes, higher density produces phrases

Intent Thresholding

Gestures are only generated when normalized velocity exceeds an activity-based threshold:

gestureIntent = 0.1 × (1 - activityLevel × 0.5)
// High activity = lower threshold = more frequent gestures

Composition Frequency

Composition timing derives from energy level and composition count, cycling through predetermined phrase lengths for variety:

baseBeats = [8, 12, 16, 10, 14] // Cycles through these lengths
beatIndex = compositionCount % 5
energyModifier = 1 - (energy × 0.3) // 0.7-1.0
beatsPerComposition = baseBeats[beatIndex] × energyModifier

High energy → 5.6-11.2 beats (shorter phrases)
Low energy → 8-16 beats (longer phrases)

Dynamic Normalization: All metric values use P10-P90 percentile-based normalization from a rolling 2-minute sample window, preventing outliers from skewing the classification.