music objects
Some of the exercises in GNU Solfege use data files that contain questions. These data files are called 'lesson files'. The lesson file exercises can easily be extended if the questions supplied with the program does not fit your needs. The following list show the exercises that use lesson files, and also show the name you should use to refer to them when you write lesson files: singanswer, chord, chord-voicing, id-by-name, dictation, sing-chord and harmonic-progression-dictation.
If you want to write lesson files, my advise is to look at
the example files in example-lesson-files/
and some of the files in lesson-files/ and use this
document and the music format
spec for reference. You should save your private lesson files in
$HOME/lessonfiles/. If you save them in lesson-files/ they might get accidentally deleted when you upgrade
the program. To practise your files, you must select them in the "Select lesson file" dialog in the "user" lesson collection. If you think it is difficult to
write lesson files using this documentation, you can vent your frustration
to the email list solfege-devel@lists.sf.net or on the wiki at
www.solfege.org/wiki.
New in version 2.0 is that Solfege by default expect the content of lesson files to be in UTF-8 encoding. gedit is a nice little editor that let you edit unicode files.
If you don't like unicode, you can tell Solfege that the file has another encoding by inserting a special comment line as the first line of the file. The following example set the charset to ISO 8859-1, a charset commonly used in many west-european languages:
# -*- coding: iso-8859-1 -*-
Russians might want to use koi8-r:
# -*- coding: koi8-r -*-
The program use the python libs to convert to unicode, so it should understand almost any encoding you can think of. If you see some characters are missing, for example when the name of questions are displayed on buttons, then most likely you have done something wrong with the encoding.
A lesson file consist 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 function, only the
first header block is used, the rest are ignored.
Definitions to put in the header block:
version = STRINGversion = "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 = STRINGdescription = STRINGcontent = LISTcontent = chord, id-by-name
random_transpose = [key|semitones|accidentals], INTEGER, INTEGER | no | yesrandom_transpose = norandom_transpose = yesrandom_transpose = accidentals, INTEGER, INTEGERkey variable like this:
question {
name = "the name"
key = "d \major"
music = music("\key d \major d' e fis")
}
INTEGER, INTEGER. To explain how this works, think of flats as negative numbers and sharps as positive numbers. The code
random_transpose = accidentals, -2, 3
random_transpose = accidentals, 2, 3
random_transpose = key, INTEGER1, INTEGER2INTEGER1 steps down or INTEGER2 steps steps up the circle of fifth. (And by my own definition, up is more sharps and down is more flats ... :-) ) This is real transposition where both the key and the notes are transposed.
random_transpose = semitones, INTEGER1, INTEGER2INTEGER1 steps down or INTEGER2 steps up. This is real transposition where both the key and the notes are transposed. You will easily end up with music in the keys with LOTS of accidentals. The code
random_transpose = semitones, -2, 6
random_transpose = INTEGER, INTEGER syntax.
labelformat = normal | progressionnormal. Set to progression for lesson files where the name of the questions is a harmonic progression, written in a undocumented, but not difficult format. Check some existing lesson file to see how it works. This variable is ignored by all exercises except id-by-name
questions_selectable = yes | nohave_repeat_slowly_button = yes | noyes if you want the exercise to have a "Repeat slowly" button. Works for id-by-name and is ignored by the other exercises.
have_repeat_arpeggio = yes | noyes if you want the exercise to have a "Repeat arpeggio" button. Works for singanswer and is ignored by the other exercises.
have_music_displayer = yes | noyes if you want the question to have a music displayer. The program will display the answer in the music displayer when the user gives up or answers correctly. Works for id-by-name and is ignored by the other exercises.
enable_right_click = yes | noyes. Set to no for lesson files where it does not make sense to right click buttons. This variable is recognised by the exercises id-by-name, chord-voicing and chord.
filldir = horiz | vertichoriz. Works for id-by-name and is ignored by the other exercises.
fillnum = INTEGER1. Works for id-by-name and is ignored by the other exercises.
name = "some short name"
music = music(MUSICSTRING, MUSICFORMAT)"music variable. Note that there is a shortcut. Instead of:
question {
name = "Lisa gikk til skolen"
music = music(...)"
}
question {
name = "Lisa gikk til skolen"
music(...)
}
music object.
tempo = INTEGER / INTEGERinstrument = STRING, INTEGERinstrument = STRING, INTEGER, STRING, INTEGER, STRING, INTEGERinstrument = "cello", 100
instrument = "bass", 100, "acoustic grand", 100, "clarinet", 100
In lesson files that is written to work with chord
exercise, two more variables can used:
inversiontoptoneBy 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/ddclue_end=1/4 will display all music in the first quarter note.
clue_music = MUSIC(Use only one if these variables in a question. Using both are undefined.)
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"}
music objectsSynopsis: music(MUSICCODE, MUSICTYPE=normal).
The default value for MUSICTYPE is
normal, so you only have to specify it for
other music types.
Available musictypes:
normal\staff command. Example:
variable = music("\staff\relative c' { c' d' }")
chord variable = music("c' e' g'", chord)
chord is defined. Calling
chord("c e g")
is the same as
music("c e g", chord)
satb variable = music("c''|e'|g|c")
c'' will be sung by the soprano, e' by the alto, etc. Short-hand function satb is defined.
voice variable = music("c'4 c' g' g' | a' a' g'2", voice)
variable = music("\staff{ c'4 c' g' g' | a' a' g'2", normal)
voice is defined.
rvoicervoice is similar to voice except that the music is in \relative mode, relative to the first tone. The music from:
variable = music("c'4 c g' g | a a g2", rvoice)
\staff\relative c'{ c4 c g' g' | a a g2 }
voice example above. Short-hand function rvoice is defined.
wavfile.wav file. The path given to the file is relative to the directory the lesson file is stored in. Example:
variable = music("share/fifth-small-220.00.wav", wavfile)
wavfile is defined.
cmdline cmdline("./bin/csound-play-harmonic-interval.sh 220.000000 320.100000")
cmdline is defined.
Global variables can save you a few key strokes.
s = "\score\relative c'{ %s }
question {
# instead of music = music("\score\relative c'{ c d e f g2 g2 }") :
music = music(s % "c d e f g2 g")
}
Also, the two variables tempo and
instrument can at top level to set the defaul values
for a whole file. You can override this for singel questions by putting
another difinition inside the question block.
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". Use tripple quotes for strings that contain line breaks:
description = """<h1>Long desription<h1> This lessonfile need very much descriptions. bla bla bla"""
" character, you have to use tripple quotes:
description = """Try <a href="solfege:practise/melodic-interval">this </a> for a simpler interval exercise."""]]>
NB: All strings have to be unicode strings. If you get error messages like this one:
In line 21 of input: does not recognise this string '<' as a valid token.'
(line 20): question {
(line 21): question {
(line 22): name = _("Ionia�)]]>
then you must check the encoding of your file. See the section about file encoding. You can change the encoding of a file using the <command>iconv</command> program:
iconv -f YOUR_ENCODING -t utf8 your.file
integertempotype (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.
Operators can only be used on strings
+%%s. One example:
\staff\relative c'{%s}" % "c d e"
evaluates to
\staff\relative c'{c d e}"
FIXME see if we should add the outdated last paragraphis