documentation_fr.md

   1 [TOC]
   2
   3 # Music Sampler
   4
   5 ## Description
   6
   7 Music Sampler est un lecteur de musique qui permet de pré-programmer des
   8 transitions musicales, qui peuvent ensuite être lancées à l'aide d'un simple
   9 appui sur une touche.
  10
  11 ## Pré-requis et installation
  12
  13 (Voir la section suivante pour Windows)
  14
  15 - Il faut avoir ffmpeg d'installé. Pour cela, il faut installer le paquet `libav-tools` (debian) :
  16
  17         sudo apt-get install libav-tools
  18
  19 Si vous utilisez la version compilée de Music Sampler (cf. plus bas pour un lien
  20 de téléchargement), il n'y a rien d'autre à installer.
  21
  22 - Pour utiliser les sources directement, les modules suivants sont requis:
  23
  24 | module      | version minimale | commentaire                                                                   |
  25 | ----------- | ---------------- | ----------------------------------------------------------------------------- |
  26 | Cython      | 0.24             | pour compiler Kivy                                                            |
  27 | Kivy        | 1.9.1            | certaines fonctionnalités nécessitent de compiler/installer avec `USE_SDL2=1` |
  28 | Markdown    | 2.6.6            | pour la documentation uniquement                                              |
  29 | pydub       | 0.16.4           |                                                                               |
  30 | Pygame      | 1.9.2.dev1       | utilisée par Kivy                                                             |
  31 | Pygments    | 2.1.3            | pour la documentation uniquement                                              |
  32 | sounddevice | 0.3.3            |                                                                               |
  33 | transitions | 0.4.1            |                                                                               |
  34 | PyYAML      | 3.11             |                                                                               |
  35
  36 Le projet est également disponible via `pip`:
  37
  38     pip install music_sampler
  39
  40 Le programme utilise les polices `Symbola` et `Ubuntu` (Regular / Bold), qui
  41 doivent être disponibles, et la librairie `portaudio`:
  42
  43     sudo apt-get install ttf-ancient-fonts ttf-ubuntu-font-family portaudio
  44
  45 Pour compiler kivy avec la librairie SDL2, il faut certains paquets installés:
  46
  47     sudo apt-get install libsdl2-dev libsdl2-image-dev libsdl2-mixer-dev libsdl2-ttf-dev
  48
  49 cf [Installation
  50 Kivy](https://kivy.org/docs/installation/installation-linux.html)
  51
  52 ## Installation sous Windows
  53
  54 Le processus suivant a permis d’installer music sampler sous windows:
  55
  56 - [Installer python 3.7.\* (prendre la version 64bit!)](https://www.python.org/downloads/windows)
  57 - Dans une invite de commande (`cmd.exe`), lancer:
  58
  59         pip install music_sampler
  60         pip install docutils pygments pypiwin32 PySDL2 kivy.deps.sdl2 kivy.deps.glew
  61
  62 - [Télécharger ffmpeg (64bit, static)](https://ffmpeg.zeranoe.com/builds/)
  63   et mettre le contenu du dossier `bin` dans le dossier avec les musiques
  64 - [Télécharger la police Ubuntu](https://www.1001fonts.com/ubuntu-font.html)
  65   et installer Ubuntu-R et Ubuntu-B (Regular et Bold) *pour tous les utilisateurs* (clic droit sur la police)
  66 - [Télécharger la police Symbola](https://fontlibrary.org/en/font/symbola)
  67   et l’installer *pour tous les utilisateurs* (clic droit sur la police)
  68 - Écrire un fichier `run.bat` avec:
  69
  70         :::bash
  71         @echo off
  72         music_sampler
  73
  74 - Lancer `run.bat` pour démarrer le programme.
  75
  76 ## Version compilée
  77
  78 Une version compilée peut être créée avec pyinstaller:
  79
  80     :::bash
  81     pyinstaller music_sampler.spec
  82
  83 ## Téléchargements
  84
  85 - Un exemple de configuration ainsi que des musiques associées à l'exemple
  86   peuvent être trouvées sur
  87   [owncloud](https://outils.immae.eu/owncloud/index.php/s/kSrIe15G1AiZ9YF)
  88 - Une version précompilée de `music_sampler` peut également être téléchargée
  89   [dans le même
  90   dossier](https://outils.immae.eu/owncloud/index.php/s/kSrIe15G1AiZ9YF/download?path=%2F&files=music_sampler)
  91   (attention, elle n'est pas toujours forcément à jour, lancer le programme avec
  92   `-V` pour voir la version compilée)
  93
  94 ## Utilisation
  95
  96 Tout le travail consiste à préparer les transitions dans le fichier de
  97 configuration `config.yml`.
  98
  99 Lancer ensuite le programme dans le dossier où se situe le fichier de
 100 configuration (voir plus bas pour une utilisation avancée). Une fenêtre
 101 représentant un clavier apparaît. Le rond orange dans le coin du clavier devient
 102 vert lorsque tout est chargé, ou rouge en cas de problème. Une touche grisée et
 103 barrée représente une touche non-utilisable pour le moment : soit parce que la
 104 musique est en cours de chargement (au lancement du programme, cela peut prendre
 105 un peu de temps sur certaines machines), soit parce qu'il y a une action en
 106 cours.
 107
 108 Un exemple de fichier de configuration est fourni, avec un certain nombre de
 109 touches et de transitions programmées (pour les trois musiques fournies), la
 110 syntaxe du fichier (expliquée plus bas) se comprend aisément en le regardant. De
 111 plus, certaines touches (par exemple 'ÉCHAP' pour tout arrêter) peuvent être
 112 gardées d'une fois sur l'autre.
 113
 114 ### Actions possibles
 115
 116   - Cliquer sur une touche : affiche les actions associées à cette touche (dans
 117     le cadre en bas à gauche).
 118   - Appuyer sur une touche : déclenche les actions associées à cette touche
 119     (affichées également dans le cadre en bas à gauche). Lorsqu'une touche a des
 120     actions en cours, son cadre est noir. Notez qu'une action de type "jouer une
 121     musique" est considérée comme terminée quand ladite musique est lancée. En
 122     cas d'appui répété sur une touche, music_sampler ne relance pas les actions
 123     associées à cette touche si ces actions ne sont pas terminées ; cela pour
 124     éviter les "accidents".
 125   - Ctrl+C ou Ctrl+Q : quitte le programme (possible aussi en cliquant
 126     simplement sur la croix en haut à droite).
 127   - Ctrl+R : recharge le fichier de configuration.
 128
 129 ### Options disponibles au lancement
 130
 131 Toutes les options au lancement sont facultatives ; la plupart du temps lancer
 132 le programme dans le bon dossier suffit. La plupart d'entre elles peuvent être
 133 définies également dans le fichier de config (à part `--config` bien sûr). Les
 134 arguments en ligne de commande ont toujours la priorité.
 135
 136   * `-h, --help` : affiche une liste des options disponibles.
 137   * `-c CONFIG, --config CONFIG` : précise le fichier de configuration à charger
 138     (par défaut, config.yml qui se trouve dans le dossier où est lancé
 139     music_sampler).
 140   * `-p MUSIC_PATH, --music-path MUSIC_PATH` : précise le chemin des musiques
 141     (par défaut, le dossier courant).
 142   * `--no-debug, --debug` : Affiche les informations de déboggage (désactivé par
 143     défaut)
 144   * `-V, --version` : affiche la version courante et quitte (utilisable
 145     uniquement pour la version compilée).
 146   * `-L, --language` : change la langue de l'application. Actuellement: fr, en
 147     (par défaut 'fr')
 148   * `--focus-warning, --no-focus-warning`: Afficher / Ne pas afficher
 149     d'avertissement lorsque l'application perd le focus (activé par défaut).
 150
 151 Les options suivantes sont plutôt réservées à un usage avancé de music_sampler,
 152 ou en cas de problème avec la configuration standard :
 153
 154   * `--no-builtin-mixing, --builtin-mixing` Effectue en interne le mixage des
 155     sons. Par défaut, music_sampler confie le mixage au système : n'activer
 156     cette option que si le système n'y parvient pas.
 157   * `-l LATENCY, --latency LATENCY` : latence. Préciser "low", "high" ou un
 158     nombre de secondes (par défaut, "high")
 159   * `-b BLOCKSIZE, --blocksize BLOCKSIZE` : taille des blocs. Nombre de frames
 160     pour chaque étape du mixeur. 0 (par défaut) signifie que le programme
 161     choisit lui-même le nombre qui lui convient.
 162   * `-f FRAME_RATE, --frame-rate FRAME_RATE` : fréquence d'échantillonnage pour
 163     jouer les musiques. Par défaut : 44100
 164   * `-x CHANNELS, --channels CHANNELS` : nombre de canaux par musique (2 par
 165     défaut, pour une écoute stéréo)
 166   * `-s SAMPLE_WIDTH, --sample-width SAMPLE_WIDTH` : largeur d'échantillonnage
 167     (nombre d'octets pour chaque frame). Par défaut : 2.
 168   * `--device DEVICE` : sélectionne le périphérique de son.
 169   * `--list-devices` : Affiche la liste des périphériques de son disponibles.
 170   * `-- ARGS` : Arguments à passer à la librairie Kivy.
 171
 172 ## Configurer les touches
 173
 174 **ATTENTION : le format du fichier de configuration est susceptible d'évoluer,
 175 sans garantie de rétrocompatibilité.**
 176
 177 Le fichier config.yml utilise la syntaxe yaml. Les catégories et sous-catégories
 178 sont gérées par l'indentation par des espaces (mais PAS par des tabulations !).
 179 le `#` est un symbole de commentaire : tout ce qui suit ce symbole sur une ligne
 180 est ignoré.
 181
 182 En cas d'erreur dans le fichier de configuration, un message d'erreur s'affiche
 183 dans le terminal. Selon la "gravité" de l'erreur, music_sampler se lance en
 184 ignorant les actions erronées (en colorant éventuellement la touche en noir), ou
 185 ne se lance pas du tout.
 186
 187 Le fichier contient plusieurs sections :
 188
 189     :::yaml
 190     config:
 191       ...
 192
 193     aliases:
 194       ...
 195
 196     music_properties:
 197       ...
 198
 199     key_properties:
 200       ...
 201
 202     keys:
 203       ...
 204
 205
 206 ### `config`
 207
 208 La section config permet d'enregistrer les paramètres habituellement donnés en
 209 ligne de commande. Les '-' dans le nom du paramètre long doivent être remplacés
 210 par des '_' (par exemple '--music-path' -> 'music_path'). Pour les switches
 211 (`debug`, `focus_warning`, `builtin_mixing`), utilisez la version sans le 'no-'
 212 et spécifiez `true` / `false` en valeur. Notez que les arguments donnés en ligne
 213 de commande sont toujours prioritaires sur les valeurs du fichier.
 214
 215 ### `music_properties` : propriétés des musiques
 216
 217 Cette section sert à définir des propriétés globales des musiques.
 218
 219 #### Exemples
 220
 221     :::yaml
 222       "music1.mp3":
 223         name: My favorite music
 224         gain: 1.4
 225 La musique "music1.mp3" est désignée par le nom "My favorite music". Elle est
 226 chargée à 140% de son volume normal.
 227
 228     :::yaml
 229       "music2.mp3":
 230         gain: 0.7
 231
 232 La musique "music2.mp3" est chargée à 70% de son volume normal.
 233
 234 #### Liste des options possibles
 235 - `name: My music` La musique sera désignée  (dans les actions, dans le
 236   terminal) comme "My music" au lieu du chemin du fichier. Par exemple le cadre
 237   des actions affichera "starting « My music » at volume 100%". Attention, cela
 238   ne fait pas office d'alias dans le fichier de configuration (voir la section
 239   *aliases*).
 240 - `gain: x` Charge la musique avec un gain de x (multiplicatif). Utiliser la
 241   commande "volume" pour changer ponctuellement le volume (0 à 100%) au cours de
 242   l'écoute.
 243
 244 ### `key_properties` : affichage et propriétés des touches
 245
 246 Cette section sert à décrire l'affichage à l'écran des touches : couleur et
 247 texte. Par défaut, une touche "attribuée" à une ou plusieurs actions s'affiche
 248 en vert.
 249
 250 #### Exemples
 251
 252     :::yaml
 253       'ESC':
 254         description:
 255           -
 256           - STOP !
 257         color: [255, 0, 0]
 258         repeat_delay: 2
 259
 260 La touche échap est de couleur rouge, et le texte "STOP !" est affiché sur la
 261 deuxième ligne. Si on appuie deux fois sur la même touche à moins de deux
 262 secondes d'intervalle, le second appui est ignoré.
 263
 264 #### Liste des options possibles
 265 - `description` : le texte qui s'affiche, à côté du "nom" de la touche. Il faut
 266   mettre un tiret pour une ligne de texte (pas de retour à la ligne
 267   automatique). La première ligne correspond à celle de la lettre associée à la
 268   touche, aussi il vaut mieux souvent la laisser vide, ou ne mettre que très peu
 269   de texte (voir l'exemple ci-dessus). Sur un écran de taille raisonnable, on
 270   peut compter 3 lignes (incluant la première) pour une touche "standard".
 271 - `color: [r, g, b]` : la couleur de la touche. r, g et b sont les proportions
 272   de rouge, vert et bleu, et doivent être des entiers entre 0 et 255.
 273 - `repeat_delay: x` (par défaut : 0) : délai de "sécurité" en cas d'appuis
 274   successifs sur la touche. La touche est désactivée (grisée et barrée) pendant
 275   toute la durée des actions puis le délai de x secondes.
 276 - `actions: liste`: Liste des actions à effectuer en appuyant sur la touche.
 277
 278 ### Propriété `common`
 279
 280 Une entrée spéciale `common` s'applique à toutes les touches. Les propriétés
 281 définies dans cette entrée peuvent être modifiées individuellement.
 282
 283 ### `keys` : actions sur les touches
 284
 285 Cette section sert à décrire, pour chaque touche, la liste des actions
 286 successives. Notez que la plupart des actions (hors `wait` et quelques cas
 287 particuliers, voir plus bas) sont quasi-instantanées.
 288
 289 *Cette section est obsolète et remplacée par une clé `actions` contenant une
 290 liste dans la section `key_properties` pour chaque touche.*
 291
 292 #### Exemples
 293
 294     :::yaml
 295     'a':
 296       - play:
 297           file: "music1.mp3"
 298           volume: 70
 299           start_at: 10
 300       - wait:
 301           duration: 5
 302       - stop:
 303           file: "music1.mp3"
 304           fade_out: 2
 305
 306 Lance la musique "music1.mp3" à 70% de son volume max, à 10 secondes du début,
 307 puis au bout de 5 secondes coupe la musique avec un fondu de 2 secondes.
 308
 309     :::yaml
 310     'b':
 311       - stop:
 312           file: "music1.mp3"
 313           fade_out: 5
 314           wait: false
 315       - play:
 316           file: "music2.mp3"
 317           fade_in: 5
 318
 319 Effectue un fondu enchaîné de 5 secondes entre "music1.mp3" et "music2.mp3"
 320
 321     :::yaml
 322     'c':
 323       - stop:
 324           file: "music1.mp3"
 325           fade_out: 5
 326           wait: true
 327       - wait:
 328           duration: 2
 329       - play:
 330           file: "music2.mp3"
 331       - seek:
 332           file: "music2.mp3"
 333           delta: false
 334           value: 60
 335 Coupe la musique "music1.mp3" avec un fondu de 5 secondes, attend la fin du
 336 fondu, puis attend encore deux secondes et lance la musique "music2.mp3", au
 337 temps d'une minute.
 338
 339     :::yaml
 340     'd':
 341       - volume:
 342           file: "music1.mp3"
 343           value: 50
 344       - play:
 345           file: "noise.mp3"
 346           loop: 1
 347       - wait:
 348           file: "noise.mp3"
 349       - volume:
 350           file: "music1.mp3"
 351           value: 100
 352
 353 Baisse le volume de "music1.mp3" pendant que le son "noise.mp3" est joué par
 354 dessus (deux fois). Le volume revient à la normale une fois que les deux écoutes
 355 du son "noise" sont terminées.
 356
 357     :::yaml
 358     'e':
 359       - pause:
 360           file: "music1.mp3"
 361       - wait:
 362           duration: 10
 363       - unpause:
 364           file: "music1.mp3"
 365       - seek:
 366           file: "music1.mp3"
 367           delta: true
 368           value: 5
 369
 370 Met en pause la musique "music1.mp3" pour 10 secondes et la relance après, en
 371 avançant de 5 secondes dans la musique.
 372
 373 #### Liste des actions possibles:
 374 - `play` : joue une musique. music_sampler ne joue qu'une musique à la fois : si
 375   la musique demandée est déjà en train d'être jouée, elle n'est pas relancée ou
 376   jouée "par dessus". Paramètres :
 377     * `file: "music.mp3"` précise la musique jouée (chemin relatif).
 378     * `fade_in: x` (facultatif) lance la musique avec un fondu au départ de x
 379       secondes.
 380     * `volume: x` (facultatif, défaut : 100) la musique doit être jouée à x% de
 381       son volume max.
 382     * `loop: x` (facultatif, défaut : 0) la musique doit être répétée x fois.
 383       Indiquer -1 pour la répéter indéfiniment. Attention, x est le nombre de
 384       répétitions, donc pour lire trois fois la musique, mettre `loop: 2`.
 385     * `start_at: x` (facultatif, défaut : 0) la musique démarre à x secondes du
 386       début.
 387     * `restart_if_running: true/false` (facultatif, défaut : false) la musique
 388       est éventuellement stoppée et redémarrée si nécessaire
 389 - `stop` : arrête une musique donnée. Paramètres :
 390     * `file: "music.mp3"` (facultatif) précise la musique à stopper. Si aucune
 391       musique n'est précisée, le `stop` s'applique à toutes les musiques.
 392     * `fade_out: x` (facultatif) stoppe la musique avec un fondu de x secondes.
 393     * `wait: true/false` (facultatif, par défaut : false) dans le cas d'un
 394       fondu, attendre la durée du fondu pour faire les actions suivantes. Si la
 395       musique s'arrêtait naturellement avant la fin du fondu, l'attente se
 396       termine lorsque la musique se termine naturellement. Lorsque plusieurs
 397       musiques sont stoppées en fondu, le `wait` n'attend que la dernière
 398       musique de la playlist (qui peut se terminer naturellement avant les
 399       autres).
 400     * `set_wait_id: name` (facultatif, inutile lorsque `wait` est à false) donne
 401       l'identifiant `name` à l'attente de fin du fondu (voir `interrupt_wait`).
 402       L'identifiant peut être n'importe quelle chaîne de caractère.
 403 - `volume` : change le volume d'une musique donnée. Paramètres :
 404     * `file: "music.mp3"` (facultatif) précise la musique. Si aucune musique
 405       n'est précisée, la modification s'applique au volume global.
 406     * `delta: true/false` (facultatif, par défaut : false) le volume doit il
 407       être précisé en absolu (false), ou en relatif (true), voir plus bas.
 408     * `value: x` Si delta est à false, met le volume à x% du volume max (x doit
 409       être entre 0 et 100). Ce facteur est appliqué à la musique déjà chargée en
 410       mémoire (voir section "propriétés"), donc le 100% fait référence au volume
 411       de chargement.
 412 Si delta est à true, applique un modificateur de x% au volume (x doit être un
 413 entier signé). Notez qu'une action "+10%" relative ne correspond pas à un
 414 pourcentage du volume actuel, mais du volume "de référence" 100%. Ainsi,
 415 effectuer +10% et -10% en relatif revient bien à 100%.
 416     * `fade: x` (facultatif) le changement de volume est appliqué en fondu sur x
 417       secondes. Il n'y a pas d'attente de la fin du fondu pour lancer les
 418       actions suivantes : au besoin, rajouter un `wait` à la main.
 419 - `pause` : met en pause une musique. Paramètres :
 420     * `file: "music.mp3"` (facultatif) précise la musique à mettre en pause. Si
 421       non précisé, s'applique à toutes les musiques.
 422 - `unpause` : relance une musique mise en pause (là où elle en était).
 423   Paramètres :
 424     * `file: "music.mp3"` (facultatif) précise la musique à relancer. Si non
 425       précisé, s'applique à toutes les musiques.
 426 - `wait` : attend un temps donné. Paramètres :
 427     * `file: "music.mp3"` (facultatif) attend la fin de la musique "music.mp3"
 428     * `duration: x` (facultatif) attend x secondes. Si `file` et `duration` sont
 429       précisés, l'attente dure jusqu'à la fin de la musique PUIS la durée donnée
 430       par `duration`.
 431     * `set_wait_id: name` (facultatif) donne l'identifiant `name` à l'attente
 432       (voir `interrupt_wait`). L'identifiant peut être n'importe quelle chaîne
 433       de caractère.
 434 Notez une fois encore que `wait` est quasiment la seule action qui attend
 435 d'avoir terminé pour lancer la commande suivante, toutes les autres sont lancées
 436 successivement mais sans attendre (donc presque simultanément) : ne pas hésiter
 437 à rajouter des commandes d'attente partout où c'est nécessaire.
 438 - `seek` : permet d'aller à un endroit précis dans une musique. Paramètres :
 439     * `file: "music.mp3"` (facultatif) précise la musique. Si aucune musique
 440       n'est précisée, l'action s'applique à toutes les musiques.
 441     * `delta: true/false` (facultatif, défaut : false) Si `delta` est true, le
 442       temps est relatif. Si delta est false, le temps est absolu, voir plus bas.
 443     * `value: x` Si `delta` est true, alors fait avancer de x secondes dans la
 444       musique (reculer si x est négatif). Si delta est false, alors la lecture
 445       se place à x secondes à partir du début. Si la musique est en train de
 446       faire un fondu (au départ, ou changement de volume), le fondu se "termine
 447       automatiquement" : et la musique est immédiatement au volume final voulu.
 448       Si la musique est en train de se terminer en fondu, le "seek" est ignoré
 449       (un fondu de fin considère la musique comme déjà terminée). En cas de
 450       `loop`, si le déplacement est relatif la musique peut éventuellement
 451       passer à la répétition suivante / précédente; sinon, le déplacement se
 452       fait dans la répétition courante.
 453 - `stop_all_actions:` Interrompt toutes les actions en cours et à faire. Notez
 454   qu'une musique lancée (y compris avec une option `loop`) est considérée comme
 455   une action "déjà terminée", et ne sera donc pas interrompue (utiliser `stop`
 456   sans arguments pour stopper toutes les musiques en écoute). Paramètre :
 457     * `other_only: true/false` (facultatif, défaut : false) : si `other_only`
 458       est true, la commande interrompt uniquement les actions des *autres*
 459       touches. Sinon, cette commande interrompt également les actions de la
 460       touche actuelle ; dans ce cas il est inutile de mettre des actions à la
 461       suite de celle-ci puisqu'elles seront systématiquement interrompues.
 462 - `interrupt_wait`: interrompt l'attente (de `wait` ou fin d'un fondu avec
 463   attente) et passe directement à l'action suivante. Paramètre :
 464     * `wait_id: name` (facultatif) précise l'identifiant du `wait` à stopper
 465       (défini par `set_wait_id`, voir les actions `wait` et `stop`). Si absent,
 466       interrompt toutes les attentes.
 467 - `pause_wait`: met une attente en pause (uniquement pour une attente ayant une
 468   durée définie). La touche qui attend cet événement ne continuera pas tant que
 469   l'attente n'est pas reprise. Paramètres :
 470     * `wait_id: name` (facultatif) précise l'identifiant du `wait` à mettre en
 471       pause. Si absent, met en pause toutes les attentes compatibles.
 472 - `unpause_wait`: reprend une attente en pause (uniquement pour une attente
 473   ayant une durée définie). Le compte à rebours reprendra pour la touche
 474   correspondante en train d'attendre. Paramètres:
 475     * `wait_id: name` (facultatif) précise l'identifiant du `wait` à reprendre.
 476       Si absent, reprend toutes les attentes compatibles.
 477 - `reset_wait`: réinitialise une attente (uniquement pour une attente ayant une
 478   durée définie). Si l'attente est en pause, le compte à rebours ne recommencera
 479   au début que lorsque l'attente sera reprise. Paramètres:
 480     * `wait_id: name` (facultatif) précise l'identifiant du `wait` à
 481       réinitialiser. Si absent, réinitialise toutes les attentes compatibles.
 482 - `run_command` : lance une commande. Paramètres :
 483     * `command: my_command` : précise la commande à lancer.
 484     * `wait: true/false` (facultatif, défaut : false) : si `wait` est true,
 485       attend que la commande ait fini de s'exécuter.
 486
 487 ### `aliases` : définir des alias
 488
 489 Il est possible de définir des alias pour les différents paramètres. Ces alias
 490 sont internes au fichier de configuration ; pour afficher un "joli" nom d'une
 491 musique, voir plutôt "music_properties".
 492
 493 La syntaxe est la suivante:
 494
 495     :::yaml
 496     aliases:
 497       alias1:
 498         param: value
 499       alias2:
 500         param1: value1
 501         param2: value2
 502
 503 On utilise ensuite, dans le fichier de configuration, `include: alias1` ou
 504 `include: [alias1, alias2]` à la place de `param: value`. Dans le cas de
 505 plusieurs aliases inclus contenant des éléments identiques, seul le dernier est
 506 pris en compte. Dans tous les cas, les alias ne sont *pas* prioritaires par
 507 rapport aux éventuels paramètres définis là où ils sont inclus. Voir les
 508 exemples ci-dessous.
 509
 510 #### Exemples
 511
 512     :::yaml
 513     aliases:
 514       music1:
 515         file: "path/to/my/favourite/music.mp3"
 516
 517     keys:
 518       'a':
 519         play:
 520           include: music1
 521
 522 `music1` est désormais un alias pour `"path/to/my/favourite/music.mp3"`. À
 523 chaque fois qu'on veut écrire `file: "path/to/my/favourite/music.mp3"`, on peut
 524 écrire à la place `include: music1`. Attention, dans la section
 525 "music_properties", les alias ne fonctionnent pas, et il faut écrire le nom du
 526 fichier complet.
 527
 528     :::yaml
 529     aliases:
 530       blue:
 531         color: [0, 0, 255]
 532
 533     keys_properties:
 534       'a':
 535         description:
 536           -
 537           - blue key
 538         include: blue
 539
 540 `blue` est un alias pour la couleur `[0, 0, 255]`. À chaque fois qu'on veut
 541 écrire `color: [0, 0, 255]`, on peut écrire `include: blue` à la place.
 542
 543     :::yaml
 544     aliases:
 545       long_time:
 546         duration: 42
 547
 548     keys:
 549       'b':
 550         wait:
 551           include: long_time
 552         play:
 553           file: "music1.mp3"
 554
 555 `long_time` est un alias pour la durée 42 secondes. Au lieu d'écrire `duration:
 556 42`, on peut écrire `include: long_time`.
 557
 558 ## Problèmes possibles
 559
 560 Sont listés ci-dessous une liste de problèmes rencontrés, avec des solutions
 561 proposées. Si vous en découvrez d'autre, contactez l'auteur pour les ajouter à
 562 la liste.
 563
 564 * Le programme se lance et s'arrête tout de suite.
 565
 566 Il s'agit généralement d'une erreur de syntaxe dans le fichier de config. Dans
 567 ce cas, le terminal doit afficher quelques détails sur l'erreur en question (au
 568 moins la ligne correspondante).
 569
 570 * La musique "grésille" affreusement.
 571
 572 Il peut s'agir d'un problème de latence (avec certains ordinateurs un peu
 573 lents). Essayez de changer la latence (par exemple, 0.1 seconde)
 574
 575 * Impossible de jouer plus d'une musique à la fois.
 576
 577 Le système n'arrive pas à mixer les musiques par lui-même. Vous pouvez essayer
 578 de regarder la liste des périphériques de son (`--list-devices`) puis en
 579 sélectionner un autre si disponible. Vous pouvez aussi essayer le mixeur intégré
 580 à music_sampler, mais les résultats ne sont pas toujours très fluides (ne pas
 581 hésiter à jouer avec les paramètres avancés comme latency et blocksize).
 582
 583 Si votre système utilise PulseAudio, il peut s'agir d'un problème de
 584 configuration du plugin ALSA. Dans ce cas, essayez de mettre la configuration
 585 suivante dans `/etc/asound.conf`, puis redémarrer la machine (solution empirique
 586 qui semble avoir fonctionné, sans garantie !):
 587
 588     pcm.!default {
 589       type pulse
 590       fallback "sysdefault"
 591       hint {
 592         show on
 593         description "Default ALSA Output (currently PulseAudio Sound Server)"
 594       }
 595     }
 596
 597     ctl.!default {
 598       type pulse
 599       fallback "sysdefault"
 600     }
 601
 602 * La console affiche une erreur :
 603
 604         Exception in thread Thread-1:
 605         Traceback (most recent call last):
 606           File "threading.py", line 914, in _bootstrap_inner
 607           File "threading.py", line 862, in run
 608           File "kivy/input/providers/mtdev.py", line 219, in _thread_run
 609           File "kivy/lib/mtdev.py", line 131, in __init__
 610         PermissionError: [Errno 13] Permission denied: '/dev/input/event6'
 611
 612 C'est une erreur de permission d'accès à un périphérique, généré par la
 613 librairie kivy. Elle peut être ignorée et n'aura pas d'incidence.
 614
 615 * Pour d'autres problèmes ou bugs à reporter, voir le [Bug
 616   Tracker](https://git.immae.eu/mantisbt/view_all_bug_page.php?project_id=1&sort=status%2Clast_updated&dir=ASC%2CDESC)
 617
 618 ## Divers
 619
 620 Les extraits de musiques proposés en exemples proviennent de
 621 [Jamendo](https://jamendo.com). Les musiques (complètes) sont disponibles en
 622 libre téléchargement pour un usage non commercial :
 623
 624 [Short Blues](https://www.jamendo.com/track/340173/short-blues)
 625
 626 [To the Fantasy war](https://www.jamendo.com/track/778560/to-the-fantasy-war)
 627
 628 Le bruit de crocodile provient de
 629 [Universal-Soundbank](http://www.universal-soundbank.com/).
 630
 631 Cet outil a été développé à l'origine pour faciliter la gestion du son pour les
 632 spectacles de la compagnie circassienne [Les pieds
 633 jaloux](http://piedsjaloux.fr/). N'ayant pas d'ingénieur son, les artistes
 634 eux-mêmes peuvent alors gérer leur musique lorsqu'ils ne sont pas sur scène :
 635 d'où la nécessité de préparer les transitions à l'avance et, au moment de la
 636 représentation, de réduire l'interaction avec la machine au minimum (une
 637 touche).