--- /dev/null
+[TOC]
+
+# Music Sampler
+
+## Description
+
+Music Sampler is a music player which associates each key on the keyboard to a
+set of actions to run.
+
+## Dependencies and installation
+
+- You need ffmpeg installed. For that, you can use package `libav-tools` (debian):
+
+ sudo apt-get install libav-tools
+
+If you use the compiled version of Music Sampler (cf. below for a download
+link), you need nothing else.
+
+- To use sources, the following modules are required:
+
+| module | minimum version | note |
+| ----------- | ---------------- | ------------------------------------------------------------- |
+| Cython | 0.24 | to compile Kivy |
+| Kivy | 1.9.1 | some features require to build/install with flag `USE_SDL2=1` |
+| Markdown | 2.6.6 | for documentation only |
+| pydub | 0.16.4 | |
+| Pygame | 1.9.2.dev1 | used by Kivy |
+| Pygments | 2.1.3 | for documentation only |
+| sounddevice | 0.3.3 | |
+| transitions | 0.4.1 | |
+| PyYAML | 3.11 | |
+
+The project is also available via `pip`:
+
+ pip install music_sampler
+
+The program makes use of fonts "Symbola" and "Ubuntu" (Regular / Bold), that
+must be available on your system, as well as the `portaudio` library:
+
+ sudo apt-get install ttf-ancient-fonts ttf-ubuntu-font-family portaudio
+
+Pour compiler kivy avec la librairie SDL2, il faut certains paquets installés:
+
+ sudo apt-get install libsdl2-dev libsdl2-image-dev libsdl2-mixer-dev libsdl2-ttf-dev
+
+cf [Installation
+Kivy](https://kivy.org/docs/installation/installation-linux.html)
+
+## Compiled version
+
+A compiled version can be created with `pyinstaller`:
+
+ :::bash
+ pyinstaller music_sampler.spec
+
+## Downloads
+
+- An example configuration together with some music examples can be found on
+ [owncloud](https://outils.immae.eu/owncloud/index.php/s/kSrIe15G1AiZ9YF)
+- A precompiled version of `music_sampler` can also be found
+ [in the same folder](https://outils.immae.eu/owncloud/index.php/s/kSrIe15G1AiZ9YF/download?path=%2F&files=music_sampler)
+ (beware, it might not be up-to-date, please run the program with `-V` to see
+ its corresponding version)
+
+## Usage
+
+The whole job consists in preparing all the transitions in the configuration
+file `config.yml`.
+
+The program should then be run in the folder in which the configuration file
+lies (see below for an advanced use). A window with a keyboard appears. The
+orange circle in the upper-right corner of the keyboard becomes green one every
+music is loaded (or red in case of problem). A key is semi-transparent and
+crossed when it is not usable at the moment: either because a music handled by
+this key is not loaded yet (it may take some time when the program launches), or
+because it has an action running.
+
+An example configuration file is given with some keys and transitions. The
+structure of the file (explained more in details below) should be easy to
+understand just by looking at it.
+
+### Possible actions
+
+ - Clic on a key: shows the associated actions in the bottom-left block of the
+ app.
+ - Key stroke: if available, runs the actions associated to this key. When a
+ key has currently running actions, his surround is black. Note that an
+ action like "play a music" is almost instantaneous as it is considered
+ "done" as soon as the music started playing.
+ To prevent accidents in case of repeated stroke on a key, `Music Sampler`
+ won't rerun the actions associated to that key if they are not already
+ finished.
+ - Ctrl+C or Ctrl+Q: leaves the program.
+ - Ctrl+R: reloads the configuration file
+
+### Options available at launch
+
+All the options below are optional; usually, running the program in the correct
+folder is enough
+
+ * `-h, --help`: shows a list of available options
+ * `-c CONFIG, --config CONFIG`: gives the configuration file to load (by
+ default, `config.yml` in the current folder).
+ * `-p MUSIC_PATH, --music-path MUSIC_PATH`: gives the path to find the musics
+ (by default, the current folder)
+ * `-d, --debug`: show debug informations in the terminal (disabled by default)
+ * `-V, --version`: show current version and exit (only for the compiled
+ version)
+ * `-L, --language`: change application language. Current languages: fr, en
+ (default 'fr')
+ * `--no-focus-warning`: don't show warning when focus gets lost.
+
+The following options are reserved for a more advanced use of Music Sampler, or
+in case of problem with the standard configuration:
+
+ * `-m, --builtin-mixing`: make the sound mixing locally. By default, Music
+ Sampler will let the system do it and open one channel per music loaded. Use
+ it only if the system cannot handle it.
+ * `-l LATENCY, --latency LATENCY`: "low", "high" or a number of seconds
+ (default "high")
+ * `-b BLOCKSIZE, --blocksize BLOCKSIZE`: Number of frames for each mixing
+ step. 0 (default) lets the program choose.
+ * `-f FRAME_RATE, --frame-rate FRAME_RATE`: default 44100Hz
+ * `-x CHANNELS, --channels CHANNELS` : Number of channels per music (default
+ 2, for stereo)
+ * `-s SAMPLE_WIDTH, --sample-width SAMPLE_WIDTH`: number of bytes per frame
+ (default 2).
+ * `--device DEVICE` : select another sound device.
+ * `--list-devices` : list available sound devices.
+ * `-- ARGS` : arguments for Kivy library.
+
+## Configure keys
+
+**Warning: the format of the configuration file is still a work in progress and
+may change without ensuring backward compatibility**
+
+The file `config.yml` uses yaml syntax. Categories and sub-categories are
+handled by space indentations (no tabs). Symbol `#` may be used for comments.
+
+In case of error in the configuration file, an error message will show up.
+Depending on its severity, Music Sampler may try to continue (ignoring
+corresponding problems) or abort.
+
+The file contains several sections:
+
+ :::yaml
+ aliases:
+ ...
+
+ music_properties:
+ ...
+
+ key_properties:
+ ...
+
+ keys:
+ ...
+
+
+### `music_properties`
+
+This section lets you define global properties for the musics.
+
+#### Examples
+
+ :::yaml
+ "music1.mp3":
+ name: My favorite music
+ gain: 1.4
+Music "music1.mp3" is named "My favorite music". She is loaded at 140% of its
+normal volume.
+
+ :::yaml
+ "music2.mp3":
+ gain: 0.7
+
+Music "music2.mp3" is loaded at 70% of its normal volume.
+
+#### List of available options
+- `name: My music` User-friendly name of the music, used in the interface
+ instead of the filename.
+
+- `gain: x` Loads the music with that initial gain x. This lets you equalize all
+ your music at desired level, independently of the volume afterwards.
+
+### `key_properties`: drawing and properties of keys
+
+This section lets you describe the drawing of the key: color, description. By
+default, a key assigned to one or more actions is shown in green
+
+#### Examples
+
+ :::yaml
+ 'ESC':
+ description:
+ -
+ - STOP!
+ color: [255, 0, 0]
+ repeat_delay: 2
+
+The "esc" key is red, and text "STOP!" is shown on the second line. The key is
+protected for 2 seconds after each stroke.
+
+#### List of availale options
+- `description`: the text on the key. Each item is shown on a line (no automatic
+ line break). First line is shown just next to the "key" name and is in bold.
+ On a standard screen, you may have about 3 lines visible (including the first
+ one)
+- `color: [r, g, b]`: the key color. r, g and b are the proportions respectively
+ of red, green and blue, and each value must be between 0 and 255
+- `repeat_delay: x` (default 0) : protection delay. Once all its actions are
+ done, the key will remain disabled (semi-transparent and crossed) for that
+ amount of time (in seconds).
+
+### `keys` : actions related to keys
+
+This section lets you describe for each key, the list of actions associated to
+it. Note that except for `wait` and some particular cases (see below), all the
+actions are almost instantaneous.
+
+
+#### Examples
+
+ :::yaml
+ 'a':
+ - play:
+ file: "music1.mp3"
+ volume: 70
+ start_at: 10
+ - wait:
+ duration: 5
+ - stop:
+ file: "music1.mp3"
+ fade_out: 2
+
+Runs music "music1.mp3" at 70% of its maximum volume, at 10 seconds from the
+start, then stops the music 5 seconds later with a 2 seconds fade out.
+
+ :::yaml
+ 'b':
+ - stop:
+ file: "music1.mp3"
+ fade_out: 5
+ wait: false
+ - play:
+ file: "music2.mp3"
+ fade_in: 5
+
+Make a cross fade of 5 seconds between "music1.mp3" and "music2.mp3"
+
+ :::yaml
+ 'c':
+ - stop:
+ file: "music1.mp3"
+ fade_out: 5
+ wait: true
+ - wait:
+ duration: 2
+ - play:
+ file: "music2.mp3"
+ - seek:
+ file: "music2.mp3"
+ delta: false
+ value: 60
+Stops music "music1.mp3" with a 5 seconds fade out, waits for the end of the
+fade out, plus 2 seconds, and then runs "music2.mp3" skipping the first minute.
+
+ :::yaml
+ 'd':
+ - volume:
+ file: "music1.mp3"
+ value: 50
+ - play:
+ file: "noise.mp3"
+ loop: 1
+ - wait:
+ file: "noise.mp3"
+ - volume:
+ file: "music1.mp3"
+ value: 100
+
+Lower volume of "music1.mp3" while "noise.mp3" is played above it (twice). Then
+the volume of the music comes back to normal.
+
+ :::yaml
+ 'e':
+ - pause:
+ file: "music1.mp3"
+ - wait:
+ duration: 10
+ - unpause:
+ file: "music1.mp3"
+ - seek:
+ file: "music1.mp3"
+ delta: true
+ value: 5
+
+Pauses "music1.mp3" for 10 seconds and reruns it afterward, seeking to 5 seconds
+later.
+
+#### List of all the actions:
+- `play` : start a music. Music Sampler only runs a music once (if you want to
+ have it playing several time concurrently, duplicate it or make symbolic
+ link). Parameters:
+ * `file: "music.mp3"` gives the played music (relative path).
+ * `fade_in: x` (optional) runs the music with x seconds fade in.
+ * `volume: x` (optional, default 100) sets the volume of the music.
+ * `loop: x` (optional, default 0) music should be repeated x times. Indicate
+ -1 for infinite loop. Note: x is the number of repetitions, thus the music
+ is actually played x+1 times.
+ * `start_at: x` (optional, default 0) start music skipping the first x
+ seconds.
+ * `restart_if_running: true/false` (optional, default false) if the music is
+ already running, stop it and restart it.
+- `stop` : stops a given music. Parameters:
+ * `file: "music.mp3"` (optional) gives the music to stop. If no music is
+ given, stops all of them.
+ * `fade_out: x` (optional) stops music with a x seconds fade out.
+ * `wait: true/false` (optional, default: false) when stopping with a fade
+ out, wait for the fade to finish before continuing to the next actions. If
+ the music stops naturally before the en of the fade out, the wait stops
+ there too. When several musics are stopped in fade out, the `wait` only
+ waits for the last one in the playlist (which can finish naturally before
+ the others).
+ * `set_wait_id: name` (optional, useless when `wait` is false) sets an id
+ `name` to the wait (see `interrupt_wait`). Any valid string may be used.
+- `volume` : change the volume of a given music. Parameters:
+ * `file: "music.mp3"` (optional) which music to change. If no music is
+ given, the global volume is changed.
+ * `delta: true/false` (optional, default false) add/remove to the volume
+ instead of setting an absolute value.
+ * `value: x` if delta is false, sets the volume to x%. Note that this factor
+ is applied to the music already loaded (with the initial gain). If delta
+ is true, adds or remove the percentage to the current volume.
+ * `fade: x` (optional) the volume change is applied with a x seconds fade.
+- `pause` : pause a music. Parameters:
+ * `file: "music.mp3"` (optional) gives the music to pause. If no music is
+ given, it applies to all playing musics.
+- `unpause` : unpause a music. Parameters:
+ * `file: "music.mp3"` (optional) gives the msuic to unpause. If no music is
+ given, it applies to all paused musics.
+- `wait` : wait for some time or for an event. Parameters:
+ * `file: "music.mp3"` (optional) wait for the end of music "music.mp3"
+ * `duration: x` (optional) wait x seconds. If `file` and `duration` are
+ given, wait the end of the music PLUS the `duration`.
+ * `set_wait_id: name` (optional) gives an id to the wait event (see
+ `interrupt_wait`). The id can be any valid string.
+Note again that this action is one of the only action that is not almost
+instantaneous. Use it wherever you need to make some time adjustments for other
+actions.
+- `seek` : seek to a specific position in a music. Parameters:
+ * `file: "music.mp3"` (optional) gives the music to seek. If no music is
+ given, applies to all playing musics.
+ * `delta: true/false` (optional, default false) If `delta` is true, the time
+ seek is relative. Otherwise, it is absolute.
+ * `value: x` If `delta` is true, then moves the music forward or backward by
+ x seconds. If delta is false, the music goes to that position. If the
+ music is fading (fade in or volume fade), the effect is immediately
+ interrupted. If the music is fading out, the "seek" is ignored. In case of
+ `loop`, a relative seek may jump to previous or next loop if possible,
+ while an absolute seek will jump to a position in the current loop.
+- `stop_all_actions:` Interrupts all the running and pending actions. Note that
+ a started music (even with a `loop` option) is the result of an action that is
+ already finished and thus will keep playing (see `stop` for that). Parameters:
+ * `other_only: true/false` (optional, default false): if `other_only` is
+ true, the interruption is valid for all keys except the one that ran the
+ action. When false, it is thus useless to add actions after that one.
+- `interrupt_wait`: stop a wait event (normal `wait` or fade out wait). The keys
+ that were waiting will move to the next actions. Parameters:
+ * `wait_id: name` : gives the id of the `wait` to interrupt (defined with
+ `set_wait_id`, see actions `wait` and `stop`). To interrupt several waits,
+ use the same action several times.
+- `run_command` : Run a command. Parameters:
+ * `command: my_command` : Gives the command to run.
+ * `wait: true/false` (optional, default false) if true, waits for the
+ command to finish (this wait is not interruptible by interrupt_wait)
+
+### `aliases` : define aliases
+
+It is possible to define some aliases for the parameters. Those aliases are
+internal to the configuration file. To give a nice name to a music, see
+"music_properties".
+
+The aliases syntax is the following:
+
+ :::yaml
+ aliases:
+ alias1:
+ param: value
+ alias2:
+ param1: value1
+ param2: value2
+
+You can then use in other places of the configuration file a special argument
+`include: alias1` or `include: [alias1, alias2]` instead of `param: value`. In
+the case of several aliases that have identical elements, only the last one is
+kept. In all cases, a value defined outside of an include takes precedence. See
+below examples.
+
+#### Examples
+
+ :::yaml
+ aliases:
+ music1:
+ file: "path/to/my/favourite/music.mp3"
+
+ keys:
+ 'a':
+ play:
+ include: music1
+
+`music1` is now an alias for `file: "path/to/my/favourite/music.mp3"`. You can
+use `include: music1` at any place where you would have written `file:
+"path/to/my/favourite/music.mp3"`. Aliases cannot be used in section
+"music_properties".
+
+ :::yaml
+ aliases:
+ blue:
+ color: [0, 0, 255]
+
+ keys_properties:
+ 'a':
+ description:
+ -
+ - blue key
+ include: blue
+
+`blue` is an alias for color `[0, 0, 255]`. Wherever you need to specify `color:
+[0, 0, 255]`, you may write `include: blue` instead.
+
+ :::yaml
+ aliases:
+ long_time:
+ duration: 42
+
+ keys:
+ 'b':
+ wait:
+ include: long_time
+ play:
+ file: "music1.mp3"
+
+`long_time` is an alias for a 42 seconds duration. Instead of `duration: 42`,
+you may use `include: long_time`.
+
+## Troubleshooting
+
+You'll find below a list of possible problems, and a possible solution. If you
+find some other problems, please contact the author.
+
+* The program starts and stops immediately.
+
+It is usually a syntax error in the config file. In that case, the terminal
+should give some informations.
+
+* The music sizzles
+
+It may be a latency problems (with slow computers). Try to adapt it to a higher
+value (~0.1 seconds)
+
+* Impossible to play more than one music at a time.
+
+The system cannot mix the musics by itself. You may have a look at the device
+list (`--list-devices`) and choose another. You may also try the integrated
+mixer, but the result may not be very fluid (you will certainly need to adjust
+blocksize and latency parameters if you do that)
+
+If your system uses PulseAudio, it may be a configuration problem for the ALSA
+plugin. In that case, try to put the following configuration in
+`/etc/asound.conf` and restart your system. This is an empirical solution that
+seems to have worked, there is no garanty that it will!
+
+ pcm.!default {
+ type pulse
+ fallback "sysdefault"
+ hint {
+ show on
+ description "Default ALSA Output (currently PulseAudio Sound Server)"
+ }
+ }
+
+ ctl.!default {
+ type pulse
+ fallback "sysdefault"
+ }
+
+* The terminal shows an error:
+
+ Exception in thread Thread-1:
+ Traceback (most recent call last):
+ File "threading.py", line 914, in _bootstrap_inner
+ File "threading.py", line 862, in run
+ File "kivy/input/providers/mtdev.py", line 219, in _thread_run
+ File "kivy/lib/mtdev.py", line 131, in __init__
+ PermissionError: [Errno 13] Permission denied: '/dev/input/event6'
+
+This is a device permission error. It can be safely ignored.
+
+* For other problems or bug, please see [Bug
+ Tracker](https://git.immae.eu/mantisbt/view_all_bug_page.php?project_id=1&sort=status%2Clast_updated&dir=ASC%2CDESC)
+
+## About
+
+The musics in the examples come from [Jamendo](https://jamendo.com). The
+complete version of those musics are available for free for a non-commercial
+use:
+
+[Short Blues](https://www.jamendo.com/track/340173/short-blues)
+
+[To the Fantasy war](https://www.jamendo.com/track/778560/to-the-fantasy-war)
+
+The crocodile noise comes from
+[Universal-Soundbank](http://www.universal-soundbank.com/).
+
+This program was developped originaly to help handling music for shows of the
+circus company [Les pieds jaloux](http://piedsjaloux.fr/). With no available
+sound manager, the artists sometimes had to run from the scene to make the sound
+transitions, making as little interaction as possible with the computed (one
+key).
## Description
-Music Sampler est un lecteur de musique qui permet de pré-programmer des transitions musicales, qui peuvent ensuite être lancées à l'aide d'un simple appui sur une touche.
+Music Sampler est un lecteur de musique qui permet de pré-programmer des
+transitions musicales, qui peuvent ensuite être lancées à l'aide d'un simple
+appui sur une touche.
## 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` (debian) :
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.
+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 |
-| ----------- | ---------------- | --------------------------------------------------------------------------- |
-| Cython | 0.24 | pour compiler Kivy |
-| Kivy | 1.9.1 | certaines fonctionnalités nécessitent de compiler/installer avec USE_SDL2=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 | |
+| module | version minimale | commentaire |
+| ----------- | ---------------- | ----------------------------------------------------------------------------- |
+| Cython | 0.24 | pour compiler Kivy |
+| Kivy | 1.9.1 | certaines fonctionnalités nécessitent de compiler/installer avec `USE_SDL2=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:
+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, et la librairie portaudio:
+Le programme utilise les polices `Symbola` et `Ubuntu` (Regular / Bold), qui
+doivent être disponibles, et la librairie `portaudio`:
sudo apt-get install ttf-ancient-fonts ttf-ubuntu-font-family portaudio
sudo apt-get install libsdl2-dev libsdl2-image-dev libsdl2-mixer-dev libsdl2-ttf-dev
-cf [Installation Kivy](https://kivy.org/docs/installation/installation-linux.html)
+cf [Installation
+Kivy](https://kivy.org/docs/installation/installation-linux.html)
## Version compilée
## 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)
+- 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.
+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. 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.
+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.
+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.
### 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).
+ - 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
-Toutes les options au lancement sont facultatives ; la plupart du temps lancer le programme dans le bon dossier suffit.
+Toutes les options au lancement sont facultatives ; la plupart du temps lancer
+le programme dans le bon dossier suffit.
* `-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).
+ * `-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).
- * `-L, --language` : change la langue de l'application. Actuellement: fr, en (par défaut 'fr')
- * `--no-focus-warning`: Ne pas afficher d'avertissement lorsque l'application perd le focus.
-
-Les options suivantes sont plutôt réservées à un usage avancé de music_sampler, ou en cas de problème avec la configuration standard :
-
- * `-m, --builtin-mixing` Effectue en interne le mixage des sons. Par défaut, music_sampler confie le mixage au système : n'activer cette option que si le système n'y parvient pas.
- * `-l LATENCY, --latency LATENCY` : latence. Préciser "low", "high" ou un nombre de secondes (par défaut, "high")
- * `-b BLOCKSIZE, --blocksize BLOCKSIZE` : taille des blocs. Nombre de frames pour chaque étape du mixeur. 0 (par défaut) signifie que le programme choisit lui-même le nombre qui lui convient.
- * `-f FRAME_RATE, --frame-rate FRAME_RATE` : fréquence d'échantillonnage pour jouer les musiques. Par défaut : 44100
- * `-x CHANNELS, --channels CHANNELS` : nombre de canaux par musique (2 par défaut, pour une écoute stéréo)
- * `-s SAMPLE_WIDTH, --sample-width SAMPLE_WIDTH` : largeur d'échantillonnage (nombre d'octets pour chaque frame). Par défaut : 2.
+ * `-V, --version` : affiche la version courante et quitte (utilisable
+ uniquement pour la version compilée).
+ * `-L, --language` : change la langue de l'application. Actuellement: fr, en
+ (par défaut 'fr')
+ * `--no-focus-warning`: Ne pas afficher d'avertissement lorsque l'application
+ perd le focus.
+
+Les options suivantes sont plutôt réservées à un usage avancé de music_sampler,
+ou en cas de problème avec la configuration standard :
+
+ * `-m, --builtin-mixing` Effectue en interne le mixage des sons. Par défaut,
+ music_sampler confie le mixage au système : n'activer cette option que si le
+ système n'y parvient pas.
+ * `-l LATENCY, --latency LATENCY` : latence. Préciser "low", "high" ou un
+ nombre de secondes (par défaut, "high")
+ * `-b BLOCKSIZE, --blocksize BLOCKSIZE` : taille des blocs. Nombre de frames
+ pour chaque étape du mixeur. 0 (par défaut) signifie que le programme
+ choisit lui-même le nombre qui lui convient.
+ * `-f FRAME_RATE, --frame-rate FRAME_RATE` : fréquence d'échantillonnage pour
+ jouer les musiques. Par défaut : 44100
+ * `-x CHANNELS, --channels CHANNELS` : nombre de canaux par musique (2 par
+ défaut, pour une écoute stéréo)
+ * `-s SAMPLE_WIDTH, --sample-width SAMPLE_WIDTH` : largeur d'échantillonnage
+ (nombre d'octets pour chaque frame). Par défaut : 2.
* `--device DEVICE` : sélectionne le périphérique de son.
* `--list-devices` : Affiche la liste des périphériques de son disponibles.
* `-- ARGS` : Arguments à passer à la librairie Kivy.
## Configurer les touches
-**ATTENTION : le format du fichier de configuration est susceptible d'évoluer, sans garantie de rétrocompatibilité.**
+**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é.
+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é.
-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 erronées (en colorant éventuellement la touche en noir), ou ne se lance pas du tout.
+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 erronées (en colorant éventuellement la touche en noir), ou
+ne se lance pas du tout.
Le fichier contient plusieurs sections :
"music1.mp3":
name: My favorite music
gain: 1.4
-La musique "music1.mp3" est désignée par le nom "My favorite music". Elle est chargée à 140% de son volume normal.
+La musique "music1.mp3" est désignée par le nom "My favorite music". Elle est
+chargée à 140% de son volume normal.
:::yaml
"music2.mp3":
La musique "music2.mp3" est chargée à 70% de son volume normal.
#### Liste des options possibles
-- `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.
+- `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 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.
+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.
#### Exemples
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. Si on appuie deux fois sur la même touche à moins de deux secondes d'intervalle, le second appui est ignoré.
+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.
+- `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-instantané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
file: "music1.mp3"
fade_out: 2
-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.
+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':
file: "music2.mp3"
delta: false
value: 60
-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.
+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.
:::yaml
'd':
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 les deux écoutes du son "noise" sont terminées.
+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':
delta: true
value: 5
-Met en pause la musique "music1.mp3" pour 10 secondes et la relance après, en avançant de 5 secondes dans la musique.
+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. 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 :
+- `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.
- * `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.
- * `restart_if_running: true/false` (facultatif, défaut : false) la musique est éventuellement stoppée et redémarrée si nécessaire
+ * `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.
+ * `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.
+ * `restart_if_running: true/false` (facultatif, défaut : false) la musique
+ est éventuellement stoppée et redémarrée si nécessaire
- `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.
+ * `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.
- * `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. Lorsque plusieurs musiques sont stoppées en fondu, le `wait` n'attend que la dernière musique de la playlist (qui peut se terminer naturellement avant les autres).
- * `set_wait_id: name` (facultatif, inutile lorsque `wait` est à false) donne l'identifiant `name` à l'attente de fin du fondu (voir `interrupt_wait`). L'identifiant peut être n'importe quelle chaîne de caractère.
+ * `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. Lorsque plusieurs
+ musiques sont stoppées en fondu, le `wait` n'attend que la dernière
+ musique de la playlist (qui peut se terminer naturellement avant les
+ autres).
+ * `set_wait_id: name` (facultatif, inutile lorsque `wait` est à false) donne
+ l'identifiant `name` à l'attente de fin du fondu (voir `interrupt_wait`).
+ L'identifiant peut être n'importe quelle chaîne de caractère.
- `volume` : change le volume d'une musique donnée. Paramètres :
- * `file: "music.mp3"` (facultatif) précise la musique. Si aucune musique n'est précisée, la modification s'applique au volume global.
- * `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.
- * `value: x` Si delta est à false, met le volume à x% du volume max (x doit être entre 0 et 100).
-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.
-Si delta est à true, applique un modificateur de x% au volume (x doit être un entier signé).
-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%.
- * `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.
+ * `file: "music.mp3"` (facultatif) précise la musique. Si aucune musique
+ n'est précisée, la modification s'applique au volume global.
+ * `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.
+ * `value: x` Si delta est à false, met le volume à x% du volume max (x doit
+ être entre 0 et 100). 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.
+Si delta est à true, applique un modificateur de x% au volume (x doit être un
+entier signé). 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%.
+ * `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.
- `pause` : met en pause une musique. Paramètres :
- * `file: "music.mp3"` (facultatif) précise la musique à mettre en pause. Si non précisé, s'applique à toutes les musiques.
-- `unpause` : relance une musique mise en pause (là où elle en était). Paramètres :
- * `file: "music.mp3"` (facultatif) précise la musique à relancer. Si non précisé, s'applique à toutes les musiques.
+ * `file: "music.mp3"` (facultatif) précise la musique à mettre en pause. Si
+ non précisé, s'applique à toutes les musiques.
+- `unpause` : relance une musique mise en pause (là où elle en était).
+ Paramètres :
+ * `file: "music.mp3"` (facultatif) précise la musique à relancer. Si non
+ précisé, s'applique à toutes les musiques.
- `wait` : attend un temps donné. Paramètres :
* `file: "music.mp3"` (facultatif) attend la fin de la musique "music.mp3"
- * `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`.
- * `set_wait_id: name` (facultatif) donne l'identifiant `name` à l'attente (voir `interrupt_wait`). L'identifiant peut être n'importe quelle chaîne de caractère.
-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.
+ * `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`.
+ * `set_wait_id: name` (facultatif) donne l'identifiant `name` à l'attente
+ (voir `interrupt_wait`). L'identifiant peut être n'importe quelle chaîne
+ de caractère.
+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). 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`.
+ * `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). 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.
+ * `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
-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".
+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:
param1: value1
param2: value2
-On utilise ensuite, dans le fichier de configuration, `include: alias1` ou `include: [alias1, alias2]` à la place de `param: value`. Dans le cas de plusieurs aliases inclus contenant des éléments identiques, seul le dernier est pris en compte. Dans tous les cas, les alias ne sont *pas* prioritaires par rapport aux éventuels paramètres définis là où ils sont inclus. Voir les exemples ci-dessous.
+On utilise ensuite, dans le fichier de configuration, `include: alias1` ou
+`include: [alias1, alias2]` à la place de `param: value`. Dans le cas de
+plusieurs aliases inclus contenant des éléments identiques, seul le dernier est
+pris en compte. Dans tous les cas, les alias ne sont *pas* prioritaires par
+rapport aux éventuels paramètres définis là où ils sont inclus. Voir les
+exemples ci-dessous.
#### Exemples
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 "music_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:
- blue key
include: blue
-`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.
+`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.
:::yaml
aliases:
play:
file: "music1.mp3"
-`long_time` est un alias pour la durée 42 secondes. Au lieu d'écrire `duration: 42`, on peut écrire `include: long_time`.
+`long_time` est un alias pour la durée 42 secondes. Au lieu d'écrire `duration:
+42`, on peut écrire `include: long_time`.
## Problèmes possibles
-Sont listés ci-dessous une liste de problèmes rencontrés, avec des solutions proposées. Si vous en découvrez d'autre, contactez l'auteur pour les ajouter à la liste.
+Sont listés ci-dessous une liste de problèmes rencontrés, avec des solutions
+proposées. Si vous en découvrez d'autre, contactez l'auteur pour les ajouter à
+la liste.
* 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).
+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.
-Il peut s'agir d'un problème de latence (avec certains ordinateurs un peu lents). Essayez de changer la latence (par exemple, 0.1 seconde)
+Il peut s'agir d'un problème de latence (avec certains ordinateurs un peu
+lents). Essayez de changer la latence (par exemple, 0.1 seconde)
* Impossible de jouer plus d'une musique à la fois.
-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).
+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 !):
+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
File "kivy/lib/mtdev.py", line 131, in __init__
PermissionError: [Errno 13] Permission denied: '/dev/input/event6'
-C'est une erreur de permission d'accès à un périphérique, généré par la librairie kivy. Elle peut être ignorée et n'aura pas d'incidence.
+C'est une erreur de permission d'accès à un périphérique, généré par la
+librairie kivy. Elle peut être ignorée et n'aura pas d'incidence.
+
+* 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&sort=status%2Clast_updated&dir=ASC%2CDESC)
-* 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&sort=status%2Clast_updated&dir=ASC%2CDESC)
## 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 :
+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 :
[Short Blues](https://www.jamendo.com/track/340173/short-blues)
[To the Fantasy war](https://www.jamendo.com/track/778560/to-the-fantasy-war)
-Le bruit de crocodile provient de [Universal-Soundbank](http://www.universal-soundbank.com/).
+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).
+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).
projects / perso / Immae / Projets / Python / MusicSampler.git / commitdiff
