Metadata-Version: 2.4
Name: chorderizer
Version: 0.3.0
Summary: Generador avanzado de progresiones de acordes MIDI con Dashboard TUI reactivo y visualizadores.
Author-email: Julio César Martinez <julioglez.93@gmail.com>
Project-URL: Homepage, https://github.com/julesklord/Chorderizer
Project-URL: Bug Tracker, https://github.com/julesklord/Chorderizer/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: MIDI
Classifier: Topic :: Artistic Software
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: mido<2.0.0,>=1.3.3
Requires-Dist: colorama<1.0.0,>=0.4.6
Requires-Dist: prompt_toolkit<4.0.0,>=3.0.0
Requires-Dist: textual<1.0.0,>=0.86.0
Requires-Dist: rich<14.0.0,>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest<8.0.0,>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov<5.0.0,>=4.1.0; extra == "dev"
Requires-Dist: ruff>=0.3.0; extra == "dev"
Dynamic: license-file

# Chorderizer: Advanced Chord Orchestration & MIDI Analysis Dashboard

[![PyPI version](https://badge.fury.io/py/chorderizer.svg)](https://badge.fury.io/py/chorderizer) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![Framework: Textual](https://img.shields.io/badge/framework-Textual-0094d2.svg)](https://textual.textualize.io/) [![Checks: Trunk](https://img.shields.io/badge/checks-Trunk-purple.svg)](https://trunk.io/)

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.

![Chorderizer Dashboard Overview](demo.gif)

## 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:

```bash
pip install chorderizer
```

### Development Setup (Source)

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

```bash
# 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:

```bash
pip install -e ".[dev]"
```

### Running the Workstation

To launch the interactive dashboard, execute the module directly:

```bash
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](Docs/USER_GUIDE.md) — End-user operational details.
- [Architecture](Docs/ARCHITECTURE.md) — System design and module interactions.
- [API Reference](Docs/API_REFERENCE.md) — Technical documentation for engine integration.
- [Decisions](DECISIONS.md) — Significant repository and architecture choices.
- [Technical Debt](TECHNICAL_DEBT.md) — Deferred work with explicit exit conditions.
- [Failures](FAILURES.md) — 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*
