diff options
Diffstat (limited to 'documentation_en.md')
-rw-r--r-- | documentation_en.md | 520 |
1 files changed, 520 insertions, 0 deletions
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 | |||
7 | Music Sampler is a music player which associates each key on the keyboard to a | ||
8 | set 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 | |||
16 | If you use the compiled version of Music Sampler (cf. below for a download | ||
17 | link), 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 | |||
33 | The project is also available via `pip`: | ||
34 | |||
35 | pip install music_sampler | ||
36 | |||
37 | The program makes use of fonts "Symbola" and "Ubuntu" (Regular / Bold), that | ||
38 | must 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 | |||
42 | Pour 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 | |||
46 | cf [Installation | ||
47 | Kivy](https://kivy.org/docs/installation/installation-linux.html) | ||
48 | |||
49 | ## Compiled version | ||
50 | |||
51 | A 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 | |||
67 | The whole job consists in preparing all the transitions in the configuration | ||
68 | file `config.yml`. | ||
69 | |||
70 | The program should then be run in the folder in which the configuration file | ||
71 | lies (see below for an advanced use). A window with a keyboard appears. The | ||
72 | orange circle in the upper-right corner of the keyboard becomes green one every | ||
73 | music is loaded (or red in case of problem). A key is semi-transparent and | ||
74 | crossed when it is not usable at the moment: either because a music handled by | ||
75 | this key is not loaded yet (it may take some time when the program launches), or | ||
76 | because it has an action running. | ||
77 | |||
78 | An example configuration file is given with some keys and transitions. The | ||
79 | structure of the file (explained more in details below) should be easy to | ||
80 | understand 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 | |||
98 | All the options below are optional; usually, running the program in the correct | ||
99 | folder 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 | |||
113 | The following options are reserved for a more advanced use of Music Sampler, or | ||
114 | in 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 | ||
135 | may change without ensuring backward compatibility** | ||
136 | |||
137 | The file `config.yml` uses yaml syntax. Categories and sub-categories are | ||
138 | handled by space indentations (no tabs). Symbol `#` may be used for comments. | ||
139 | |||
140 | In case of error in the configuration file, an error message will show up. | ||
141 | Depending on its severity, Music Sampler may try to continue (ignoring | ||
142 | corresponding problems) or abort. | ||
143 | |||
144 | The 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 | |||
162 | This 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 | ||
170 | Music "music1.mp3" is named "My favorite music". She is loaded at 140% of its | ||
171 | normal volume. | ||
172 | |||
173 | :::yaml | ||
174 | "music2.mp3": | ||
175 | gain: 0.7 | ||
176 | |||
177 | Music "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 | |||
188 | This section lets you describe the drawing of the key: color, description. By | ||
189 | default, 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 | |||
201 | The "esc" key is red, and text "STOP!" is shown on the second line. The key is | ||
202 | protected 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 | |||
217 | This section lets you describe for each key, the list of actions associated to | ||
218 | it. Note that except for `wait` and some particular cases (see below), all the | ||
219 | actions 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 | |||
236 | Runs music "music1.mp3" at 70% of its maximum volume, at 10 seconds from the | ||
237 | start, 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 | |||
249 | Make 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 | ||
265 | Stops music "music1.mp3" with a 5 seconds fade out, waits for the end of the | ||
266 | fade 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 | |||
282 | Lower volume of "music1.mp3" while "noise.mp3" is played above it (twice). Then | ||
283 | the 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 | |||
298 | Pauses "music1.mp3" for 10 seconds and reruns it afterward, seeking to 5 seconds | ||
299 | later. | ||
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. | ||
348 | Note again that this action is one of the only action that is not almost | ||
349 | instantaneous. Use it wherever you need to make some time adjustments for other | ||
350 | actions. | ||
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 | |||
380 | It is possible to define some aliases for the parameters. Those aliases are | ||
381 | internal to the configuration file. To give a nice name to a music, see | ||
382 | "music_properties". | ||
383 | |||
384 | The aliases syntax is the following: | ||
385 | |||
386 | :::yaml | ||
387 | aliases: | ||
388 | alias1: | ||
389 | param: value | ||
390 | alias2: | ||
391 | param1: value1 | ||
392 | param2: value2 | ||
393 | |||
394 | You 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 | ||
396 | the case of several aliases that have identical elements, only the last one is | ||
397 | kept. In all cases, a value defined outside of an include takes precedence. See | ||
398 | below 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 | ||
413 | use `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`, | ||
445 | you may use `include: long_time`. | ||
446 | |||
447 | ## Troubleshooting | ||
448 | |||
449 | You'll find below a list of possible problems, and a possible solution. If you | ||
450 | find some other problems, please contact the author. | ||
451 | |||
452 | * The program starts and stops immediately. | ||
453 | |||
454 | It is usually a syntax error in the config file. In that case, the terminal | ||
455 | should give some informations. | ||
456 | |||
457 | * The music sizzles | ||
458 | |||
459 | It may be a latency problems (with slow computers). Try to adapt it to a higher | ||
460 | value (~0.1 seconds) | ||
461 | |||
462 | * Impossible to play more than one music at a time. | ||
463 | |||
464 | The system cannot mix the musics by itself. You may have a look at the device | ||
465 | list (`--list-devices`) and choose another. You may also try the integrated | ||
466 | mixer, but the result may not be very fluid (you will certainly need to adjust | ||
467 | blocksize and latency parameters if you do that) | ||
468 | |||
469 | If your system uses PulseAudio, it may be a configuration problem for the ALSA | ||
470 | plugin. In that case, try to put the following configuration in | ||
471 | `/etc/asound.conf` and restart your system. This is an empirical solution that | ||
472 | seems 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 | |||
498 | This 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 | |||
505 | The musics in the examples come from [Jamendo](https://jamendo.com). The | ||
506 | complete version of those musics are available for free for a non-commercial | ||
507 | use: | ||
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 | |||
513 | The crocodile noise comes from | ||
514 | [Universal-Soundbank](http://www.universal-soundbank.com/). | ||
515 | |||
516 | This program was developped originaly to help handling music for shows of the | ||
517 | circus company [Les pieds jaloux](http://piedsjaloux.fr/). With no available | ||
518 | sound manager, the artists sometimes had to run from the scene to make the sound | ||
519 | transitions, making as little interaction as possible with the computed (one | ||
520 | key). | ||