Introduction
azchords is a software library and set of command‑line utilities designed to generate, analyze, and transform musical chord structures. The project emerged to fill a niche in music technology where developers and educators require a programmatic interface for chord manipulation that is both lightweight and expressive. By abstracting the complexities of music theory into a set of composable functions, azchords facilitates tasks such as chord progression generation, key transposition, and automated accompaniment construction. The library is written primarily in Python, with optional bindings in Rust and JavaScript, allowing it to integrate seamlessly into a wide range of environments, from web applications to desktop music production suites.
History and Development
azchords was conceived in 2017 by a team of music technologists at a small independent research lab. The initial motivation was to support a longitudinal study on automated composition techniques for educational music software. Early prototypes were implemented in a single Python script that could parse simple chord symbols and output MIDI events. As the codebase grew, the authors recognized the value of formalizing the module into a reusable library, leading to the release of version 1.0.0 in March 2019. Since then, the project has seen a steady cadence of releases, with major milestones including the introduction of a Rust backend in 2020, the first web API in 2021, and a comprehensive documentation suite in 2022.
The development model follows a transparent open‑source process. Issues are tracked on a public repository, and pull requests undergo a review pipeline that emphasizes code quality, test coverage, and adherence to the project's coding standards. The governance structure is committee‑based, with rotating maintainers drawn from active contributors. A yearly community meeting provides a forum for discussing future directions and coordinating releases.
Over the past five years, azchords has accumulated a user base that includes academic researchers, independent software developers, and hobbyist musicians. Surveys conducted in 2023 indicate that 63% of respondents use azchords primarily for educational applications, 22% for composition assistance, and 15% for integration into digital audio workstations.
Design and Architecture
Core Library
The core of azchords is a pure‑Python module that exposes a set of classes and functions for working with musical concepts. At its heart is the Chord class, which encapsulates a chord's root, quality, extensions, and inversions. Chords are represented internally as collections of semitone offsets relative to the root. This representation allows for efficient arithmetic operations such as transposition, inversion, and interval calculation.
The library also includes a Key class, modeling a musical key in terms of its tonic and mode. The key context is used for validating chord diatonicity and for suggesting complementary chords within a progression. The Progression class aggregates multiple Chord objects and provides utilities for applying common progressional transformations such as cadential substitutions and modal mixture.
Command‑Line Interface
azchords ships with a comprehensive command‑line interface (CLI) that offers a suite of utilities for converting chord symbols to MIDI, generating random progressions, and visualizing chord structures. The CLI is built on the Click library, which provides a declarative syntax for defining commands and options. Each command accepts input either from the command line, a text file, or a MIDI file, and outputs results in a chosen format such as JSON, CSV, or standard MIDI files.
Examples of CLI commands include:
azchords parse "Cmaj7 G7 Am7 Dm7"– parses a space‑separated chord string and prints detailed chord information.azchords midi --key G --tempo 120 -o output.mid "Dm7 G7 Cmaj7"– generates a MIDI file containing the specified progression in the key of G.azchords random --length 8 --style blues --output prog.json– creates an eight‑measure blues‑style progression and writes it to a JSON file.
Web API
Recognizing the need for a server‑side component, the project includes a lightweight Flask‑based web API. The API exposes endpoints for chord analysis, key detection, and progression generation. Each endpoint accepts JSON payloads and returns structured data, making it straightforward to integrate azchords into web applications or microservices. The API is documented with Swagger, and the project ships with a Docker image for rapid deployment.
Key Concepts
Chord Notation and Representation
azchords adopts the Nashville Number System and the Nashville chord symbol notation as its primary input formats. The parser accepts a wide variety of chord symbols, including quality indicators (maj, min, dim, aug, sus, add, no), extensions (7, 9, 11, 13), and alterations (b5, #9). When parsing a symbol, the library resolves the root note to a pitch class (0–11) and constructs a list of intervals that define the chord's constituent notes.
For example, the symbol F#maj9 is parsed into a root of 6 (F#), a major triad (0, 4, 7), and an added major ninth (14). The library then normalizes all intervals modulo 12 to maintain a compact representation.
Music Theory Integration
Beyond symbolic parsing, azchords incorporates a simplified music‑theory engine that can infer the function of chords within a key. By evaluating the relationship between a chord’s intervals and the scale degrees of a given key, the engine assigns Roman‑numeral labels (e.g., I, ii, V7). This feature is useful for musicological analysis, educational feedback, and advanced composition algorithms.
The theory engine also supports mode detection. When presented with a progression, it can suggest a most probable key and mode based on the distribution of chord functions. This is achieved through a Bayesian scoring system that weighs the likelihood of each key given the observed chords.
Algorithmic Chord Generation
azchords provides deterministic and stochastic generation routines. Deterministic generation allows users to supply a seed progression and receive variations that preserve harmonic function. Stochastic generation uses Markov chains derived from a corpus of popular music to produce novel progressions that emulate stylistic conventions.
Markov models are trained on MIDI datasets, with state transitions defined by chord Roman‑numeral labels. Transition probabilities are stored in a lookup table, enabling fast sampling during generation. Users can constrain the output by specifying target keys, styles, or chord quality restrictions.
Implementation Details
Data Structures
The library defines several core data structures:
Note– represents a pitch class and an octave offset.Chord– stores root, quality, extensions, and inversion information.Key– models a key signature and mode.Progression– an ordered collection of chords.
These structures are implemented as lightweight dataclasses, enabling concise syntax and automatic generation of common methods such as equality checks and string representations.
Algorithms
Chord transposition is implemented as a simple addition of semitone offsets to the root, followed by modulo 12 normalization. Inversion is handled by cyclically permuting the interval list and adjusting the bass note accordingly. The Markov chain generator uses efficient random sampling via the alias method to ensure constant‑time chord selection.
Key detection employs a weighted scoring mechanism that evaluates the fit of a progression to each major and minor key. The algorithm assigns higher scores to progressions that include more diatonic chords relative to the key. In cases of equal scores, the algorithm prefers keys with fewer accidentals.
Performance Optimizations
While the library is primarily written in Python, performance‑critical sections such as chord matching and Markov sampling are implemented in Rust using the PyO3 binding framework. The Rust code is compiled to a shared library that is loaded by the Python runtime, providing near‑native execution speeds. Benchmarks indicate that chord generation for a 32‑measure progression executes in under 5 milliseconds on a standard laptop.
Usage and Examples
Installing the Package
azchords is distributed via the Python Package Index (PyPI) and can be installed with the following command:
pip install azchords
For projects that require the Rust backend, users should ensure that a Rust toolchain is available, as the wheel includes compiled Rust extensions that will be built during installation.
Command‑Line Operations
Below is a typical workflow using the CLI:
- Parse a chord string:
azchords parse "Dm7 G7 Cmaj7" - Generate a MIDI file:
azchords midi --key G --tempo 120 -o progression.mid "Dm7 G7 Cmaj7" - Export JSON representation:
azchords export --format json -o chords.json "Dm7 G7 Cmaj7"
The CLI also supports batch processing of text files containing chord sequences, allowing for large‑scale generation tasks.
Library Usage
In a Python script, a developer can import the library and construct chords programmatically:
from azchords import Chord, Key, Progression
key = Key("G", "major")
progression = Progression([
Chord("Dm7", key),
Chord("G7", key),
Chord("Cmaj7", key)
])
midi_data = progression.to_midi()
with open("example.mid", "wb") as f:
f.write(midi_data)
The to_midi method creates a standard MIDI representation, with each chord rendered as a chord voicing occupying a single MIDI track.
Integration with DAWs
azchords can serve as a plugin backend for digital audio workstations (DAWs) via the VST3 and AU plugin formats. The project includes a minimal C++ wrapper that exposes the core Rust functions to the DAW host. Users can insert an azchords plugin into a track, feed it a chord progression, and receive MIDI notes in real time.
Applications
Music Education
Educators use azchords to create interactive chord exercises that adapt to a student’s skill level. By generating practice progressions with controlled harmonic complexity, teachers can provide targeted learning experiences. The library’s ability to annotate chords with Roman‑numeral labels also supports visualizing harmonic functions in classroom settings.
Composition Assistance
Songwriters employ azchords to brainstorm chord ideas. The Markov chain generator produces progressions that mimic the harmonic language of specific genres, such as jazz, blues, or pop. Users can filter results by desired qualities, ensuring that the generated progressions align with their artistic vision.
Music Information Retrieval
Researchers in music information retrieval (MIR) integrate azchords into their pipelines to extract chord annotations from audio recordings. By combining the library’s key detection algorithm with spectral analysis tools, MIR systems can produce high‑confidence chord transcriptions for large datasets.
Generative Music Systems
Artificial intelligence music generation frameworks incorporate azchords as a post‑processing step that converts raw MIDI sequences into harmonically coherent progressions. The library’s deterministic transformations enable reproducible results, which is valuable for scientific evaluation of generative models.
Community and Ecosystem
Contributors
As of 2026, the project lists 47 active contributors on its repository. Contributions range from code enhancements and documentation updates to issue triaging and user support. The maintainers recognize contributors through a yearly award program that highlights significant impacts on the project’s development.
Governance Model
azchords follows a meritocratic governance model. Decisions are made through a combination of issue discussion, pull request reviews, and consensus voting on proposed changes. The project’s bylaws, available in the repository, outline the roles of maintainers, contributors, and community members, and specify procedures for dispute resolution.
Related Projects
While azchords maintains its own focus on chord manipulation, it interfaces with several complementary projects:
music21– for advanced musicological analysis.madmom– for audio feature extraction.Jupyter Notebook– for interactive experimentation.SuperCollider– for sound synthesis in tandem with chord generation.
These integrations allow developers to build richer music‑processing workflows that leverage multiple specialized libraries.
Future Work
The roadmap for azchords includes the following planned features:
- Support for microtonal chord sets.
- Real‑time chord recognition via WebRTC.
- Integration with MuseScore for chord export.
- An enhanced key‑signing tool that visualizes modal interchange.
Additionally, the project is exploring the use of neural network models to generate Markov chains on a per‑genre basis, thereby improving stylistic fidelity.
License
azchords is released under the MIT License, granting users broad freedom to use, modify, and distribute the software. The project includes a full LICENSE file in its distribution bundle.
Contact
For questions, bug reports, or feature requests, users can open issues on the project’s GitHub repository or contact the maintainers via the community forum. The maintainers provide timely responses and maintain a helpful FAQ section that addresses common usage scenarios.
Appendix
The project includes extensive unit tests that cover 95% of the codebase. The tests are executed automatically in continuous integration (CI) pipelines on both Linux and macOS platforms. Users are encouraged to contribute additional test cases that reflect edge‑cases in chord parsing and generation.
Conclusion
azchords is a robust, well‑documented, and community‑driven tool for chord parsing, analysis, generation, and integration. Its blend of symbolic parsing, music‑theory inference, and algorithmic generation makes it versatile for educational, compositional, and research purposes. By maintaining high code quality, performance, and open governance, the project continues to serve a diverse user base while evolving with emerging music technology trends.
No comments yet. Be the first to comment!