Lesson files

In GNU Solfege, each exercise is created by a lesson file interpreted by one of the exercise modules.

If you create your own lesson files, you should save them in a directory named lessonfiles in your home directory. On MS Windows the directory is probably C:\Documents and Settings\yourusername. To be sure, you can search for the file .solfegerc. The directory lessonfiles should be created in the same directory as .solfegerc. Then you should add your lesson file to the Practise menu. You do this with the learning tree editor available on the Edit menu.

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

File encoding

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.

Comments

Everything after # on a line is ignored. Example:

# This line is ignored. The next line is not.
question { bla bla }

Types

Strings

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 la section intitulée « File encoding ». You can change the encoding of a file using the iconv program:

iconv -f YOUR_ENCODING -t utf8 your.file

Tempo

The tempo of music is entered as bpm/beatlen. The following example will set the tempo to 120 beats per minute, each beat being a quarter note.

tempo = 120/4

Global variables

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")
}

Lesson file contents

A lesson file consist of one header block and zero or more question blocks:

header {
 ASSIGNMENT
 ASSIGNMENT
 ...
}
question {
 ASSIGNMENT
 ...
}

Header block

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

random_transpose = no

No transposition will be done.

random_transpose = yes

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.

random_transpose = accidentals, INTEGER1, INTEGER2

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.

random_transpose = key, INTEGER1, INTEGER2

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.

random_transpose = semitones, INTEGER1, INTEGER2

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 New. By default, Solfege will play the music when the user clicks New, and only display the music when the question is answered correctly and the 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 Play music button. When the user clicks New the music will be displayed in the music displayer, but no music is played. Click Play music to hear the music.

at_question_start = play

The exercise will get a Display music button. When the user clicks New the music is played. Click Display music to see the music.

at_question_start = show, play

When the user clicks New the music is both played and displayed.

Modules: idbyname, elembuilder and rhythmtapping2.

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:c4 , 1:c8 c8 , 2:c16 c16 c16 c16 , 3:c8 c16 c16 , 4:c16 c16 c8 , 5:c16 c8 c16 , 6:c8. c16 , 7:c16 c8. , 8:r4 , 9:r8c8 , 10:r8 c16 c16 , 11:r16 c16 c8 , 12:r16c8c16 , 13:r16 c16 c16 c16 , 14:r8 r16 c16 , 15:r16 c8. , 16:c12 c12 c12 , 17:r12 c12 c12 , 18:c12 r12 c12 , 19:c12 c12 r12 , 20:r12 r12 c12 , 21:r12 c12 r12 , 22:c4. , 23:c4 c8 , 24:c8 c4 , 25:c8 c8 c8 , 26:c4 c16 c16 , 27:c16 c16 c4 , 28:c8 c8 c16 c16 , 29:c8 c16 c16 c8 , 30:c16 c16 c8 c8 , 31:c8 c16 c16 c16 c16 , 32:c16 c16 c8 c16 c16 , 33:c16 c16 c16 c16 c8 , 34:c16 c16 c16 c16 c16 c16

Modules: rhythm and rhythmtapping2

Variables that has been obsoleted

number_of_intervals = INTEGER

Made obsolete in Solfege 3.1.5. Solfege will find this number automatically now, so this variable is ignored.

Question block

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 la section intitulée « 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 la section intitulée « 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

music objects

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 la section intitulée « 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")
cmdline

Run an external program. Example:

cmdline("./bin/csound-play-harmonic-interval.sh 220.000000 320.100000")

Functions

_

_ 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.

Operators

Operators can only be used on strings. + is used for joining strings, and % is similar to what you find in python, but it is very limited. It only know about %s. One example:

"\staff\relative c'{%s}" % "c d e"

evaluates to

\staff\relative c'{c d e}