DeChord - Real-Time Music Key and Chord Recognition Tool

May 23, 2026 · View on GitHub

Welcome to DeChord! This application is designed for musicians, music enthusiasts, and anyone interested in analyzing the harmonic content of audio files. DeChord uses advanced music analysis algorithms to recognize the musical key and chords in an audio file and displays this information in real-time through an intuitive graphical user interface.

Images

Screenshot (10) Screenshot (9) Screenshot (14)

Features

Key and Chord Recognition

Key Recognition: Detects the musical key of an audio file using the madmom library.
Chord Recognition: Identifies chords in the audio file with start and end times.
Native Chord Engine: Uses lv-chordia as the default large-vocabulary chord engine, with madmom kept as the secondary fallback engine.
Chord Label Normalization: Normalizes detected chord labels into a consistent display format, with support for richer labels such as seventh, suspended, diminished, augmented, extended, altered, and slash chords when an analysis engine provides them.
Chord Details: Shows the current chord quality and note spelling while the song plays.
Real-Time Display: Shows the current, previous, and next chords in real-time as the audio plays.

Audio Playback

Play/Pause: Controls to play and pause the audio.
Seek: Allows seeking forward and backward in the audio track.
Volume Control: Adjustable volume control through a slider.
Mute: Mute and unmute the audio.

User Interface

Drag and Drop: Supports dragging and dropping audio files into the application window.
Theme Toggle: Switch between dark and light themes.
Progress Slider: Displays and controls the current position within the audio file.
Key Display: Shows the detected musical key.
Export Chords: Export recognized chord timelines.
Enhanced Exports: Saves chord timelines with quality, notes, and bass information in text, CSV, and JSON formats.
Keyboard Shortcuts: Various keyboard shortcuts for quick access to functions.

Additional Features

GitHub Redirect: Opens the GitHub repository in a web browser.
Exception Handling: Custom exception handler to manage and print exceptions.

Technology Stack

Libraries and Frameworks

Python: The primary programming language used for development.
PyQt5: For building the graphical user interface.
lv-chordia: Large-vocabulary chord recognition for seventh, suspended, diminished, augmented, extended, altered, and slash chords.
madmom: Music signal processing library used for key/tempo analysis and as the fallback chord engine.

Windows Installation

Prerequisites

Python 3.7 or higher
Pip (Python package installer)

Setup

Clone the repository:

git clone https://github.com/chinmaykrishnroy/DeChord.git
cd DeChord

Run the main script. It creates the virtual environment, installs all dependencies, prepares FFmpeg, and starts the app:
```
run.bat
```
Run createWindowsShortcut.bat to generate a shortcut for the application:
```
createWindowsShortcut.bat
```
Use the shortcut file 'DeChord' to open the application from next time.

Linux/MacOS Installation

Prerequisites

Python 3.7 or higher
Pip (Python package installer)

Setup

Clone the repository:

git clone https://github.com/chinmaykrishnroy/DeChord.git
cd DeChord

Build and run the main script:
```
chmod +x run.sh && ./run.sh
```
Run createLinuxShortcut.sh to generate Desktop shortcut for the application:
```
chmod +x createLinuxShortcut.sh && ./createLinuxShortcut.sh
```
Use the Desktop Shortcut file 'DeChord' to open the application from the next time.

Runtime Settings

run.bat and run.sh install lv-chordia as the native chord engine. If it is unavailable at runtime, DeChord falls back to madmom so the app remains usable.

Runtime settings can be overridden with environment variables:

DECHORD_CHORD_ENGINE=lv-chordia, madmom, or auto
DECHORD_CHORD_DICT=submission, ismir2017, or full
DECHORD_ANIMATE_CHORDS=false by default. Set to true only if you want optional chord-lane slide animation.

How to Use

Loading an Audio File

Click the Open button or use the drag and drop feature to load an audio file.
Supported formats: .wav, .mp3, .m4a, .aac.

Playback Controls

Play/Pause: Use the play/pause button to start or pause the audio.
Seek: Use the forward and backward buttons to seek 10 seconds ahead or back.
Mute: Click the mute button to mute or unmute the audio.
Volume Control: Adjust the volume using the slider.
Progress Slider: Drag the slider to move to a different part of the audio file.

Chord and Key Recognition

The application will automatically start recognizing chords and the key when an audio file is loaded.
The recognized chords will be displayed in real-time as the audio plays.
The detected key will be displayed above the playback controls.

Exporting Chords

Click the Save Chords button to export the recognized chord timeline to text, CSV, and JSON.

Toggling Theme

Click the Theme button to switch between dark and light themes.

Redirect to GitHub

Click the GitHub button to open the project's GitHub repository in your web browser.

Keyboard Shortcuts

Esc: Close the application
-: Minimize the application
T: Toggle theme
P: Play/Pause
Left Arrow: Seek backward
Right Arrow: Seek forward
M: Mute/Unmute
O: Open audio file
E: Export chords
R: Redirect to GitHub

Code Structure

Main Files and Directories

main.py: The entry point of the application.
interface.py: Contains the GUI layout and setup.
chords.py: Functions and classes related to chord recognition.
chord_engines.py: Engine selection and fallback logic for lv-chordia and madmom.
advanced_chord_worker.py: Isolated subprocess worker for the PyTorch-based lv-chordia engine.
key.py: Functions and classes related to key recognition.
icons/: Directory containing icon files.
export/: Directory where exported chord files are saved.

Key Classes

KeyRecognitionThread: A thread for performing key recognition.
ChordRecognitionThread: A thread for performing chord recognition.
Ui_MainWindow: The class is for the application's user interface.
MainWindow: The main window class for every other class's integration and features.

Exception Handling

A custom exception handler is set up to handle and print exceptions, making debugging easier.

Customizing the Application

Adding New Features

To add new features, you can extend the existing classes or add new ones. Ensure to update the GUI (interface.py) and connect the new functionalities appropriately.

For the chord-recognition product plan, see ROADMAP.md.

Modifying the Theme

To modify the themes, you can update the dark_theme and light_theme stylesheets in the theme.py file.

Contributing

Reporting Issues

If you find any bugs or issues, please report them in the Issues section of the GitHub repository.

Pull Requests

I welcome contributions! Please fork the repository and create a pull request with your changes. Ensure your code follows the existing coding style and includes appropriate documentation and tests.

Coding Standards

Follow PEP 8 guidelines for Python code.
Document your code using docstrings.
Write meaningful commit messages.

License

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

Acknowledgements

Libraries and Tools

lv-chordia: For large-vocabulary chord recognition.
madmom: For music signal processing algorithms and fallback chord recognition.
PyQt5: For the GUI framework.
Python: The programming language used.