In GNU Solfege, each exercise is created by a lesson file interpreted by one of the exercise modules.
Exercise modules
harmonicintervals
Train harmonic intervals.
melodicintervals
Train one or more melodic intervals.
singinterval
This is an exercise where the program display an interval and play the first tone. Then the user should sing the interval, and then click a button to hear the correct answer. There is no microphone support yet.
idbyname
This is a very generic exercise. In its most basic form, the program will play some sound, and you have to select among several buttons that in some way represents the music.
chord
The 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
A two-step exercise. First you should identify the chord. Then you should stack the tones in the chord in the correct order.
compareintervals
Solfege plays two intervals, and you should say which one is largest.
rhythm
A simple rhythm exercise. Solfege will randomly generate rhythm patterns that the user should recreate by clicking on buttons.
dictation
harmonicprogressiondictation
idtone
identifybpm
twelvetone
singchord
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.
Everything after # on a line is ignored. Example:
# This line is ignored. The next line is not. question { bla bla }
Strings are quoted with the "
character. Example:
"this is a string"
Use tripple quotes for strings that contain line breaks, or
if the string itself has to contain the "
character:
description = """<h1>Long desription<h1> This lessonfile need very much descriptions. Qoutes (") are ok here. bla bla bla"""
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 ';lt;' as a valid token.' (line 20): question { (line 21): question { (line 22): name = _("Ionia�)
then you must check the encoding of your file, and maybe you should read the section called “File encoding”. You can change the encoding of a file using the iconv program:
iconv -f YOUR_ENCODING -t utf8 your.file
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") }
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.
Variables shared by many exercise modules
module
Tell what execise module that will run the lesson file. This
variable is requried for all lesson files. (The variable was added in
Solfege 2.9.0 where it replaced the content
variable.). Example:
module = idbyname
lesson_id
Each file need a unique identifier. The identifier can be any string
you like, and if you don't add one, Solfege will add one for you. Solfege
will also offer to create a new lesson_id
if you have
two files with identical lesson_id
. Example:
lesson_id = "5b30c9ae-09f1-40b3-9333-4789638dc851"
version
Tell the version of solfege the lessonfile is known to work with. 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. Example:
version = "3.0.7"
title
Short one-line description that will be used for creating the menu entry for the exercise. You should add this to all lesson files. Example:
title = "Minor and major chords in root position"
lesson_heading
A short heading that will be displayed above the exercise. It should say what the purpose of the exercise is. Some modules provide a default value, others leave the string empty. Example:
lesson_heading = _("Identify the chord")
help
This variable say which help file from the user manual will be displayed when the user presses F1. Example:
help = "idbyname-intonation"
By default, Solfege will display the help file that has the same name as the exercise module being used in the lesson file.
theory
This variable say which help file from the user manual will be displayed when the user presses F3. Pressing F3 should display music theory about the exercise. Don't include this variable if there are no music theory written. Example:
theory = "scales/maj"
random_transpose
In some exercises the program can transpose the music to
create variation. The default value is yes
. (The
default value changed from no
to
yes
in Solfege 3.0.)
Used in modules: chord
,
chordvoicing
, harmonicprogressiondictation
,
idbyname
, singanswer
,
singchord
Possible values
No transposition will be done.
The exercise will do random transposition. What kind of transposition depends on the exercise, but you get a ok result from this. This is the default value.
Transpose the question by random and make sure the key signature of the question does not get more than a certain number of accidentals. In this context, the number of accidentals can be described by an integer value. A negative value denote a number of flats (b), and a positive number denote a number o sharps (#). Zero mean no accidentals. The integers INTEGER1 and INTEGER2 defines a range of allowed number of accidentals.
For this transposition mode to work properly, the music in
the lessonfile has to be in the keys c major or a minor,
or the question must have a key
variable telling the key signature.
Transpose the music INTEGER1 steps down or INTEGER2 steps up the circle of fifth. In this context up is more sharps and down is more flats. This is real transposition where both the key and the notes are transposed.
Transpose the music at most INTEGER1 semitones down or INTEGER2 semitones 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.
enable_right_click = no
By default, Solfege will let the user right-click on buttons to hear
the music they represent without guessing. Set this variable to
no
for lesson files where it does not make sense, for
example in a idbyname
lesson file where many questions
have the same name.
Modules: idbyname
, chordvoicing
and chord
.
disable_unused_intervals
= no
By default, Solfege will make the buttons insensitive for intervals
that are not being asked. Set this variable to no
if you
want all buttons to be sensitive.
Modules: harmonicinterval
and
melodicinterval
.
ask_for_intervals_0
Select which intervals to ask for. 1 for minor second, 2 for major
second, 3 or minor third etc. Use a negative number for descending
intervals. To ask for more that one interval create the variables
ask_for_intervals_1
,
ask_for_intervals_2
etc. In the following example
Solfege will ask for two intervals. The first will be either a minor second
or a major second, both intervals going up. And the second interval will be
either major second or minor third, both intervals going down.
ask_for_intervals_0 = [1, 2] ask_for_intervals_1 = [-2, -3]
Modules: melodicinterval
and
singinterval
.
intervals
This variable tell which intervals should be asked for in exercises
using the harmonicinterval
module. 1 for minor second, 2 for major
second, 3 or minor third etc. Example that will practise thirds:
intervals = [3, 4]
Modules: harmonicinterval
.
test
This variable defines the test for the exercise. In a test,
Solfege will ask all the questions in the lesson file a number
of times.
This variable is always used together with test_requirement
.
In the following example, each question will be asked
3 times:
test = "3x"
Modules: harmonicinterval
,
idbyname
, melodicinterval
and singinterval
.
test_requirement
This variable defines how large percentage of the questions has to be answered correctly to pass the test. Example:
test_requirement = "90%"
Modules: harmonicinterval
,
idbyname
, melodicinterval
and singinterval
.
have_repeat_arpeggio_button
= yes
Set to yes
if you want the exercise to have a
"Repeat arpeggio" button.
Modules: singanswer
.
have_music_displayer
= yes
Set to yes
if you want the question to have a
music displayer.
In the idbyname module, setting this variable will add a music displayer where the program will display the answer when the user gives up or answers the question correctly. You might also want to read about at_question_start.
In the singanswer
module, setting this variable
will add a music displayer where the music will be displayed when
the question is displayed.
Modules: idbyname
,
elembuilder
and
singanswer
.
at_question_start
This variable changes what happens when the user clicks
have_music_displayer
variable is set to
yes
. Setting this variable will also set
have_music_displayer
to yes
.
at_question_start = show
The exercise will get a
button. When the user clicks the music will be displayed in the music displayer, but no music is played. Click to hear the music.at_question_start = play
The exercise will get a
button. When the user clicks the music is played. Click to see the music.at_question_start = show, play
When the user clicks
the music is both played and displayed.Modules: idbyname
, elembuilder
and rhythmtapping2
.
vmusic
This variable holds a representation of the question intended to be
displayed. This can be necessary if the music is a .wav or .mp3 file. It
will be used when the user clicks Show music or when the question is
answered correctly (if we have a musicdisplayer). Added to
idbyname
in Solfege 2.5.1 and to
elembuilder
in 3.9.2.
Modules: idbyname
and elembuilder
.
rhythm_elements
A list of integers (1-34) telling what elementes we should use when creating questions. Example:
rhythm_elements = 0, 1, 2, 3, 4
0: ,
1:
,
2:
,
3:
,
4:
,
5:
,
6:
,
7:
,
8:
,
9:
,
10:
,
11:
,
12:
,
13:
,
14:
,
15:
,
16:
,
17:
,
18:
,
19:
,
20:
,
21:
,
22:
,
23:
,
24:
,
25:
,
26:
,
27:
,
28:
,
29:
,
30:
,
31:
,
32:
,
33:
,
34:
Modules: rhythm
and rhythmtapping2
Variables you can define in the question block
name
Questions written for the idbyname or the chord exercise modules need a name.
music
For most lesson files the music representing the question is assigned to this variable. Note that there is a shortcut. Instead of:
question { name = "Lisa gikk til skolen" music = music(...)" }
you can write:
question { name = "Lisa gikk til skolen" music(...) }
Music objects are documented in the section called “music
objects”.
tempo
Set the tempo for this questions music. The variable is defined "beats per minute" / "notelen per beat". Example:
tempo = 150 / 4
This variable can also be defined globally for the whole lesson file. Do do so you should put it in the beginning of the file, outside any question blocks.
Modules: idbyname
, chord
,
chordvoicing
and
rhythmtapping
.
instrument
By default, Solfege will use the instrument specified on the preferences window when playing questions. This variable let you select a different instrument. Example:
instrument = "cello", 100
The instrument name has to be quoted. The integer is the velocity of the tones, and it should be in the range 0-127. You can see a list of instrument names in the section called “Midi instrument names”. 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
This variable can also be defined globally for the whole lesson file. Do do so you should put it in the beginning of the file, outside any question blocks.
Modules: idbyname
, chord
,
singanswer
and chordvoicing
Each question in your lesson files will define one or more
music
objects.
music
This is music entered completely following the music format FIXME spec. This means you
have to enter complete code with a \staff
command. Example:
variable = music("\staff\relative c' { c' d' }")
chord
Enter the tones from the lowest to the highest tone, like this:
variable = chord("c' e' g'")
satb
This type of music is used by the singchord exercises. It let you say which tones of a chord the different voices in a choir will sing. Take this, for example:
variable = satb("c''|e'|g|c")
The c''
will be sung by the soprano, e'
by the alto, g
by the tenor and
c
by the bass. Please notice that when this music
is played in arpeggio, the tones to be sung by the women, will be played
one octave deeper, of the user is a male. And vice versa if the user
is a female or a child.
voice
This musictype saves some key strokes if you want to enter a melody.
variable = voice("c'4 c' g' g' | a' a' g'2")
is the same as
variable = music("\staff{ c'4 c' g' g' | a' a' g'2")
rvoice
rvoice
is similar to voice
except that the music is in \relative
mode, relative
to the first tone. The following two statements produce the same music:
variable = rvoice("c'4 c g' g | a a g2") \staff\relative c'{ c4 c g' g' | a a g2 }
percussion
This music object provides a simple way to play rhythms with percussion instruments. Each tone represents a percussion instrument as defined in the section called “Percussion instrument names”. In the following example, the tone c is translated to the midi sound Side Stick and d to a Mute triangle.
variable = rhythm("d4 d d d c8 c8 c4")
rhythm
This music object let you write questions that taps rhythms with the
two instruments defined in the preferences window. The tone
c
will play the rhythm representing the question,
and the tone d
can be used if you want to write some
sort of "count-in" before the question starts. Example:
rhythm("d4 d d d c8 c8 c4 c c8 c8")
You should only use two pitches, c
and
d
. Other pitches will print a warning, but will still
work in the current implementation. To play real percussion with many
different instruments you should use the percussion music object.
midifile
Play a midi file. The path given to the file is relative to the directory the lesson file is stored in. Example:
variable = midifile("share/example.mid")
wavfile
Play a .wav
file. The path given to the file
is relative to the directory the lesson file is stored in. Example:
variable = wavfile("share/fifth-small-220.00.wav")
mp3file
Play a MP3 file. Similar to wavfile
.
oggfile
Play an Ogg Vorbis file. Similar to wavfile
.
cmdline
Run an external program. Example:
cmdline("./bin/csound-play-harmonic-interval.sh 220.000000 320.100000")
_
_
takes a string as its only argument. Use this if you want Solfege to translate the string for you. Example:
title = _("Bla bla title")
include
Includes another file. Example:
include("singchord-1")
The lesson header variables will be taken from the including lesson file. Only a variable is only defined in the included lesson file, and not in the including lesson file, then the value will be taken from the included file.