## Pré-requis et installation
-Il faut avoir ffmpeg d'installé. Pour cela, il faut installer le paquet `libav-tools` :
+- Il faut avoir ffmpeg d'installé. Pour cela, il faut installer le paquet `libav-tools` :
- :::bash
+ ```
sudo apt-get install libav-tools
+ ```
+
+Si vous utilisez la version compilée de Music Sampler (cf. plus bas pour un lien de téléchargement), il n'y a rien d'autre à installer.
+
+- Pour utiliser les sources directement, les modules suivants sont requis:
+
+| module | version minimale | commentaire |
+| ----------- | ---------------- | -------------------------------- |
+| Kivy | 1.9.1 | |
+| Markdown | 2.6.6 | pour la documentation uniquement |
+| pydub | 0.16.4 | |
+| Pygame | 1.9.2.dev1 | utilisée par Kivy |
+| Pygments | 2.1.3 | pour la documentation uniquement |
+| sounddevice | 0.3.3 | |
+| transitions | 0.4.1 | |
+| PyYAML | 3.11 | |
+
+Le projet est également disponible via pip:
+
+ pip install music_sampler
+
+- Le programme utilise les polices "Symbola" et "Ubuntu" (Regular / Bold), qui doivent être disponibles.
+
+ ```
+ sudo apt-get install ttf-ancient-fonts ttf-ubuntu-font-family
+ ```
+
+## Version compilée
+
+Une version compilée peut être créée avec pyinstaller:
-Si vous utilisez la version compilée de Music Sampler, il n'y a pas d'installation nécessaire.
+ :::bash
+ pyinstaller music_sampler.spec
+
+## Téléchargements
+
+- Un exemple de configuration ainsi que des musiques associées à l'exemple peuvent être trouvées sur [owncloud](https://outils.immae.eu/owncloud/index.php/s/kSrIe15G1AiZ9YF)
+- Une version précompilée de `music_sampler` peut également être téléchargée [dans le même dossier](https://outils.immae.eu/owncloud/index.php/s/kSrIe15G1AiZ9YF/download?path=%2F&files=music_sampler) (attention, elle n'est pas toujours forcément à jour, lancer le programme avec `-V` pour voir la version compilée)
## 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
* `-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).
## 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é.
- `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.
-
- 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
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
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).
+Si votre système utilise PulseAudio, il peut s'agir d'un problème de configuration du plugin ALSA. Dans ce cas, essayez de mettre la configuration suivante dans `/etc/asound.conf`, puis redémarrer la machine (solution empirique qui semble avoir fonctionné, sans garantie !):
+
+ pcm.!default {
+ type pulse
+ fallback "sysdefault"
+ hint {
+ show on
+ description "Default ALSA Output (currently PulseAudio Sound Server)"
+ }
+ }
+
+ ctl.!default {
+ type pulse
+ fallback "sysdefault"
+ }
+
+ * Pour d'autres problèmes ou bugs à reporter, voir le [Bug Tracker](https://git.immae.eu/mantisbt/view_all_bug_page.php?project_id=1)
## Divers
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 :
projects / perso / Immae / Projets / Python / MusicSampler.git / blobdiff