7 Music Sampler is a music player which associates each key on the keyboard to a
10 ## Dependencies and installation
12 - You need ffmpeg installed. For that, you can use package `libav-tools` (debian):
14 sudo apt-get install libav-tools
16 If you use the compiled version of Music Sampler (cf. below for a download
17 link), you need nothing else.
19 - To use sources, the following modules are required:
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 |
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 | |
33 The project is also available via `pip`:
35 pip install music_sampler
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:
40 sudo apt-get install ttf-ancient-fonts ttf-ubuntu-font-family portaudio
42 To compile Kivy with the SDL2 library, you need some packages:
44 sudo apt-get install libsdl2-dev libsdl2-image-dev libsdl2-mixer-dev libsdl2-ttf-dev
47 Kivy](https://kivy.org/docs/installation/installation-linux.html)
51 A compiled version can be created with `pyinstaller`:
54 pyinstaller music_sampler.spec
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)
67 The whole job consists in preparing all the transitions in the configuration
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.
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.
84 - Clic on a key: shows the associated actions in the bottom-left block of the
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
93 - Ctrl+C or Ctrl+Q: leaves the program.
94 - Ctrl+R: reloads the configuration file
96 ### Options available at launch
98 All the options below are optional; usually, running the program in the correct
99 folder is enough. Most of the parameters can be defined also in the config file.
100 The command line parameters always take precedence.
102 * `-h, --help`: shows a list of available options
103 * `-c CONFIG, --config CONFIG`: gives the configuration file to load (by
104 default, `config.yml` in the current folder).
105 * `-p MUSIC_PATH, --music-path MUSIC_PATH`: gives the path to find the musics
106 (by default, the current folder)
107 * `--no-debug, --debug`: show debug informations in the terminal (disabled by
109 * `-V, --version`: show current version and exit (only for the compiled
111 * `-L, --language`: change application language. Current languages: fr, en
113 * `--focus-warning, --no-focus-warning`: show / don't show warning when focus gets
114 lost (default is to show it)
116 The following options are reserved for a more advanced use of Music Sampler, or
117 in case of problem with the standard configuration:
119 * `--no-builtin-mixing, --builtin-mixing`: make the sound mixing locally. By
120 default, Music Sampler will let the system do it and open one channel per
121 music loaded. Use it only if the system cannot handle it.
122 * `-l LATENCY, --latency LATENCY`: "low", "high" or a number of seconds
124 * `-b BLOCKSIZE, --blocksize BLOCKSIZE`: Number of frames for each mixing
125 step. 0 (default) lets the program choose.
126 * `-f FRAME_RATE, --frame-rate FRAME_RATE`: default 44100Hz
127 * `-x CHANNELS, --channels CHANNELS` : Number of channels per music (default
129 * `-s SAMPLE_WIDTH, --sample-width SAMPLE_WIDTH`: number of bytes per frame
131 * `--device DEVICE` : select another sound device.
132 * `--list-devices` : list available sound devices.
133 * `-- ARGS` : arguments for Kivy library.
137 **Warning: the format of the configuration file is still a work in progress and
138 may change without ensuring backward compatibility**
140 The file `config.yml` uses yaml syntax. Categories and sub-categories are
141 handled by space indentations (no tabs). Symbol `#` may be used for comments.
143 In case of error in the configuration file, an error message will show up.
144 Depending on its severity, Music Sampler may try to continue (ignoring
145 corresponding problems) or abort.
147 The file contains several sections:
167 The config section lets you store configuration parameters that you would
168 normally use in the command line parameters. The '-' in the long parameter name
169 should be replaced by '_' (e.g. '--music-path' -> 'music_path'). For toggles
170 (`debug`, `focus_warning`, `builtin_mixing`) use the version without 'no-' and
171 specify `true` or `false` as value. Note that command line arguments always take
174 ### `music_properties`
176 This section lets you define global properties for the musics.
182 name: My favorite music
184 Music "music1.mp3" is named "My favorite music". She is loaded at 140% of its
191 Music "music2.mp3" is loaded at 70% of its normal volume.
193 #### List of available options
194 - `name: My music` User-friendly name of the music, used in the interface
195 instead of the filename.
197 - `gain: x` Loads the music with that initial gain x. This lets you equalize all
198 your music at desired level, independently of the volume afterwards.
200 ### `key_properties`: drawing and properties of keys
202 This section lets you describe the drawing of the key: color, description. By
203 default, a key assigned to one or more actions is shown in green
215 The "esc" key is red, and text "STOP!" is shown on the second line. The key is
216 protected for 2 seconds after each stroke.
218 #### List of availale options
219 - `description`: the text on the key. Each item is shown on a line (no automatic
220 line break). First line is shown just next to the "key" name and is in bold.
221 On a standard screen, you may have about 3 lines visible (including the first
223 - `color: [r, g, b]`: the key color. r, g and b are the proportions respectively
224 of red, green and blue, and each value must be between 0 and 255
225 - `repeat_delay: x` (default 0) : protection delay. Once all its actions are
226 done, the key will remain disabled (semi-transparent and crossed) for that
227 amount of time (in seconds).
229 #### `common` key property
231 A special entry `common` has its properties applying to all the keys. They can
232 be overriden individually.
234 ### `keys` : actions related to keys
236 This section lets you describe for each key, the list of actions associated to
237 it. Note that except for `wait` and some particular cases (see below), all the
238 actions are almost instantaneous.
255 Runs music "music1.mp3" at 70% of its maximum volume, at 10 seconds from the
256 start, then stops the music 5 seconds later with a 2 seconds fade out.
268 Make a cross fade of 5 seconds between "music1.mp3" and "music2.mp3"
284 Stops music "music1.mp3" with a 5 seconds fade out, waits for the end of the
285 fade out, plus 2 seconds, and then runs "music2.mp3" skipping the first minute.
301 Lower volume of "music1.mp3" while "noise.mp3" is played above it (twice). Then
302 the volume of the music comes back to normal.
317 Pauses "music1.mp3" for 10 seconds and reruns it afterward, seeking to 5 seconds
320 #### List of all the actions:
321 - `play` : start a music. Music Sampler only runs a music once (if you want to
322 have it playing several time concurrently, duplicate it or make symbolic
324 * `file: "music.mp3"` gives the played music (relative path).
325 * `fade_in: x` (optional) runs the music with x seconds fade in.
326 * `volume: x` (optional, default 100) sets the volume of the music.
327 * `loop: x` (optional, default 0) music should be repeated x times. Indicate
328 -1 for infinite loop. Note: x is the number of repetitions, thus the music
329 is actually played x+1 times.
330 * `start_at: x` (optional, default 0) start music skipping the first x
332 * `restart_if_running: true/false` (optional, default false) if the music is
333 already running, stop it and restart it.
334 - `stop` : stops a given music. Parameters:
335 * `file: "music.mp3"` (optional) gives the music to stop. If no music is
336 given, stops all of them.
337 * `fade_out: x` (optional) stops music with a x seconds fade out.
338 * `wait: true/false` (optional, default: false) when stopping with a fade
339 out, wait for the fade to finish before continuing to the next actions. If
340 the music stops naturally before the en of the fade out, the wait stops
341 there too. When several musics are stopped in fade out, the `wait` only
342 waits for the last one in the playlist (which can finish naturally before
344 * `set_wait_id: name` (optional, useless when `wait` is false) sets an id
345 `name` to the wait (see `interrupt_wait`). Any valid string may be used.
346 - `volume` : change the volume of a given music. Parameters:
347 * `file: "music.mp3"` (optional) which music to change. If no music is
348 given, the global volume is changed.
349 * `delta: true/false` (optional, default false) add/remove to the volume
350 instead of setting an absolute value.
351 * `value: x` if delta is false, sets the volume to x%. Note that this factor
352 is applied to the music already loaded (with the initial gain). If delta
353 is true, adds or remove the percentage to the current volume.
354 * `fade: x` (optional) the volume change is applied with a x seconds fade.
355 - `pause` : pause a music. Parameters:
356 * `file: "music.mp3"` (optional) gives the music to pause. If no music is
357 given, it applies to all playing musics.
358 - `unpause` : unpause a music. Parameters:
359 * `file: "music.mp3"` (optional) gives the msuic to unpause. If no music is
360 given, it applies to all paused musics.
361 - `wait` : wait for some time or for an event. Parameters:
362 * `file: "music.mp3"` (optional) wait for the end of music "music.mp3"
363 * `duration: x` (optional) wait x seconds. If `file` and `duration` are
364 given, wait the end of the music PLUS the `duration`.
365 * `set_wait_id: name` (optional) gives an id to the wait event (see
366 `interrupt_wait`). The id can be any valid string.
367 Note again that this action is one of the only action that is not almost
368 instantaneous. Use it wherever you need to make some time adjustments for other
370 - `seek` : seek to a specific position in a music. Parameters:
371 * `file: "music.mp3"` (optional) gives the music to seek. If no music is
372 given, applies to all playing musics.
373 * `delta: true/false` (optional, default false) If `delta` is true, the time
374 seek is relative. Otherwise, it is absolute.
375 * `value: x` If `delta` is true, then moves the music forward or backward by
376 x seconds. If delta is false, the music goes to that position. If the
377 music is fading (fade in or volume fade), the effect is immediately
378 interrupted. If the music is fading out, the "seek" is ignored. In case of
379 `loop`, a relative seek may jump to previous or next loop if possible,
380 while an absolute seek will jump to a position in the current loop.
381 - `stop_all_actions:` Interrupts all the running and pending actions. Note that
382 a started music (even with a `loop` option) is the result of an action that is
383 already finished and thus will keep playing (see `stop` for that). Parameters:
384 * `other_only: true/false` (optional, default false): if `other_only` is
385 true, the interruption is valid for all keys except the one that ran the
386 action. When false, it is thus useless to add actions after that one.
387 - `interrupt_wait`: stop a wait event (normal `wait` or fade out wait). The keys
388 that were waiting will move to the next actions. Parameters:
389 * `wait_id: name` : gives the id of the `wait` to interrupt (defined with
390 `set_wait_id`, see actions `wait` and `stop`). To interrupt several waits,
391 use the same action several times.
392 - `run_command` : Run a command. Parameters:
393 * `command: my_command` : Gives the command to run.
394 * `wait: true/false` (optional, default false) if true, waits for the
395 command to finish (this wait is not interruptible by interrupt_wait)
397 ### `aliases` : define aliases
399 It is possible to define some aliases for the parameters. Those aliases are
400 internal to the configuration file. To give a nice name to a music, see
403 The aliases syntax is the following:
413 You can then use in other places of the configuration file a special argument
414 `include: alias1` or `include: [alias1, alias2]` instead of `param: value`. In
415 the case of several aliases that have identical elements, only the last one is
416 kept. In all cases, a value defined outside of an include takes precedence. See
424 file: "path/to/my/favourite/music.mp3"
431 `music1` is now an alias for `file: "path/to/my/favourite/music.mp3"`. You can
432 use `include: music1` at any place where you would have written `file:
433 "path/to/my/favourite/music.mp3"`. Aliases cannot be used in section
448 `blue` is an alias for color `[0, 0, 255]`. Wherever you need to specify `color:
449 [0, 0, 255]`, you may write `include: blue` instead.
463 `long_time` is an alias for a 42 seconds duration. Instead of `duration: 42`,
464 you may use `include: long_time`.
468 You'll find below a list of possible problems, and a possible solution. If you
469 find some other problems, please contact the author.
471 * The program starts and stops immediately.
473 It is usually a syntax error in the config file. In that case, the terminal
474 should give some informations.
478 It may be a latency problems (with slow computers). Try to adapt it to a higher
481 * Impossible to play more than one music at a time.
483 The system cannot mix the musics by itself. You may have a look at the device
484 list (`--list-devices`) and choose another. You may also try the integrated
485 mixer, but the result may not be very fluid (you will certainly need to adjust
486 blocksize and latency parameters if you do that)
488 If your system uses PulseAudio, it may be a configuration problem for the ALSA
489 plugin. In that case, try to put the following configuration in
490 `/etc/asound.conf` and restart your system. This is an empirical solution that
491 seems to have worked, there is no garanty that it will!
495 fallback "sysdefault"
498 description "Default ALSA Output (currently PulseAudio Sound Server)"
504 fallback "sysdefault"
507 * The terminal shows an error:
509 Exception in thread Thread-1:
510 Traceback (most recent call last):
511 File "threading.py", line 914, in _bootstrap_inner
512 File "threading.py", line 862, in run
513 File "kivy/input/providers/mtdev.py", line 219, in _thread_run
514 File "kivy/lib/mtdev.py", line 131, in __init__
515 PermissionError: [Errno 13] Permission denied: '/dev/input/event6'
517 This is a device permission error. It can be safely ignored.
519 * For other problems or bug, please see [Bug
520 Tracker](https://git.immae.eu/mantisbt/view_all_bug_page.php?project_id=1&sort=status%2Clast_updated&dir=ASC%2CDESC)
524 The musics in the examples come from [Jamendo](https://jamendo.com). The
525 complete version of those musics are available for free for a non-commercial
528 [Short Blues](https://www.jamendo.com/track/340173/short-blues)
530 [To the Fantasy war](https://www.jamendo.com/track/778560/to-the-fantasy-war)
532 The crocodile noise comes from
533 [Universal-Soundbank](http://www.universal-soundbank.com/).
535 This program was developped originaly to help handling music for shows of the
536 circus company [Les pieds jaloux](http://piedsjaloux.fr/). With no available
537 sound manager, the artists sometimes had to run from the scene to make the sound
538 transitions, making as little interaction as possible with the computed (one