mrcodefinger / twelvetones

0.7.1 2026-08-19 13:21 UTC

Requires

• php: ^8.2

Requires (Dev)

• phpunit/phpunit: ^12.0

MIT

• Gabriel Serwas

Published on Packagist.org on 2026-08-19 13:24 UTC

README

This library displays all twelve tones in random order or along systematic interval sequences (chromatic, whole tone, minor/major third, circle of fifths, circle of fourths).

Requires PHP 8.2 or later.

composer install
composer test
php index.php

Usage

use MrCodefinger\TwelveTones\Direction;
use MrCodefinger\TwelveTones\OrderMode;
use MrCodefinger\TwelveTones\Service\RandomValue;
use MrCodefinger\TwelveTones\Service\TwelveTones;

$tones = new TwelveTones([
    'A',
    'B',
    'C',
    'D',
    'E',
    'F',
    'G',
    new RandomValue(['Ab', 'G#']),
    new RandomValue(['Bb', 'A#']),
    new RandomValue(['C#', 'Db']),
    new RandomValue(['D#', 'Eb']),
    new RandomValue(['F#', 'Gb']),
], OrderMode::Random);

Order modes

An optional $start note (default C) rotates the sequence so it begins on that pitch. Random order ignores $start. An optional $direction (default Direction::Ascending) reverses the interval step for descending practice; remaining cycles still start on the next unused chromatic pitch. Chromatic, whole-tone, and third sequences use sharps when ascending and flats when descending (an explicit sharp or flat $start still wins).

Mode	Example from C
OrderMode::Random	shuffled, enharmonic spellings random
OrderMode::Chromatic	C C# D D# E F F# G G# A A# B
OrderMode::Chromatic descending	C B Bb A Ab G Gb F E Eb D Db
OrderMode::WholeTone	C D E F# G# A# C# D# F G A B
OrderMode::WholeTone descending	C Bb Ab Gb E D Db B A G F Eb
OrderMode::MinorThird	C D# F# A C# E G A# D F G# B
OrderMode::MinorThird descending	C A Gb Eb Db Bb G E D B Ab F
OrderMode::MajorThird	C E G# C# F A D F# A# D# G B
OrderMode::MajorThird descending	C Ab E Db A F D Bb Gb Eb B G
OrderMode::Fifths	C G D A E B F# C# G# D# A# F
OrderMode::Fourths	C F Bb Eb Ab Db Gb B E A D G

$tones = new TwelveTones([...], OrderMode::Fifths);
echo $tones;

$fromEb = new TwelveTones([...], OrderMode::Chromatic, start: 'Eb');

$descending = new TwelveTones([...], OrderMode::MinorThird, direction: Direction::Descending);

foreach ($tones->getValue() as $tone) {
    echo $tone . ' ';
}

Intervals that do not visit all twelve pitch classes in one cycle (whole tone, minor third, major third) concatenate the remaining cycles so every key still appears.

Transposition

PitchClass::transposeSequence() shifts a finished sequence by any interval within the octave, which is what a second reference row for transposing instruments needs. Since only pitch classes are involved, an interval and its inversion produce the same row: a major sixth up equals a minor third down.

use MrCodefinger\TwelveTones\Interval;
use MrCodefinger\TwelveTones\PitchClass;

$row = $tones->getValue();

$forBbInstruments = PitchClass::transposeSequence($row, Interval::MajorSecond->value);
$downAMinorThird = PitchClass::transposeSequence($row, -Interval::MinorThird->value);

Without an explicit $useFlats each destination is spelled as that interval from its source name: a minor third from G is Bb, not A#. Pass $useFlats to force the canonical chromatic names instead. PitchClass::transposeName() does the same for one note name, PitchClass::transpose() works on pitch class integers, and Interval::inverted() returns the complement to the octave.

Instrument transpositions in interval terms: Bb instruments Interval::MajorSecond, Eb instruments Interval::MajorSixth, F instruments Interval::PerfectFifth.

ShuffleArray is still available as a deprecated alias for random order.

https://twelvetones.eu/