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 transitions musicales, qui peuvent ensuite être lancées à l'aide d'un simple appui sur une touche.
   8
   9 ## Pré-requis et installation
  10
  11 - Il faut avoir ffmpeg d'installé. Pour cela, il faut installer le paquet `libav-tools` :
  12
  13     ```
  14     sudo apt-get install libav-tools
  15     ```
  16
  17 Si vous utilisez la version compilée de Music Sampler, il n'y a rien d'autre à installer.
  18
  19 - Pour utiliser les sources directement, les modules suivants sont requis:
  20
  21 | module      | version minimale | commentaire                      |
  22 | ----------- | ---------------- | -------------------------------- |
  23 | Kivy        | 1.9.1            |                                  |
  24 | Markdown    | 2.6.6            | pour la documentation uniquement |
  25 | pydub       | 0.16.4           |                                  |
  26 | Pygame      | 1.9.2pre         | utilisée par Kivy                |
  27 | Pygments    | 2.1.3            | pour la documentation uniquement |
  28 | sounddevice | 0.3.3            |                                  |
  29 | transitions | 0.4.1            |                                  |
  30 | PyYAML      | 3.11             |                                  |
  31
  32 - Le programme utilise les polices "Symbola" et "Ubuntu" (Regular / Bold), qui doivent être disponibles.
  33
  34     ```
  35     sudo apt-get install ttf-ancient-fonts ttf-ubuntu-font-family
  36     ```
  37
  38 ## Version compilée
  39
  40 Une version compilée peut être créée avec pyinstaller:
  41
  42     :::bash
  43     pyinstaller music_sampler.spec
  44
  45 ## Utilisation
  46
  47 Tout le travail consiste à préparer les transitions dans le fichier de configuration config.yml.
  48
  49 Lancer ensuite le programme dans le dossier où se situe le fichier de configuration (voir plus bas pour une utilisation avancée). Une fenêtre représentant un clavier apparaît. Le rond orange dans le coin du clavier devient vert lorsque tout est chargé, ou rouge en cas de problème. Une touche grisée et barrée représente une touche non-utilisable pour le moment : soit parce que la musique est en cours de chargement (au lancement du programme, cela peut prendre un peu de temps sur certaines machines), soit parce qu'il y a une action en cours.
  50
  51 Un exemple de fichier de configuration est fourni, avec un certain nombre de touches et de transitions programmées (pour les trois musiques fournies), la syntaxe du fichier (expliquée plus bas) se comprend aisément en le regardant. De plus, certaines touches (par exemple 'ÉCHAP' pour tout arrêter) peuvent être gardées d'une fois sur l'autre.
  52
  53 ### Actions possibles
  54
  55   - Cliquer sur une touche : affiche les actions associées à cette touche (dans le cadre en bas à gauche).
  56   - Appuyer sur une touche : déclenche les actions associées à cette touche (affichées également dans le cadre en bas à gauche). Lorsqu'une touche a des actions en cours, son cadre est noir. Notez qu'une action de type "jouer une musique" est considérée comme terminée quand ladite musique est lancée.
  57 En cas d'appui répété sur une touche, music_sampler ne relance pas les actions associées à cette touche si ces actions ne sont pas terminées ; cela pour éviter les "accidents".
  58   - Ctrl+C ou Ctrl+Q : quitte le programme (possible aussi en cliquant simplement sur la croix en haut à droite).
  59   - Ctrl+R : recharge le fichier de configuration.
  60
  61 ### Options disponibles au lancement
  62
  63 Toutes les options au lancement sont facultatives ; la plupart du temps lancer le programme dans le bon dossier suffit.
  64
  65   * `-h, --help` : affiche une liste des options disponibles.
  66   * `-c CONFIG, --config CONFIG` : précise le fichier de configuration à charger (par défaut, config.yml qui se trouve dans le dossier où est lancé music_sampler).
  67   * `-p MUSIC_PATH, --music-path MUSIC_PATH` : précise le chemin des musiques (par défaut, le dossier courant).
  68   * `-d, --debug` : Affiche les informations de déboggage (désactivé par défaut)
  69   * `-V, --version` : affiche la version courante et quitte (utilisable uniquement pour la version compilée).
  70
  71 Les options suivantes sont plutôt réservées à un usage avancé de music_sampler, ou en cas de problème avec la configuration standard :
  72
  73   * `-m, --builtin-mixing` Effectue en interne le mixage des sons. Par défaut, music_sampler confie le mixage au système : n'activer cette option que si le système n'y parvient pas.
  74   * `-l LATENCY, --latency LATENCY` : latence. Préciser "low", "high" ou un nombre de secondes (par défaut, "high")
  75   * `-b BLOCKSIZE, --blocksize BLOCKSIZE` : taille des blocs. Nombre de frames pour chaque étape du mixeur. 0 (par défaut) signifie que le programme choisit lui-même le nombre qui lui convient.
  76   * `-f FRAME_RATE, --frame-rate FRAME_RATE` : fréquence d'échantillonnage pour jouer les musiques. Par défaut : 44100
  77   * `-x CHANNELS, --channels CHANNELS` : nombre de canaux par musique (2 par défaut, pour une écoute stéréo)
  78   * `-s SAMPLE_WIDTH, --sample-width SAMPLE_WIDTH` : largeur d'échantillonnage (nombre d'octets pour chaque frame). Par défaut : 2.
  79   * `--device DEVICE` : sélectionne le périphérique de son.
  80   * `--list-devices` : Affiche la liste des périphériques de son disponibles.
  81   * `-- ARGS` : Arguments à passer à la librairie Kivy.
  82
  83 ## Configurer les touches
  84
  85 **ATTENTION : le format du fichier de configuration est susceptible d'évoluer, sans garantie de rétrocompatibilité.**
  86
  87 Le fichier config.yml utilise la syntaxe yaml. Les catégories et sous-catégories sont gérées par l'indentation par des espaces (mais PAS par des tabulations !).
  88 le `#` est un symbole de commentaire : tout ce qui suit ce symbole sur une ligne est ignoré.
  89
  90 En cas d'erreur dans le fichier de configuration, un message d'erreur s'affiche dans le terminal. Selon la "gravité" de l'erreur, music_sampler se lance en ignorant les actions erronées (en colorant éventuellement la touche en noir), ou ne se lance pas du tout.
  91
  92 Le fichier contient plusieurs sections :
  93
  94     :::yaml
  95     aliases:
  96       ...
  97
  98     music_properties:
  99       ...
 100
 101     key_properties:
 102       ...
 103
 104     keys:
 105       ...
 106
 107
 108 ### `music_properties` : propriétés des musiques
 109
 110 Cette section sert à définir des propriétés globales des musiques.
 111
 112 #### Exemples
 113
 114     :::yaml
 115       "music1.mp3":
 116         name: My favorite music
 117         gain: 1.4
 118 La musique "music1.mp3" est désignée par le nom "My favorite music". Elle est chargée à 140% de son volume normal.
 119
 120     :::yaml
 121       "music2.mp3":
 122         gain: 0.7
 123
 124 La musique "music2.mp3" est chargée à 70% de son volume normal.
 125
 126 #### Liste des options possibles
 127 - `name: My music` La musique sera désignée  (dans les actions, dans le terminal) comme "My music" au lieu du chemin du fichier. Par exemple le cadre des actions affichera "starting « My music » at volume 100%". Attention, cela ne fait pas office d'alias dans le fichier de configuration (voir la section *aliases*).
 128 - `gain: x` Charge la musique avec un gain de x (multiplicatif). Utiliser la commande "volume" pour changer ponctuellement le volume (0 à 100%) au cours de l'écoute.
 129
 130 ### `key_properties` : affichage et propriétés des touches
 131
 132 Cette section sert à décrire l'affichage à l'écran des touches : couleur et texte. Par défaut, une touche "attribuée" à une ou plusieurs actions s'affiche en vert.
 133
 134 #### Exemples
 135
 136     :::yaml
 137       'ESC':
 138         description:
 139           -
 140           - STOP !
 141         color: [255, 0, 0]
 142         repeat_delay: 2
 143
 144 La touche échap est de couleur rouge, et le texte "STOP !" est affiché sur la deuxième ligne. Si on appuie deux fois sur la même touche à moins de deux secondes d'intervalle, le second appui est ignoré.
 145
 146 #### Liste des options possibles
 147 - `description` : le texte qui s'affiche, à côté du "nom" de la touche. Il faut mettre un tiret pour une ligne de texte (pas de retour à la ligne automatique). La première ligne correspond à celle de la lettre associée à la touche, aussi il vaut mieux souvent la laisser vide, ou ne mettre que très peu de texte (voir l'exemple ci-dessus). Sur un écran de taille raisonnable, on peut compter 3 lignes (incluant la première) pour une touche "standard".
 148 - `color: [r, g, b]` : la couleur de la touche. r, g et b sont les proportions de rouge, vert et bleu, et doivent être des entiers entre 0 et 255.
 149 - `repeat_delay: x` (par défaut : 0) : délai de "sécurité" en cas d'appuis successifs sur la touche. La touche est désactivée (grisée et barrée) pendant toute la durée des actions puis le délai de x secondes.
 150
 151 ### `keys` : actions sur les touches
 152
 153 Cette section sert à décrire, pour chaque touche, la liste des actions successives. Notez que la plupart des actions (hors `wait` et quelques cas particuliers, voir plus bas) sont quasi-instantanées.
 154
 155
 156 #### Exemples
 157
 158     :::yaml
 159     'a':
 160       - play:
 161           file: "music1.mp3"
 162           volume: 70
 163           start_at: 10
 164       - wait:
 165           duration: 5
 166       - stop:
 167           file: "music1.mp3"
 168           fade_out: 2
 169
 170 Lance la musique "music1.mp3" à 70% de son volume max, à 10 secondes du début, puis au bout de 5 secondes coupe la musique avec un fondu de 2 secondes.
 171
 172     :::yaml
 173     'b':
 174       - stop:
 175           file: "music1.mp3"
 176           fade_out: 5
 177           wait: false
 178       - play:
 179           file: "music2.mp3"
 180           fade_in: 5
 181
 182 Effectue un fondu enchaîné de 5 secondes entre "music1.mp3" et "music2.mp3"
 183
 184     :::yaml
 185     'c':
 186       - stop:
 187           file: "music1.mp3"
 188           fade_out: 5
 189           wait: true
 190       - wait:
 191           duration: 2
 192       - play:
 193           file: "music2.mp3"
 194       - seek:
 195           file: "music2.mp3"
 196           delta: false
 197           value: 60
 198 Coupe la musique "music1.mp3" avec un fondu de 5 secondes, attend la fin du fondu, puis attend encore deux secondes et lance la musique "music2.mp3", au temps d'une minute.
 199
 200     :::yaml
 201     'd':
 202       - volume:
 203           file: "music1.mp3"
 204           value: 50
 205       - play:
 206           file: "noise.mp3"
 207           loop: 1
 208       - wait:
 209           file: "noise.mp3"
 210       - volume:
 211           file: "music1.mp3"
 212           value: 100
 213
 214 Baisse le volume de "music1.mp3" pendant que le son "noise.mp3" est joué par dessus (deux fois). Le volume revient à la normale une fois que les deux écoutes du son "noise" sont terminées.
 215
 216     :::yaml
 217     'e':
 218       - pause:
 219           file: "music1.mp3"
 220       - wait:
 221           duration: 10
 222       - unpause:
 223           file: "music1.mp3"
 224       - seek:
 225           file: "music1.mp3"
 226           delta: true
 227           value: 5
 228
 229 Met en pause la musique "music1.mp3" pour 10 secondes et la relance après, en avançant de 5 secondes dans la musique.
 230
 231 #### Liste des actions possibles:
 232 - `play` : joue une musique. music_sampler ne joue qu'une musique à la fois : si la musique demandée est déjà en train d'être jouée, elle n'est pas relancée ou jouée "par dessus". Paramètres :
 233     * `file: "music.mp3"` précise la musique jouée (chemin relatif).
 234     * `fade_in: x` (facultatif) lance la musique avec un fondu au départ de x secondes.
 235     * `volume: x` (facultatif, défaut : 100) la musique doit être jouée à x% de son volume max.
 236     * `loop: x` (facultatif, défaut : 0) la musique doit être répétée x fois. Indiquer -1 pour la répéter indéfiniment. Attention, x est le nombre de répétitions, donc pour lire trois fois la musique, mettre `loop: 2`.
 237     * `start_at: x` (facultatif, défaut : 0) la musique démarre à x secondes du début.
 238     * `restart_if_running: true/false` (facultatif, défaut : false) la musique est éventuellement stoppée et redémarrée si nécessaire
 239 - `stop` : arrête une musique donnée. Paramètres :
 240     * `file: "music.mp3"` (facultatif) précise la musique à stopper. Si aucune musique n'est précisée, le `stop` s'applique à toutes les musiques.
 241     * `fade_out: x` (facultatif) stoppe la musique avec un fondu de x secondes.
 242     * `wait: true/false` (facultatif, par défaut : false) dans le cas d'un fondu, attendre la durée du fondu pour faire les actions suivantes. Si la musique s'arrêtait naturellement avant la fin du fondu, l'attente se termine lorsque la musique se termine naturellement. Lorsque plusieurs musiques sont stoppées en fondu, le `wait` n'attend que la dernière musique de la playlist (qui peut se terminer naturellement avant les autres).
 243     * `set_wait_id: name` (facultatif, inutile lorsque `wait` est à false) donne l'identifiant `name` à l'attente de fin du fondu (voir `interrupt_wait`). L'identifiant peut être n'importe quelle chaîne de caractère.
 244 - `volume` : change le volume d'une musique donnée. Paramètres :
 245     * `file: "music.mp3"` (facultatif) précise la musique. Si aucune musique n'est précisée, la modification s'applique au volume global.
 246     * `delta: true/false` (facultatif, par défaut : false) le volume doit il être précisé en absolu (false), ou en relatif (true), voir plus bas.
 247     * `value: x` Si delta est à false, met le volume à x% du volume max (x doit être entre 0 et 100).
 248 Ce facteur est appliqué à la musique déjà chargée en mémoire (voir section "propriétés"), donc le 100% fait référence au volume de chargement.
 249 Si delta est à true, applique un modificateur de x% au volume (x doit être un entier signé).
 250 Notez qu'une action "+10%" relative ne correspond pas à un pourcentage du volume actuel, mais du volume "de référence" 100%. Ainsi, effectuer +10% et -10% en relatif revient bien à 100%.
 251     * `fade: x` (facultatif) le changement de volume est appliqué en fondu sur x secondes. Il n'y a pas d'attente de la fin du fondu pour lancer les actions suivantes : au besoin, rajouter un `wait` à la main.
 252 - `pause` : met en pause une musique. Paramètres :
 253     * `file: "music.mp3"` (facultatif) précise la musique à mettre en pause. Si non précisé, s'applique à toutes les musiques.
 254 - `unpause` : relance une musique mise en pause (là où elle en était). Paramètres :
 255     * `file: "music.mp3"` (facultatif) précise la musique à relancer. Si non précisé, s'applique à toutes les musiques.
 256 - `wait` : attend un temps donné. Paramètres :
 257     * `file: "music.mp3"` (facultatif) attend la fin de la musique "music.mp3"
 258     * `duration: x` (facultatif) attend x secondes. Si `file` et `duration` sont précisés, l'attente dure jusqu'à la fin de la musique PUIS la durée donnée par `duration`.
 259     * `set_wait_id: name` (facultatif) donne l'identifiant `name` à l'attente (voir `interrupt_wait`). L'identifiant peut être n'importe quelle chaîne de caractère.
 260 Notez une fois encore que `wait` est quasiment la seule action qui attend d'avoir terminé pour lancer la commande suivante, toutes les autres sont lancées successivement mais sans attendre (donc presque simultanément) : ne pas hésiter à rajouter des commandes d'attente partout où c'est nécessaire.
 261 - `seek` : permet d'aller à un endroit précis dans une musique. Paramètres :
 262     * `file: "music.mp3"` (facultatif) précise la musique. Si aucune musique n'est précisée, l'action s'applique à toutes les musiques.
 263     * `delta: true/false` (facultatif, défaut : false) Si `delta` est true, le temps est relatif. Si delta est false, le temps est absolu, voir plus bas.
 264     * `value: x` Si `delta` est true, alors fait avancer de x secondes dans la musique (reculer si x est négatif). Si delta est false, alors la lecture se place à x secondes à partir du début. Si la musique est en train de faire un fondu (au départ, ou changement de volume), le fondu se "termine automatiquement" : et la musique est immédiatement au volume final voulu. Si la musique est en train de se terminer en fondu, le "seek" est ignoré (un fondu de fin considère la musique comme déjà terminée). En cas de `loop`, si le déplacement est relatif la musique peut éventuellement passer à la répétition suivante / précédente; sinon, le déplacement se fait dans la répétition courante.
 265 - `stop_all_actions:` Interrompt toutes les actions en cours et à faire. Notez qu'une musique lancée (y compris avec une option `loop`) est considérée comme une action "déjà terminée", et ne sera donc pas interrompue (utiliser `stop` sans arguments pour stopper toutes les musiques en écoute). Paramètre :
 266     * `other_only: true/false` (facultatif, défaut : false) : si `other_only` est true, la commande interrompt uniquement les actions des *autres* touches. Sinon, cette commande interrompt également les actions de la touche actuelle ; dans ce cas il est inutile de mettre des actions à la suite de celle-ci puisqu'elles seront systématiquement interrompues.
 267 - `interrupt_wait`: interrompt l'attente (de `wait` ou fin d'un fondu avec attente) et passe directement à l'action suivante. Paramètre :
 268     * `wait_id: name` : précise l'identifiant du `wait` à stopper (défini par `set_wait_id`, voir les actions `wait` et `stop`). Pour interrompre plusieurs `wait` d'un seul coup, il faut mettre plusieurs `interrupt_wait`.
 269 - `run_command` : lance une commande. Paramètres :
 270     * `command: my_command` : précise la commande à lancer.
 271     * `wait: true/false` (facultatif, défaut : false) : si `wait` est true, attend que la commande ait fini de s'exécuter.
 272
 273 ### `aliases` : définir des alias
 274
 275 Il est possible de définir des alias pour les différents paramètres. Ces alias sont internes au fichier de configuration ; pour afficher un "joli" nom d'une musique, voir plutôt "music_properties".
 276
 277 La syntaxe est la suivante:
 278
 279     :::yaml
 280     aliases:
 281       alias1:
 282         param: value
 283       alias2:
 284         param1: value1
 285         param2: value2
 286
 287 On utilise ensuite, dans le fichier de configuration, `include: alias1` ou `include: [alias1, alias2]` à la place de `param: value`. Dans le cas de plusieurs aliases inclus contenant des éléments identiques, seul le dernier est pris en compte. Dans tous les cas, les alias ne sont *pas* prioritaires par rapport aux éventuels paramètres définis là où ils sont inclus. Voir les exemples ci-dessous.
 288
 289 #### Exemples
 290
 291     :::yaml
 292     aliases:
 293       music1:
 294         file: "path/to/my/favourite/music.mp3"
 295
 296     keys:
 297       'a':
 298         play:
 299           include: music1
 300
 301 `music1` est désormais un alias pour `"path/to/my/favourite/music.mp3"`. À chaque fois qu'on veut écrire `file: "path/to/my/favourite/music.mp3"`, on peut écrire à la place `include: music1`. Attention, dans la section "music_properties", les alias ne fonctionnent pas, et il faut écrire le nom du fichier complet.
 302
 303     :::yaml
 304     aliases:
 305       blue:
 306         color: [0, 0, 255]
 307
 308     keys_properties:
 309       'a':
 310         description:
 311           -
 312           - blue key
 313         include: blue
 314
 315 `blue` est un alias pour la couleur `[0, 0, 255]`. À chaque fois qu'on veut écrire `color: [0, 0, 255]`, on peut écrire `include: blue` à la place.
 316
 317     :::yaml
 318     aliases:
 319       long_time:
 320         duration: 42
 321
 322     keys:
 323       'b':
 324         wait:
 325           include: long_time
 326         play:
 327           file: "music1.mp3"
 328
 329 `long_time` est un alias pour la durée 42 secondes. Au lieu d'écrire `duration: 42`, on peut écrire `include: long_time`.
 330
 331 ## Problèmes possibles
 332
 333 Sont listés ci-dessous une liste de problèmes rencontrés, avec des solutions proposées. Si vous en découvrez d'autre, contactez l'auteur pour les ajouter à la liste.
 334
 335  * Le programme se lance et s'arrête tout de suite.
 336
 337 Il s'agit généralement d'une erreur de syntaxe dans le fichier de config. Dans ce cas, le terminal doit afficher quelques détails sur l'erreur en question (au moins la ligne correspondante).
 338
 339  * La musique "grésille" affreusement.
 340
 341 Il peut s'agir d'un problème de latence (avec certains ordinateurs un peu lents). Essayez de changer la latence (par exemple, 0.1 seconde)
 342
 343   * Impossible de jouer plus d'une musique à la fois.
 344
 345 Le système n'arrive pas à mixer les musiques par lui-même. Vous pouvez essayer de regarder la liste des périphériques de son (`--list-devices`) puis en sélectionner un autre si disponible. Vous pouvez aussi essayer le mixeur intégré à music_sampler, mais les résultats ne sont pas toujours très fluides (ne pas hésiter à jouer avec les paramètres avancés comme latency et blocksize).
 346
 347 Si votre système utilise PulseAudio, il peut s'agir d'un problème de configuration du plugin ALSA. Dans ce cas, essayez de mettre la configuration suivante dans `/etc/asound.conf`, puis redémarrer la machine (solution empirique qui semble avoir fonctionné, sans garantie !):
 348
 349     pcm.!default {
 350       type pulse
 351       fallback "sysdefault"
 352       hint {
 353         show on
 354         description "Default ALSA Output (currently PulseAudio Sound Server)"
 355       }
 356     }
 357
 358     ctl.!default {
 359       type pulse
 360       fallback "sysdefault"
 361     }
 362
 363   * Pour d'autres problèmes ou bugs à reporter, voir le [Bug Tracker](https://git.immae.eu/mantisbt/view_all_bug_page.php?project_id=1)
 364 ## Divers
 365
 366 Les extraits de musiques proposés en exemples proviennent de [Jamendo](https://jamendo.com). Les musiques (complètes) sont disponibles en libre téléchargement pour un usage non commercial :
 367
 368 [Short Blues](https://www.jamendo.com/track/340173/short-blues)
 369
 370 [To the Fantasy war](https://www.jamendo.com/track/778560/to-the-fantasy-war)
 371
 372 Le bruit de crocodile provient de [Universal-Soundbank](http://www.universal-soundbank.com/).
 373
 374 Cet outil a été développé à l'origine pour faciliter la gestion du son pour les spectacles de la compagnie circassienne [Les pieds jaloux](http://piedsjaloux.fr/). N'ayant pas d'ingénieur son, les artistes eux-mêmes peuvent alors gérer leur musique lorsqu'ils ne sont pas sur scène : d'où la nécessité de préparer les transitions à l'avance et, au moment de la représentation, de réduire l'interaction avec la machine au minimum (une touche).