doc: added new features

diff --git a/documentation_fr.md b/documentation_fr.md
index bd42e5573f44cf25a505d10424fa58492c1cfc0f..1544cc528df9293188db8b8df2e3daa727422653 100644 (file)
--- a/documentation_fr.md
+++ b/documentation_fr.md
@@ -25,6 +25,8 @@ Appuyer sur une touche déclenche les actions associées à cette touche (affich
 
 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 successif 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".
+
 ### Options disponibles au lancement
 
 Toutes les options au lancement sont facultatives ; la plupart du temps lancer le programme dans le bon dossier suffit.
@@ -49,7 +51,9 @@ Les options suivantes sont plutôt réservées à un usage avancé de music_samp
 ## Configurer les touches
 
 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é.
+le `#` est un symbole de commentaire : tout ce qui suit ce symbole sur une ligne est ignoré. 
+
+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 erronnées (en colorant éventuellement la touche en noir), ou ne se lance pas du tout.
 
 Le fichier contient plusieurs sections :
 
@@ -111,7 +115,7 @@ La touche échap est de couleur rouge, et le texte "STOP !" est affiché sur la
 
 ### `keys` : actions sur les touches
 
-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.
+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 (donc quasi-simultanément).
 
 
 #### Exemples
@@ -121,13 +125,14 @@ Cette section sert à décrire, pour chaque touche, la liste des actions success
       - play: 
           file: "music1.mp3"
           volume: 70
+          start_at: 10
       - wait:
           duration: 5
       - stop:
           file: "music1.mp3"
           fade_out: 2
 
-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.
+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.
 
     :::yaml
     'b':
@@ -171,7 +176,7 @@ Coupe la musique "music1.mp3" avec un fondu de 5 secondes, attend la fin du fond
           file: "music1.mp3"
           value: 100
 
-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é.
+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.
 
     :::yaml
     'e':
@@ -189,11 +194,12 @@ Baisse le volume de "music1.mp3" pendant que le son "noise.mp3" est joué par de
 Met en pause la musique "music1.mp3" pour 10 secondes et la relance après, en avançant de 5 secondes dans la musique.
 
 #### Liste des actions possibles: 
-- `play` : joue une musique. Paramètres :
+- `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 :
     * `file: "music.mp3"` précise la musique jouée (chemin relatif).
     * `fade_in: x` (facultatif) lance la musique avec un fondu au départ de x secondes.
     * `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".
     * `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`.
+    * `start_at: x` (facultatif, défaut : 0) la musique démarre à x secondes du début.
 - `stop` : arrête une musique donnée. Paramètres :
     * `file: "music.mp3"` (facultatif) précise la musique à stopper. Si aucune musique n'est précisée, le `stop` s'applique à toutes les musiques.
     * `fade_out: x` (facultatif) stoppe la musique avec un fondu de x secondes.
@@ -220,13 +226,13 @@ Notez une fois enore que `wait` est quasiment la seule action qui attend d'avoir
     * `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).
-- `stop_all_actions:` Interrompt toutes les actions en cours et à faire.
+- `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 :
-    * `wait_id: name` : précise l'identifiant du `wait` à stopper (défini par `set_wait_id`, voir les actions `wait` et `stop`).
+    * `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`.
 
 ### `aliases` : définir des alias
 
-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".
+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".
 
 La syntaxe est la suivante:
     :::yaml
@@ -250,7 +256,7 @@ On utilise ensuite, dans le fichier de configuration, `include: alias1` à la pl
         play:
           include: music1
 
-`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.
+`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.
 
     :::yaml
     aliases:
@@ -286,7 +292,7 @@ Sont listés ci-dessous une liste de problèmes rencontrés, avec des solutions
 
  * Le programme se lance et s'arrête tout de suite.
 
-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.
+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).
 
  * La musique "grésille" affreusement.
 
@@ -307,7 +313,3 @@ Les extraits de musiques proposés en exemples proviennent de [Jamendo](https://
 Le bruit de crocodile provient de [Universal-Soundbank](http://www.universal-soundbank.com/).
 
 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).
-
-## Contact
-
-Blabla