The .scale file format

In addition to supporting the popular Scala .scl format, Pocket Orchestra supports the new .scale format, which is specifically designed to tune real-life instruments. The .scl format lacks room for a fundamental frequency, which is critical for determining a proper tuning for an instrument, and it does not allow users to name each note. The .scale format allows for both of these things, allowing for more customizability and a more readable output. When a .scl file is loaded, the fundamental frequency is assumed to be A = 440Hz and a name is automatically given to each note based on how it approximates the 12-tone equal tempered scale. The .scale file avoids both of these potentially unwanted assumptions. Using the Scale Builder in Pocket Orchestra, converting between these two file types is quite simple.

This page is intended to describe the format of the .scale file for people who wish to write their scales manually, or for developers of music software who wish to support reading and writing .scale files.

I had three purposes when designing the .scale format: the contents of the file should be easily understood and discussed by humans, the file should be easy for machines to read, and the file should store information valuable to tuning software. With that in mind, I arrived at this format:

• White space is ignored (blank lines are skipped as though they did not exist). This This allows for users to space the file out into a more readable format.
• All lines beginning with the the "//" string are ignored as if they did not exist. This lets users to comment their code. Furthermore, any text on a line following a "//" string is ignored as if it did not exist.
• The first four non-comment, non-blank lines act as the header of the .scale file.
• The first line is the scale name.
• The second line is a scale description
• The third line is the fundamental frequency of the tuning. Following the first comma on that line should be a number that expresses the fundamental frequency in Hz. For example, this is a valid line: "Base frequency, 440.0" (remember, white space is ignored). The number can be expressed as a positive decimal or whole number.
• The fourth and final header line is the number of notes in the scale, Following the first comma on that line should be a number that expresses the number of notes in the scale. For example, this is a valid line: "Scale size, 12". This number must be a positive whole number.
• The remaining non-blank, non-comment lines all hold pitch data. This data is given in the following format: "[note name],[data type],[data]". White space is allowed for readability, and will be ignored.
• Two commas separate these three points of information.
• [note name] is limited to 8 characters, and it tells the software what to call that particular note. Examples include "A", "Bb", "G#+", and "asdfasdf". Pocket Orchestra displays this information as musicians tune their instruments.
• [data type] tells the software how to read the next piece of data. It has only three possible values: "ratio", "cents", and "frequency". Any other value will give an error.
• [data] actually contains the pitch data of that particular note. Ratios are expressed with one "/" character separating numerator from denominator. Examples include "3/2", "2.5/2.2", and "8/6". Cents and frequency (in Hz) are both expressed by either a positive whole number or decimal. Note that frequency is not supported in the .scl format, as no fundamental frequency can be stored in that file.
• The following are examples of valid pitch lines: "A, ratio, 3.3/2.4", "G#, cents, 23", and "asdfasdf, frequency, 400.3".
• All files are ASCII-encoded (or 8-bit character text files).

Don't worry, you don't need to understand any of this to use Pocket Orchestra to its full extent. The Scale Builder handles all the formatting for you.

This is an example of a properly formatted .scale file:


//This is what a comment looks like

//All white space is ignored.

//Header section comes first.
//It is always 4 lines long.
//1st line is the scale name,
//2nd is the description,
//3rd is frequency to build scale from,
//4th is the number of pitches in the scale.
//Commas separate base frequency
//and scale size from the data they contain.

Just Scale (12 tones) //NAME
This line is the scale description. //DESCRIPTION
Base frequency, 440.0 //TONIC FREQUENCY
Scale size, 12 //# OF NOTES IN SCALE

//Begin pitch data.
//Before first comma is note name,
//after first comma is data type
//(ratio, cents, or frequency),
//and after second comma is actual data.

//ratios are separated by the "/" character,
//and every number can be expressed
//as a whole number or a decimal.

A, ratio, 1.0/1.0
//tonic is optional, but recommended.
//Otherwise software won't know what to name it!

Bb, ratio, 25.0/24.0
B, ratio, 9.0/8.0
C, ratio, 6.0/5.0
C#, ratio, 5.0/4.0
D, cents, 498.05
Eb, ratio, 45.0/32.0
E, frequency, 660
F, ratio, 8.0/5.0
F#, ratio, 5.0/3.0
G, ratio, 9.0/5.0
G#, ratio, 15.0/8.0

//octave is optional.



If you have any questions or suggestions, send me an email at drew@drewpendergrass.com