How liutunglin/harmonica-sheet-generator works
Project type and purpose
• This is a domain-specific open-source music generation tool (a CLI/GUI Python application) that produces three-track harmonica MIDI sheets (melody, chords, bass) based on user-selected styles and tempos.
File structure
• Top-level directories and files:
• midis/ – output folder for generated MIDI files
• models/ – pre-trained Magenta model files (.mag) for melody and lookback RNN
• scripts/ – core Python scripts for configuration, UI, and each generation step
• requirements.txt, README.md, .gitignore
• Within scripts/:
• ui.py – GUI entry point
• generate_midi.py – orchestrator that ties all generation steps and writes the final MIDI
• generate_chords.py, generate_bass.py, generate_melody.py – individual track generators
• style_config.py – style definitions (chord progressions & rhythms)
• chords.py – helper module for chord notes lookup
README for additional insights
• The system uses Magenta’s improv_rnn (LSTM) for conditioned melody generation.
• Chord generation relies on a predefined set of harmonica chords and progressions.
• Bass generation follows simple root-note and arpeggio patterns.
• Users interact via CLI flags or a simple GUI.
• Outputs are MIDI files in the midis/ directory for further editing in DAWs.
Main components and interactions
a. Components
1. User Interface
– CLI (generate_midi.py + args)
– GUI (ui.py)
2. Style Configuration
– style_config.py defines progressions & rhythm patterns by style
3. Generation Engine
i. Chord Generator (scripts/generate_chords.py + chords.py)
ii. Melody Generator (scripts/generate_melody.py + models/improv_rnn.mag)
iii. Bass Generator (scripts/generate_bass.py)
4. Assembler & MIDI Writer
– scripts/generate_midi.py invokes each sub-generator, merges tracks, writes MIDI
5. File System
– models/ (input .mag files)
– midis/ (output .mid files)
6. External Dependencies
– Magenta (TensorFlow) for RNN inference
– Python libraries from requirements.txt
b. Relationships / Data flow
• User → (CLI flags or GUI) → Orchestrator
• Orchestrator → Style Config → each generator
• Each generator → produces a track (note sequence)
• Assembler → merges tracks → writes MIDI → midis/
Important architectural patterns & design principles
• Pipeline pattern: clear separation of stages (config → chords → melody → bass → assembly)
• Modularity: each track generator is an independent script/module
• Plug-in-style models: additional Magenta models can be swapped in models/
• Single responsibility: style_config.py only defines progression and rhythm data
• Extensibility: add new styles or instruments by extending style_config or adding new scripts