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     :::bash
  14     sudo apt-get install libav-tools
  15
  16 Si vous utilisez la version compilée de Music Sampler, il n'y a pas d'installation nécessaire.
  17
  18 ## Utilisation
  19
  20 Tout le travail consiste à préparer les transitions dans le fichier de configuration config.yml.
  21
  22 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. Les touches programmées apparaissent d'abord légèrement grisées, lorsque les musiques associées sont en cours de chargement, ou pas encore chargées. Le rond orange dans le coin du clavier devient vert lorsque tout est chargé.
  23
  24 Appuyer sur une touche déclenche les actions associées à cette touche (affichées dans le cadre en bas à gauche). Cliquer sur la touche affiche les actions associées à la touche mais ne les déclenche pas. Les deux autres cadres montrent respectivement un historique des touches appuyées et la liste des musiques en train d'être jouées.
  25
  26 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.
  27
  28 ### Options disponibles au lancement
  29
  30 Toutes les options au lancement sont facultatives ; la plupart du temps lancer le programme dans le bon dossier suffit.
  31
  32   * `-h, --help` : affiche une liste des options disponibles.
  33   * `-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).
  34   * `-d, --debug` : Affiche les informations de débuggage (désactivé par défaut)
  35   * `-V, --version` : affiche la version courante et quitte (utilisable uniquement pour la version compilée).
  36
  37 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 :
  38
  39   * `-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.
  40   * `-l LATENCY, --latency LATENCY` : latence. Préciser "low", "high" ou un nombre de secondes (par défaut, "high")
  41   * `-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.
  42   * `-f FRAME_RATE, --frame-rate FRAME_RATE` : fréquence d'échantillonnage pour jouer les musiques. Par défaut : 44100
  43   * `-x CHANNELS, --channels CHANNELS` : nombre de canaux par musique (2 par défaut, pour une écoute stéréo)
  44   * `-s SAMPLE_WIDTH, --sample-width SAMPLE_WIDTH` : largeur d'échantillonnage (nombre d'octets pour chaque frame). Par défaut : 2.
  45   * `--device DEVICE` : sélectionne le périphérique de son.
  46   * `--list-devices` : Affiche la liste des périphériques de son disponibles.
  47   * `-- ARGS` : Arguments à passer à la librairie Kivy.
  48
  49 ## Configurer les touches
  50
  51 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 !).
  52 le `#` est un symbole de commentaire : tout ce qui suit ce symbole sur une ligne est ignoré.
  53
  54 Le fichier contient plusieurs sections :
  55
  56     :::yaml
  57     aliases:
  58       ...
  59
  60     music_properties:
  61       ...
  62
  63     key_properties:
  64       ...
  65
  66     keys:
  67       ...
  68
  69
  70 ### `music_properties` : propriétés des musiques
  71
  72 Cette section sert à définir des propriétés globales des musiques.
  73
  74 #### Exemples
  75
  76     :::yaml
  77       "music1.mp3":
  78         name: My favorite music
  79         gain: 1.4
  80 La musique "music1.mp3" est désignée par le nom "My favorite music". Elle est chargée à 140% de son volume normal.
  81
  82     :::yaml
  83       "music2.mp3":
  84         gain: 0.7
  85
  86 La musique "music2.mp3" est chargée à 70% de son volume normal.
  87
  88 #### Liste des options possibles
  89 - `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*).
  90 - `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.
  91
  92 ### `key_properties` : affichage des touches
  93
  94 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.
  95
  96 #### Exemples
  97
  98     :::yaml
  99       'ESC':
 100         description:
 101           -
 102           - STOP !
 103         color: [255, 0, 0]
 104
 105 La touche échap est de couleur rouge, et le texte "STOP !" est affiché sur la deuxième ligne.
 106
 107 #### Liste des options possibles
 108 - `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".
 109 - `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.
 110
 111
 112 ### `keys` : actions sur les touches
 113
 114 Cette section sert à décrire, pour chaque touche, la liste des actions successives. Notez que la plupart des commandes (hors `wait` et quelques cas particuliers, voir plus bas), les actions sont exécutées les unes à la suite des autres, sans attendre que la précédente soit terminée.
 115
 116
 117 #### Exemples
 118
 119     :::yaml
 120     'a':
 121       - play:
 122           file: "music1.mp3"
 123           volume: 70
 124       - wait:
 125           duration: 5
 126       - stop:
 127           file: "music1.mp3"
 128           fade_out: 2
 129
 130 Lance la musique "music1.mp3" à 70% de son volume max, puis au bout de 5 secondes coupe la musique avec un fondu de 2 secondes.
 131
 132     :::yaml
 133     'b':
 134       - stop:
 135           file: "music1.mp3"
 136           fade_out: 5
 137           wait: false
 138       - play:
 139           file: "music2.mp3"
 140           fade_in: 5
 141
 142 Effectue un fondu enchaîné de 5 secondes entre "music1.mp3" et "music2.mp3"
 143
 144     :::yaml
 145     'c':
 146       - stop:
 147           file: "music1.mp3"
 148           fade_out: 5
 149           wait: true
 150       - wait:
 151           duration: 2
 152       - play:
 153           file: "music2.mp3"
 154       - seek:
 155           file: "music2.mp3"
 156           delta: false
 157           value: 60
 158 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.
 159
 160     :::yaml
 161     'd':
 162       - volume:
 163           file: "music1.mp3"
 164           value: 50
 165       - play:
 166           file: "noise.mp3"
 167           loop: 1
 168       - wait:
 169           file: "noise.mp3"
 170       - volume:
 171           file: "music1.mp3"
 172           value: 100
 173
 174 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 le son "noise" est terminé.
 175
 176     :::yaml
 177     'e':
 178       - pause:
 179           file: "music1.mp3"
 180       - wait:
 181           duration: 10
 182       - unpause:
 183           file: "music1.mp3"
 184       - seek:
 185           file: "music1.mp3"
 186           delta: true
 187           value: 5
 188
 189 Met en pause la musique "music1.mp3" pour 10 secondes et la relance après, en avançant de 5 secondes dans la musique.
 190
 191 #### Liste des actions possibles:
 192 - `play` : joue une musique. Paramètres :
 193     * `file: "music.mp3"` précise la musique jouée (chemin relatif).
 194     * `fade_in: x` (facultatif) lance la musique avec un fondu au départ de x secondes.
 195     * `volume: x` (facultatif, défaut : 100) la musique doit être jouée à x% de son volume max (x doit être entre 0 et 100). Pour jouer une musique à plus de 100%, voir la section "file: properties".
 196     * `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`.
 197 - `stop` : arrête une musique donnée. Paramètres :
 198     * `file: "music.mp3"` (facultatif) précise la musique à stopper. Si aucune musique n'est précisée, le `stop` s'applique à toutes les musiques.
 199     * `fade_out: x` (facultatif) stoppe la musique avec un fondu de x secondes.
 200     * `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. FIXME
 201     * `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.
 202 - `volume` : change le volume d'une musique donnée. Paramètres :
 203     * `file: "music.mp3"` (facultatif) précise la musique. Si aucune musique n'est précisée, la modification s'applique au volume global.
 204     * `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.
 205     * `value: x` Si delta est à false, met le volume à x% du volume max (x doit être entre 0 et 100).
 206 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.
 207 Si delta est à true, applique un modificateur de x% au volume (x doit être un entier signé).
 208 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%.
 209     * `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.
 210 - `pause` : met en pause une musique. Paramètres :
 211     * `file: "music.mp3"` (facultatif) précise la musique à mettre en pause. Si non précisé, s'applique à toutes les musiques.
 212 - `unpause` : relance une musique mise en pause (là où elle en était). Paramètres :
 213     * `file: "music.mp3"` (facultatif) précise la musique à relancer. Si non précisé, s'applique à toutes les musiques.
 214 - `wait` : attend un temps donné. Paramètres :
 215     * `file: "music.mp3"` (facultatif) attend la fin de la musique "music.mp3"
 216     * `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`.
 217     * `set_wait_id: name` (facultatif, inutile lorsque `wait` est à false) donne l'identifiant `name` à l'attente (voir `interrupt_wait`). L'identifiant peut être n'importe quelle chaîne de caractère.
 218 Notez une fois enore 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.
 219 - `seek` : permet d'aller à un endroit précis dans une musique. Paramètres :
 220     * `file: "music.mp3"` (facultatif) précise la musique. Si aucune musique n'est précisée, l'action s'applique à toutes les musiques.
 221     * `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.
 222     * `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).
 223 - `stop_all_actions:` Interrompt toutes les actions en cours et à faire.
 224 - `interrupt_wait`: Interrompt l'attente (de `wait` ou fin d'un fondu avec attente) et passe directement à l'action suivante. Paramètre :
 225     * `wait_id: name` : précise l'identifiant du `wait` à stopper (défini par `set_wait_id`, voir les actions `wait` et `stop`).
 226
 227 ### `aliases` : définir des alias
 228
 229 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 "file: properties".
 230
 231 La syntaxe est la suivante:
 232     :::yaml
 233     aliases:
 234       alias1:
 235         param: value
 236       alias2:
 237         param: value
 238
 239 On utilise ensuite, dans le fichier de configuration, `include: alias1` à la place de `param: value`. Voir les exemples ci-dessous.
 240
 241 #### Exemples
 242
 243     :::yaml
 244     aliases:
 245       music1:
 246         file: "path/to/my/favourite/music.mp3"
 247
 248     keys:
 249       'a':
 250         play:
 251           include: music1
 252
 253 `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 "file_properties", les alias ne fonctionnent pas, et il faut écrire le nom du fichier complet.
 254
 255     :::yaml
 256     aliases:
 257       blue:
 258         color: [0, 0, 255]
 259
 260     keys_properties:
 261       'a':
 262         description:
 263           -
 264           - blue key
 265         include: blue
 266
 267 `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.
 268
 269     :::yaml
 270     aliases:
 271       long_time:
 272         duration: 42
 273
 274     keys:
 275       'b':
 276         wait:
 277           include: long_time
 278         play:
 279           file: "music1.mp3"
 280
 281 `long_time` est un alias pour la durée 42 secondes. Au lieu d'écrire `duration: 42`, on peut écrire `include: long_time`.
 282
 283 ## Problèmes possibles
 284
 285 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.
 286
 287  * Le programme se lance et s'arrête tout de suite.
 288
 289 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). Si besoin, relancer avec -d (débug) pour avoir plus de détails.
 290
 291  * La musique "grésille" affreusement.
 292
 293 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)
 294
 295   * Impossible de jouer plus d'une musique à la fois.
 296
 297 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).
 298
 299 ## Divers
 300
 301 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 :
 302
 303 [Short Blues](https://www.jamendo.com/track/340173/short-blues)
 304
 305 [To the Fantasy war](https://www.jamendo.com/track/778560/to-the-fantasy-war)
 306
 307 Le bruit de crocodile provient de [Universal-Soundbank](http://www.universal-soundbank.com/).
 308
 309 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).
 310
 311 ## Contact
 312
 313 Blabla