Lessonfiles

On this page...

# Fichiers leçons

Certains exercices de GNU Solfege utilisent des fichiers de données qui contiennent des questions. Ces fichiers de données sont appelés 'fichiers leçons'. Les exercices des fichiers leçons peuvent être aisément augmentés si les questions fournies avec le programme ne satisfont pas vos besoins. La liste suivante indique les exercices qui utilisent les fichiers leçons, et vous indique également le nom que vous devez utiliser pour vous y référer lorsque vous écrivez des fichiers leçons: Il faut changer l'appellation de la variable "content" si nous déplaçons cette liste ailleurs. chanter la réponse (singanswer), accords (chord), accords complexes (chord-voicing), reconnaître (id-by-name), dictée de notes (dictation), chanter un accord (sing-chord) et dictée d'accords (harmonic-progression-dictation).

Si vous voulez écrire des fichiers leçons, mon conseil est d'étudier les fichiers exemples dans `example-lesson-files/` ainsi que les fichiers de `lesson-files/`. Utilisez ce document et la spécification du format musical comme références. Vous pouvez sauvegarder vos fichiers leçons privés dans `$HOME/lessonfiles/`. Si vous les sauvegardez dans `lesson-files/` ils peuvent être détruits accidentellement quand vous installerez une version plus récente du programme. Pour vous entraîner avec vos fichiers, il vous faut les sélectionner dans la fenêtre de dialogue "Sélectionner un fichier de leçons" dans la collection de leçons "utilisateur". Si vous trouvez difficile d'écrire un fichier leçon en utiklisant cette documentation, vous pouvez décharger votre frustration sur la liste de diffusion solfege-devel@lists.sf.net ou sur le wiki à www.solfege.org/wiki.

## Codage des fichiers

Depuis la version 2.0, Solfege s'attend par défaut à ce que le contenu d'un fichier leçon soit encodé en UTF-8. gedit est un petit éditeur sympa qui vous permet d'éditer des fichiers unicodes.

Si vous n'aimez pas unicode, vous pouvez indiquer à Solfege que le fichier est encodé différemment en insérant une ligne de commentaire spéciale à la première ligne du fichier. L'exemple suivant définit le jeu de caractères ISO 8859-1, un jeu de caractères couramment utilisé dans beaucoup de langues ouest européennes:

      # -*- coding: iso-8859-1 -*-

Les russes pourront souhaiter utiliser koi8-r:

      # -*- coding: koi8-r -*-

Le programme utilise les librairies python pour convertir en unicode, donc il devrait comprendre pratiquement tous les encodages auxquels vous pouvez penser. Si vous voyez que certains caractères manquent, par exemple lorsque les noms de questions sont affichés sur des boutons, c'est probablement que vous avez fait quelque chose d'incorrect dans l'encodage.

## Contenu des fichiers leçons

Un fichier leçon consiste en un bloc d'entête (header) suivi d'un ou plusieurs blocs de questions:

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

## Bloc d'entête

Le bloc d'entête peut être placé n'importe où dans le fichier, mais par convention il devrait être le premier bloc du fichier. Si plus d'un bloc d'entête est trouvé, par exemple lorsque la fonction `include` est utilisée, seul le premier bloc d'entête sera pris en compte, les autres étant ignorés.

Définitions à insérer dans le bloc d'entête:

`version = STRING`
  Indique la version la plus ancienne de solfege dont le bon fonctionnement avec le fichier leçon est connu. Par exemple `version = "1.1.1"` Cette variable n'est pas obligatoire, mais doit être utilisée parce qu'elle pourra aider (mais pas garantir) à éviter des problèmes si le format des fichiers leçons est modifié dans l'avenir.
`title = STRING`
  Courte description d'une seule ligne. Vous devez l'inclure dans chaque fichier leçon.
`description = STRING`
  Optionnel, description longue qui peut contenir des marques html tags. A inclure si vous devez décrire comment le fichier leçon doit être utilisé. La decription est lue lors de l'utilisation de Solfège sur la page "configuration" d'un exercice lorsque l'utilisateur clique sur le bouton "Détails".
`content = LIST`
  Une liste de tous les exercices qui peuvent utiliser ce fichier leçon. Cette variable est obligatoire. Les valeurs possibles sont les noms des exercices utilisant des fichiers leçons, comme documenté au début de cette aide. certains fichiers leçons peuvent être utiles pour plus d'un exercice. Par exemple, un fichier avec des accords peut également être utilisé dan l'exercice "reconnaître", et doit comporter `content = chord, id-by-name`
`random_transpose = [key|semitones|accidentals], INTEGER, INTEGER | no | yes`
  Dans certains exercices, le programme peut transposer la musique pour produire des variations. La variable est ignorée dans les exercices qui ne permettent pas la transposition.
  `random_transpose = no`
    C'est la valeur par défaut. Acune transposition ne sera effectuée.
  `random_transpose = yes`
    L'exercice effectuera des transpositions aléatoires. Le type de transposition dépend de l'exercice mais vous obtiendrez un bon résultat avec cette option.
  `random_transpose = accidentals, INTEGER, INTEGER`
    Pour que ce mode de transposition fonctiomme correctement, la musique du fichier leçon doit être en tonalité de Do majeur ou de La mineur ou la question doit comporter une variable `key` comme ceci :

      question {
        name = "le nom"
        key = "d \major"
        music = music("\key d \major d' e fis")
      }

    Ce mode transpose aléatoirement la musique. Faites attention, le nombre de bémols ou de dièses est dans l'intervalle défini par `INTEGER, INTEGER`. Pour comprendre comment ça marche, imaginez que les bémols sont des nombres négatifs et les dièses des nombres positifs. Le code :

      random_transpose = accidentals, -2, 3

    produira des questions avec 1 ou 2 bémols, sans altération ou avec 1, 2 ou 3 dièses. Le code :

      random_transpose = accidentals, 2, 3

    produira des questions avec 2 ou 3 dièses.
  `random_transpose = key, INTEGER1, INTEGER2`
    Transpose la musique `INTEGER1` crans plus bas ou `INTEGER2` crans plus haut modulo cinq. (Et de ma propre définition, plus haut égale plus de dièses et plus bas plus de bémols... :-) ) C'est la vraie transposition où à la fois la tonalité et les notes sont transposées.
  `random_transpose = semitones, INTEGER1, INTEGER2`
    Transpose la musique d'au plus `INTEGER1` crans plus bas ou `INTEGER2` crans plus haut. C'est la vraie transposition où à la fois la tonalité et les notes sont transposées. Vous obtiendrez vite de la musique dans des tonalités avec BEAUCOUP d'altérations. Le code

      random_transpose = semitones, -2, 6

    transposera les questions de pas plus de 2 demi tons vers le bas ni plus de 6 demi tons vers le haut. C'est pareil que l'ancienne syntaxe `random_transpose = INTEGER, INTEGER`.
`labelformat = normal | progression`
  La valeur par défaut est `normal`. Définissez la à `progression` pour les fichiers leçons où le nom des quetions est une progression harmonique, écrite dans un format non documenté, mais pas difficile. Regardez un fichier leçon existant pour voir comment ça marche. Cette variable est ignorée dans tous les exercices sauf "reconnaître"

FIXME

`questions_selectable = yes | no`
  Permet à l'utilisateur de sélectionner quelles sont les questions du fichier leçon à poser. Fonctionne pour reconnaître et est ignoré par les autres exercices.
`have_repeat_slowly_button = yes | no`
  Définir à `yes` si vous voulez que l'exercice ait un bouton "Répéter lentement". Fonctionne pour reconnaître et est ignoré par les autres exercices.
`have_repeat_arpeggio = yes | no`
  Définir à `yes` si vous voulez que l'exercice ait un bouton "Répéter l'arpège". Fonctionne pour chanter la réponse et est ignoré par les autres exercices.
`have_music_displayer = yes | no`
  Définir à `yes` si vous voulez que la question puisse afficher la musique. Le programme affiche la réponse lorsque l'utilisateur abandonne ou donne la bonne réponse. Fonctionne pour reconnaître et est ignoré par les autres exercices.
`enable_right_click = yes | no`
  Valeur par défaut : `yes`. Définir à `no` dans les fichiers leçons pour lesquels le click droit sur les boutons n'a pas de sens. Cette variable est reconnue par les exercices reconnaître, chanter l'accord and accords.
`filldir = horiz | vertic`
  Indique la direction dans laquelle les boutons sont écrits. La valeur par défaut est `horiz`. Fonctionne pour reconnaître et est ignorée par les autres exercices.
`fillnum = INTEGER`
  Indique le nombre de boutons dans chaque ligne ou colonne. La valeur par défaut est `1`. Fonctionne pour reconnaître et est ignoré par les autres exercices.

## Bloc de question

`name = "un nom court"`
  Les questions écrites pour les exercices reconnaître et accords nécessitent un nom.

<!-- FIXME UGH what to write about shortcut... -->

`music = music(MUSICSTRING, MUSICFORMAT)"`
  Pour la plupart des fichiers leçons, la musique représentant la question est assignée à la variable `music`. Notez qu'il y a un raccourci. Au lieu de :

      question {
       name = "Lisa gikk til skolen"
       music = music(...)"
      }

  vous pouvez écrire :

      question {
       name = "Lisa gikk til skolen"
       music(...)
      }

  Il y a une section spécifique pour documenter l'objet @music@@.
`tempo = INTEGER / INTEGER`
  pulsations par minute / durée de la pulsation en fractions de ronde, par exemple 120/4.
`instrument = STRING, INTEGER`
`instrument = STRING, INTEGER, STRING, INTEGER, STRING, INTEGER`
  Exemple:

      instrument = "cello", 100

  Le nom d'instrument doit être l'un de ceux définis dans le fichier soundcard/__init__.py. Si vous n'entrez pas le nom complet, solfege essaiera de trouver un nom d'instrument correspondant. L'entier est le volume de la note, il doit être dans l'intervalle 0-127. Pour les fichiers leçons où ça a un sens, il est possible de spécifier trois instruments différents. L'exemple suivant utilisera l'instrument "bass" pour la note la plus basse, "piano" pour les notes du milieu et "clarinet" pour la note la plus haute :

      instrument = "bass", 100, "acoustic grand", 100, "clarinet", 100

  Solfege essaiera de trouver les instruments midi à utiliser dans cet ordre :
  * dans le bloc de question
  * dans les variables globales du fichier leçon
  * à défaut, l'instrument sélectionné dans la fenêtre des préferences

### Définitions du bloc de question pour l'exercice accords

<!-- UGH FIXME complete this --> Dans les fichiers leçons utilisables avec l'exercice `chord` (accords), deux variables supplémentaires peuvent être utilisées:

`inversion`
  0 = sans renversement, 1 = premier renversement, etc.
`toptone`
  1, 3, 5, 7

### Définitions du bloc de question pour l'exercice dictée

Par défaut, l'exercice dictée montre la première cononne de musique, et l'utilisateur doit écrire le reste. Mais si la première colonne n'est pas suffisante, par exemple si il y a seulement des silences sur le premier temps, ces deux variables peuvent indiquer au programme combien de musique il doit afficher :

`clue_end = nn/dd`
  `clue_end=1/4` affiche toute la musique de la première noire (blanche=2, croche=8).

UGH FIXME rewrite para

`clue_music = MUSIC`
  Affiche exactement la musique que vous voulez. Si par exemple vous voulez tout afficher la portée du haut et juste une note pour celle du bas.

(Utilisez seulement l'une de ces variables dans une même question. Utiliser nes deux n'est pas défini.)

### Définitions du bloc de question pour l'exercice chanter l'accord exercise

Les questions pour cet exercice doivent comporter la variable `key` si la tonalité est différente de do major (or la minor). Par exemple :

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

## Objets `music`

Synopsis: `music(MUSICCODE, MUSICTYPE=normal)`. La valeur par défaut pour `MUSICTYPE` est `normal`, donc il n'est nécessaire de la spécifier que pour les autres types de musique. Types de musique disponibles :

`normal`
  Il s'agit de musique respectant complètement la spécification du format musical. Cela signifie que vous devez entrer le code complet avec une commande `\staff`. Par exemple:

      variable = music("\staff\relative c' { c' d' }")

`chord` (accord)
  Entrez les notes de la plus basse à la plus haute, comme ceci :

      variable = music("c' e' g'", chord)

  La fonction raccourci `chord` est définie. Appeler

chord("c e g") est la même chose que

      music("c e g", chord)

`satb`
  Utilisez ce format pour entrer de la musique où le programme doit savoir quelle voix (dans un choeur) va chanter les différentes notes. Prenez ceci, par exemple :

      variable = music("c''|e'|g|c")

  La note `c''` sera chantée par la soprano, `e'` par l'alto, etc. La fonction raccourci `satb` est définie.
`voice`
  Ce format évite un peu de frappe si vous voulez entrer une mélodie.

      variable = music("c'4 c' g' g' | a' a' g'2", voice)

  est identique à

      variable = music("\staff{ c'4 c' g' g' | a' a' g'2", normal)

  La fonction raccourci `voice` est définie.
`rvoice`
  `rvoice` est similaire à `voice` sauf que la musique est en mode `\relative`, par rapport à la première note. La musique :

      variable = music("c'4 c g' g | a a g2", rvoice)

  sera interprétée comme

      \staff\relative c'{ c4 c g' g' | a a g2 }

  et produira la même musique que dans l'exemple @voice`du dessus. La fonction raccourci` rvoice@@ est définie.
`wavfile`
  MUSICDATA est le nom d'un fichier `.wav`. Le chemin du fichier est relatif au répertoire où sont stockés les fichiers leçons. Par exemple:

      variable = music("share/fifth-small-220.00.wav", wavfile)

  La fonction raccourci `wavfile` est définie.
`cmdline`
  MUSICDATA est une ligne de commande que vous voulez exécuter. Par exemple :

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

  La fonction raccourci `cmdline` est définie.

## Variables globales

Les variables globales peuvent vous éviter un peu de frappe.

      s = "\score\relative c'{ %s }

      question {
       # au lieu de music = music("\score\relative c'{ c d e f g2 g2 }") :
       music = music(s % "c d e f g2 g")
      }

Egalement, les deux variables `tempo` et `instrument` peuvent être utiles pour définir au début les valeurs par défaut pour tout le fichier. Vour pourrez toujours les modifier pour une question particulière en mettant une autre définition dans le bloc de question.

## Commentaires

Tout ce qui est sur une ligne après # est ignoré

## Grammaire

Avis: Je ne connais aucune des façons standard de définir la grammaire, comme BNF. Donc c'est juste un essai de description du format de fichier pour que les gens puissent commencer à écrire des fichiers leçons.

Les fichiers leçons consistent en définitions de variables et en blocs contenant des définitions de variables.

### Fonctions

`_`
  prend une chaîne de caractères comme seul argument. A utiliser si vous voulez que Solfege traduise la chaîne pour vous. Pa exemple :

      description = _("This is a short description")

`include`
  inclut un autre fichier dans celui ci. Pa exemple:

      include("singchord-1")

### Types

`string`
  ce qui est entre les guillemets `"`, comme ceci: `"c'est une chaîne"`. Utilisez des triples guillemetspour les chaînes qui contiennent des retours à la ligne:

      description = """<h1>Description longue <h1> Ce fichier leçon nécessite beaucoup de description. bla bla bla"""

  Si la chaîne doit contenir le caractère `"`, vous devez également utiliser des triples guillemets :

      description = """Essayez <a href="solfege:practise/melodic-interval"> ceci </a>
      pour un exercice d'intervalle plus simple."""]]>

NB: Toutes les chaînes doivent être au format unicode. Si vous obtenez des messages d'erreur comme celui ci :

      In line 21 of input: does not recognise this string '<' as a valid token.'
      (line 20): question {
      (line 21): question {
      (line 22):   name = _("Ionia�)]]>

alors vérifiez l'encodage de votre fichier. Voir la section sur l'encodage des fichiers. Vous pouvez changer l'encodage d'un fichier en utilisant le programme <command>iconv</command> :

      iconv -f YOUR_ENCODING -t utf8 votre.fichier

`integer`
  est un nombre entier...
`tempotype (manquant d'un meilleur nom)`
  est entré en `bpm/beatlen`. Par exemple :

      tempo = 120/4

indique un tempo de 120 pulsations par minute, chaque pulsation étant une noire.

### Opérateurs

Les opérateurs peuvent seulement être utilisés sur les chaînes de caractères

`+`
  est utilisé pour concaténer des chaînes
`%`
  est similaire à ce qu'on trouve dans python, mais est très limité. Est limité à `%s`. Par exemple:

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

donne

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

FIXME see if we should add the outdated last paragraphis