7 Music Sampler est un lecteur de musique qui permet de pré-programmer des
8 transitions musicales, qui peuvent ensuite être lancées à l'aide d'un simple
11 ## Pré-requis et installation
13 - Il faut avoir ffmpeg d'installé. Pour cela, il faut installer le paquet `libav-tools` (debian) :
15 sudo apt-get install libav-tools
17 Si vous utilisez la version compilée de Music Sampler (cf. plus bas pour un lien
18 de téléchargement), il n'y a rien d'autre à installer.
20 - Pour utiliser les sources directement, les modules suivants sont requis:
22 | module | version minimale | commentaire |
23 | ----------- | ---------------- | ----------------------------------------------------------------------------- |
24 | Cython | 0.24 | pour compiler Kivy |
25 | Kivy | 1.9.1 | certaines fonctionnalités nécessitent de compiler/installer avec `USE_SDL2=1` |
26 | Markdown | 2.6.6 | pour la documentation uniquement |
28 | Pygame | 1.9.2.dev1 | utilisée par Kivy |
29 | Pygments | 2.1.3 | pour la documentation uniquement |
30 | sounddevice | 0.3.3 | |
31 | transitions | 0.4.1 | |
34 Le projet est également disponible via `pip`:
36 pip install music_sampler
38 Le programme utilise les polices `Symbola` et `Ubuntu` (Regular / Bold), qui
39 doivent être disponibles, et la librairie `portaudio`:
41 sudo apt-get install ttf-ancient-fonts ttf-ubuntu-font-family portaudio
43 Pour compiler kivy avec la librairie SDL2, il faut certains paquets installés:
45 sudo apt-get install libsdl2-dev libsdl2-image-dev libsdl2-mixer-dev libsdl2-ttf-dev
48 Kivy](https://kivy.org/docs/installation/installation-linux.html)
52 Une version compilée peut être créée avec pyinstaller:
55 pyinstaller music_sampler.spec
59 - Un exemple de configuration ainsi que des musiques associées à l'exemple
60 peuvent être trouvées sur
61 [owncloud](https://outils.immae.eu/owncloud/index.php/s/kSrIe15G1AiZ9YF)
62 - Une version précompilée de `music_sampler` peut également être téléchargée
64 dossier](https://outils.immae.eu/owncloud/index.php/s/kSrIe15G1AiZ9YF/download?path=%2F&files=music_sampler)
65 (attention, elle n'est pas toujours forcément à jour, lancer le programme avec
66 `-V` pour voir la version compilée)
70 Tout le travail consiste à préparer les transitions dans le fichier de
71 configuration `config.yml`.
73 Lancer ensuite le programme dans le dossier où se situe le fichier de
74 configuration (voir plus bas pour une utilisation avancée). Une fenêtre
75 représentant un clavier apparaît. Le rond orange dans le coin du clavier devient
76 vert lorsque tout est chargé, ou rouge en cas de problème. Une touche grisée et
77 barrée représente une touche non-utilisable pour le moment : soit parce que la
78 musique est en cours de chargement (au lancement du programme, cela peut prendre
79 un peu de temps sur certaines machines), soit parce qu'il y a une action en
82 Un exemple de fichier de configuration est fourni, avec un certain nombre de
83 touches et de transitions programmées (pour les trois musiques fournies), la
84 syntaxe du fichier (expliquée plus bas) se comprend aisément en le regardant. De
85 plus, certaines touches (par exemple 'ÉCHAP' pour tout arrêter) peuvent être
86 gardées d'une fois sur l'autre.
90 - Cliquer sur une touche : affiche les actions associées à cette touche (dans
91 le cadre en bas à gauche).
92 - Appuyer sur une touche : déclenche les actions associées à cette touche
93 (affichées également dans le cadre en bas à gauche). Lorsqu'une touche a des
94 actions en cours, son cadre est noir. Notez qu'une action de type "jouer une
95 musique" est considérée comme terminée quand ladite musique est lancée. En
96 cas d'appui répété sur une touche, music_sampler ne relance pas les actions
97 associées à cette touche si ces actions ne sont pas terminées ; cela pour
98 éviter les "accidents".
99 - Ctrl+C ou Ctrl+Q : quitte le programme (possible aussi en cliquant
100 simplement sur la croix en haut à droite).
101 - Ctrl+R : recharge le fichier de configuration.
103 ### Options disponibles au lancement
105 Toutes les options au lancement sont facultatives ; la plupart du temps lancer
106 le programme dans le bon dossier suffit. La plupart d'entre elles peuvent être
107 définies également dans le fichier de config (à part `--config` bien sûr). Les
108 arguments en ligne de commande ont toujours la priorité.
110 * `-h, --help` : affiche une liste des options disponibles.
111 * `-c CONFIG, --config CONFIG` : précise le fichier de configuration à charger
112 (par défaut, config.yml qui se trouve dans le dossier où est lancé
114 * `-p MUSIC_PATH, --music-path MUSIC_PATH` : précise le chemin des musiques
115 (par défaut, le dossier courant).
116 * `--no-debug, --debug` : Affiche les informations de déboggage (désactivé par
118 * `-V, --version` : affiche la version courante et quitte (utilisable
119 uniquement pour la version compilée).
120 * `-L, --language` : change la langue de l'application. Actuellement: fr, en
122 * `--focus-warning, --no-focus-warning`: Afficher / Ne pas afficher
123 d'avertissement lorsque l'application perd le focus (activé par défaut).
125 Les options suivantes sont plutôt réservées à un usage avancé de music_sampler,
126 ou en cas de problème avec la configuration standard :
128 * `--no-builtin-mixing, --builtin-mixing` Effectue en interne le mixage des
129 sons. Par défaut, music_sampler confie le mixage au système : n'activer
130 cette option que si le système n'y parvient pas.
131 * `-l LATENCY, --latency LATENCY` : latence. Préciser "low", "high" ou un
132 nombre de secondes (par défaut, "high")
133 * `-b BLOCKSIZE, --blocksize BLOCKSIZE` : taille des blocs. Nombre de frames
134 pour chaque étape du mixeur. 0 (par défaut) signifie que le programme
135 choisit lui-même le nombre qui lui convient.
136 * `-f FRAME_RATE, --frame-rate FRAME_RATE` : fréquence d'échantillonnage pour
137 jouer les musiques. Par défaut : 44100
138 * `-x CHANNELS, --channels CHANNELS` : nombre de canaux par musique (2 par
139 défaut, pour une écoute stéréo)
140 * `-s SAMPLE_WIDTH, --sample-width SAMPLE_WIDTH` : largeur d'échantillonnage
141 (nombre d'octets pour chaque frame). Par défaut : 2.
142 * `--device DEVICE` : sélectionne le périphérique de son.
143 * `--list-devices` : Affiche la liste des périphériques de son disponibles.
144 * `-- ARGS` : Arguments à passer à la librairie Kivy.
146 ## Configurer les touches
148 **ATTENTION : le format du fichier de configuration est susceptible d'évoluer,
149 sans garantie de rétrocompatibilité.**
151 Le fichier config.yml utilise la syntaxe yaml. Les catégories et sous-catégories
152 sont gérées par l'indentation par des espaces (mais PAS par des tabulations !).
153 le `#` est un symbole de commentaire : tout ce qui suit ce symbole sur une ligne
156 En cas d'erreur dans le fichier de configuration, un message d'erreur s'affiche
157 dans le terminal. Selon la "gravité" de l'erreur, music_sampler se lance en
158 ignorant les actions erronées (en colorant éventuellement la touche en noir), ou
159 ne se lance pas du tout.
161 Le fichier contient plusieurs sections :
182 La section config permet d'enregistrer les paramètres habituellement donnés en
183 ligne de commande. Les '-' dans le nom du paramètre long doivent être remplacés
184 par des '_' (par exemple '--music-path' -> 'music_path'). Pour les switches
185 (`debug`, `focus_warning`, `builtin_mixing`), utilisez la version sans le 'no-'
186 et spécifiez `true` / `false` en valeur. Notez que les arguments donnés en ligne
187 de commande sont toujours prioritaires sur les valeurs du fichier.
189 ### `music_properties` : propriétés des musiques
191 Cette section sert à définir des propriétés globales des musiques.
197 name: My favorite music
199 La musique "music1.mp3" est désignée par le nom "My favorite music". Elle est
200 chargée à 140% de son volume normal.
206 La musique "music2.mp3" est chargée à 70% de son volume normal.
208 #### Liste des options possibles
209 - `name: My music` La musique sera désignée (dans les actions, dans le
210 terminal) comme "My music" au lieu du chemin du fichier. Par exemple le cadre
211 des actions affichera "starting « My music » at volume 100%". Attention, cela
212 ne fait pas office d'alias dans le fichier de configuration (voir la section
214 - `gain: x` Charge la musique avec un gain de x (multiplicatif). Utiliser la
215 commande "volume" pour changer ponctuellement le volume (0 à 100%) au cours de
218 ### `key_properties` : affichage et propriétés des touches
220 Cette section sert à décrire l'affichage à l'écran des touches : couleur et
221 texte. Par défaut, une touche "attribuée" à une ou plusieurs actions s'affiche
234 La touche échap est de couleur rouge, et le texte "STOP !" est affiché sur la
235 deuxième ligne. Si on appuie deux fois sur la même touche à moins de deux
236 secondes d'intervalle, le second appui est ignoré.
238 #### Liste des options possibles
239 - `description` : le texte qui s'affiche, à côté du "nom" de la touche. Il faut
240 mettre un tiret pour une ligne de texte (pas de retour à la ligne
241 automatique). La première ligne correspond à celle de la lettre associée à la
242 touche, aussi il vaut mieux souvent la laisser vide, ou ne mettre que très peu
243 de texte (voir l'exemple ci-dessus). Sur un écran de taille raisonnable, on
244 peut compter 3 lignes (incluant la première) pour une touche "standard".
245 - `color: [r, g, b]` : la couleur de la touche. r, g et b sont les proportions
246 de rouge, vert et bleu, et doivent être des entiers entre 0 et 255.
247 - `repeat_delay: x` (par défaut : 0) : délai de "sécurité" en cas d'appuis
248 successifs sur la touche. La touche est désactivée (grisée et barrée) pendant
249 toute la durée des actions puis le délai de x secondes.
250 - `actions: liste`: Liste des actions à effectuer en appuyant sur la touche.
252 ### Propriété `common`
254 Une entrée spéciale `common` s'applique à toutes les touches. Les propriétés
255 définies dans cette entrée peuvent être modifiées individuellement.
257 ### `keys` : actions sur les touches
259 Cette section sert à décrire, pour chaque touche, la liste des actions
260 successives. Notez que la plupart des actions (hors `wait` et quelques cas
261 particuliers, voir plus bas) sont quasi-instantanées.
263 *Cette section est obsolète et remplacée par une clé `actions` contenant une
264 liste dans la section `key_properties` pour chaque touche.*
280 Lance la musique "music1.mp3" à 70% de son volume max, à 10 secondes du début,
281 puis au bout de 5 secondes coupe la musique avec un fondu de 2 secondes.
293 Effectue un fondu enchaîné de 5 secondes entre "music1.mp3" et "music2.mp3"
309 Coupe la musique "music1.mp3" avec un fondu de 5 secondes, attend la fin du
310 fondu, puis attend encore deux secondes et lance la musique "music2.mp3", au
327 Baisse le volume de "music1.mp3" pendant que le son "noise.mp3" est joué par
328 dessus (deux fois). Le volume revient à la normale une fois que les deux écoutes
329 du son "noise" sont terminées.
344 Met en pause la musique "music1.mp3" pour 10 secondes et la relance après, en
345 avançant de 5 secondes dans la musique.
347 #### Liste des actions possibles:
348 - `play` : joue une musique. music_sampler ne joue qu'une musique à la fois : si
349 la musique demandée est déjà en train d'être jouée, elle n'est pas relancée ou
350 jouée "par dessus". Paramètres :
351 * `file: "music.mp3"` précise la musique jouée (chemin relatif).
352 * `fade_in: x` (facultatif) lance la musique avec un fondu au départ de x
354 * `volume: x` (facultatif, défaut : 100) la musique doit être jouée à x% de
356 * `loop: x` (facultatif, défaut : 0) la musique doit être répétée x fois.
357 Indiquer -1 pour la répéter indéfiniment. Attention, x est le nombre de
358 répétitions, donc pour lire trois fois la musique, mettre `loop: 2`.
359 * `start_at: x` (facultatif, défaut : 0) la musique démarre à x secondes du
361 * `restart_if_running: true/false` (facultatif, défaut : false) la musique
362 est éventuellement stoppée et redémarrée si nécessaire
363 - `stop` : arrête une musique donnée. Paramètres :
364 * `file: "music.mp3"` (facultatif) précise la musique à stopper. Si aucune
365 musique n'est précisée, le `stop` s'applique à toutes les musiques.
366 * `fade_out: x` (facultatif) stoppe la musique avec un fondu de x secondes.
367 * `wait: true/false` (facultatif, par défaut : false) dans le cas d'un
368 fondu, attendre la durée du fondu pour faire les actions suivantes. Si la
369 musique s'arrêtait naturellement avant la fin du fondu, l'attente se
370 termine lorsque la musique se termine naturellement. Lorsque plusieurs
371 musiques sont stoppées en fondu, le `wait` n'attend que la dernière
372 musique de la playlist (qui peut se terminer naturellement avant les
374 * `set_wait_id: name` (facultatif, inutile lorsque `wait` est à false) donne
375 l'identifiant `name` à l'attente de fin du fondu (voir `interrupt_wait`).
376 L'identifiant peut être n'importe quelle chaîne de caractère.
377 - `volume` : change le volume d'une musique donnée. Paramètres :
378 * `file: "music.mp3"` (facultatif) précise la musique. Si aucune musique
379 n'est précisée, la modification s'applique au volume global.
380 * `delta: true/false` (facultatif, par défaut : false) le volume doit il
381 être précisé en absolu (false), ou en relatif (true), voir plus bas.
382 * `value: x` Si delta est à false, met le volume à x% du volume max (x doit
383 être entre 0 et 100). Ce facteur est appliqué à la musique déjà chargée en
384 mémoire (voir section "propriétés"), donc le 100% fait référence au volume
386 Si delta est à true, applique un modificateur de x% au volume (x doit être un
387 entier signé). Notez qu'une action "+10%" relative ne correspond pas à un
388 pourcentage du volume actuel, mais du volume "de référence" 100%. Ainsi,
389 effectuer +10% et -10% en relatif revient bien à 100%.
390 * `fade: x` (facultatif) le changement de volume est appliqué en fondu sur x
391 secondes. Il n'y a pas d'attente de la fin du fondu pour lancer les
392 actions suivantes : au besoin, rajouter un `wait` à la main.
393 - `pause` : met en pause une musique. Paramètres :
394 * `file: "music.mp3"` (facultatif) précise la musique à mettre en pause. Si
395 non précisé, s'applique à toutes les musiques.
396 - `unpause` : relance une musique mise en pause (là où elle en était).
398 * `file: "music.mp3"` (facultatif) précise la musique à relancer. Si non
399 précisé, s'applique à toutes les musiques.
400 - `wait` : attend un temps donné. Paramètres :
401 * `file: "music.mp3"` (facultatif) attend la fin de la musique "music.mp3"
402 * `duration: x` (facultatif) attend x secondes. Si `file` et `duration` sont
403 précisés, l'attente dure jusqu'à la fin de la musique PUIS la durée donnée
405 * `set_wait_id: name` (facultatif) donne l'identifiant `name` à l'attente
406 (voir `interrupt_wait`). L'identifiant peut être n'importe quelle chaîne
408 Notez une fois encore que `wait` est quasiment la seule action qui attend
409 d'avoir terminé pour lancer la commande suivante, toutes les autres sont lancées
410 successivement mais sans attendre (donc presque simultanément) : ne pas hésiter
411 à rajouter des commandes d'attente partout où c'est nécessaire.
412 - `seek` : permet d'aller à un endroit précis dans une musique. Paramètres :
413 * `file: "music.mp3"` (facultatif) précise la musique. Si aucune musique
414 n'est précisée, l'action s'applique à toutes les musiques.
415 * `delta: true/false` (facultatif, défaut : false) Si `delta` est true, le
416 temps est relatif. Si delta est false, le temps est absolu, voir plus bas.
417 * `value: x` Si `delta` est true, alors fait avancer de x secondes dans la
418 musique (reculer si x est négatif). Si delta est false, alors la lecture
419 se place à x secondes à partir du début. Si la musique est en train de
420 faire un fondu (au départ, ou changement de volume), le fondu se "termine
421 automatiquement" : et la musique est immédiatement au volume final voulu.
422 Si la musique est en train de se terminer en fondu, le "seek" est ignoré
423 (un fondu de fin considère la musique comme déjà terminée). En cas de
424 `loop`, si le déplacement est relatif la musique peut éventuellement
425 passer à la répétition suivante / précédente; sinon, le déplacement se
426 fait dans la répétition courante.
427 - `stop_all_actions:` Interrompt toutes les actions en cours et à faire. Notez
428 qu'une musique lancée (y compris avec une option `loop`) est considérée comme
429 une action "déjà terminée", et ne sera donc pas interrompue (utiliser `stop`
430 sans arguments pour stopper toutes les musiques en écoute). Paramètre :
431 * `other_only: true/false` (facultatif, défaut : false) : si `other_only`
432 est true, la commande interrompt uniquement les actions des *autres*
433 touches. Sinon, cette commande interrompt également les actions de la
434 touche actuelle ; dans ce cas il est inutile de mettre des actions à la
435 suite de celle-ci puisqu'elles seront systématiquement interrompues.
436 - `interrupt_wait`: interrompt l'attente (de `wait` ou fin d'un fondu avec
437 attente) et passe directement à l'action suivante. Paramètre :
438 * `wait_id: name` (facultatif) précise l'identifiant du `wait` à stopper
439 (défini par `set_wait_id`, voir les actions `wait` et `stop`). Si absent,
440 interrompt toutes les attentes.
441 - `pause_wait`: met une attente en pause (uniquement pour une attente ayant une
442 durée définie). La touche qui attend cet événement ne continuera pas tant que
443 l'attente n'est pas reprise. Paramètres :
444 * `wait_id: name` (facultatif) précise l'identifiant du `wait` à mettre en
445 pause. Si absent, met en pause toutes les attentes compatibles.
446 - `unpause_wait`: reprend une attente en pause (uniquement pour une attente
447 ayant une durée définie). Le compte à rebours reprendra pour la touche
448 correspondante en train d'attendre. Paramètres:
449 * `wait_id: name` (facultatif) précise l'identifiant du `wait` à reprendre.
450 Si absent, reprend toutes les attentes compatibles.
451 - `reset_wait`: réinitialise une attente (uniquement pour une attente ayant une
452 durée définie). Si l'attente est en pause, le compte à rebours ne recommencera
453 au début que lorsque l'attente sera reprise. Paramètres:
454 * `wait_id: name` (facultatif) précise l'identifiant du `wait` à
455 réinitialiser. Si absent, réinitialise toutes les attentes compatibles.
456 - `run_command` : lance une commande. Paramètres :
457 * `command: my_command` : précise la commande à lancer.
458 * `wait: true/false` (facultatif, défaut : false) : si `wait` est true,
459 attend que la commande ait fini de s'exécuter.
461 ### `aliases` : définir des alias
463 Il est possible de définir des alias pour les différents paramètres. Ces alias
464 sont internes au fichier de configuration ; pour afficher un "joli" nom d'une
465 musique, voir plutôt "music_properties".
467 La syntaxe est la suivante:
477 On utilise ensuite, dans le fichier de configuration, `include: alias1` ou
478 `include: [alias1, alias2]` à la place de `param: value`. Dans le cas de
479 plusieurs aliases inclus contenant des éléments identiques, seul le dernier est
480 pris en compte. Dans tous les cas, les alias ne sont *pas* prioritaires par
481 rapport aux éventuels paramètres définis là où ils sont inclus. Voir les
489 file: "path/to/my/favourite/music.mp3"
496 `music1` est désormais un alias pour `"path/to/my/favourite/music.mp3"`. À
497 chaque fois qu'on veut écrire `file: "path/to/my/favourite/music.mp3"`, on peut
498 écrire à la place `include: music1`. Attention, dans la section
499 "music_properties", les alias ne fonctionnent pas, et il faut écrire le nom du
514 `blue` est un alias pour la couleur `[0, 0, 255]`. À chaque fois qu'on veut
515 écrire `color: [0, 0, 255]`, on peut écrire `include: blue` à la place.
529 `long_time` est un alias pour la durée 42 secondes. Au lieu d'écrire `duration:
530 42`, on peut écrire `include: long_time`.
532 ## Problèmes possibles
534 Sont listés ci-dessous une liste de problèmes rencontrés, avec des solutions
535 proposées. Si vous en découvrez d'autre, contactez l'auteur pour les ajouter à
538 * Le programme se lance et s'arrête tout de suite.
540 Il s'agit généralement d'une erreur de syntaxe dans le fichier de config. Dans
541 ce cas, le terminal doit afficher quelques détails sur l'erreur en question (au
542 moins la ligne correspondante).
544 * La musique "grésille" affreusement.
546 Il peut s'agir d'un problème de latence (avec certains ordinateurs un peu
547 lents). Essayez de changer la latence (par exemple, 0.1 seconde)
549 * Impossible de jouer plus d'une musique à la fois.
551 Le système n'arrive pas à mixer les musiques par lui-même. Vous pouvez essayer
552 de regarder la liste des périphériques de son (`--list-devices`) puis en
553 sélectionner un autre si disponible. Vous pouvez aussi essayer le mixeur intégré
554 à music_sampler, mais les résultats ne sont pas toujours très fluides (ne pas
555 hésiter à jouer avec les paramètres avancés comme latency et blocksize).
557 Si votre système utilise PulseAudio, il peut s'agir d'un problème de
558 configuration du plugin ALSA. Dans ce cas, essayez de mettre la configuration
559 suivante dans `/etc/asound.conf`, puis redémarrer la machine (solution empirique
560 qui semble avoir fonctionné, sans garantie !):
564 fallback "sysdefault"
567 description "Default ALSA Output (currently PulseAudio Sound Server)"
573 fallback "sysdefault"
576 * La console affiche une erreur :
578 Exception in thread Thread-1:
579 Traceback (most recent call last):
580 File "threading.py", line 914, in _bootstrap_inner
581 File "threading.py", line 862, in run
582 File "kivy/input/providers/mtdev.py", line 219, in _thread_run
583 File "kivy/lib/mtdev.py", line 131, in __init__
584 PermissionError: [Errno 13] Permission denied: '/dev/input/event6'
586 C'est une erreur de permission d'accès à un périphérique, généré par la
587 librairie kivy. Elle peut être ignorée et n'aura pas d'incidence.
589 * Pour d'autres problèmes ou bugs à reporter, voir le [Bug
590 Tracker](https://git.immae.eu/mantisbt/view_all_bug_page.php?project_id=1&sort=status%2Clast_updated&dir=ASC%2CDESC)
594 Les extraits de musiques proposés en exemples proviennent de
595 [Jamendo](https://jamendo.com). Les musiques (complètes) sont disponibles en
596 libre téléchargement pour un usage non commercial :
598 [Short Blues](https://www.jamendo.com/track/340173/short-blues)
600 [To the Fantasy war](https://www.jamendo.com/track/778560/to-the-fantasy-war)
602 Le bruit de crocodile provient de
603 [Universal-Soundbank](http://www.universal-soundbank.com/).
605 Cet outil a été développé à l'origine pour faciliter la gestion du son pour les
606 spectacles de la compagnie circassienne [Les pieds
607 jaloux](http://piedsjaloux.fr/). N'ayant pas d'ingénieur son, les artistes
608 eux-mêmes peuvent alors gérer leur musique lorsqu'ils ne sont pas sur scène :
609 d'où la nécessité de préparer les transitions à l'avance et, au moment de la
610 représentation, de réduire l'interaction avec la machine au minimum (une
projects / perso / Immae / Projets / Python / MusicSampler.git / blob