documentation_fr.md

   1 [TOC]
   2
   3 # Music Sampler
   4
   5 ## Description
   6
   7 Music Sampler permet de pré-programmer des transitions musicales, qui peuvent ensuite être lancées à l'aide d'un simple appui sur une touche.
   8
   9
  10 ## Pré-requis et installation
  11
  12 Il faut avoir ffmpeg d'installé. Pour cela, il faut installer le paquet `libav-tools` :
  13
  14     :::bash
  15     sudo apt-get install libav-tools
  16
  17 Si vous utilisez la version compilée de Music Sampler, il n'y a pas d'installation nécessaire.
  18
  19 ## Utilisation
  20
  21 Tout le travail consiste à préparer les transitions dans le fichier de configuration config.yml
  22
  23 Lancer ensuite le programme dans le dossier où se situe le fichier. 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é.
  24
  25 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.
  26
  27 ## Configurer les touches
  28
  29 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 !).
  30 le `#` est un symbole de commentaire : tout ce qui suit ce symbole sur une ligne est ignoré.
  31
  32 Le fichier contient plusieurs sections :
  33
  34     :::yaml
  35     aliases:
  36       ...
  37
  38     music_properties:
  39       ...
  40
  41     key_properties:
  42       ...
  43
  44     keys:
  45       ...
  46
  47
  48 ### `music_properties` : propriétés des musiques
  49
  50 Cette section sert à définir des propriétés globales des musiques.
  51
  52 #### Exemples
  53
  54     :::yaml
  55       "music1.mp3":
  56         name: My favorite music
  57         gain: 1.4
  58 La musique "music1.mp3" est désignée par le nom "My favorite music". Elle est chargée à 140% de son volume normal.
  59
  60     :::yaml
  61       "music2.mp3":
  62         gain: 0.7
  63
  64 La musique "music2.mp3" est chargée à 70% de son volume normal.
  65
  66 #### Liste des options possibles
  67 - `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*).
  68 - `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.
  69
  70 ### `key_properties` : affichage des touches
  71
  72 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.
  73
  74 #### Exemples
  75
  76     :::yaml
  77       'ESC':
  78         description:
  79           -
  80           - STOP !
  81         color: [255, 0, 0]
  82
  83 La touche échap est de couleur rouge, et le texte "STOP !" est affiché sur la deuxième ligne.
  84
  85 #### Liste des options possibles
  86 - `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".
  87 - `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.
  88
  89
  90 ### `keys` : actions sur les touches
  91
  92 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.
  93
  94
  95 #### Exemples
  96
  97     :::yaml
  98     'a':
  99       - play:
 100           file: "music1.mp3"
 101           volume: 70
 102       - wait:
 103           duration: 5
 104       - stop:
 105           file: "music1.mp3"
 106           fade_out: 2
 107
 108 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.
 109
 110     :::yaml
 111     'b':
 112       - stop:
 113           file: "music1.mp3"
 114           fade_out: 5
 115           wait: false
 116       - play:
 117           file: "music2.mp3"
 118           fade_in: 5
 119
 120 Effectue un fondu enchaîné de 5 secondes entre "music1.mp3" et "music2.mp3"
 121
 122     :::yaml
 123     'c':
 124       - stop:
 125           file: "music1.mp3"
 126           fade_out: 5
 127           wait: true
 128       - wait:
 129           duration: 2
 130       - play:
 131           file: "music2.mp3"
 132       - seek:
 133           file: "music2.mp3"
 134           delta: false
 135           value: 60
 136 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.
 137
 138     :::yaml
 139     'd':
 140       - volume:
 141           file: "music1.mp3"
 142           value: 50
 143       - play:
 144           file: "noise.mp3"
 145           loop: 1
 146       - wait:
 147           file: "noise.mp3"
 148       - volume:
 149           file: "music1.mp3"
 150           value: 100
 151
 152 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é.
 153
 154     :::yaml
 155     'e':
 156       - pause:
 157           file: "music1.mp3"
 158       - wait:
 159           duration: 10
 160       - unpause:
 161           file: "music1.mp3"
 162       - seek:
 163           file: "music1.mp3"
 164           delta: true
 165           value: 5
 166
 167 Met en pause la musique "music1.mp3" pour 10 secondes et la relance après, en avançant de 5 secondes dans la musique.
 168
 169 #### Liste des actions possibles:
 170 - `play` : joue une musique. Paramètres :
 171     * `file: "music.mp3"` précise la musique jouée (chemin relatif).
 172     * `fade_in: x` (facultatif) lance la musique avec un fondu au départ de x secondes.
 173     * `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".
 174     * `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`.
 175 - `stop` : arrête une musique donnée. Paramètres :
 176     * `file: "music.mp3"` (facultatif) précise la musique à stopper. Si aucune musique n'est précisée, le `stop` s'applique à toutes les musiques.
 177     * `fade_out: x` (facultatif) stoppe la musique avec un fondu de x secondes.
 178     * `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
 179 - `volume` : change le volume d'une musique donnée. Paramètres :
 180     * `file: "music.mp3"` (facultatif) précise la musique. Si aucune musique n'est précisée, la modification s'applique au volume global.
 181     * `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.
 182     * `value: x` Si delta est à false, met le volume à x% du volume max (x doit être entre 0 et 100).
 183 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.
 184 Si delta est à true, applique un modificateur de x% au volume (x doit être un entier signé).
 185 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%.
 186     * `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.
 187 - `pause` : met en pause une musique. Paramètres :
 188     * `file: "music.mp3"` (facultatif) précise la musique à mettre en pause. Si non précisé, s'applique à toutes les musiques.
 189 - `unpause` : relance une musique mise en pause (là où elle en était). Paramètres :
 190     * `file: "music.mp3"` (facultatif) précise la musique à relancer. Si non précisé, s'applique à toutes les musiques.
 191 - `wait` : attend un temps donné. Paramètres :
 192     * `file: "music.mp3"` (facultatif) attend la fin de la musique "music.mp3"
 193     * `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`.
 194 Notez une fois enore que `wait` est quasiment la seule action qui attend d'avoir terminé pour lancer la commane 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.
 195 - `seek` : permet d'aller à un endroit précis dans une musique. Paramètres :
 196     * `file: "music.mp3"` (facultatif) précise la musique. Si aucune musique n'est précisée, l'action s'applique à toutes les musiques.
 197     * `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.
 198     * `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).
 199     * `stop_all_actions:` Interrompt toutes les actions en cours et à faire.
 200
 201 ### `aliases` : définir des alias
 202
 203 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".
 204
 205
 206 #### Exemples
 207
 208     :::yaml
 209     aliases:
 210       music1:
 211         file: "path/to/my/favourite/music.mp3"
 212
 213     keys:
 214       'a':
 215         play:
 216           include: music1
 217
 218 `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.
 219
 220     :::yaml
 221     aliases:
 222       blue:
 223         color: [0, 0, 255]
 224
 225     keys_properties:
 226       'a':
 227         description:
 228           -
 229           - blue key
 230         include: blue
 231
 232 `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.
 233
 234     :::yaml
 235     aliases:
 236       long_time:
 237         duration: 42
 238
 239     keys:
 240       'b':
 241         wait:
 242           include: long_time
 243         play:
 244           file: "music1.mp3"
 245
 246 `long_time` est un alias pour la durée 42 secondes. Au lieu d'écrire `duration: 42`, on peut écrire `include: long_time`.