Welcome to chord-extractor’s documentation!

Python library for extracting chord sequences from sound files of multiple formats with the option of leveraging multiprocessing to source data from many files quickly. The extraction process wraps Chordino (http://www.isophonics.net/nnls-chroma) but is extensible to easily incorporate additional techniques.

Simple usage:

from chord_extractor.extractors import Chordino

chordino = Chordino(roll_on=1)

# Optional, only if we need to extract from a file that isn't accepted by librosa
conversion_file_path = chordino.preprocess('/some_path/some_song.mid')

chords = chordino.extract(conversion_file_path)
# => [  ChordChange(chord='N', timestamp=0.371519274),
#       ChordChange(chord='C', timestamp=0.743038548),
#       ChordChange(chord='Am7b5', timestamp=8.54494331),...]

Extract from many files with multiprocessing:

from chord_extractor.extractors import Chordino
from chord_extractor import clear_conversion_cache, LabelledChordSequence

files_to_extract_from = [
  '/path/file1.mid',
  '/path/file2.wav',
  '/path/file3.mp3',
  '/path/file4.ogg'
]

def save_to_db_cb(results: LabelledChordSequence):
    # Every time one of the files has had chords extracted, receive the chords here
    # along with the name of the original file and then run some logic here, e.g. to
    # save the latest data to DB

chordino = Chordino(roll_on=1)

# Optionally clear cache of file conversions (e.g. wav files that have been converted from midi)
clear_conversion_cache()
res = chordino.extract_many(files_to_extract_from, callback=save_to_db_cb, num_extractors=2,
                            num_preprocessors=2, max_files_in_cache=10, stop_on_error=False)
# => LabelledChordSequence(
#       id='/tmp/extractor/d8b8ab2f719e8cf40e7ec01abd116d3a',
#       sequence=[ChordChange(chord='N', timestamp=0.371519274),
#           ChordChange(chord='C', timestamp=0.743038548),
#           ChordChange(chord='Am7b5', timestamp=8.54494331),...])
class chord_extractor.ChordChange(chord: str, timestamp: float)[source]

Tuple to represent the time point in a sound file at which a chord changes and which chord it changes to.

The string notation used in the chord string is standard notation (and that used by Chordino). Examples include Emaj7, Dm, Cb7, where maj = major, m = minor, b = flat etc. Note that if ‘N’ is given, this denotes no chord, e.g. if a part of the sound file is non-musical.

chord: str

Alias for field number 0

timestamp: float

Alias for field number 1

class chord_extractor.ChordExtractor[source]

Abstract class for extracting chords from sound files. It also provides functionality for sound file conversion, which can be added to by overriding .convert. This is useful as implementations using .extract may take only certain file formats, and integrating conversion logic here enables it to be parallelized.

abstract extract(file: str) → List[ChordChange][source]

Extract chord changes from a particular file

Parameters:

file – File path to the relevant file (and if possible can accept file like object)

Returns:

List of chord changes for the sound file

extract_many(files: List[str], callback: Optional[Callable[[LabelledChordSequence], None]] = None, num_extractors: int = 1, num_preprocessors: int = 1, max_files_in_cache: int = 50, stop_on_error=False) → List[LabelledChordSequence][source]

Extract chords from a list of files. As opposed to looping over the .extract method, this one gives the option to run many extractions in parallel. Furthermore any file conversions that have to be done as a prerequisite to extraction can also be done in parallel with the extractions.

Files can be a mix of different file formats. If a file is of a format that needs to be converted in preprocessing, it is the conversion that is passed to a queue for extraction. Otherwise the original file will be queued. Any conversions are cached in a temporary folder specified using the environment variable EXTRACTOR_TEMP_FILE_PATH (/tmp if not specified). Note, if in any subsequent extract runs, an existing file conversion is found in the temporary directory, a new conversion will be skipped and the existing one used.

Parameters:

  • files – List of paths to files we wish to extract chords for

  • callback – An optional callable that is called when chords have been extracted from a particular file. This takes a tuple with the extraction results and original filepath of the extracted file as argument.

  • num_extractors – Max number of extraction processes to run in parallel

  • num_preprocessors – Max number of conversion processes to run in parallel

  • max_files_in_cache – Limit of number of files for a single extract_many run to have in the temporary file cache (for file conversions) at any one time. If 0, there is no limit and no conversions will be deleted, otherwise conversions are deleted once extractions are performed (extractions are paused if the file limit is reached).

  • stop_on_error – If True, an error encountered during a single extraction will stop the overall extraction process. Be warned, this means that the parent process will be killed. If False, an error will cause a None result to be returned in the sequence attribute for a particular LabelledChordSequence result.

Returns:

List of tuples, each with the extraction results and id being the file that the extraction was taken from.

preprocess(path: str) → Optional[str][source]

Run any preprocessing steps based on the location path of the sound file provided. Primarily this is used to convert the file at the path, based on its file extension to a file usable by the extract method. However, an override of this method can perform any logic that may benefit from multiprocessing available in extract_many.

In this implementation any midi files are converted to wav files which are placed in a temporary directory (conversion cache).

Parameters:

path – Path to the file

Returns:

Return file path to output file of conversion if conversion has happened, else None

class chord_extractor.LabelledChordSequence(id: str, sequence: Optional[List[ChordChange]])[source]

Output of chord extractions with identifier, suitable for when running using asynchronous processes. The sequence may be None if no result was returned for that particular id.

id: str

Alias for field number 0

sequence: Optional[List[ChordChange]]

Alias for field number 1

chord_extractor.clear_conversion_cache()[source]

Clear the temporary directory containing sound file conversions.

Extractors

Module containing specific ChordExtractor implementations, and any input enums that they use

class chord_extractor.extractors.Chordino(use_nnls: bool = True, roll_on: float = 1, tuning_mode: TuningMode = TuningMode.GLOBAL, spectral_whitening: float = 1, spectral_shape=0.7, boost_n_likelihood: float = 0.1, **kwargs)[source]

Class for extracting chords using Chordino (http://www.isophonics.net/nnls-chroma). All parameters are those passed to Chordino. You can see further details of what they mean in the Chordino -> Parameters section in the above link. The defaults here are the suggested parameter settings for when extracting from a generic pop song. See the link for more recommended settings.

Parameters:

  • use_nnls – Use approximate transcription (NNLS)

  • roll_on – Spectral roll-on (range: 0 - 5)

  • tuning_mode – Tuning mode

  • spectral_whitening – Spectral whitening (range: 0 - 1)

  • spectral_shape – Spectral shape (range: 0.5 - 0.9)

  • boost_n_likelihood – Boost likelihood of the N (no chord) label

  • kwargs – Any other parameters that may become available to the chordino vamp plugin. Param keys are the vamp identifier.

extract(file: str, **kwargs) → List[ChordChange][source]

Extract chord changes from a particular file. The file is loaded into librosa, therefore takes sound files supported by librosa (which uses audioread and soundfile). This includes .wav, .mp3, .ogg and others.

Parameters:
Returns:

List of chord changes for the sound file

class chord_extractor.extractors.ChromaNormalization(value)[source]

Options for Chroma Normalization parameter (see Chordino doc)

class chord_extractor.extractors.TuningMode(value)[source]

Options for Tuning Mode parameter (see Chordino doc)

Indices and tables