Microtonal Playground

General
Tones
Tones Object
Fixed Frequency
Interval
Frequency Element with a Custom Label
Repeat
Invalid Array Elements
Referencing User Data

General

Microtone Playground is one of the Microtonal Fabric applications. It is an in-browser application that provides a way of playing with different thinkable tonal systems. The user uses a simple grid keyboard with a fixed number and arrangement of keys. The main method of playing is based on a 10-finger touchscreen. In this case, all kinds of chords combined with glissando can be played. Without a touchscreen, it can be played with a mouse/trackball.

Tones

The user creates a tonal system by defining frequencies for all or some keys and defines some presentation detail, such as labels on the keyboard elements. All this data is created as a single tone object.

Tones Object

Frequencies are put in an array representing rows, each row being an array of row keys. Any array size is allowed — redundant data will be ignored, and missing data will be filled with disabled keys.

Array elements representing frequencies for the keys are defined as a polymorphic set, so the elements can be of several different types: fixed frequency, an interval from a base note, fixed frequency or interval with a custom label, or repeat object.

The structure of the tones object:

tones
tones.metadata

Metadata is the information on the tonal system shown when “Tonal System Metadata” is turned on. The text lines are shown in the order of the properties as they appear in the object tones.metadata. For property names, it is recommended to take care of proper capitalization and use quotation marks if blank space characters have to be used in the name. The values can be any objects, but they will be rendered as HTML strings. So, the string values can contain arbitrary HTML markup.
Two properties are processed in a special way: tones.metadata.title and tones.metadata.copyright; see below.

tones.metadata.title

tones.metadata.title is shown as the heading of the metadata element.

tones.metadata.copyright

Copyright HTML is prefixed with “Copyright ©”. This element is rendered at the end of the metadata element.

tones.size
tones.size.width

Number of columns in the keyboard table.
The table width is not reduced, if some or all elements of tones.rows have lower length. Instead, missing row elements are rendered as disabled. In other cases, when the object repeat is used, the missing data is filled in automatically.

tones.size.height

Number of rows in the keyboard table. This is only a limiting property. The actual number of rows cannot be greater than this number, but it could be smaller if the actual number of elements of tones.rows is smaller.

tones.base

Base frequency in Hz is used to calculate the frequencies specified as intervals.

tones.transpositionUnits

Number of transposition units per octave. For 12-EDO, this value is usually 12. This value is used in the calculations of the minimum and maximum values of Transposition.

tones.rows

Array of arrays of tone objects.
A tone object can represent a fixed frequency, interval, or frequency element with a custom label.

tones.rowTitles

Array of arrays of strings. Each string is the title of a row corresponding to the mode. The object repeat can be used at the end of some rows. It specifies that the last string should be used for the rest of the modes.

tones.keyboardStyle

Optional set of rules used for custom styling of keyboard elements.

tones.keyboardStyle.className

Class name used for the keyboard parent element to avoid the clash with the application style descriptor. Should be a non-empty string representing a valid CSS class name.

tones.keyboardStyle.rules

List of strings each representing a CSS rule. Each string value is prepended with a class selector based on tones.keyboardStyle.className before the application. It makes the style applied only to the key elements.

Example: 

            keyboardStyle: {
                className: "keyboard",
                rules: [
                    "b:first-of-type { color: navy }",
                    "b:last-of-type { color: green }"
                ]
            },

Fixed Frequency

Fixed frequency is a floating-point or integer number, representing frequency in Hertz.

Interval

The intervals are defined by the calls to the functions interval(numerator, denominator), where numerator and denominator are positive integer numbers representing a rational number numerator/denominator. Interval is the element of a free Abelian group with the multiplicative group operation.

Frequency Element with a Custom Label

Such elements take on of the forms: { label: "label", interval: interval(numerator, denominator) } or { label: "label", frequency: number }. These forms allow the definition of a custom label with an interval, or a fixed frequency object. If a label is not defined, is an empty string or this property with the name label is not of a String type, it renders the corresponding key disabled. Likewise, a key is disabled when the frequency is zero or not defined, or an interval is not defined.

Repeat

The special object repeat is used to mark the row array for repetition of the previous elements. It works only if the repeat object is the last element of an array, otherwise, it renders the corresponding key disabled. The repetition works in the following way: all the elements before the element repeat are copied to fill in the complete row in a repeating pattern. The labels are simply copied, but the repeated frequencies are transposed to the next octave per each repetition.

Invalid Array Elements

Array elements of the types not listed above render the corresponding part of the keys disabled. Other cases when the key is disabled are described above.

Referencing User Data

The application looks for the default user data file with the definition of tones. The default file name is “user.data”, it should be located in the same directory as the main application file “index.html”.

To customize the tonal system and keyboard, the user needs to provide an alternative file and specify the name in the URL query string with the location relative to the location of the main application file. This query strings start with '?' immediately followed by the file name, without parameter names or anything else. For example:

.../index.html?custom/shruti.user.data

The location of the data file relative to the main application file should be taken into account if redirection is used. For example, if the HTML file shown below is placed in the immediate subdirectory of the main application file, it may look like this:

<!DOCTYPE html>
<html lang="en-us">
    <head>
        <meta http-equiv="refresh" content="0; url=../index.html?custom/shruti.user.data" />
    </head>
</html>

If the user data file is not found, the application shows an error after the user hits the button “start”.