On this page...

  1. Fichiers leçons
    1. 1.1 Codage des fichiers

    2. 1.2 Contenu des fichiers leçons
    3. 1.3 Bloc d'entête
    4. 1.4 Bloc de question
    5. 1.5 Objets music
    6. 1.6 Variables globales
    7. 1.7 Commentaires
    8. 1.8 Grammaire

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