How promethiuml/chordprogressor works
Project type and purpose
• This is a standalone Python-based musical tool (“Chord Progressor”) that computes smooth chord‐to‐chord voice leadings and plays them back instantly via audio backends.
• It’s not a web app or microservice—it’s a CLI/desktop utility focused on music theory and sound playback.
File structure
• Top level modules:
• progressor.py – the main entrypoint/CLI demo
• chord.py, note.py – core domain models (Chord, Note)
• chord_transforms.py, voice_leading.py – algorithms that manipulate/optimize chords
• sound_engine.py – central dispatcher for producing sound
• pygame_output.py, media_output.py – pluggable audio backends
• constants.py, utils.py – shared definitions & helper functions
• sounds/ – file store of pre-rendered note‐samples (.wav) addressed by index/name
• requirements.txt – lists external dependencies (pygame, playsound)
Extract README insights
• Uses pygame or playsound to output audio
• Core class hierarchy: Note → Chord → progression via connect_to()
• Future refactors: external chord symbol parser; improved voicing algorithm
Main components
A. CLI Application Layer
• progressor.py: parses user invocation, selects demo or custom progression
B. Music Core Layer
• Module (note.py, constants.py)
• Chord Module (chord.py, chord_transforms.py)
• Voice-Leading Module (voice_leading.py)
• Utilities (utils.py)
C. Sound Engine Layer
• sound_engine.py: orchestrates mapping Note/Chord → sample frames
D. Audio Backend Layer (Strategy Pattern)
• pygame_output.py
• media_output.py
E. File System / Sample Store
• sounds/*.wav
Relationships and data flows
1. User runs progressor.py → instantiates Note and Chord objects
2. Chord.connect_to() invokes voice_leading.py → returns optimized voicing (interval sets)
3. progressor.py calls sound_engine.play(chords)
4. sound_engine consults Audio Backend Factory → selects either pygame_output or media_output
5. Chord→Note events passed to backend → backend loads .wav samples from sounds/ → audio sent to OS sound API
Architectural patterns & principles
• Strategy pattern for pluggable backends (pygame vs. playsound)
• Single Responsibility: each module handles one aspect (parsing, transformation, playback)
• Data‐flow emphasis: immutable Note/Chord objects feed pure transformation functions → playback
Technologies & frameworks
• Python 3.x
• pygame (direct sound buffer scheduling)
• playsound (simple media layer)
• WAV sample library (44.1 kHz pre-rendered notes)
Capturing essential elements
• Do not collapse distinct modules: show chord_transforms and voice_leading separately
• Sample store with “Indexed .wav files named by pitch index” to highlight lookup logic