motif/Phase 2 Implementation v2.0.md

Wario Synth v2: Phase 2 Implementation Plan

Project: Wario Synthesis Engine v2
Owner: Andy @ birdmania
Status: Implementation Phase
Target: Game Boy-authentic MIDI conversion with enhanced polyphony
Repository: https://github.com/b1rdmania/motif

---

Project Overview

Build a Game Boy-authentic synthesis engine (v2) that captures the true DMG-CPU sound chip character while preserving v1's "any MIDI works" philosophy. The v2 engine will be hosted separately and won't intrude on v1's functionality.

Key Architecture Decision: 8-channel "Super Game Boy" setup (4 pulse, 2 wave, 2 noise) instead of authentic 4-channel limitation. This preserves GB sound character while handling complex MIDI files gracefully.

---

Critical Constraint: v1 Isolation

v1 MUST remain completely untouched and functional throughout v2 development.

What stays UNTOUCHED (v1):

• src/synthesis/SynthesisEngine.ts - current engine, no changes
• src/core/MotifEngine.ts - current orchestration, no changes
• All existing files in src/ - completely untouched
• index.html, play.html, embed.html - no modifications
• Live site at wario.style continues to work exactly as today

What gets CREATED (v2):

• Brand new directory: src-v2/ - entirely separate codebase
• New entry point: v2.html - doesn't touch existing HTML files
• Separate Vite build config if needed
• Could become separate repo later if desired

What v2 CAN import (read-only):

• src/midi/MIDIParser.ts - reuse existing MIDI parsing
• Shared types from src/types/index.ts if compatible
• Nothing else - all synthesis code is fresh

Benefits of this approach:

1. Develop v2 while v1 stays live and stable
2. If v2 has issues, v1 is completely unaffected
3. A/B test with simple URL switch (/ vs /v2)
4. Rollback is trivial - just don't deploy v2 code
5. Can eventually merge or keep separate forever

---

Repository Structure

/Users/andy/MOTIF/
├── src/                          # v1 (current, unchanged)
│   ├── core/MotifEngine.ts
│   ├── synthesis/SynthesisEngine.ts
│   └── ...
├── src-v2/                       # v2 (NEW - separate tree)
│   ├── audio/
│   │   ├── apu/
│   │   │   ├── APU.ts           # Main 8-channel coordinator
│   │   │   ├── PulseChannel.ts  # GB pulse with duty cycles
│   │   │   ├── WaveChannel.ts   # 4-bit wavetable
│   │   │   ├── NoiseChannel.ts  # LFSR noise
│   │   │   └── Mixer.ts         # Stereo mixing
│   │   ├── synthesis/
│   │   │   ├── DutyCycle.ts     # 4 GB duty patterns
│   │   │   ├── LFSR.ts          # Noise generator
│   │   │   ├── WaveTable.ts     # 4-bit quantization
│   │   │   └── FrequencyCalc.ts # GB frequency formulas
│   │   └── midi/
│   │       ├── TrackAnalyzer.ts # Analyze MIDI structure
│   │       ├── ChannelMapper.ts # Assign tracks to 8 channels
│   │       └── Arpeggiator.ts   # Convert chords to arps
│   ├── core/
│   │   └── GameBoyPlayer.ts     # Main v2 entry point
│   └── types/
│       └── index.ts             # v2-specific types
├── public/
│   └── v2/                       # v2 UI assets
└── v2.html                       # v2 demo page

---

Phase 1: Core Sound Engine (Week 1-2)

Goal: Implement authentic GB sound generation with Web Audio API

1.1 Duty Cycle Implementation

Create src-v2/audio/synthesis/DutyCycle.ts:

• Define 4 GB duty patterns (12.5%, 25%, 50%, 75%)
• Convert patterns to PeriodicWave for Web Audio
• Pattern format: 8-step arrays [0,0,0,0,0,0,0,1] etc

Create src-v2/audio/apu/PulseChannel.ts:

• Pre-create all 4 duty waveforms on init
• playNote(midiNote, duration, velocity) method
• Use GB frequency formula (not standard MIDI)
• Simple envelope (fast attack, quick release)
• Return { osc, gain } for cleanup

Success Criteria: Each duty cycle sounds distinctly different when tested

1.2 GB Frequency Formulas

Create src-v2/audio/synthesis/FrequencyCalc.ts:

• calculatePulseFrequency(midiNote) → Hz
  • Formula: 131072 / (2048 - registerValue)
  • Convert MIDI → standard freq → register → GB freq
• calculateWaveFrequency(midiNote) → Hz
  • Formula: 65536 / (2048 - registerValue)
• calculateNoiseFrequency(pitch, mode) → Hz
  • Formula: 524288 / divisor / 2^(shift+1)

Success Criteria: Frequencies are slightly "off" from standard tuning (GB characteristic)

1.3 LFSR Noise Generator

Create src-v2/audio/synthesis/LFSR.ts:

• Implement 15-bit LFSR (default mode)
• Implement 7-bit LFSR (tonal mode)
• clock() method returns 0 or 1
• XOR bits 0 and 1, shift right, set bit 14

Create src-v2/audio/apu/NoiseChannel.ts:

• playNoise(duration, frequency, velocity) method
• Generate buffer with LFSR output
• Clock LFSR at calculated rate
• Apply envelope to buffer playback

Success Criteria: Noise sounds crunchy/metallic, not smooth white noise

1.4 Wave Channel with 4-bit Quantization

Create src-v2/audio/synthesis/WaveTable.ts:

• Store 32 samples × 4-bit (0-15 values)
• quantize(value) rounds to 4-bit
• Presets: generateBass(), generatePad(), generateLead()
• createBuffer(audioContext) converts to AudioBuffer

Create src-v2/audio/apu/WaveChannel.ts:

• Load wavetable on construction
• playNote(midiNote, duration, velocity) method
• Use BufferSource with looping
• Set playback rate for pitch
• Volume levels: 0, 100%, 50%, 25% (bit-shift style)

Success Criteria: Wave channel has audible digital "staircase" effect

1.5 Testing Phase 1

Create src-v2/audio/test/soundTest.ts:

• Test all 4 duty cycles sequentially
• Test wave channel with bass preset
• Test both noise modes (7-bit and 15-bit)
• Play test sequence: duty sweeps, bass note, drum hits

---

Phase 2: Channel Manager & 8-Channel APU (Week 2-3)

Goal: Coordinate 8 independent GB channels with mixing

2.1 APU Coordinator

Create src-v2/audio/apu/APU.ts:

• Initialize 4 pulse, 2 wave, 2 noise channels
• Channel IDs: p1-p4, w1-w2, n1-n2
• Master gain connected to destination
• Per-channel gain nodes for mixing
• scheduleNote(note: ChannelNote) routes to appropriate channel
• Track which channels are busy (channelBusy map)
• isChannelFree(channelId, atTime) for voice allocation

Key Methods:

• scheduleNote({ channel, midiNote, startTime, duration, velocity })
• schedulePulseNote(), scheduleWaveNote(), scheduleNoiseNote()
• setChannelPan(channelId, pan) for stereo

2.2 Channel Gain & Mixing

In src-v2/audio/apu/APU.ts:

• Each channel connects to individual GainNode
• Individual gains connect to master gain
• Master gain at ~0.7 to prevent clipping
• Per-channel volumes match role importance

Success Criteria: Can play 8 simultaneous notes without clipping

2.3 Integration Test

Create src-v2/audio/test/apuTest.ts:

• Schedule notes on all 8 channels simultaneously
• Verify no audio glitches or pops
• Test channel busy/free logic
• Test master volume control

---

Phase 3: MIDI Intelligence Layer (Week 3-4)

Goal: Smart track analysis and channel assignment for arbitrary MIDIs

3.1 Track Analyzer

Create src-v2/audio/midi/TrackAnalyzer.ts:

• analyzeTrack(track) returns TrackAnalysis
• Detect drums (channel 9 or percussive patterns)
• Calculate note range (min, max, avg pitch)
• Calculate note density (notes per second)
• Detect chords (simultaneous notes)
• Assign role: drums, bass, lead, harmony, pad, fx

Analysis Logic:

• Drums: channel 9 OR very short notes with low pitch variation
• Bass: average pitch < 48 (C3)
• Lead: high pitch (>72) with high density (>5 notes/sec)
• Pad: low density (<2 notes/sec), long notes
• Harmony: medium density with detected chords
• FX: very high density (>10 notes/sec)

3.2 Arpeggiator

Create src-v2/audio/midi/Arpeggiator.ts:

• arpeggiate(notes, speed) converts chords to fast note sequences
• Group notes by time (10ms tolerance)
• Single notes pass through unchanged
• Chords (2+ simultaneous notes) → fast arpeggio
• Default speed: 1/64 note
• Sort chord notes low-to-high
• Cycle through chord notes for full duration

Success Criteria: 3-note chord becomes smooth fast arpeggio

3.3 Channel Mapper

Create src-v2/audio/midi/ChannelMapper.ts:

• mapTracks(midiTracks) returns array of ChannelAssignment
• Analyze all tracks first
• Sort by priority (drums > bass > lead > harmony)
• Assign intelligently:
  • Drums → n1, n2 (noise channels)
  • Bass → w1 (wave bass preset)
  • Pads → w2 (wave pad preset)
  • Lead → p1, p2 (pulse with sweep, 50% duty)
  • Harmony → p3, p4 (pulse, 25% duty, arpeggiated)
• Mark which tracks need arpeggiator
• Specify duty cycle per assignment

Priority Calculation:

• Drums +30 points
• Bass +25 points
• Lead +20 points
• Note density +up to 20 points
• Velocity +up to 10 points

Success Criteria: Mario theme maps melody to pulse, no bass assigned (no bass in song)

3.4 Integration Test

Create src-v2/audio/test/mapperTest.ts:

• Load test MIDI (simple melody + bass + drums)
• Run through analyzer and mapper
• Verify drum tracks → noise channels
• Verify bass → wave channel
• Verify melody → pulse channel
• Print channel assignments for inspection

---

Phase 4: Main Player & Integration (Week 4)

Goal: Complete end-to-end MIDI → GB audio pipeline

4.1 Game Boy Player

Create src-v2/core/GameBoyPlayer.ts:

• Main entry point for v2 engine
• async playMIDI(midiBuffer: ArrayBuffer)
• Parse MIDI using existing src/midi/MIDIParser.ts
• Analyze tracks → assign channels → convert to GB notes
• Schedule all notes in APU
• stop() method resets APU
• Return playback info (duration, assignments for UI)

Pipeline:

1. Parse MIDI → NoteEvent[]
2. Analyze tracks → TrackAnalysis[]
3. Map to channels → ChannelAssignment[]
4. Apply arpeggiator where needed
5. Convert to ChannelNote[] format
6. Schedule in APU

4.2 V2 Types

Create src-v2/types/index.ts:

• ChannelNote interface
• ChannelAssignment interface
• TrackAnalysis interface
• ArpNote interface
• GB-specific config types

4.3 Demo Page

Create v2.html:

• Simple test UI for v2 engine
• File upload input for MIDI
• Play/stop buttons
• Volume slider
• Display channel assignments
• Show which channels are active (visual)

Create src-v2/main.ts:

• Wire up UI to GameBoyPlayer
• Handle file uploads
• Display playback state
• Show assignment information

4.4 Integration Test

Test with reference MIDIs:

• Mario theme: Simple melody (should use p1)
• Tetris theme: Bass + lead (should use w1 + p1)
• Pokémon theme: Chords (should arpeggiate to p3/p4)
• Hotel California: Complex (use all 8 channels)

Success Criteria:

• All test MIDIs sound recognizable
• No audio glitches or pops
• Drums sound punchy (noise)
• Bass sounds solid (wave)
• Melody is clear (pulse)
• Chords arpeggiate smoothly

---

Phase 5: Polish & Optimization (Week 5)

5.1 Performance Optimization

In src-v2/audio/apu/APU.ts:

• Limit simultaneous notes to 32 total
• Implement voice stealing (oldest note first)
• Add onended cleanup for oscillators
• Pre-create reusable nodes where possible

5.2 Browser Compatibility

In src-v2/core/GameBoyPlayer.ts:

• Add AudioContext resume on user interaction
• Handle Safari audio quirks
• Add mobile audio unlock
• Test on Chrome, Firefox, Safari

5.3 Advanced Features (Nice-to-Have)

• Stereo Panning: GB-style hard L/R/center per channel
• Duty Cycle Switching: Change duty mid-playback for variation
• Custom Wavetables: User-editable wave presets
• Export to WAV: Offline rendering to downloadable file

---

Phase 6: Deployment Strategy

6.1 Alpha Testing (Week 6)

• Deploy v2 to staging URL (e.g., v2.wario.style or wario.style/beta)
• Keep v1 at main URL unchanged
• Test with small group (5-10 people)
• Gather feedback on authenticity
• Fix critical bugs

6.2 Beta Release (Week 7)

• Deploy to production behind feature flag
• Add "Try v2 Beta" button on main site
• A/B test user preferences (v1 vs v2)
• Monitor performance metrics
• Gradual rollout: 10% → 50% → 100%

6.3 Full Release (Week 8)

• Make v2 the default engine
• Keep v1 available as "Classic Mode"
• Update README and docs
• Social media announcement
• Monitor error rates and feedback

Rollback Plan:

• Feature flag can instantly revert to v1
• Maintain "problematic MIDI" database
• User preference saved in localStorage

---

Technical Notes

Web Audio Implementation

Key Web Audio APIs:

• PeriodicWave for duty cycles
• OscillatorNode for pulse channels
• AudioBufferSourceNode for wave/noise
• GainNode for volume/envelopes
• audioContext.currentTime for precise scheduling

Memory Management:

source.onended = () => {
  source.disconnect()
  gain.disconnect()
}

Latency Target: <50ms from schedule to sound

What Matters vs What Doesn't

✅ CRITICAL (Implement):

• Exact duty cycle patterns
• LFSR noise generation
• 4-bit wave quantization
• GB frequency formulas
• Fast arpeggios
• Simple envelopes

❌ SKIP (Emulator minutiae):

• Length counter edge cases
• DIV-APU timing sync
• Wave RAM corruption bugs
• Sweep overflow quirks
• DAC pop suppression
• High-pass filter modeling

---

Testing Strategy

Testing follows a layered approach - technical specs for implementation correctness, community feedback for authenticity.

Layer 1: Technical Sanity Checks (Automated, Quick)

Quick checks that catch implementation bugs:

• Waveform visualization - view duty cycles in browser dev tools or canvas oscilloscope
• LFSR sequence verification - first 20 values match known GB sequence
• Frequency spot-check - play A4 (440Hz), verify it's slightly off (~438.5Hz due to GB register rounding)

Setup time: ~30 minutes. Run on every build.

Layer 2: Reference MIDI Corpus (Manual, Essential)

Core QA loop with 5 test MIDIs:

MIDI	What it tests
Mario Bros theme	Simple melody on pulse channels
Tetris theme	Bass + lead separation
Pokemon battle music	Chord arpeggiation
Any pop song with drums	Noise channel percussion
Hotel California	Complex multi-track mapping

Process: Run each through v2, listen with headphones, note what sounds wrong.

Layer 3: Community Vibe Check (Subjective, Final)

Post short clips to:

• r/chiptunes subreddit
• Chiptune Café Discord

Ask: "Does this sound like a Game Boy?"

Real chiptune people will identify specific issues ("duty cycles wrong", "noise too clean", etc.)

What to Skip

• Automated audio comparison (too complex, diminishing returns)
• Cycle-accurate timing tests (emulator territory, not our goal)
• Formal A/B studies (overkill for this project)

Success Metrics

• All Layer 1 checks pass
• All 5 reference MIDIs sound recognizable
• Community feedback: "yes, sounds like GB"
• Zero audio glitches or pops
• Works on Chrome, Firefox, Safari
• <100ms latency

---

File Checklist

Core Sound Engine (Phase 1)

• src-v2/audio/synthesis/DutyCycle.ts
• src-v2/audio/synthesis/FrequencyCalc.ts
• src-v2/audio/synthesis/LFSR.ts
• src-v2/audio/synthesis/WaveTable.ts
• src-v2/audio/apu/PulseChannel.ts
• src-v2/audio/apu/WaveChannel.ts
• src-v2/audio/apu/NoiseChannel.ts
• src-v2/audio/test/soundTest.ts

APU & Mixing (Phase 2)

• src-v2/audio/apu/APU.ts
• src-v2/audio/apu/Mixer.ts
• src-v2/audio/test/apuTest.ts

MIDI Intelligence (Phase 3)

• src-v2/audio/midi/TrackAnalyzer.ts
• src-v2/audio/midi/Arpeggiator.ts
• src-v2/audio/midi/ChannelMapper.ts
• src-v2/audio/test/mapperTest.ts

Integration (Phase 4)

• src-v2/core/GameBoyPlayer.ts
• src-v2/types/index.ts
• src-v2/main.ts
• v2.html

Documentation

• docs/GB_SOUND_SPECS.md (technical reference)
• docs/V2_ARCHITECTURE.md (system overview)
• CHANGELOG_V2.md (version history)

---

Future Enhancements (v3+)

Short Term:

• User-adjustable duty cycles via UI
• Custom wavetable editor
• Real-time parameter tweaking
• Oscilloscope visualizer
• MIDI file upload (not just search)

Medium Term:

• Frequency sweep on pulse channels
• Vibrato effects
• Echo/delay using note repeats
• Better envelope shaping (ADSR editor)
• Recording/export to WAV

Long Term:

• Full tracker-style sequencer
• Multiple retro chips (NES APU, C64 SID)
• VST plugin version
• Mobile app with touch controls
• Collaborative editing

---

Document Version: 2.0
Last Updated: January 2026
Status: Ready for implementation