chorderizer 0.3.0

Generador avanzado de progresiones de acordes MIDI con Dashboard TUI reactivo y visualizadores.

Chorderizer: Advanced Chord Orchestration & MIDI Analysis Dashboard

Chorderizer is a specialized Python-based orchestration tool and harmonic workstation designed for professional composers, theorists, and music producers. It provides a robust engine for exploring diatonic relationships across a wide array of musical scales, enabling precise customization of chord voicings and the generation of production-ready MIDI sequences.

Project Philosophy

The core objective of Chorderizer is to bridge the gap between abstract music theory and digital composition. By providing an interactive, low-latency TUI (Terminal User Interface) dashboard, the tool allows for rapid prototyping of harmonic progressions while maintaining strict adherence to diatonic principles and ergonomic voice leading.

Supported Scope

Chorderizer is intentionally focused on:

• interactive harmonic exploration for composers and producers
• diatonic and modal chord generation
• MIDI export and quick tablature support
• terminal-first workflows powered by Textual

It does not currently aim to be:

• a full DAW replacement
• a general-purpose notation editor
• a complete guitar voicing engine for every tuning or fingering strategy
• a music theory engine for non-Western systems or arbitrary microtonal scales
• a plugin host or real-time MIDI router

Core Capabilities

Harmonic Engine & Theory Support

The underlying music theory engine has been expanded to support 11 distinct scales, covering the fundamental building blocks of Western and contemporary harmony:

• Diatonic Standards: Major (Ionian), Natural Minor (Aeolian).
• Modal Harmony: Full support for Greek Modes (Dorian, Phrygian, Lydian, Mixolydian, Locrian).
• Advanced Tonality: Harmonic Minor, Melodic Minor (Ascending).
• Pentatonic Structures: Major and Minor Pentatonic variations.

Reactive TUI Dashboard

The v0.2.x release introduces a comprehensive dashboard built on the Textual framework, facilitating real-time visualization and interaction:

• Piano Visualizer: A 2-octave responsive keyboard rendering active MIDI notes with precision.
• Guitar Fretboard: A 12-fret interactive diapasón highlighting scale tonics and specific chord positions.
• Guitar Tab Generator: Automated conversion of MIDI chord voicings into playable tablature notation.
• Diatonic Table: Real-time calculation of chord names, degrees (Roman Numeral Analysis), and MIDI note arrays based on selected extensions.

MIDI Export & Humanization

The MIDI engine (powered by mido) is designed to produce sequences that feel organic and professional:

• Note Extensions: Support for Triads, 6ths, 7ths, 9ths, 11ths, and 13ths.
• Inversion Logic: Precise control over 1st, 2nd, and 3rd inversions.
• Humanization Engine: Intelligent velocity randomization and micro-timing adjustments.
• Automated Basslines: Optional generation of root-based bass tracks for full harmonic context.

Installation & Execution

Prerequisites

• Python 3.8 or higher.
• Recommended: A terminal with support for true color and UTF-8 characters (e.g., Windows Terminal, iTerm2, Alacritty).

Installation

The easiest way to install Chorderizer is via PyPI:

pip install chorderizer

Development Setup (Source)

If you wish to contribute or run the latest development version:

# Clone the repository
git clone https://github.com/julesklord/chorderizer.git
cd chorderizer

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # Or .venv\Scripts\activate on Windows

# Install the package
pip install .

For development:

pip install -e ".[dev]"

Running the Workstation

To launch the interactive dashboard, execute the module directly:

python -m chorderizer.chorderizer

Dashboard Interface Guide

The TUI is designed for keyboard-driven efficiency:

• [A] Add Chord: Commits the currently highlighted chord in the table to the progression list (Right Sidebar).
• [X] Clear List: Flushes the internal progression buffer.
• [E] Export MIDI: Serializes the current progression list into a standard MIDI file (SMF) in ~/chord_generator_midi_exports.
• [H] Manual: Displays the comprehensive on-screen operation manual.
• [Q] Terminate: Safely closes the application.

Technical Standards & Quality Assurance

The codebase adheres to PEP 8 standards and utilizes modern tooling to ensure stability and maintainability:

• Linting & Formatting: Managed via Ruff and Trunk for lightning-fast quality control.
• Testing Suite: Comprehensive unit tests managed via pytest, ensuring integrity of the theory engine and MIDI generation.
• Architecture: Modular design separating theory logic (theory_utils.py), MIDI generation (generators.py), the classic orchestration flow (chorderizer.py + ui.py), and the reactive Textual dashboard (tui_app.py + tui_widgets.py).

Maintenance Notes

This repository follows a maintained-project standard:

• critical repository changes are tracked in DECISIONS.md
• known trade-offs and deferred work live in TECHNICAL_DEBT.md
• notable failures and broken assumptions are recorded in FAILURES.md

Supplementary Documentation

For detailed technical specifications, refer to the following documents:

• User Guide — End-user operational details.
• Architecture — System design and module interactions.
• API Reference — Technical documentation for engine integration.
• Decisions — Significant repository and architecture choices.
• Technical Debt — Deferred work with explicit exit conditions.
• Failures — Production or development failures worth preserving as calibration data.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

---

Created with ❤️ for the musical community. Powered by Python, Textual, and Antigravity