documentation fr: new features

diff --git a/documentation_fr.md b/documentation_fr.md
index d4dbf944e4796f6fda43c76194da427d3f17e0d7..f6f8f02b6be4936fed15904339bbfc3fa699f7f8 100644 (file)
--- a/documentation_fr.md
+++ b/documentation_fr.md
@@ -13,19 +13,23 @@ Il faut avoir ffmpeg d'installé. Pour cela, il faut installer le paquet `libav-
     :::bash
     sudo apt-get install libav-tools
 
-Si vous utilisez la version compilée de Music Sampler, il n'y a pas d'installation nécessaire.
+Si vous utilisez la version compilée de Music Sampler, il n'y a rien d'autre à installer.
 
 ## Utilisation
 
 Tout le travail consiste à préparer les transitions dans le fichier de configuration config.yml.
 
-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é, ou rouge en cas de problème.
-
-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.
+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.
 
 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.
 
-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".
+### Actions possibles
+
+  - Cliquer sur une touche : affiche les actions associées à cette touche (dans le cadre en bas à gauche).
+  - 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. 
+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".
+  - Ctrl+C ou Ctrl+Q : quitte le programme (possible aussi en cliquant simplement sur la croix en haut à droite).
+  - Ctrl+R : recharge le fichier de configuration.
 
 ### Options disponibles au lancement
 
@@ -33,6 +37,7 @@ Toutes les options au lancement sont facultatives ; la plupart du temps lancer l
 
   * `-h, --help` : affiche une liste des options disponibles.
   * `-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).
+  * `-p MUSIC_PATH, --music-path MUSIC_PATH` : précise le chemin des musiques (par défaut, le dossier courant).
   * `-d, --debug` : Affiche les informations de déboggage (désactivé par défaut)
   * `-V, --version` : affiche la version courante et quitte (utilisable uniquement pour la version compilée).
 
@@ -50,6 +55,8 @@ Les options suivantes sont plutôt réservées à un usage avancé de music_samp
 
 ## Configurer les touches
 
+**ATTENTION : le format du fichier de configuration est susceptible d'évoluer, sans garantie de rétrocompatibilité.**
+
 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 !).
 le `#` est un symbole de commentaire : tout ce qui suit ce symbole sur une ligne est ignoré. 
 
@@ -93,7 +100,7 @@ La musique "music2.mp3" est chargée à 70% de son volume normal.
 - `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*). 
 - `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.
 
-### `key_properties` : affichage des touches
+### `key_properties` : affichage et propriétés des touches
 
 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.
 
@@ -105,17 +112,18 @@ Cette section sert à décrire l'affichage à l'écran des touches : couleur et
           - 
           - STOP !
         color: [255, 0, 0]
+        repeat_delay: 2
 
-La touche échap est de couleur rouge, et le texte "STOP !" est affiché sur la deuxième ligne.
+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é.
 
 #### Liste des options possibles
 - `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".
 - `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.
-
+- `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.
 
 ### `keys` : actions sur les touches
 
-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-instantannées.
+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.
 
 
 #### Exemples
@@ -225,11 +233,15 @@ Notez qu'une action "+10%" relative ne correspond pas à un pourcentage du volum
 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.
 - `seek` : permet d'aller à un endroit précis dans une musique. Paramètres :
     * `file: "music.mp3"` (facultatif) précise la musique. Si aucune musique n'est précisée, l'action s'applique à toutes les musiques.
-    * `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.
-    * `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.
-- `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). La commande interrompt également les options à faire de cette même touche, il est donc inutile de programmer des actions à la suite de celle-ci.
-- `interrupt_wait`: Interrompt l'attente (de `wait` ou fin d'un fondu avec attente) et passe directement à l'action suivante. Paramètre :
+    * `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.
+    * `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.
+- `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 :
+    * `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.
+- `interrupt_wait`: interrompt l'attente (de `wait` ou fin d'un fondu avec attente) et passe directement à l'action suivante. Paramètre :
     * `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`.
+- `run_command` : lance une commande. Paramètres :
+    * `command: my_command` : précise la commande à lancer.
+    * `wait: true/false` (facultatif, défaut : false) : si `wait` est true, attend que la commande ait fini de s'exécuter.
 
 ### `aliases` : définir des alias