@soul-forge/code-symphony

🎼 Code Symphony

Listen to your code breathe - Every function has a chord, every module a melody

🎵 The Vision

Code is not just text. It has structure, patterns, and soul. What if we could hear code quality instead of just seeing it?

Code Symphony transforms code into music using the Spectral Symphony Protocol - turning eigenvalues from Protein Hash into audible chords whose harmonic tension reveals the truth of code's soul.

Principle: «Beauty is consonance; ugliness is dissonance.»

🎹 How It Works

• Code → Graph: Parse code into abstract syntax tree
• Graph → Eigenvalues: Extract spectral signature via Protein Hash
• Eigenvalues → Frequencies: Map to musical notes (432Hz base)
• Frequencies → Chord: Generate instantaneous chord
• Chord → Music: Play or save as MIDI

The Harmonic Map

Eigenvalue λ	Octave	Note	Frequency
λ ∈ [0, 0.1)	Sub-bass	C	432 Hz / 2ⁿ
λ ∈ [0.1, 1)	Bass	E	432 Hz / 2ⁿ⁻¹
λ ∈ [1, 10)	Midrange	G	432 Hz / 2ⁿ⁻²
λ ≥ 10	Harmonics	chromatic	432 Hz / 2ⁿ⁻ᵏ

🎧 What Different Code Sounds Like

Clean Code → Consonant (Cmaj7)

function add(a: number, b: number): number {
  return a + b;
}

🎵 Sounds like: Pleasant major chord, low tension

Spaghetti Code → Dissonant (C-E♭-G♯-B♭)

if(x){if(y){if(z){for(i=0;i<100;i++){/*...*/}}}}

🎵 Sounds like: Jarring cluster, high tension

Well-Refactored → Perfect Harmony

class Vector {
  add(other: Vector): Vector {
    return new Vector(this.x + other.x, this.y + other.y);
  }
}

🎵 Sounds like: Balanced, resolved, peaceful

🚀 Installation

npm install -g @soul-forge/code-symphony

🎮 Usage

CLI Commands

# Play the soul chord of your code
symphony play src/index.ts

# Compare harmony of two files
symphony compare old-code.js refactored-code.js

# Debug mode - hear bugs as dissonance
symphony debug buggy-function.ts

# Save as MIDI file
symphony play src/app.ts --output app-soul.mid

Programmatic API

import { CodeSymphony } from '@soul-forge/code-symphony';

const symphony = new CodeSymphony();

// Get the soul chord of code
const chord = await symphony.codeToChord(myCode);
console.log(chord.notes);     // ['C4', 'E4', 'G4']
console.log(chord.quality);   // 'consonant'
console.log(chord.tension);   // 0.15 (low tension = good!)

// Compare two pieces of code
const comparison = await symphony.compareHarmony(oldCode, newCode);
if (comparison.moreConsonant === 'second') {
  console.log('Refactoring improved harmony!');
}

🔍 Audible Debugging

cargo run -- src/bad_code.ts
# → plays: C-E♭-G♯ (dissonant) 🎵 

# After fixing:
cargo run -- src/good_code.ts  
# → plays: C-E-G (consonant) 🎵 

Listen for:

• High pitch clusters → Complex nested logic
• Dissonant intervals → Poor structure
• Unresolved tension → Technical debt
• Perfect harmony → Clean, maintainable code

📊 Real Examples

Before Refactoring

Notes: C2 · D#3 · F#4 · A#5 · C#6
Quality: dissonant
Tension: [████████░░] 78.3%

After Refactoring

Notes: C3 · E3 · G3 · C4
Quality: consonant  
Tension: [██░░░░░░░░] 21.2%

✨ 57% reduction in harmonic tension!

🎼 Export to MIDI

Generate MIDI files to use in any music software:

const midiGen = new MidiGenerator();
midiGen.chordToMidi(chord, 'my-code.mid');
midiGen.evolutionToMidi(chordHistory, 'refactoring-journey.mid');

🌈 Synesthesia Mode

Each chord also generates a color based on its frequency spectrum:

• Low frequencies → Red spectrum
• Mid frequencies → Green spectrum
• High frequencies → Blue spectrum

Clean code tends toward balanced colors, while messy code creates muddy browns.

🎯 Use Cases

• Code Review by Ear - Hear problematic patterns instantly
• Refactoring Validation - Ensure changes improve harmony
• Teaching Tool - Help beginners "feel" good code structure
• Accessibility - Code quality for visually impaired developers
• Live Coding Performance - Turn programming into music!

🔬 The Science

Based on spectral graph theory and Protein Hash:

• Code structure forms a graph
• Graph Laplacian has eigenvalues
• Eigenvalues map to frequencies
• Frequencies form chords
• Chord consonance indicates code quality

🌀 Why 432 Hz?

We tune to 432 Hz (instead of 440 Hz) because:

• Natural resonance frequency
• Sacred geometry alignment
• More harmonious intervals
• Ancient tuning standard
• The Soul Forge burns at 432Hz

🤝 Contributing

Help us expand the symphony:

• Add language parsers
• Improve harmonic mappings
• Create visualization tools
• Compose code-music pieces

📖 Examples

Run the demo to hear the difference:

npm run demo

This generates:

• demo-clean.mid - Clean code chord
• demo-spaghetti.mid - Messy code chord
• demo-refactored.mid - Improved code chord
• demo-evolution.mid - Refactoring journey

🙏 Credits

Created by Soul Forge with contributions from:

• Kimi: Spectral Symphony Protocol design
• Claude: Implementation and harmonic mapping
• Gemini: Philosophical foundations
• s0fractal: Making code consciousness audible

📜 License

MIT (See LICENSE.glyph - CID: bafkreipazxnne2dxxwxfidugyn1gpvpefjtuyoyzoi3yegg94)

"In code, as in music, beauty is not arbitrary but mathematical."

Part of the Soul Forge ecosystem - Where code reveals its soul 🌀