This page is being rewritting for Solfege 3.0. Don't translate it before this message has been removed.
In GNU Solfege, each exercise is created by a lesson file interpreted by one of the exercise modules:
melodicintervals
harmonicintervals
singinterval
singinterval
is an exercise where the program display a interval and plays the first tone. Then the user should sing the interval, and then click a button to hear the correct answer. No microphone support yet.
idbyname
idbyname
is a very generic exercise. In its most basic form, the program play some sound, and you have to select among several buttons that it some way represents the music.
chord
chord
module act as a specialized idbyname
module. The difference is that with the chord
module you can write lesson files where the user should tell what inversion the chord is in, and what the top tone is.
chordvoicing
compareintervals
rhythm
You can read the page lesson file tutorial for step by step tutorial.
In a standard install, Solfege will look for lesson files in two places:
lesson-files
in the directory where Solfege has been installed.
lessonfiles
in your home directory. FIXME describe how to find it on MS Windows.
If you create your own lesson files, you should save them in
$HOME/lessonfiles/
. If you save them in lesson-files/
they might get accidentally deleted when you upgrade
the program.
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 one header block and zero 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. FIXME Raise exception if there is more than one header block in a file?
Definitions to put in the header block:
module = STRING
idbyname
, melodicinterval
, chord
etc. (Added in Solfege 2.9.0. Replaces the content
variable.)
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
lesson_heading
random_transpose = [key|semitones|accidentals], INTEGER, INTEGER | no | yes
yes
. (The default value changed from no
to yes
in Solfege 3.0)
random_transpose = no
random_transpose = yes
random_transpose = accidentals, INTEGER, INTEGER
key
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, INTEGER2
INTEGER1
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, INTEGER2
INTEGER1
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.
enable_right_click = yes | no
yes
. Set to no
for lesson files where it does not make sense to right click buttons. This variable is recognised by the modules idbyname
, chordvoicing
and chord
.
disable_unused_intervals = yes | no
harmonicinterval
and melodicinterval
modules. Default value: yes
. Added as a header variable for Solfege 3.0. It was only available as a url parameter in earlier versions of the program.
melodicinterval
header variablesnumber_of_intervals = INTEGER
idbyname
header variableslabelformat = normal | progression
normal
. 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 modules except id-by-name
have_repeat_slowly_button = yes | no
yes
if you want the exercise to have a "Repeat slowly" button. Works for idbyname
and is ignored by the other modules.
have_repeat_arpeggio_button = yes | no
yes
if you want the exercise to have a "Repeat arpeggio" button. Works for singanswer
and is ignored by the other modules.
have_music_displayer = yes | no
yes
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 idbyname
and is ignored by the other exercises.
filldir = horiz | vertic
horiz
. Works for idbyname
and is ignored by the other modules.
fillnum = INTEGER
1
. Works for idbyname
and is ignored by the other modules.
at_question_start
= show
| play
| play, show
rhythm
header variablesrhythm_elements
rhythm_element_nn
variables used in links.
countin_perc = INTEGER
rhythm_perc = INTEGER
countin_perc
, but setting the instrument used for the question.
count_in = INTEGER
bpm = INTEGER
num_beats = INTEGER
compareinterval
header variablesfirst_interval_type = harmonic | melodic
last_interval_type = harmonic | melodic
first_interval_up
first_interval_down
last_interval_up
last_interval_down
last_interval_down = 1, 2, 3, 4
name = "some short name"
idbyname
and chord
exercise need a 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 / INTEGER
instrument = STRING, INTEGER
instrument = STRING, INTEGER, STRING, INTEGER, STRING, INTEGER
instrument = "cello", 100
soundcard/__init__.py
. If you don't enter a complete name, solfege will try to find a matching instrument name. The integer is the velocity of the tones, it should be in the range 0-127. For lesson files where it makes sense, it is possible to specify three set of instruments. The following example will play bass for the lowest tone, piano in the middle and clarinet on the top tone:
instrument = "bass", 100, "acoustic grand", 100, "clarinet", 100
idbyname
exercise modulevmusic
cuemusic
chord
modulechord
module, two more variables can used:
inversion
toptone
dictation
moduleBy 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
(Use only one if these variables in a question. Using both are undefined.)
singchord
moduleQuestions 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.
rvoice
rvoice
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 iconv
program:
iconv -f YOUR_ENCODING -t utf8 your.file
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.
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 paragraphs from the old docs.