chordless

Description

chordless is a MIDI note analyzer that runs on Linux. Any modern Linux version (i.e. with ALSA) should work.

The initial project goals are partially completed.

Project Goals

• Display currently "on" notes from a MIDI instrument (DONE)
• Display chord names matching the note structure (DONE)
• Flesh out supported chords with all typical chord types and inversions (IN PROGRESS)
• Customize displayed info using GUI controls (IN PROGRESS - octave display, sharp/flat preference, best chord only, bass-only matching)
• Conform to the Google C++ Style Guide.

Compiling

Requirements:

• CMake 3.25+
• Ninja build system
• Qt 6.3 dev files
• OpenGL dev files required by Qt6
• ALSA dev files
• Boost program_options and json dev files
• An internet connection, since gtest 1.15.0 is downloaded from github during the build

Install Dependencies

Debian/Ubuntu:

sudo apt install -y cmake ninja-build qt6-base-dev qt6-declarative-dev libgl1-mesa-dev libasound2-dev libboost-json1.81-dev libboost-program-options1.81-dev

Fedora:

sudo dnf install -y cmake ninja-build qt6-qtbase-devel qt6-qtdeclarative-devel mesa-libGL-devel alsa-lib-devel boost-devel libstdc++-static

Build Instructions

Release Build:

cmake --workflow --preset release
# Binary location: build/release/chordless

Debug Build (with tests and coverage):

cmake --workflow --preset debug
# Binary location: build/debug/chordless
# Run tests: ctest --test-dir build/debug
# Coverage report: ./coverage_summary.sh

Usage

In addition to compile dependencies, qml6-module-qtquick-templates is used at runtime.

Running build/release/chordless from the project root will use the provided chords.json config file. Use chordless -c FILE_NAME to specify a different chord configuration or path.

An ALSA MIDI input port is opened when the application launches. Use an ALSA utility such as aconnectgui to connect your MIDI instrument to chordless. Notes are read from all MIDI channels, and all other MIDI traffic is ignored.

Testing without MIDI Hardware

For testing without a physical MIDI device, see notespew/README.md.

Development

Testing

The project includes comprehensive unit tests using Google Test:

# Run all tests
cmake --workflow --preset debug

# Check test coverage (requires debug build)
./coverage_summary.sh

Architecture

The codebase is organized into several modules:

• note/: Note naming, event handling, and observation
• chord/: Chord matching and analysis
• input/: ALSA MIDI input handling
• settings/: Configuration management

Key components:

• NoteObserver: Base class for note change notifications
• ChordMatcher: Analyzes note patterns to identify chords
• ScientificNoteNamer: Converts MIDI notes to scientific notation (e.g., "C₄")

Planned steps

• Deploy as portable AppImage package that includes dependencies
• Use a config file for general program settings
• Update project screenshot(s) to reflect current UI and features

Features

Bass-Only Matching (Relaxed Chord Recognition)

The "Bass Only" mode enables relaxed chord matching that focuses on harmony from the bass notes upward. This is useful when playing melody notes above a chord voicing.

How it works:

• Starting from the lowest note, analyzes ascending notes progressively
• Stops at the first non-matching note in the pattern
• Returns the best chord match found in the contiguous bass notes
• Ignores non-chord tones, passing tones, and melody notes above the chord

UI Control: Toggle the "Bass Only" checkbox in the application.

See doc/CHORDS.md for detailed algorithm explanation and testing instructions.

Further work

• Inversion notation display options
  • Control whether and how chord inversions are displayed
  • Options could include: Off, Classical (figured bass), Slash notation (C/E), Plain English ("2nd Inversion")
  • UI widget to select display preference
• Select key/mode, for improved chord naming/analysis
• JACK MIDI input
• Sustain checkbox: Keep notes on, respecting sustain pedal