Lesson files
Önceki | Bölüm 4. Extending GNU Solfege | Sonraki

## 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 “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: , 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 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 “`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 “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 “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}

Önceki | Yukarı | Sonraki
Bölüm 4. Extending GNU Solfege | Başlangıç | The `harmonicinterval` module