If you want to write lesson files, my advise is to look at
some of the files in lesson-files/
and use this
document and the music format
spec for reference.
A lesson file contains of a header block and one or more
question blocks:
header { ASSIGNMENT ASSIGNMENT ... } question { ASSIGNMENT ... }
The header block can be placed anywhere in the file, but by convention
it should be the first block in the file. If more that one header block
is found, for example when using the include
command, only the
first header block is used, the rest are ignored.
Definitions to put in the header block:
version = STRING
version = "1.1.1"
This variable is not required, but it should be used because
it can (but don't guarantee to) help avoid
trouble if the lesson file format changes in the future.
title = STRING
description = STRING
content = LIST
chord
, dictation
, id-by-name
,
harmony
and sing-chord
Some lessonfiles can be useful for more than one exercise.
For example a file with chords can also be used by the id-by-name
exercise, and should have: content = chord, id-by-name
musicformat = FORMAT
normal
: The default value
chord
: any music "MUSIC CODE" will be interpreted as:
\staff{ < MUSIC CODE > }or
\staff\transpose NOTENAME{ < MUSIC CODE > }
musicformat = chord
is necessary if lesson files
written for the chord exercise should be used by for example the
id-by-name exercise.
satb
: the music "c | bes g | e | G C"
will be interpreted as:
\staff{ \stemUp < c > } \addvoice{ \stemDown < bes g > } \staff{\clef bass; \stemUp < e > } \addvoice{ \stemDown < G C > }This is used by the sing-chord exercise.
random_transpose = yes | no
random_transpose = integer, integer
If you use the format with two integers, the integers tell the
range the music should be translated. If you write
random_transpose = -5, 12
the music will be ransposed
no more than 5 semitones down or 12 semitones up (one octave).
random_transpose = yes
is the same as
random_transpose = -5, 6
and random_transpose = no
is the same as random_transpose = 0, 0
labelformat = normal | progression
filldir = horiz | vertic
fillnum = INTEGER
filldir
tell the direction the buttons are filled,
and fillnum
tell how many buttons there are in
each row or column.
name = "some short name"
music = "\staff{c'2 g' e4 e c1}"
question { tempo = 160/4 name = "Lisa gikk til skolen" music = "\staff\relative c'{c d e f g2 g2}" }
you can write:
question { tempo = 160/4 name = "Lisa gikk til skolen" "\staff\relative c'{c d e f g2 g2}" }
tempo = 130/4
In lesson files that is written to work with chord
exercise,
two more variables can used:
inversion
toptone
By default, the dictation exercise will show the first column of music, and then the user should write the rest. But if the first column is not good enough, if there for example are only rests on the first beat, these two variables can tell the program how much music to display:
clue_end = nn/dd
clue_end=1/4
will display all music in the first quarter note.
clue_music = MUSIC
Questions for this exercise need to have the key
variable set if the key signature is anything else than
c major (or a minor). Example:
question { "c''|e'|g|c" } question { "a'|e'|c'|a" } question { key="d \major" "a'|fis'|d'|d"} question { key="f \minor" "as'|f'|c'|f"}
Global variables can save you a few key strokes.
s = "\score\relative c'{ %s } question { # instead of music = "\score\relative c'{ c d e f g2 g2 } : music = s % "c d e f g2 g" }
The global variable tempo
will be the default tempo
for the questions following the definition. If not set, the
default value is 120 beats per minute. That equals the definition
tempo = 60/4
Everything after # on a line is ignored
Disclaimer: I don't know any of the standard ways of describing grammar, like BNF. So this is just an attemt to describe the file format to get people started writing lesson files.
Lessonfiles consists of assignment statements and blocks containing assignment statements.
_
description = _("This is a short description")
include
include(singchord-1)
string
"
character, like this: "this is a string"
.
The string can contain line breaks, so this is valid:
description = "<h1>Long desription</h1> This lessonfile need very much descriptions. bla bla bla"
If the string need to contain the "
character, you have
to use tripple quotes:
description = """Try <a href="solfege:practise/melodic-intervall">this </a> for a simpler interval exercise."""
integer
tempotype (in lack of a better name)
bpm/beatlen
. An example:
tempo = 120/4
will set the tempo to 120 beats per minute, each beat being a quarter note.
The operators can only be used on strings
+
%
%s
. Examples:
"\staff\relative c'{%s}" % "c d e"evaluates to
"\staff\relative c'{c d e}"
To be put on the right side of assignments. The current parser does not complain if you redefines the identifiers, so don't do that!
chord, dictation, id-by-name, sing-chord
content
horiz, vertic
normal, progression
labelformat
values.
yes, no
Identifiers match the regular expression "[a-zA-Z]+[\w_-]*".
There are two block types, header
and question
blocktype { CONTENTS }