iammordaty/key-tools

KeyTools is a library that allows you to convert musical keys between notations. In addition, KeyTools allows you to calculate matching keys for harmonic mixing.

0.8.2 2020-03-03 14:37 UTC

Requires

• php: >=7.1

Requires (Dev)

• phpunit/phpunit: ^7

MIT

• iammordaty

• automation
• key
• beatport
• Traktor
• dj
• harmonic-mixing
• camelot-wheel
• rekordbox

README

KeyTools is a library that allows you to convert musical keys between notations. In addition, KeyTools allows you to calculate matching keys for harmonic mixing.

Supported notations:

• Camelot Key
• Open Key
• Musical
• Musical used by Beatport
• Musical used by Essentia streaming extractor

KeyTools is based on the code written by @mossspence, which can be found here.

Table of Contents

• Installation
• Requirements
• Usage
• Tests
• Further information
• License

Installation

The easiest way to install this library is via composer:

$ composer require iammordaty/key-tools

Requirements

• PHP 7.1 and higher

Usage

The following example shows how to calculate a new key.

use KeyTools\KeyTools;

$keyTools = new KeyTools();

echo $keyTools->calculateKey('3A'); // "3A"
echo $keyTools->calculateKey('3A', 1); // "4A"
echo $keyTools->calculateKey('3A', 2); // "5A"
echo $keyTools->calculateKey('3A', -1); // "2A"
echo $keyTools->calculateKey('3A', 0, true); // "3B"

KeyTools can return keys with a leading zero – just set the parameter leading_zero to true, as in the following example. Please note that, this setting applies only to Camelot Key and Open Key notations.

use KeyTools\KeyTools;

$keyTools = new KeyTools([ 
    'leading_zero' => true, 
    'notation' => KeyTools::NOTATION_CAMELOT_KEY, 
]);

echo $keyTools->calculateKey('3A'); // "03A"
echo $keyTools->calculateKey('3A', 1); // "04A"
echo $keyTools->calculateKey('3A', 2); // "05A"
echo $keyTools->calculateKey('3A', -1); // "02A"
echo $keyTools->calculateKey('3A', 0, true); // "03B"

To calculate new key, you can also use shorthand methods:

echo $keyTools->noChange('3A'); // "3A"
echo $keyTools->perfectFifth('3A'); // "4A"
echo $keyTools->wholeStep('3A'); // "5A"
echo $keyTools->perfectFourth('3A'); // "2A"
echo $keyTools->relativeMinorToMajor('3A'); // "3B"

Also, conversion of keys between notations is easy:

echo $keyTools->convertKeyToNotation('Fmin', KeyTools::NOTATION_CAMELOT_KEY); // "4A"
echo $keyTools->convertKeyToNotation('Fmin', KeyTools::NOTATION_OPEN_KEY); // "9M"
echo $keyTools->convertKeyToNotation('Fmin', KeyTools::NOTATION_MUSICAL); // = "Fm"

KeyTools allows key and notation validation by suitable methods...

$key = 'Fmin';
$notation = KeyTools::NOTATION_CAMELOT_KEY;

$keyTools = new KeyTools();

if (!$keyTools->isValidKey($key)) {
    exit('Invalid key');
}

if (!$keyTools->isSupportedNotation($notation)) {
    exit('Unsupported notation');
}

echo $keyTools->convertKeyToNotation($key, $notation); // "4A"

... or by throwing appropriate exceptions:

use KeyTools\Exception\InvalidKeyException;
use KeyTools\Exception\UnsupportedNotationException;

$key = 'Fmin';
$notation = KeyTools::NOTATION_CAMELOT_KEY;

try {
    $keyTools = new KeyTools();

    echo $keyTools->convertKeyToNotation($key, $notation); // "4A"
} catch (InvalidKeyException | UnsupportedNotationException $e) {
    echo $e->getMessage();
}

Tests

Copy phpunit.xml.dist file to phpunit.xml and use PHPUnit to run tests:

$ ./vendor/bin/phpunit

Further information

• Harmonic mixing overview and how-to
• "What Is Harmonic Mixing?" – tutorial by DJ Endo
• "Digital DJing: harmonic mixing" – tutorial by Radley Marx
• Open Key notation
• Camelot wheel (image)
• More possibilities for harmonic mixing (image)
• Essentia – C++ library for audio and music analysis, description and synthesis
• Essentia streaming extractor music command-line tool

License

iammordaty/key-tools is licensed under the MIT License.