aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorIsmaël Bouya <ismael.bouya@normalesup.org>2016-08-11 21:36:12 +0200
committerIsmaël Bouya <ismael.bouya@normalesup.org>2016-08-11 21:47:55 +0200
commitfaed2fa84ff988067532ae880df1ca00efb6a993 (patch)
tree4f08cf1421a6bcbd481374d5317f60104dbe335d
parent814c30c6835b25d06977af1dd2d1e565c45121cc (diff)
downloadMusicSampler-faed2fa84ff988067532ae880df1ca00efb6a993.tar.gz
MusicSampler-faed2fa84ff988067532ae880df1ca00efb6a993.tar.zst
MusicSampler-faed2fa84ff988067532ae880df1ca00efb6a993.zip
Add english documentation1.2.2
-rw-r--r--README2
-rw-r--r--build_readme.py25
-rw-r--r--documentation_en.md520
-rw-r--r--documentation_fr.md380
4 files changed, 820 insertions, 107 deletions
diff --git a/README b/README
index 6017dcd..627e5da 100644
--- a/README
+++ b/README
@@ -1,7 +1,7 @@
1Music Sampler is a music player which associates each key on the keyboard to a 1Music Sampler is a music player which associates each key on the keyboard to a
2set of actions to run. 2set of actions to run.
3 3
4See full documentation in french in documentation_fr.md 4See full documentation in documentation_fr.md or documentation_en.md
5 5
6Git repository: 6Git repository:
7https://git.immae.eu/?p=perso/Immae/Projets/Python/MusicSampler.git 7https://git.immae.eu/?p=perso/Immae/Projets/Python/MusicSampler.git
diff --git a/build_readme.py b/build_readme.py
index 655e001..9f33dbd 100644
--- a/build_readme.py
+++ b/build_readme.py
@@ -1,7 +1,17 @@
1import markdown 1import markdown
2from markdown.extensions.toc import slugify
2 3
3html = markdown.markdownFromFile( 4def lang_slugify(lang):
4 input="documentation_fr.md", 5 def l_slugify(value, separator):
6 return slugify(lang + "__" + value, separator)
7 return l_slugify
8
9def get_markdown(md_file, lang, table_of_content):
10 with open(md_file, "r") as f:
11 text = f.read()
12
13 return markdown.markdown(
14 text=text,
5 extensions=[ 15 extensions=[
6 'markdown.extensions.codehilite', 16 'markdown.extensions.codehilite',
7 'markdown.extensions.toc', 17 'markdown.extensions.toc',
@@ -12,6 +22,15 @@ html = markdown.markdownFromFile(
12 'noclasses': True, 22 'noclasses': True,
13 }, 23 },
14 'markdown.extensions.toc': { 24 'markdown.extensions.toc': {
15 'title': 'Sommaire' 25 'title': table_of_content,
26 'slugify': lang_slugify(lang)
16 } 27 }
17 }) 28 })
29
30
31print("<p><a href='#lang-en'>Documenation in english</a></p>")
32print("<p><a href='#lang-fr'>Documenation en Français</a></p>")
33print("<hr id='lang-en'/>")
34print(get_markdown("documentation_en.md", "en", "Table of contents"))
35print("<hr id='lang-fr'/>")
36print(get_markdown("documentation_fr.md", "fr", "Sommaire"))
diff --git a/documentation_en.md b/documentation_en.md
new file mode 100644
index 0000000..87b9bd7
--- /dev/null
+++ b/documentation_en.md
@@ -0,0 +1,520 @@
1[TOC]
2
3# Music Sampler
4
5## Description
6
7Music Sampler is a music player which associates each key on the keyboard to a
8set of actions to run.
9
10## Dependencies and installation
11
12- You need ffmpeg installed. For that, you can use package `libav-tools` (debian):
13
14 sudo apt-get install libav-tools
15
16If you use the compiled version of Music Sampler (cf. below for a download
17link), you need nothing else.
18
19- To use sources, the following modules are required:
20
21| module | minimum version | note |
22| ----------- | ---------------- | ------------------------------------------------------------- |
23| Cython | 0.24 | to compile Kivy |
24| Kivy | 1.9.1 | some features require to build/install with flag `USE_SDL2=1` |
25| Markdown | 2.6.6 | for documentation only |
26| pydub | 0.16.4 | |
27| Pygame | 1.9.2.dev1 | used by Kivy |
28| Pygments | 2.1.3 | for documentation only |
29| sounddevice | 0.3.3 | |
30| transitions | 0.4.1 | |
31| PyYAML | 3.11 | |
32
33The project is also available via `pip`:
34
35 pip install music_sampler
36
37The program makes use of fonts "Symbola" and "Ubuntu" (Regular / Bold), that
38must be available on your system, as well as the `portaudio` library:
39
40 sudo apt-get install ttf-ancient-fonts ttf-ubuntu-font-family portaudio
41
42Pour compiler kivy avec la librairie SDL2, il faut certains paquets installés:
43
44 sudo apt-get install libsdl2-dev libsdl2-image-dev libsdl2-mixer-dev libsdl2-ttf-dev
45
46cf [Installation
47Kivy](https://kivy.org/docs/installation/installation-linux.html)
48
49## Compiled version
50
51A compiled version can be created with `pyinstaller`:
52
53 :::bash
54 pyinstaller music_sampler.spec
55
56## Downloads
57
58- An example configuration together with some music examples can be found on
59 [owncloud](https://outils.immae.eu/owncloud/index.php/s/kSrIe15G1AiZ9YF)
60- A precompiled version of `music_sampler` can also be found
61 [in the same folder](https://outils.immae.eu/owncloud/index.php/s/kSrIe15G1AiZ9YF/download?path=%2F&files=music_sampler)
62 (beware, it might not be up-to-date, please run the program with `-V` to see
63 its corresponding version)
64
65## Usage
66
67The whole job consists in preparing all the transitions in the configuration
68file `config.yml`.
69
70The program should then be run in the folder in which the configuration file
71lies (see below for an advanced use). A window with a keyboard appears. The
72orange circle in the upper-right corner of the keyboard becomes green one every
73music is loaded (or red in case of problem). A key is semi-transparent and
74crossed when it is not usable at the moment: either because a music handled by
75this key is not loaded yet (it may take some time when the program launches), or
76because it has an action running.
77
78An example configuration file is given with some keys and transitions. The
79structure of the file (explained more in details below) should be easy to
80understand just by looking at it.
81
82### Possible actions
83
84 - Clic on a key: shows the associated actions in the bottom-left block of the
85 app.
86 - Key stroke: if available, runs the actions associated to this key. When a
87 key has currently running actions, his surround is black. Note that an
88 action like "play a music" is almost instantaneous as it is considered
89 "done" as soon as the music started playing.
90 To prevent accidents in case of repeated stroke on a key, `Music Sampler`
91 won't rerun the actions associated to that key if they are not already
92 finished.
93 - Ctrl+C or Ctrl+Q: leaves the program.
94 - Ctrl+R: reloads the configuration file
95
96### Options available at launch
97
98All the options below are optional; usually, running the program in the correct
99folder is enough
100
101 * `-h, --help`: shows a list of available options
102 * `-c CONFIG, --config CONFIG`: gives the configuration file to load (by
103 default, `config.yml` in the current folder).
104 * `-p MUSIC_PATH, --music-path MUSIC_PATH`: gives the path to find the musics
105 (by default, the current folder)
106 * `-d, --debug`: show debug informations in the terminal (disabled by default)
107 * `-V, --version`: show current version and exit (only for the compiled
108 version)
109 * `-L, --language`: change application language. Current languages: fr, en
110 (default 'fr')
111 * `--no-focus-warning`: don't show warning when focus gets lost.
112
113The following options are reserved for a more advanced use of Music Sampler, or
114in case of problem with the standard configuration:
115
116 * `-m, --builtin-mixing`: make the sound mixing locally. By default, Music
117 Sampler will let the system do it and open one channel per music loaded. Use
118 it only if the system cannot handle it.
119 * `-l LATENCY, --latency LATENCY`: "low", "high" or a number of seconds
120 (default "high")
121 * `-b BLOCKSIZE, --blocksize BLOCKSIZE`: Number of frames for each mixing
122 step. 0 (default) lets the program choose.
123 * `-f FRAME_RATE, --frame-rate FRAME_RATE`: default 44100Hz
124 * `-x CHANNELS, --channels CHANNELS` : Number of channels per music (default
125 2, for stereo)
126 * `-s SAMPLE_WIDTH, --sample-width SAMPLE_WIDTH`: number of bytes per frame
127 (default 2).
128 * `--device DEVICE` : select another sound device.
129 * `--list-devices` : list available sound devices.
130 * `-- ARGS` : arguments for Kivy library.
131
132## Configure keys
133
134**Warning: the format of the configuration file is still a work in progress and
135may change without ensuring backward compatibility**
136
137The file `config.yml` uses yaml syntax. Categories and sub-categories are
138handled by space indentations (no tabs). Symbol `#` may be used for comments.
139
140In case of error in the configuration file, an error message will show up.
141Depending on its severity, Music Sampler may try to continue (ignoring
142corresponding problems) or abort.
143
144The file contains several sections:
145
146 :::yaml
147 aliases:
148 ...
149
150 music_properties:
151 ...
152
153 key_properties:
154 ...
155
156 keys:
157 ...
158
159
160### `music_properties`
161
162This section lets you define global properties for the musics.
163
164#### Examples
165
166 :::yaml
167 "music1.mp3":
168 name: My favorite music
169 gain: 1.4
170Music "music1.mp3" is named "My favorite music". She is loaded at 140% of its
171normal volume.
172
173 :::yaml
174 "music2.mp3":
175 gain: 0.7
176
177Music "music2.mp3" is loaded at 70% of its normal volume.
178
179#### List of available options
180- `name: My music` User-friendly name of the music, used in the interface
181 instead of the filename.
182
183- `gain: x` Loads the music with that initial gain x. This lets you equalize all
184 your music at desired level, independently of the volume afterwards.
185
186### `key_properties`: drawing and properties of keys
187
188This section lets you describe the drawing of the key: color, description. By
189default, a key assigned to one or more actions is shown in green
190
191#### Examples
192
193 :::yaml
194 'ESC':
195 description:
196 -
197 - STOP!
198 color: [255, 0, 0]
199 repeat_delay: 2
200
201The "esc" key is red, and text "STOP!" is shown on the second line. The key is
202protected for 2 seconds after each stroke.
203
204#### List of availale options
205- `description`: the text on the key. Each item is shown on a line (no automatic
206 line break). First line is shown just next to the "key" name and is in bold.
207 On a standard screen, you may have about 3 lines visible (including the first
208 one)
209- `color: [r, g, b]`: the key color. r, g and b are the proportions respectively
210 of red, green and blue, and each value must be between 0 and 255
211- `repeat_delay: x` (default 0) : protection delay. Once all its actions are
212 done, the key will remain disabled (semi-transparent and crossed) for that
213 amount of time (in seconds).
214
215### `keys` : actions related to keys
216
217This section lets you describe for each key, the list of actions associated to
218it. Note that except for `wait` and some particular cases (see below), all the
219actions are almost instantaneous.
220
221
222#### Examples
223
224 :::yaml
225 'a':
226 - play:
227 file: "music1.mp3"
228 volume: 70
229 start_at: 10
230 - wait:
231 duration: 5
232 - stop:
233 file: "music1.mp3"
234 fade_out: 2
235
236Runs music "music1.mp3" at 70% of its maximum volume, at 10 seconds from the
237start, then stops the music 5 seconds later with a 2 seconds fade out.
238
239 :::yaml
240 'b':
241 - stop:
242 file: "music1.mp3"
243 fade_out: 5
244 wait: false
245 - play:
246 file: "music2.mp3"
247 fade_in: 5
248
249Make a cross fade of 5 seconds between "music1.mp3" and "music2.mp3"
250
251 :::yaml
252 'c':
253 - stop:
254 file: "music1.mp3"
255 fade_out: 5
256 wait: true
257 - wait:
258 duration: 2
259 - play:
260 file: "music2.mp3"
261 - seek:
262 file: "music2.mp3"
263 delta: false
264 value: 60
265Stops music "music1.mp3" with a 5 seconds fade out, waits for the end of the
266fade out, plus 2 seconds, and then runs "music2.mp3" skipping the first minute.
267
268 :::yaml
269 'd':
270 - volume:
271 file: "music1.mp3"
272 value: 50
273 - play:
274 file: "noise.mp3"
275 loop: 1
276 - wait:
277 file: "noise.mp3"
278 - volume:
279 file: "music1.mp3"
280 value: 100
281
282Lower volume of "music1.mp3" while "noise.mp3" is played above it (twice). Then
283the volume of the music comes back to normal.
284
285 :::yaml
286 'e':
287 - pause:
288 file: "music1.mp3"
289 - wait:
290 duration: 10
291 - unpause:
292 file: "music1.mp3"
293 - seek:
294 file: "music1.mp3"
295 delta: true
296 value: 5
297
298Pauses "music1.mp3" for 10 seconds and reruns it afterward, seeking to 5 seconds
299later.
300
301#### List of all the actions:
302- `play` : start a music. Music Sampler only runs a music once (if you want to
303 have it playing several time concurrently, duplicate it or make symbolic
304 link). Parameters:
305 * `file: "music.mp3"` gives the played music (relative path).
306 * `fade_in: x` (optional) runs the music with x seconds fade in.
307 * `volume: x` (optional, default 100) sets the volume of the music.
308 * `loop: x` (optional, default 0) music should be repeated x times. Indicate
309 -1 for infinite loop. Note: x is the number of repetitions, thus the music
310 is actually played x+1 times.
311 * `start_at: x` (optional, default 0) start music skipping the first x
312 seconds.
313 * `restart_if_running: true/false` (optional, default false) if the music is
314 already running, stop it and restart it.
315- `stop` : stops a given music. Parameters:
316 * `file: "music.mp3"` (optional) gives the music to stop. If no music is
317 given, stops all of them.
318 * `fade_out: x` (optional) stops music with a x seconds fade out.
319 * `wait: true/false` (optional, default: false) when stopping with a fade
320 out, wait for the fade to finish before continuing to the next actions. If
321 the music stops naturally before the en of the fade out, the wait stops
322 there too. When several musics are stopped in fade out, the `wait` only
323 waits for the last one in the playlist (which can finish naturally before
324 the others).
325 * `set_wait_id: name` (optional, useless when `wait` is false) sets an id
326 `name` to the wait (see `interrupt_wait`). Any valid string may be used.
327- `volume` : change the volume of a given music. Parameters:
328 * `file: "music.mp3"` (optional) which music to change. If no music is
329 given, the global volume is changed.
330 * `delta: true/false` (optional, default false) add/remove to the volume
331 instead of setting an absolute value.
332 * `value: x` if delta is false, sets the volume to x%. Note that this factor
333 is applied to the music already loaded (with the initial gain). If delta
334 is true, adds or remove the percentage to the current volume.
335 * `fade: x` (optional) the volume change is applied with a x seconds fade.
336- `pause` : pause a music. Parameters:
337 * `file: "music.mp3"` (optional) gives the music to pause. If no music is
338 given, it applies to all playing musics.
339- `unpause` : unpause a music. Parameters:
340 * `file: "music.mp3"` (optional) gives the msuic to unpause. If no music is
341 given, it applies to all paused musics.
342- `wait` : wait for some time or for an event. Parameters:
343 * `file: "music.mp3"` (optional) wait for the end of music "music.mp3"
344 * `duration: x` (optional) wait x seconds. If `file` and `duration` are
345 given, wait the end of the music PLUS the `duration`.
346 * `set_wait_id: name` (optional) gives an id to the wait event (see
347 `interrupt_wait`). The id can be any valid string.
348Note again that this action is one of the only action that is not almost
349instantaneous. Use it wherever you need to make some time adjustments for other
350actions.
351- `seek` : seek to a specific position in a music. Parameters:
352 * `file: "music.mp3"` (optional) gives the music to seek. If no music is
353 given, applies to all playing musics.
354 * `delta: true/false` (optional, default false) If `delta` is true, the time
355 seek is relative. Otherwise, it is absolute.
356 * `value: x` If `delta` is true, then moves the music forward or backward by
357 x seconds. If delta is false, the music goes to that position. If the
358 music is fading (fade in or volume fade), the effect is immediately
359 interrupted. If the music is fading out, the "seek" is ignored. In case of
360 `loop`, a relative seek may jump to previous or next loop if possible,
361 while an absolute seek will jump to a position in the current loop.
362- `stop_all_actions:` Interrupts all the running and pending actions. Note that
363 a started music (even with a `loop` option) is the result of an action that is
364 already finished and thus will keep playing (see `stop` for that). Parameters:
365 * `other_only: true/false` (optional, default false): if `other_only` is
366 true, the interruption is valid for all keys except the one that ran the
367 action. When false, it is thus useless to add actions after that one.
368- `interrupt_wait`: stop a wait event (normal `wait` or fade out wait). The keys
369 that were waiting will move to the next actions. Parameters:
370 * `wait_id: name` : gives the id of the `wait` to interrupt (defined with
371 `set_wait_id`, see actions `wait` and `stop`). To interrupt several waits,
372 use the same action several times.
373- `run_command` : Run a command. Parameters:
374 * `command: my_command` : Gives the command to run.
375 * `wait: true/false` (optional, default false) if true, waits for the
376 command to finish (this wait is not interruptible by interrupt_wait)
377
378### `aliases` : define aliases
379
380It is possible to define some aliases for the parameters. Those aliases are
381internal to the configuration file. To give a nice name to a music, see
382"music_properties".
383
384The aliases syntax is the following:
385
386 :::yaml
387 aliases:
388 alias1:
389 param: value
390 alias2:
391 param1: value1
392 param2: value2
393
394You can then use in other places of the configuration file a special argument
395`include: alias1` or `include: [alias1, alias2]` instead of `param: value`. In
396the case of several aliases that have identical elements, only the last one is
397kept. In all cases, a value defined outside of an include takes precedence. See
398below examples.
399
400#### Examples
401
402 :::yaml
403 aliases:
404 music1:
405 file: "path/to/my/favourite/music.mp3"
406
407 keys:
408 'a':
409 play:
410 include: music1
411
412`music1` is now an alias for `file: "path/to/my/favourite/music.mp3"`. You can
413use `include: music1` at any place where you would have written `file:
414"path/to/my/favourite/music.mp3"`. Aliases cannot be used in section
415"music_properties".
416
417 :::yaml
418 aliases:
419 blue:
420 color: [0, 0, 255]
421
422 keys_properties:
423 'a':
424 description:
425 -
426 - blue key
427 include: blue
428
429`blue` is an alias for color `[0, 0, 255]`. Wherever you need to specify `color:
430[0, 0, 255]`, you may write `include: blue` instead.
431
432 :::yaml
433 aliases:
434 long_time:
435 duration: 42
436
437 keys:
438 'b':
439 wait:
440 include: long_time
441 play:
442 file: "music1.mp3"
443
444`long_time` is an alias for a 42 seconds duration. Instead of `duration: 42`,
445you may use `include: long_time`.
446
447## Troubleshooting
448
449You'll find below a list of possible problems, and a possible solution. If you
450find some other problems, please contact the author.
451
452* The program starts and stops immediately.
453
454It is usually a syntax error in the config file. In that case, the terminal
455should give some informations.
456
457* The music sizzles
458
459It may be a latency problems (with slow computers). Try to adapt it to a higher
460value (~0.1 seconds)
461
462* Impossible to play more than one music at a time.
463
464The system cannot mix the musics by itself. You may have a look at the device
465list (`--list-devices`) and choose another. You may also try the integrated
466mixer, but the result may not be very fluid (you will certainly need to adjust
467blocksize and latency parameters if you do that)
468
469If your system uses PulseAudio, it may be a configuration problem for the ALSA
470plugin. In that case, try to put the following configuration in
471`/etc/asound.conf` and restart your system. This is an empirical solution that
472seems to have worked, there is no garanty that it will!
473
474 pcm.!default {
475 type pulse
476 fallback "sysdefault"
477 hint {
478 show on
479 description "Default ALSA Output (currently PulseAudio Sound Server)"
480 }
481 }
482
483 ctl.!default {
484 type pulse
485 fallback "sysdefault"
486 }
487
488* The terminal shows an error:
489
490 Exception in thread Thread-1:
491 Traceback (most recent call last):
492 File "threading.py", line 914, in _bootstrap_inner
493 File "threading.py", line 862, in run
494 File "kivy/input/providers/mtdev.py", line 219, in _thread_run
495 File "kivy/lib/mtdev.py", line 131, in __init__
496 PermissionError: [Errno 13] Permission denied: '/dev/input/event6'
497
498This is a device permission error. It can be safely ignored.
499
500* For other problems or bug, please see [Bug
501 Tracker](https://git.immae.eu/mantisbt/view_all_bug_page.php?project_id=1&sort=status%2Clast_updated&dir=ASC%2CDESC)
502
503## About
504
505The musics in the examples come from [Jamendo](https://jamendo.com). The
506complete version of those musics are available for free for a non-commercial
507use:
508
509[Short Blues](https://www.jamendo.com/track/340173/short-blues)
510
511[To the Fantasy war](https://www.jamendo.com/track/778560/to-the-fantasy-war)
512
513The crocodile noise comes from
514[Universal-Soundbank](http://www.universal-soundbank.com/).
515
516This program was developped originaly to help handling music for shows of the
517circus company [Les pieds jaloux](http://piedsjaloux.fr/). With no available
518sound manager, the artists sometimes had to run from the scene to make the sound
519transitions, making as little interaction as possible with the computed (one
520key).
diff --git a/documentation_fr.md b/documentation_fr.md
index 529329c..a55ae73 100644
--- a/documentation_fr.md
+++ b/documentation_fr.md
@@ -4,35 +4,39 @@
4 4
5## Description 5## Description
6 6
7Music 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. 7Music Sampler est un lecteur de musique qui permet de pré-programmer des
8transitions musicales, qui peuvent ensuite être lancées à l'aide d'un simple
9appui sur une touche.
8 10
9## Pré-requis et installation 11## Pré-requis et installation
10 12
11- Il faut avoir ffmpeg d'installé. Pour cela, il faut installer le paquet `libav-tools` : 13- Il faut avoir ffmpeg d'installé. Pour cela, il faut installer le paquet `libav-tools` (debian) :
12 14
13 sudo apt-get install libav-tools 15 sudo apt-get install libav-tools
14 16
15Si 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. 17Si vous utilisez la version compilée de Music Sampler (cf. plus bas pour un lien
18de téléchargement), il n'y a rien d'autre à installer.
16 19
17- Pour utiliser les sources directement, les modules suivants sont requis: 20- Pour utiliser les sources directement, les modules suivants sont requis:
18 21
19| module | version minimale | commentaire | 22| module | version minimale | commentaire |
20| ----------- | ---------------- | --------------------------------------------------------------------------- | 23| ----------- | ---------------- | ----------------------------------------------------------------------------- |
21| Cython | 0.24 | pour compiler Kivy | 24| Cython | 0.24 | pour compiler Kivy |
22| Kivy | 1.9.1 | certaines fonctionnalités nécessitent de compiler/installer avec USE_SDL2=1 | 25| Kivy | 1.9.1 | certaines fonctionnalités nécessitent de compiler/installer avec `USE_SDL2=1` |
23| Markdown | 2.6.6 | pour la documentation uniquement | 26| Markdown | 2.6.6 | pour la documentation uniquement |
24| pydub | 0.16.4 | | 27| pydub | 0.16.4 | |
25| Pygame | 1.9.2.dev1 | utilisée par Kivy | 28| Pygame | 1.9.2.dev1 | utilisée par Kivy |
26| Pygments | 2.1.3 | pour la documentation uniquement | 29| Pygments | 2.1.3 | pour la documentation uniquement |
27| sounddevice | 0.3.3 | | 30| sounddevice | 0.3.3 | |
28| transitions | 0.4.1 | | 31| transitions | 0.4.1 | |
29| PyYAML | 3.11 | | 32| PyYAML | 3.11 | |
30 33
31Le projet est également disponible via pip: 34Le projet est également disponible via `pip`:
32 35
33 pip install music_sampler 36 pip install music_sampler
34 37
35Le programme utilise les polices "Symbola" et "Ubuntu" (Regular / Bold), qui doivent être disponibles, et la librairie portaudio: 38Le programme utilise les polices `Symbola` et `Ubuntu` (Regular / Bold), qui
39doivent être disponibles, et la librairie `portaudio`:
36 40
37 sudo apt-get install ttf-ancient-fonts ttf-ubuntu-font-family portaudio 41 sudo apt-get install ttf-ancient-fonts ttf-ubuntu-font-family portaudio
38 42
@@ -40,7 +44,8 @@ Pour compiler kivy avec la librairie SDL2, il faut certains paquets installés:
40 44
41 sudo apt-get install libsdl2-dev libsdl2-image-dev libsdl2-mixer-dev libsdl2-ttf-dev 45 sudo apt-get install libsdl2-dev libsdl2-image-dev libsdl2-mixer-dev libsdl2-ttf-dev
42 46
43cf [Installation Kivy](https://kivy.org/docs/installation/installation-linux.html) 47cf [Installation
48Kivy](https://kivy.org/docs/installation/installation-linux.html)
44 49
45## Version compilée 50## Version compilée
46 51
@@ -51,57 +56,104 @@ Une version compilée peut être créée avec pyinstaller:
51 56
52## Téléchargements 57## Téléchargements
53 58
54- 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) 59- Un exemple de configuration ainsi que des musiques associées à l'exemple
55- 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) 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
63 [dans le même
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)
56 67
57## Utilisation 68## Utilisation
58 69
59Tout le travail consiste à préparer les transitions dans le fichier de configuration config.yml. 70Tout le travail consiste à préparer les transitions dans le fichier de
71configuration `config.yml`.
60 72
61Lancer 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. 73Lancer ensuite le programme dans le dossier où se situe le fichier de
74configuration (voir plus bas pour une utilisation avancée). Une fenêtre
75représentant un clavier apparaît. Le rond orange dans le coin du clavier devient
76vert lorsque tout est chargé, ou rouge en cas de problème. Une touche grisée et
77barrée représente une touche non-utilisable pour le moment : soit parce que la
78musique est en cours de chargement (au lancement du programme, cela peut prendre
79un peu de temps sur certaines machines), soit parce qu'il y a une action en
80cours.
62 81
63Un 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. 82Un exemple de fichier de configuration est fourni, avec un certain nombre de
83touches et de transitions programmées (pour les trois musiques fournies), la
84syntaxe du fichier (expliquée plus bas) se comprend aisément en le regardant. De
85plus, certaines touches (par exemple 'ÉCHAP' pour tout arrêter) peuvent être
86gardées d'une fois sur l'autre.
64 87
65### Actions possibles 88### Actions possibles
66 89
67 - Cliquer sur une touche : affiche les actions associées à cette touche (dans le cadre en bas à gauche). 90 - Cliquer sur une touche : affiche les actions associées à cette touche (dans
68 - 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. 91 le cadre en bas à gauche).
69En 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". 92 - Appuyer sur une touche : déclenche les actions associées à cette touche
70 - Ctrl+C ou Ctrl+Q : quitte le programme (possible aussi en cliquant simplement sur la croix en haut à droite). 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).
71 - Ctrl+R : recharge le fichier de configuration. 101 - Ctrl+R : recharge le fichier de configuration.
72 102
73### Options disponibles au lancement 103### Options disponibles au lancement
74 104
75Toutes les options au lancement sont facultatives ; la plupart du temps lancer le programme dans le bon dossier suffit. 105Toutes les options au lancement sont facultatives ; la plupart du temps lancer
106le programme dans le bon dossier suffit.
76 107
77 * `-h, --help` : affiche une liste des options disponibles. 108 * `-h, --help` : affiche une liste des options disponibles.
78 * `-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). 109 * `-c CONFIG, --config CONFIG` : précise le fichier de configuration à charger
79 * `-p MUSIC_PATH, --music-path MUSIC_PATH` : précise le chemin des musiques (par défaut, le dossier courant). 110 (par défaut, config.yml qui se trouve dans le dossier où est lancé
111 music_sampler).
112 * `-p MUSIC_PATH, --music-path MUSIC_PATH` : précise le chemin des musiques
113 (par défaut, le dossier courant).
80 * `-d, --debug` : Affiche les informations de déboggage (désactivé par défaut) 114 * `-d, --debug` : Affiche les informations de déboggage (désactivé par défaut)
81 * `-V, --version` : affiche la version courante et quitte (utilisable uniquement pour la version compilée). 115 * `-V, --version` : affiche la version courante et quitte (utilisable
82 * `-L, --language` : change la langue de l'application. Actuellement: fr, en (par défaut 'fr') 116 uniquement pour la version compilée).
83 * `--no-focus-warning`: Ne pas afficher d'avertissement lorsque l'application perd le focus. 117 * `-L, --language` : change la langue de l'application. Actuellement: fr, en
84 118 (par défaut 'fr')
85Les options suivantes sont plutôt réservées à un usage avancé de music_sampler, ou en cas de problème avec la configuration standard : 119 * `--no-focus-warning`: Ne pas afficher d'avertissement lorsque l'application
86 120 perd le focus.
87 * `-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. 121
88 * `-l LATENCY, --latency LATENCY` : latence. Préciser "low", "high" ou un nombre de secondes (par défaut, "high") 122Les options suivantes sont plutôt réservées à un usage avancé de music_sampler,
89 * `-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. 123ou en cas de problème avec la configuration standard :
90 * `-f FRAME_RATE, --frame-rate FRAME_RATE` : fréquence d'échantillonnage pour jouer les musiques. Par défaut : 44100 124
91 * `-x CHANNELS, --channels CHANNELS` : nombre de canaux par musique (2 par défaut, pour une écoute stéréo) 125 * `-m, --builtin-mixing` Effectue en interne le mixage des sons. Par défaut,
92 * `-s SAMPLE_WIDTH, --sample-width SAMPLE_WIDTH` : largeur d'échantillonnage (nombre d'octets pour chaque frame). Par défaut : 2. 126 music_sampler confie le mixage au système : n'activer cette option que si le
127 système n'y parvient pas.
128 * `-l LATENCY, --latency LATENCY` : latence. Préciser "low", "high" ou un
129 nombre de secondes (par défaut, "high")
130 * `-b BLOCKSIZE, --blocksize BLOCKSIZE` : taille des blocs. Nombre de frames
131 pour chaque étape du mixeur. 0 (par défaut) signifie que le programme
132 choisit lui-même le nombre qui lui convient.
133 * `-f FRAME_RATE, --frame-rate FRAME_RATE` : fréquence d'échantillonnage pour
134 jouer les musiques. Par défaut : 44100
135 * `-x CHANNELS, --channels CHANNELS` : nombre de canaux par musique (2 par
136 défaut, pour une écoute stéréo)
137 * `-s SAMPLE_WIDTH, --sample-width SAMPLE_WIDTH` : largeur d'échantillonnage
138 (nombre d'octets pour chaque frame). Par défaut : 2.
93 * `--device DEVICE` : sélectionne le périphérique de son. 139 * `--device DEVICE` : sélectionne le périphérique de son.
94 * `--list-devices` : Affiche la liste des périphériques de son disponibles. 140 * `--list-devices` : Affiche la liste des périphériques de son disponibles.
95 * `-- ARGS` : Arguments à passer à la librairie Kivy. 141 * `-- ARGS` : Arguments à passer à la librairie Kivy.
96 142
97## Configurer les touches 143## Configurer les touches
98 144
99**ATTENTION : le format du fichier de configuration est susceptible d'évoluer, sans garantie de rétrocompatibilité.** 145**ATTENTION : le format du fichier de configuration est susceptible d'évoluer,
146sans garantie de rétrocompatibilité.**
100 147
101Le 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 !). 148Le fichier config.yml utilise la syntaxe yaml. Les catégories et sous-catégories
102le `#` est un symbole de commentaire : tout ce qui suit ce symbole sur une ligne est ignoré. 149sont gérées par l'indentation par des espaces (mais PAS par des tabulations !).
150le `#` est un symbole de commentaire : tout ce qui suit ce symbole sur une ligne
151est ignoré.
103 152
104En 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. 153En cas d'erreur dans le fichier de configuration, un message d'erreur s'affiche
154dans le terminal. Selon la "gravité" de l'erreur, music_sampler se lance en
155ignorant les actions erronées (en colorant éventuellement la touche en noir), ou
156ne se lance pas du tout.
105 157
106Le fichier contient plusieurs sections : 158Le fichier contient plusieurs sections :
107 159
@@ -129,7 +181,8 @@ Cette section sert à définir des propriétés globales des musiques.
129 "music1.mp3": 181 "music1.mp3":
130 name: My favorite music 182 name: My favorite music
131 gain: 1.4 183 gain: 1.4
132La musique "music1.mp3" est désignée par le nom "My favorite music". Elle est chargée à 140% de son volume normal. 184La musique "music1.mp3" est désignée par le nom "My favorite music". Elle est
185chargée à 140% de son volume normal.
133 186
134 :::yaml 187 :::yaml
135 "music2.mp3": 188 "music2.mp3":
@@ -138,12 +191,20 @@ La musique "music1.mp3" est désignée par le nom "My favorite music". Elle est
138La musique "music2.mp3" est chargée à 70% de son volume normal. 191La musique "music2.mp3" est chargée à 70% de son volume normal.
139 192
140#### Liste des options possibles 193#### Liste des options possibles
141- `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*). 194- `name: My music` La musique sera désignée (dans les actions, dans le
142- `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. 195 terminal) comme "My music" au lieu du chemin du fichier. Par exemple le cadre
196 des actions affichera "starting « My music » at volume 100%". Attention, cela
197 ne fait pas office d'alias dans le fichier de configuration (voir la section
198 *aliases*).
199- `gain: x` Charge la musique avec un gain de x (multiplicatif). Utiliser la
200 commande "volume" pour changer ponctuellement le volume (0 à 100%) au cours de
201 l'écoute.
143 202
144### `key_properties` : affichage et propriétés des touches 203### `key_properties` : affichage et propriétés des touches
145 204
146Cette 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. 205Cette section sert à décrire l'affichage à l'écran des touches : couleur et
206texte. Par défaut, une touche "attribuée" à une ou plusieurs actions s'affiche
207en vert.
147 208
148#### Exemples 209#### Exemples
149 210
@@ -155,16 +216,28 @@ Cette section sert à décrire l'affichage à l'écran des touches : couleur et
155 color: [255, 0, 0] 216 color: [255, 0, 0]
156 repeat_delay: 2 217 repeat_delay: 2
157 218
158La 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é. 219La touche échap est de couleur rouge, et le texte "STOP !" est affiché sur la
220deuxième ligne. Si on appuie deux fois sur la même touche à moins de deux
221secondes d'intervalle, le second appui est ignoré.
159 222
160#### Liste des options possibles 223#### Liste des options possibles
161- `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". 224- `description` : le texte qui s'affiche, à côté du "nom" de la touche. Il faut
162- `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. 225 mettre un tiret pour une ligne de texte (pas de retour à la ligne
163- `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. 226 automatique). La première ligne correspond à celle de la lettre associée à la
227 touche, aussi il vaut mieux souvent la laisser vide, ou ne mettre que très peu
228 de texte (voir l'exemple ci-dessus). Sur un écran de taille raisonnable, on
229 peut compter 3 lignes (incluant la première) pour une touche "standard".
230- `color: [r, g, b]` : la couleur de la touche. r, g et b sont les proportions
231 de rouge, vert et bleu, et doivent être des entiers entre 0 et 255.
232- `repeat_delay: x` (par défaut : 0) : délai de "sécurité" en cas d'appuis
233 successifs sur la touche. La touche est désactivée (grisée et barrée) pendant
234 toute la durée des actions puis le délai de x secondes.
164 235
165### `keys` : actions sur les touches 236### `keys` : actions sur les touches
166 237
167Cette 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. 238Cette section sert à décrire, pour chaque touche, la liste des actions
239successives. Notez que la plupart des actions (hors `wait` et quelques cas
240particuliers, voir plus bas) sont quasi-instantanées.
168 241
169 242
170#### Exemples 243#### Exemples
@@ -181,7 +254,8 @@ Cette section sert à décrire, pour chaque touche, la liste des actions success
181 file: "music1.mp3" 254 file: "music1.mp3"
182 fade_out: 2 255 fade_out: 2
183 256
184Lance 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. 257Lance la musique "music1.mp3" à 70% de son volume max, à 10 secondes du début,
258puis au bout de 5 secondes coupe la musique avec un fondu de 2 secondes.
185 259
186 :::yaml 260 :::yaml
187 'b': 261 'b':
@@ -209,7 +283,9 @@ Effectue un fondu enchaîné de 5 secondes entre "music1.mp3" et "music2.mp3"
209 file: "music2.mp3" 283 file: "music2.mp3"
210 delta: false 284 delta: false
211 value: 60 285 value: 60
212Coupe 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. 286Coupe la musique "music1.mp3" avec un fondu de 5 secondes, attend la fin du
287fondu, puis attend encore deux secondes et lance la musique "music2.mp3", au
288temps d'une minute.
213 289
214 :::yaml 290 :::yaml
215 'd': 291 'd':
@@ -225,7 +301,9 @@ Coupe la musique "music1.mp3" avec un fondu de 5 secondes, attend la fin du fond
225 file: "music1.mp3" 301 file: "music1.mp3"
226 value: 100 302 value: 100
227 303
228Baisse 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. 304Baisse le volume de "music1.mp3" pendant que le son "noise.mp3" est joué par
305dessus (deux fois). Le volume revient à la normale une fois que les deux écoutes
306du son "noise" sont terminées.
229 307
230 :::yaml 308 :::yaml
231 'e': 309 'e':
@@ -240,53 +318,114 @@ Baisse le volume de "music1.mp3" pendant que le son "noise.mp3" est joué par de
240 delta: true 318 delta: true
241 value: 5 319 value: 5
242 320
243Met en pause la musique "music1.mp3" pour 10 secondes et la relance après, en avançant de 5 secondes dans la musique. 321Met en pause la musique "music1.mp3" pour 10 secondes et la relance après, en
322avançant de 5 secondes dans la musique.
244 323
245#### Liste des actions possibles: 324#### Liste des actions possibles:
246- `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 : 325- `play` : joue une musique. music_sampler ne joue qu'une musique à la fois : si
326 la musique demandée est déjà en train d'être jouée, elle n'est pas relancée ou
327 jouée "par dessus". Paramètres :
247 * `file: "music.mp3"` précise la musique jouée (chemin relatif). 328 * `file: "music.mp3"` précise la musique jouée (chemin relatif).
248 * `fade_in: x` (facultatif) lance la musique avec un fondu au départ de x secondes. 329 * `fade_in: x` (facultatif) lance la musique avec un fondu au départ de x
249 * `volume: x` (facultatif, défaut : 100) la musique doit être jouée à x% de son volume max. 330 secondes.
250 * `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`. 331 * `volume: x` (facultatif, défaut : 100) la musique doit être jouée à x% de
251 * `start_at: x` (facultatif, défaut : 0) la musique démarre à x secondes du début. 332 son volume max.
252 * `restart_if_running: true/false` (facultatif, défaut : false) la musique est éventuellement stoppée et redémarrée si nécessaire 333 * `loop: x` (facultatif, défaut : 0) la musique doit être répétée x fois.
334 Indiquer -1 pour la répéter indéfiniment. Attention, x est le nombre de
335 répétitions, donc pour lire trois fois la musique, mettre `loop: 2`.
336 * `start_at: x` (facultatif, défaut : 0) la musique démarre à x secondes du
337 début.
338 * `restart_if_running: true/false` (facultatif, défaut : false) la musique
339 est éventuellement stoppée et redémarrée si nécessaire
253- `stop` : arrête une musique donnée. Paramètres : 340- `stop` : arrête une musique donnée. Paramètres :
254 * `file: "music.mp3"` (facultatif) précise la musique à stopper. Si aucune musique n'est précisée, le `stop` s'applique à toutes les musiques. 341 * `file: "music.mp3"` (facultatif) précise la musique à stopper. Si aucune
342 musique n'est précisée, le `stop` s'applique à toutes les musiques.
255 * `fade_out: x` (facultatif) stoppe la musique avec un fondu de x secondes. 343 * `fade_out: x` (facultatif) stoppe la musique avec un fondu de x secondes.
256 * `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). 344 * `wait: true/false` (facultatif, par défaut : false) dans le cas d'un
257 * `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. 345 fondu, attendre la durée du fondu pour faire les actions suivantes. Si la
346 musique s'arrêtait naturellement avant la fin du fondu, l'attente se
347 termine lorsque la musique se termine naturellement. Lorsque plusieurs
348 musiques sont stoppées en fondu, le `wait` n'attend que la dernière
349 musique de la playlist (qui peut se terminer naturellement avant les
350 autres).
351 * `set_wait_id: name` (facultatif, inutile lorsque `wait` est à false) donne
352 l'identifiant `name` à l'attente de fin du fondu (voir `interrupt_wait`).
353 L'identifiant peut être n'importe quelle chaîne de caractère.
258- `volume` : change le volume d'une musique donnée. Paramètres : 354- `volume` : change le volume d'une musique donnée. Paramètres :
259 * `file: "music.mp3"` (facultatif) précise la musique. Si aucune musique n'est précisée, la modification s'applique au volume global. 355 * `file: "music.mp3"` (facultatif) précise la musique. Si aucune musique
260 * `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. 356 n'est précisée, la modification s'applique au volume global.
261 * `value: x` Si delta est à false, met le volume à x% du volume max (x doit être entre 0 et 100). 357 * `delta: true/false` (facultatif, par défaut : false) le volume doit il
262Ce 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. 358 être précisé en absolu (false), ou en relatif (true), voir plus bas.
263Si delta est à true, applique un modificateur de x% au volume (x doit être un entier signé). 359 * `value: x` Si delta est à false, met le volume à x% du volume max (x doit
264Notez 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%. 360 être entre 0 et 100). Ce facteur est appliqué à la musique déjà chargée en
265 * `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. 361 mémoire (voir section "propriétés"), donc le 100% fait référence au volume
362 de chargement.
363Si delta est à true, applique un modificateur de x% au volume (x doit être un
364entier signé). Notez qu'une action "+10%" relative ne correspond pas à un
365pourcentage du volume actuel, mais du volume "de référence" 100%. Ainsi,
366effectuer +10% et -10% en relatif revient bien à 100%.
367 * `fade: x` (facultatif) le changement de volume est appliqué en fondu sur x
368 secondes. Il n'y a pas d'attente de la fin du fondu pour lancer les
369 actions suivantes : au besoin, rajouter un `wait` à la main.
266- `pause` : met en pause une musique. Paramètres : 370- `pause` : met en pause une musique. Paramètres :
267 * `file: "music.mp3"` (facultatif) précise la musique à mettre en pause. Si non précisé, s'applique à toutes les musiques. 371 * `file: "music.mp3"` (facultatif) précise la musique à mettre en pause. Si
268- `unpause` : relance une musique mise en pause (là où elle en était). Paramètres : 372 non précisé, s'applique à toutes les musiques.
269 * `file: "music.mp3"` (facultatif) précise la musique à relancer. Si non précisé, s'applique à toutes les musiques. 373- `unpause` : relance une musique mise en pause (là où elle en était).
374 Paramètres :
375 * `file: "music.mp3"` (facultatif) précise la musique à relancer. Si non
376 précisé, s'applique à toutes les musiques.
270- `wait` : attend un temps donné. Paramètres : 377- `wait` : attend un temps donné. Paramètres :
271 * `file: "music.mp3"` (facultatif) attend la fin de la musique "music.mp3" 378 * `file: "music.mp3"` (facultatif) attend la fin de la musique "music.mp3"
272 * `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`. 379 * `duration: x` (facultatif) attend x secondes. Si `file` et `duration` sont
273 * `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. 380 précisés, l'attente dure jusqu'à la fin de la musique PUIS la durée donnée
274Notez 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. 381 par `duration`.
382 * `set_wait_id: name` (facultatif) donne l'identifiant `name` à l'attente
383 (voir `interrupt_wait`). L'identifiant peut être n'importe quelle chaîne
384 de caractère.
385Notez une fois encore que `wait` est quasiment la seule action qui attend
386d'avoir terminé pour lancer la commande suivante, toutes les autres sont lancées
387successivement mais sans attendre (donc presque simultanément) : ne pas hésiter
388à rajouter des commandes d'attente partout où c'est nécessaire.
275- `seek` : permet d'aller à un endroit précis dans une musique. Paramètres : 389- `seek` : permet d'aller à un endroit précis dans une musique. Paramètres :
276 * `file: "music.mp3"` (facultatif) précise la musique. Si aucune musique n'est précisée, l'action s'applique à toutes les musiques. 390 * `file: "music.mp3"` (facultatif) précise la musique. Si aucune musique
277 * `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. 391 n'est précisée, l'action s'applique à toutes les musiques.
278 * `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. 392 * `delta: true/false` (facultatif, défaut : false) Si `delta` est true, le
279- `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 : 393 temps est relatif. Si delta est false, le temps est absolu, voir plus bas.
280 * `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. 394 * `value: x` Si `delta` est true, alors fait avancer de x secondes dans la
281- `interrupt_wait`: interrompt l'attente (de `wait` ou fin d'un fondu avec attente) et passe directement à l'action suivante. Paramètre : 395 musique (reculer si x est négatif). Si delta est false, alors la lecture
282 * `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`. 396 se place à x secondes à partir du début. Si la musique est en train de
397 faire un fondu (au départ, ou changement de volume), le fondu se "termine
398 automatiquement" : et la musique est immédiatement au volume final voulu.
399 Si la musique est en train de se terminer en fondu, le "seek" est ignoré
400 (un fondu de fin considère la musique comme déjà terminée). En cas de
401 `loop`, si le déplacement est relatif la musique peut éventuellement
402 passer à la répétition suivante / précédente; sinon, le déplacement se
403 fait dans la répétition courante.
404- `stop_all_actions:` Interrompt toutes les actions en cours et à faire. Notez
405 qu'une musique lancée (y compris avec une option `loop`) est considérée comme
406 une action "déjà terminée", et ne sera donc pas interrompue (utiliser `stop`
407 sans arguments pour stopper toutes les musiques en écoute). Paramètre :
408 * `other_only: true/false` (facultatif, défaut : false) : si `other_only`
409 est true, la commande interrompt uniquement les actions des *autres*
410 touches. Sinon, cette commande interrompt également les actions de la
411 touche actuelle ; dans ce cas il est inutile de mettre des actions à la
412 suite de celle-ci puisqu'elles seront systématiquement interrompues.
413- `interrupt_wait`: interrompt l'attente (de `wait` ou fin d'un fondu avec
414 attente) et passe directement à l'action suivante. Paramètre :
415 * `wait_id: name` : précise l'identifiant du `wait` à stopper (défini par
416 `set_wait_id`, voir les actions `wait` et `stop`). Pour interrompre
417 plusieurs `wait` d'un seul coup, il faut mettre plusieurs
418 `interrupt_wait`.
283- `run_command` : lance une commande. Paramètres : 419- `run_command` : lance une commande. Paramètres :
284 * `command: my_command` : précise la commande à lancer. 420 * `command: my_command` : précise la commande à lancer.
285 * `wait: true/false` (facultatif, défaut : false) : si `wait` est true, attend que la commande ait fini de s'exécuter. 421 * `wait: true/false` (facultatif, défaut : false) : si `wait` est true,
422 attend que la commande ait fini de s'exécuter.
286 423
287### `aliases` : définir des alias 424### `aliases` : définir des alias
288 425
289Il 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". 426Il est possible de définir des alias pour les différents paramètres. Ces alias
427sont internes au fichier de configuration ; pour afficher un "joli" nom d'une
428musique, voir plutôt "music_properties".
290 429
291La syntaxe est la suivante: 430La syntaxe est la suivante:
292 431
@@ -298,7 +437,12 @@ La syntaxe est la suivante:
298 param1: value1 437 param1: value1
299 param2: value2 438 param2: value2
300 439
301On 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. 440On utilise ensuite, dans le fichier de configuration, `include: alias1` ou
441`include: [alias1, alias2]` à la place de `param: value`. Dans le cas de
442plusieurs aliases inclus contenant des éléments identiques, seul le dernier est
443pris en compte. Dans tous les cas, les alias ne sont *pas* prioritaires par
444rapport aux éventuels paramètres définis là où ils sont inclus. Voir les
445exemples ci-dessous.
302 446
303#### Exemples 447#### Exemples
304 448
@@ -312,7 +456,11 @@ On utilise ensuite, dans le fichier de configuration, `include: alias1` ou `incl
312 play: 456 play:
313 include: music1 457 include: music1
314 458
315`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. 459`music1` est désormais un alias pour `"path/to/my/favourite/music.mp3"`. À
460chaque fois qu'on veut écrire `file: "path/to/my/favourite/music.mp3"`, on peut
461écrire à la place `include: music1`. Attention, dans la section
462"music_properties", les alias ne fonctionnent pas, et il faut écrire le nom du
463fichier complet.
316 464
317 :::yaml 465 :::yaml
318 aliases: 466 aliases:
@@ -326,7 +474,8 @@ On utilise ensuite, dans le fichier de configuration, `include: alias1` ou `incl
326 - blue key 474 - blue key
327 include: blue 475 include: blue
328 476
329`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. 477`blue` est un alias pour la couleur `[0, 0, 255]`. À chaque fois qu'on veut
478écrire `color: [0, 0, 255]`, on peut écrire `include: blue` à la place.
330 479
331 :::yaml 480 :::yaml
332 aliases: 481 aliases:
@@ -340,25 +489,38 @@ On utilise ensuite, dans le fichier de configuration, `include: alias1` ou `incl
340 play: 489 play:
341 file: "music1.mp3" 490 file: "music1.mp3"
342 491
343`long_time` est un alias pour la durée 42 secondes. Au lieu d'écrire `duration: 42`, on peut écrire `include: long_time`. 492`long_time` est un alias pour la durée 42 secondes. Au lieu d'écrire `duration:
49342`, on peut écrire `include: long_time`.
344 494
345## Problèmes possibles 495## Problèmes possibles
346 496
347Sont 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. 497Sont listés ci-dessous une liste de problèmes rencontrés, avec des solutions
498proposées. Si vous en découvrez d'autre, contactez l'auteur pour les ajouter à
499la liste.
348 500
349* Le programme se lance et s'arrête tout de suite. 501* Le programme se lance et s'arrête tout de suite.
350 502
351Il 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). 503Il s'agit généralement d'une erreur de syntaxe dans le fichier de config. Dans
504ce cas, le terminal doit afficher quelques détails sur l'erreur en question (au
505moins la ligne correspondante).
352 506
353* La musique "grésille" affreusement. 507* La musique "grésille" affreusement.
354 508
355Il 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) 509Il peut s'agir d'un problème de latence (avec certains ordinateurs un peu
510lents). Essayez de changer la latence (par exemple, 0.1 seconde)
356 511
357* Impossible de jouer plus d'une musique à la fois. 512* Impossible de jouer plus d'une musique à la fois.
358 513
359Le 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). 514Le système n'arrive pas à mixer les musiques par lui-même. Vous pouvez essayer
515de regarder la liste des périphériques de son (`--list-devices`) puis en
516sélectionner un autre si disponible. Vous pouvez aussi essayer le mixeur intégré
517à music_sampler, mais les résultats ne sont pas toujours très fluides (ne pas
518hésiter à jouer avec les paramètres avancés comme latency et blocksize).
360 519
361Si 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 !): 520Si votre système utilise PulseAudio, il peut s'agir d'un problème de
521configuration du plugin ALSA. Dans ce cas, essayez de mettre la configuration
522suivante dans `/etc/asound.conf`, puis redémarrer la machine (solution empirique
523qui semble avoir fonctionné, sans garantie !):
362 524
363 pcm.!default { 525 pcm.!default {
364 type pulse 526 type pulse
@@ -384,17 +546,29 @@ Si votre système utilise PulseAudio, il peut s'agir d'un problème de configura
384 File "kivy/lib/mtdev.py", line 131, in __init__ 546 File "kivy/lib/mtdev.py", line 131, in __init__
385 PermissionError: [Errno 13] Permission denied: '/dev/input/event6' 547 PermissionError: [Errno 13] Permission denied: '/dev/input/event6'
386 548
387C'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. 549C'est une erreur de permission d'accès à un périphérique, généré par la
550librairie kivy. Elle peut être ignorée et n'aura pas d'incidence.
551
552* Pour d'autres problèmes ou bugs à reporter, voir le [Bug
553 Tracker](https://git.immae.eu/mantisbt/view_all_bug_page.php?project_id=1&sort=status%2Clast_updated&dir=ASC%2CDESC)
388 554
389* 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)
390## Divers 555## Divers
391 556
392Les 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 : 557Les extraits de musiques proposés en exemples proviennent de
558[Jamendo](https://jamendo.com). Les musiques (complètes) sont disponibles en
559libre téléchargement pour un usage non commercial :
393 560
394[Short Blues](https://www.jamendo.com/track/340173/short-blues) 561[Short Blues](https://www.jamendo.com/track/340173/short-blues)
395 562
396[To the Fantasy war](https://www.jamendo.com/track/778560/to-the-fantasy-war) 563[To the Fantasy war](https://www.jamendo.com/track/778560/to-the-fantasy-war)
397 564
398Le bruit de crocodile provient de [Universal-Soundbank](http://www.universal-soundbank.com/). 565Le bruit de crocodile provient de
566[Universal-Soundbank](http://www.universal-soundbank.com/).
399 567
400Cet 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). 568Cet outil a été développé à l'origine pour faciliter la gestion du son pour les
569spectacles de la compagnie circassienne [Les pieds
570jaloux](http://piedsjaloux.fr/). N'ayant pas d'ingénieur son, les artistes
571eux-mêmes peuvent alors gérer leur musique lorsqu'ils ne sont pas sur scène :
572d'où la nécessité de préparer les transitions à l'avance et, au moment de la
573représentation, de réduire l'interaction avec la machine au minimum (une
574touche).