capo 0.7

Capo: A Python Library for Guitar Chord Transposition

Capo: A Python Library for Guitar Chord Transposition

Overview

Capo is a lightweight Python library for guitarists and developers that provides precise chord transposition across capo positions. It allows users to easily convert chord progressions from one capo setting to another, supporting sharps, flats, complex chord types, and slash chords. Whether you're building a songwriting assistant, a practice tool, or a music theory application, Capo delivers a clear, reliable foundation for working with chord mappings and capo calculations in Python.

PyPI Counter
Github Stars

Branch	main	dev
CI

Code Quality

Installation

Source Code

• Download Version 0.7 or Latest Source
• pip install .

PyPI

• Check Python Packaging User Guide
• pip install capo==0.7

Usage

Capo Map

Automatically converts chords between different capo positions while preserving harmonic relationships.

>>> from capo import capo_map
>>> capo_map(["A", "Em", "C", "G"], target_capo=2, current_capo=0)
['G', 'Dm', 'A#', 'F']
>>> capo_map(["A", "Em", "C", "G"], target_capo=2, current_capo=0, flat_mode=True)
['G', 'Dm', 'Bb', 'F']

Transpose

Shifts chords up or down by a specified number of semitones to change the song's key.

>>> from capo import transpose
>>> transpose(["A", "E", "Cm", "G", "Fmaj7"], semitones=3)
['C', 'G', 'D#m', 'A#', 'G#maj7']
>>> transpose(["A", "E", "Cm", "G", "Fmaj7"], semitones=3, flat_mode=True)
['C', 'G', 'Ebm', 'Bb', 'Abmaj7']

Key Scores

Returns all possible keys and their corresponding scores for a given list of chords using the Krumhansl-Schmuckler algorithm.

>>> from capo import key_scores
>>> key_scores(["Em", "Am", "G", "Bm", "Em", "C", "G", "Bm", "Em"])
{'A#m': 0.4871417233740239, 'G#': 0.4774543026320962, 'A#': 0.5520334829280494, 'D': 0.7477367635967468, 'Am': 0.6716505683174476, 'Gm': 0.6750401588831327, 'A': 0.6622255631674839, 'Dm': 0.6367313900369936, 'G': 0.8399547248439911, 'F#m': 0.6173531647275109, 'Fm': 0.530630809877153, 'C#m': 0.5987423938857308, 'D#': 0.5377480823857491, 'C': 0.7278176839673419, 'F#': 0.5572647563660749, 'F': 0.5820127037844264, 'Em': 0.8254612345527799, 'C#': 0.4563950736636346, 'E': 0.7179587455649095, 'B': 0.7088375508524547, 'G#m': 0.6478594798186766, 'D#m': 0.564206942839128, 'Cm': 0.6280335727363678, 'Bm': 0.8030131913724882}
>>> key_scores(["G#", "G#", "Fm", "C#", "D#", "G#", "Fm", "C#", "D#"], flat_mode=True)
{'Cbm': 0.5059430034954594, 'D': 0.47214060767880817, 'Fbm': 0.5663422985823668, 'Am': 0.626082212718544, 'Gm': 0.6473142793320639, 'Gb': 0.6249570609550481, 'Dm': 0.5984541508829389, 'G': 0.5502083795108782, 'Fm': 0.8274571550716174, 'Dbm': 0.6608315888220377, 'Bbm': 0.7017791458623973, 'Abm': 0.7402210552899815, 'Ab': 0.8839844066440953, 'Bb': 0.6867751194296899, 'Ebm': 0.6941303268339243, 'Db': 0.7655343684259058, 'F': 0.6847698356536668, 'Fb': 0.573580307659009, 'Gbm': 0.5507809081451287, 'Eb': 0.8043262373344897, 'Cb': 0.5963990540758232, 'C': 0.6631957481323153, 'Cm': 0.8049063265566369, 'A': 0.4962731607074994}

Detect Key

Automatically identifies the musical key from a sequence of chords using the Krumhansl-Schmuckler algorithm.

>>> from capo import detect_key
>>> detect_key(["Em", "Am", "G", "Bm", "Em", "C", "G", "Bm", "Em"])
'G'
>>> detect_key(["G#", "G#", "Fm", "C#", "D#", "G#", "Fm", "C#", "D#"], flat_mode=True)
'Ab'

Transpose to Key

Automatically transposes a list of chords from their current key to a target key.
If the current key is not provided, it will be detected automatically.

[!NOTE] Chords are shifted chromatically; chord qualities are not adjusted to the target key's scale.

>>> from capo import transpose_to_key
>>> transpose_to_key(["Am", "F", "C", "G"], target_key="C")
['Em', 'C', 'G', 'D']
>>> transpose_to_key(["Am", "F", "C", "G"], current_key="A", target_key="C")
['Cm', 'G#', 'D#', 'A#']
>>> transpose_to_key(["Am", "F", "C", "G"], current_key="A", target_key="C", flat_mode=True)
['Cm', 'Ab', 'Eb', 'Bb']

Sharp / Flat Conversion

Converts chord notation between sharp and flat representations without changing pitch.

>>> from capo import sharp_to_flat, flat_to_sharp
>>> sharp_to_flat(["A#", "C#", "F#m", "G#7"])
['Bb', 'Db', 'Gbm', 'Ab7']
>>> flat_to_sharp(["Bb", "Db", "Gbm", "Ab7"])
['A#', 'C#', 'F#m', 'G#7']

Issues & Bug Reports

Just fill an issue and describe it. We'll check it ASAP!

• Please complete the issue template

References

1- Guitar chords capo calculator - GuitarPlayerBox

2- Enharmonic Equivalents - Music Theory Academy

3- Capo Calculator

4- Chord Transposer: Online Tool to Transpose Chords

5- Enharmonic Equivalent Chart with Enharmonic Note Names

6- Schmuckler, M.A., 1989. Expectation in music: Investigation of melodic and harmonic processes. Music Perception, 7(2), pp.109-149.

7- Chord Interval Chart: How Chords Are made (Notes and Interval Formulas)

8- Guitar Chords Explained: Diagrams, Exercises, Theory, Tips & Tricks

Show Your Support

Star This Repo

Give a ⭐️ if this project helped you!

Donate to Our Project

Bitcoin

1KtNLEEeUbTEK9PdN6Ya3ZAKXaqoKUuxCy

Ethereum

0xcD4Db18B6664A9662123D4307B074aE968535388

Litecoin

Ldnz5gMcEeV8BAdsyf8FstWDC6uyYR6pgZ

Doge

DDUnKpFQbBqLpFVZ9DfuVysBdr249HxVDh

Tron

TCZxzPZLcJHr2qR3uPUB1tXB6L3FDSSAx7

Ripple

rN7ZuRG7HDGHR5nof8nu5LrsbmSB61V1qq

Binance Coin

bnb1zglwcf0ac3d0s2f6ck5kgwvcru4tlctt4p5qef

Tether

0xcD4Db18B6664A9662123D4307B074aE968535388

Dash

Xd3Yn2qZJ7VE8nbKw2fS98aLxR5M6WUU3s

Stellar

GALPOLPISRHIYHLQER2TLJRGUSZH52RYDK6C3HIU4PSMNAV65Q36EGNL

Zilliqa

zil1knmz8zj88cf0exr2ry7nav9elehxfcgqu3c5e5

Coffeete

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

Unreleased

0.7 - 2026-02-12

Added

• sharp_to_flat function
• flat_to_sharp function
• 6#11 chord quality
• add9 chord quality
• 6add9 chord quality
• aug#11 chord quality
• maj7#5 chord quality
• 9#5 chord quality
• 13#5 chord quality
• m(maj9) chord quality
• m6add9 chord quality
• 9b5 chord quality
• 9#11 chord quality
• 13b9 chord quality
• 13#11 chord quality
• 13#9 chord quality
• 5 chord quality

Changed

• README.md updated
• Test system modified

0.6 - 2026-01-05

Added

• key_scores function

Changed

• detect_key function modified
• README.md updated
• Test system modified

0.5 - 2025-12-15

Added

• transpose_to_key function

Changed

• capo_map function modified
• README.md updated
• Test system modified

0.4 - 2025-12-05

Added

• detect_key function

Changed

• _validate_chords function modified
• README.md updated
• Test system modified

0.3 - 2025-11-26

Added

• Double sharp notes
• Double flat notes

Changed

• Fb bug fixed
• Cb bug fixed
• E# bug fixed
• B# bug fixed
• README.md updated
• Test system modified

0.2 - 2025-11-15

Added

• transpose function
• Logo

Changed

• README.md updated
• capo_map function modified
• Test system modified

0.1 - 2025-11-05

Added

• capo_map function
• Flat notes
• Sharp notes