Quickstart

Installation

Install mscales by entering the following into your terminal:

pip install mscales

Generation

In mscales, musical scales are conceived as binary vectors. You can generate all scales with chromatic cardinality c as follows:

>>> from mscales import Scales
>>> s = Scales(c=12)

The variable scales has initialized all potential scales with cardinality 12. In order to access these scales, call the .all() method:

>>> scales = s.all()
>>> scales
array([[0, 0, 0, ..., 0, 0, 0],
       [0, 0, 0, ..., 0, 0, 1],
       [0, 0, 0, ..., 0, 1, 0],
       ...,
       [1, 1, 1, ..., 1, 0, 1],
       [1, 1, 1, ..., 1, 1, 0],
       [1, 1, 1, ..., 1, 1, 1]])

This will return a \(2^c \times c\) numpy array:

>>> scales.shape
(4096, 12)

Warning

Be careful with your choice for c! Since scales are binary vectors, there are \(2^c\) scales, a number that can grow very quickly and seriously slow down your computer.

It is also possible to only generate the scales of chromatic cardinality c with a particular diatonic cardinality d:

>>> s = Scales(c=12, d=7)
>>> scales = s.all()
>>> scales.shape
(792, 12)

One can access a specific scale through its row index:

>>> scale = scales[500,:]
>>> scale
array([1, 0, 1, 1, 0, 1, 1, 0, 1, 1, 0, 0])

The pitch-class represenation of all scales can be obtained as a list of numpy arrays:

>>> s.pitch_classes()
[array([], dtype=int64),
 array([11]),
 array([10]),
 array([10, 11]),
 ...
 array([2, 3, 4, 5, 6, 9]),
 array([ 2,  3,  4,  5,  6,  9, 11]),
 array([ 2,  3,  4,  5,  6,  9, 10]),
 array([ 2,  3,  4,  5,  6,  9, 10, 11]),
 ...]

and the corresponding interval vectors can be accessed as a list of Counter objects:

>>> s.interval_vectors()
[Counter(),
 Counter(),
 Counter(),
 Counter({1: 1}),
 ...
 Counter({1: 4, 2: 3, 3: 3, 4: 2, 7: 1, 6: 1, 5: 1}),
 Counter({1: 4, 2: 4, 3: 3, 4: 2, 7: 2, 9: 1, 6: 2, 8: 1, 5: 2}),
 Counter({1: 5, 2: 3, 3: 3, 4: 3, 7: 2, 8: 1, 6: 2, 5: 2}),
 Counter({1: 6, 2: 4, 3: 3, 4: 3, 7: 3, 8: 2, 9: 1, 6: 3, 5: 3}),
 ...]

Plotting

Scales from this collection can then be accessed and plotted. Either as a simple bar plot:

from mscales import Scales
from mscales.plots import plot_barcode

scales = Scales(c=12, d=7).all()
scale = scales[500]

plot_barcode(scale)
Example scale barcode plot.

Fig. 1 Example scale barcode plot.

or as a polar stem plot:

from mscales import Scales
from mscales.plots import plot_polar

scales = Scales(c=12, d=7).all()
scale = scales[500]

plot_polar(scale)
Example scale polar plot.

Fig. 3 Example scale polar plot.

Sonification

Note

Currently, we can only synthesize scales with a cardinality of 12 because mscales relies on the pretty-midi library.

Sonification, the mapping of generated scales to sound, is achieved with the sound module.

from mscales.sound import tone_cloud

t = tone_cloud(scale, save_as="example_scale.mid")

There are lots of parameters to change the sound. They will be documented in more detail in future releases.

Now, go on to read about the two main objects in mscales: scales and pitch-class sets.