ChordForge

ChordForge is a Rust-first CLI/TUI for audio, MIDI, and music-theory workflows.

Install

cargo install --path .

Cargo tracks its own installs, so running this again rebuilds only when sources change and replaces the binary without extra flags. If ~/.cargo/bin/chordforge already exists but was not installed by cargo (for example copied there by build.sh), the first run needs --force:

cargo install --path . --force

Verification

scripts/verify.sh is the full local gate: formatting, clippy with -D warnings, debug and release test runs, a release build, and the Kani bounded proof when cargo-kani is installed.

To run it automatically before pushes (local git hooks, no hosted CI):

git config core.hooksPath .githooks

Feature gating and budget

The default build ships SoundFont playback (soundfont) and LV2 plugin discovery/instantiation scaffolding (lv2). Lean builds can drop both with --no-default-features, and CLAP hosting is opt-in with --features clap-host. The release binary and build-time soft budgets are recorded in docs/features.md; scripts/verify.sh warns when the release build drifts past them and also checks the lean and CLAP feature builds.

Interactive flows

• chordforge run opens the main TUI dashboard for routing and transport.
• chordforge theory singing-live is the guided vocal coach.
• chordforge theory singing-helper is a short one-shot pitch check against a reference tone.
• chordforge theory tuner-live is the live tuner display.
• chordforge theory vocal-monitor tracks mic plus backing track and can export recordings and metadata.

Tutorial mode

Run chordforge --tutorial for a short, step-by-step walkthrough of the interactive commands and how to operate them from the terminal.

Temperament and tuner support

Pitch detection uses hybrid autocorrelation plus FFT analysis, and the tuner accepts --temperament equal|just|meantone|well and --notation scientific|solfege|international. Historical temperaments are implemented as real cent tables, not labels.

Practice and notation

• chordforge theory rhythm-score scores your timing against a metronome, from the mic or a WAV file.
• chordforge theory ear-training runs a spaced-repetition quiz for intervals and chord qualities and persists scheduling state.
• chordforge theory loop locks a recorded phrase to a tempo, draws a waveform, and writes a loop WAV; --tap derives the tempo from tap timestamps.
• chordforge theory chordpro parses ChordPro files, transposes them, prints chord markers above lyric lines, and can export MIDI or play them.
• chordforge theory tab renders local tablature for every chord in a ChordPro file.
• chordforge theory notation exports a Roman-numeral progression's chord tones to MusicXML and LilyPond.

The trainer --midi-output flag streams the drill pattern to a MIDI port for real, and analysis (theory analyze) performs monophonic transcription, chord labeling, tempo, and key estimation on WAV input.