This page describes the file format of the score input files to create
microtonal MIDI-files with
Scala. The emphasis is on flexible
description of pitches and easy experimenting with different tunings without editing the file.
To do the conversion, use the EXAMPLE command, or go to the
Tools->Transform sequence to MIDI-file dialog.
Each statement must be put on a different line in the file.
Everything after an exclamation mark are comments to be ignored.
Parameters between square brackets are optional.
time command parameters
If a zero is indicated above as time parameter, this means that this field is
ignored. It does not mean that the statement must appear at the beginning,
except for "exclude", "frequency" and "division". The other statements
may appear anywhere and more than once and their scope is everything below
until an eventual other statement of the same kind. The zero may not be
omitted and is reserved for future use. The tempo can be changed independent
of the start times.
Explanation of the parameters
<time> is the start time in units of 1/240 part of a quarter note. This
is the default unit. Another unit can be specified with the "division"
statement, which must appear at the beginning and gives the number of ticks
for one quarter note. The maximum value is 32767 and the default 240. It's
advisable not to make it smaller than 2 to avoid problems with MIDI file
players. For negative values see the MIDI file specification standard.
<duration> is in units of 1/240 part (or other division) of a quarter note.
<filename> is the name of a scale file or "0" for the current scale. ("0"
only allowed with "ladder", "chord" and "load".)
<formal octave> is a literal pitch value representing the period.
<notation system> is a name of a notation system, for example E31. The
default notation system is E12. See also SET NOTATION.
<offset degree> is the degree of the given chord or ladder that receives
the pitch of the preceding parameter.
<val> is a list of integers separated by spaces and enclosed between < and |.
It can serve as a mapping from primes to scale degrees.
<velocity> is an optional onset key velocity value that overrides the
default value for those particular note(s) only.
<degree/pitch/name> is either a degree number or a pitch value enclosed
in square brackets (meaning approximate) or a pitch value enclosed in
parentheses (meaning literal) or a note name according to the specified
notation system. If it's in square brackets then the nearest pitch in the
scale to the given pitch will be taken. If it's in parentheses then that pitch
will be taken, even if it's not in the current scale.
When a note name is used, it is like giving an equal tempered pitch in square
brackets. That means the nearest pitch in the scale to the nominal value for
the note name will be taken. If the note is outside the scale range, then an
octave number must be given after the note name with a full stop in between
without spaces, for example: D#.-1 or Ab;.3.
However if notation systems for just intonation are used (EITZ, JI, JI2,
SAJI1, SAJI2, SAJI3, SA12R, SAHTT) or LT, then a note name is not approximated
by a scale pitch, but taken literally, like a pitch value between
parentheses. The octave value can be changed however at the notation statement
(default 2). The current scale will then be irrelevant.
For notation systems whose name begins with an E and which are diatonic, all
accidentals may be used in any combination, that is all of them except E9, E10, E16 and E18.
For other ones, only the names which are explicitly given in the SHOW SCALE command can be used.
So one can easily transform pieces from one temperament to another by giving another "notation" statement.
The following are all valid "note" statements:
0 note 4 400 ! Degree number, pitch depends on scale
0 note -8 400 ! Degree number, pitch depends on scale
0 note |-2 0 1> 400 ! Degree number, pitch depends on scale and val
0 note E\ 400 100 ! Note name, pitch depends on scale and notation system
0 note E\.-2 400 100 ! Note name, pitch depends on scale and notation system
0 note (5/4) 400 127 ! Literal pitch
0 note (386.3) 400 127 ! Literal pitch
0 note (|-2 0 1>) 400 127 ! Literal pitch
0 note [5/4] 400 127 ! Approximate pitch, pitch depends on scale
0 note [|-2 0 1>] 400 127 ! Approximate pitch, pitch depends on scale
Explanation of the statements
If there are MIDI channels which should not be retuned, these channel
numbers should be specified with "exclude" (for a drum track for
example; (10 is standard, 16 for SoundBlaster). It must then appear at the
beginning and may appear more than once. Only one channel can be given as a
parameter. If you need to exclude multiple channels, then use multiple exclude
With "default" you can specify a scale to be used in case the
current scale is empty. If the current scale is not empty its pitches will be
used and this statement has no effect.
With "load" the used scale can be replaced. This can be done at
any time point. The current scale will also be superceded and can be reinstated
with "load 0".
With "outfile" the name for the output-file can be declared. If no
output-file parameter is given with the command, this name will be used,
otherwise the parameter will override.
With "equal" the used scale will be replaced by an equal
temperament. This can be done at any time point. The current scale will also be
superceded. The formal octave parameter is optional. Default is 2/1. The current
scale can be reinstated with "load 0".
The "lt_pars" statement is only used in combination with a
"notation lt" statement and specifies the parameters for this notation.
See also SET LT_PARS. The third parameter, lower
bound, is not strictly necessary here but provided for compatibility with the
SET LT_PARS command. It's not a restriction for the gamut in any case.
An alternative for this statement is "lt_gens", so only of one them should
be used. This specifies the generator not as an equal tempered scale degree,
but as a pitch.
With "key" one can change the tonic of the used scale. The
parameter is the new key. It's relative to degree 0 of the original scale. You
can use this prior to a modulation. A pitch value between square brackets or a
note name may also be the parameter. In this case the nearest scale degree will
be taken. A pitch value between parentheses is not allowed. The key value will
be reset to 0 after each "track" statement.
With "transpose" a frequency transposition can be done. It's like
using "frequency" but then with a relative value instead of an
absolute one. The parameter may be a scale degree, a pitch between parentheses
or square brackets, or note name. Note that the time value is ignored, but the
position of the statement is important. All statements below are affected,
regardless of their time value until a new track begins. The transpose value
will be made zero at the beginning of each track. Note also that when a scale
degree is given as parameter, only the frequency changes but not the key,
unless a "key" statement is given at the same spot.
A scale degree of 0 has the effect of resetting the transposition to zero,
otherwise the effect is cumulative.
With "notation" one can set the notation system to be used for
specifying pitches. The initial value is E12. See also SET
NOTATION. The optional octave parameter can be used to give another octave
value for the notation, for example to use stretched or shrinked octaves
without having to change the note names. The value must be enclosed in
0 notation E15 (1170.0) could be used to notate 78CET (Alpha scale).
The "val" statement can be used to specify a mapping from primes to
scale degrees, for example:
0 val <31 49 72 87 107|. This does not change the used scale. It enables
scale degree numbers to be specified as prime exponent vectors like this:
0 note |1 0 -1 3> 100. The number of elements in the vector must be equal
to or less than in the val statement. The scale degree number is obtained by
adding the pairwise multiplied elements of val and note vector. If the note
vector is shorter, then zeroes will be assumed as missing values.
With "note" one can specify a single note with the given pitch and
duration. The velocity parameter is optional, if it's not given then the value
given with the "velocity" statement is taken.
The pitch can be specified as a scale degree number, a literal pitch
surrounded by parentheses (see also Pitches), a literal pitch to be
approximated by the current scale surrounded by square brackets, or a note
name in the specified notation system. In the latter case, the nearest scale
pitch to the nominal value of the note name will be taken, so the notation
system should be suitable for the current or specified scale for proper
results. However if the notation is for just intonation (EITZ, JI, JI2, SAJI1,
SAJI2, SAJI3, SA12R, SAHTT) or LT, then the literal value will be taken, and
the current scale will be irrelevant. The scale degree number may also be
given in prime exponent notation, see above.
With "bend" all sounding notes in the current track will be bent by the
given interval. The effect is cumulative. So in order to sound a trill, you
need alternating positive and negative intervals. The interval limit will
depend on the tuning of the notes, unless the /MTS option is used in which
case it is the whole pitch bend range. If it is reached it will be kept at the
maximum or minimum pitch bend value.
The difference with "transpose" is that the latter only affects the pitch of
notes coming after the statement.
If another base frequency than 261.626 Hertz for middle C is wanted, then
it can be set with the "frequency" statement. One can also specify the
frequency relative to another degree than 0. Then put the degree number behind
the frequency. For example "0 frequency 440.0 9". A scale must be
present in memory in that case, or be specified in the file above the frequency
The "tempo" statement changes the global tempo from the given time
on. The parameter is in microseconds per quarter note. It can also be given in
quarter notes per minute. Then put "pm" behind the value with
space in between. Like this: "0 tempo 120 pm".
If the "relative" statement is given then all subsequent time
values are not interpreted as absolute time but relative to the end time of the
previous statement. So if you want consecutive notes with no pause in between
them, then all time values must be zero. Other positive time values give a
pause, negative time values are also allowed for simultaneous notes. The time
of the relative statement resets the absolute time to this value, as does
the time of the "track" statement. The "relative" statement
will usually be put at the beginning of the input file, so it specifies relative
times for the whole file.
If the "addtime" statement is encountered, then all subsequent time
values will have the specified offset added. This makes it easy to repeat a
phrase by copying it, so the times don't need to be changed if it's preceded by
the addtime statement. It can also be used to prevent the times to become
large. The effect is cumulative, except for the value 0 which will set the
offset back to zero.
With the "text" statement you can put a song title, author name,
copyright notice, track title or whatever in the MIDI-file. The text itself
must be enclosed by double quotes ("). Up to 128 of these statements can be
With "timesig" the default value of 4/4 can be changed.
<num/den> is the signature, where the denominator must be a power of two.
<MIDI clocks> is optional, default is 24. It is the number of MIDI clocks
in a metronome click. <32nd-notes> is also optional, default is 8. It is
the number of notated 32nd-notes per MIDI quarter note. This statement may only
occur once. Subsequent ones will be ignored.
The "track" statement may be used to group notes and programs
together in case more than one program is used simultaneously. Then the
"program" statement must come after the "track" statement. If
no "program" statement is given then a program change message will not
be inserted in the output file for that track. It's not necessary to use
different track numbers for different track statements if the same program
number is used within them. You can put a program change at any point in a
track. This changes the program for all subsequent notes in the track(s) with
that track number. You cannot use more than one program number simultaneously
within one track. A track ends when there is a new track statement or at the
end of the file. The time of a track statement is ignored unless there is a
preceding "relative" statement. Then this time is the absolute
starting time of the track. Track statements have no bearing on other things
than program changes, parameter messages, key and transpose statements.
With "chord" one can have a chord where the pitches are in a
scale file. The filename can be a normal filename, in which case the pitches
are approximated by the pitches in the current scale. It can also be a file
name enclosed in parentheses, in which case the pitches are taken literally. A
zero can be given and then the current scale is the chord. The pitch parameter
after the duration parameter is optional and it is an offset pitch for the
chord. If it's omitted then the root gets 1/1 as pitch. Then the offset degree
is the degree of the chord that receives the pitch of the preceding parameter.
If it's omitted then it is degree 0. The velocity parameter is as with
With "ladder" it's the same as with "chord" except that
the tones do not sound simultaneously but after one another.
With "portamento" you can create a sliding tone. The first pitch is
the start and the second the end pitch. It only works with the /MTS qualifier.
Without it you will get a note with the first pitch.
With the "parameter" statement a MIDI parameter (controller)
message can be given (like volume, pan, modulation, etc.) If it is given inside
a track, it affects the subsequent notes in that track.
With the "mnote" statement an untranslated MIDI note message can be given,
circumventing the pitch bend processing. This can be used for the drum sounds
on MIDI channel 10 of the General MIDI Standard. Warning: only use MIDI channels with this statement which have
been excluded with the exclude command, otherwise strange results can
occur due to active pitch bends on that channel.
The default file extension for scale files in the input file is '.scl'
and for the output file parameter it's '.mid'. The input file needs a
If there is an error in the input file, then the message 'Error in file format'
will be given followed by the contents of the line that causes the error. If a
wildcard is given in the filename, then the first file that matches it will be used.