7 Music Sampler is a music player which associates each key on the keyboard to a
10 ## Dependencies and installation
12 (See next section for Windows installation)
14 - You need ffmpeg installed. For that, you can use package `libav-tools` (debian):
16 sudo apt-get install libav-tools
18 If you use the compiled version of Music Sampler (cf. below for a download
19 link), you need nothing else.
21 - To use sources, the following modules are required:
23 | module | minimum version | note |
24 | ----------- | ---------------- | ------------------------------------------------------------- |
25 | Cython | 0.24 | to compile Kivy |
26 | Kivy | 1.9.1 | some features require to build/install with flag `USE_SDL2=1` |
27 | Markdown | 2.6.6 | for documentation only |
29 | Pygame | 1.9.2.dev1 | used by Kivy |
30 | Pygments | 2.1.3 | for documentation only |
31 | sounddevice | 0.3.3 | |
32 | transitions | 0.4.1 | |
35 The project is also available via `pip`:
37 pip install music_sampler
39 The program makes use of fonts "Symbola" and "Ubuntu" (Regular / Bold), that
40 must be available on your system, as well as the `portaudio` library:
42 sudo apt-get install ttf-ancient-fonts ttf-ubuntu-font-family portaudio
44 To compile Kivy with the SDL2 library, you need some packages:
46 sudo apt-get install libsdl2-dev libsdl2-image-dev libsdl2-mixer-dev libsdl2-ttf-dev
49 Kivy](https://kivy.org/docs/installation/installation-linux.html)
51 ## Installation sous Windows
53 Following processed worked to install music sampler in a Windows
56 - [Install python 3.7.\* (take 64bit version!)](https://www.python.org/downloads/windows)
57 - In a command shell (`cmd.exe`), run:
59 pip install music_sampler
60 pip install docutils pygments pypiwin32 PySDL2 kivy.deps.sdl2 kivy.deps.glew
62 - [Install ffmpeg (64bit, static)](https://ffmpeg.zeranoe.com/builds/)
63 and put the content of folder `bin` in the same folder as music and configs.
64 - [Download Ubuntu font](https://www.1001fonts.com/ubuntu-font.html)
65 and install Ubuntu-R and Ubuntu-B (Regular and Bold) *for all users* (right clic on the font)
66 - [Download Symbola font](https://fontlibrary.org/en/font/symbola)
67 and install it *for all users* (right clic on the font)
68 - Write a `run.bat` file with:
74 - Run this `run.bat` when you need it.
78 A compiled version can be created with `pyinstaller`:
81 pyinstaller music_sampler.spec
85 - An example configuration together with some music examples can be found on
86 [owncloud](https://outils.immae.eu/owncloud/index.php/s/kSrIe15G1AiZ9YF)
87 - A precompiled version of `music_sampler` can also be found
88 [in the same folder](https://outils.immae.eu/owncloud/index.php/s/kSrIe15G1AiZ9YF/download?path=%2F&files=music_sampler)
89 (beware, it might not be up-to-date, please run the program with `-V` to see
90 its corresponding version)
94 The whole job consists in preparing all the transitions in the configuration
97 The program should then be run in the folder in which the configuration file
98 lies (see below for an advanced use). A window with a keyboard appears. The
99 orange circle in the upper-right corner of the keyboard becomes green one every
100 music is loaded (or red in case of problem). A key is semi-transparent and
101 crossed when it is not usable at the moment: either because a music handled by
102 this key is not loaded yet (it may take some time when the program launches), or
103 because it has an action running.
105 An example configuration file is given with some keys and transitions. The
106 structure of the file (explained more in details below) should be easy to
107 understand just by looking at it.
111 - Clic on a key: shows the associated actions in the bottom-left block of the
113 - Key stroke: if available, runs the actions associated to this key. When a
114 key has currently running actions, his surround is black. Note that an
115 action like "play a music" is almost instantaneous as it is considered
116 "done" as soon as the music started playing.
117 To prevent accidents in case of repeated stroke on a key, `Music Sampler`
118 won't rerun the actions associated to that key if they are not already
120 - Ctrl+C or Ctrl+Q: leaves the program.
121 - Ctrl+R: reloads the configuration file
123 ### Options available at launch
125 All the options below are optional; usually, running the program in the correct
126 folder is enough. Most of the parameters can be defined also in the config file.
127 The command line parameters always take precedence.
129 * `-h, --help`: shows a list of available options
130 * `-c CONFIG, --config CONFIG`: gives the configuration file to load (by
131 default, `config.yml` in the current folder).
132 * `-p MUSIC_PATH, --music-path MUSIC_PATH`: gives the path to find the musics
133 (by default, the current folder)
134 * `--no-debug, --debug`: show debug informations in the terminal (disabled by
136 * `-V, --version`: show current version and exit (only for the compiled
138 * `-L, --language`: change application language. Current languages: fr, en
140 * `--focus-warning, --no-focus-warning`: show / don't show warning when focus gets
141 lost (default is to show it)
143 The following options are reserved for a more advanced use of Music Sampler, or
144 in case of problem with the standard configuration:
146 * `--no-builtin-mixing, --builtin-mixing`: make the sound mixing locally. By
147 default, Music Sampler will let the system do it and open one channel per
148 music loaded. Use it only if the system cannot handle it.
149 * `-l LATENCY, --latency LATENCY`: "low", "high" or a number of seconds
151 * `-b BLOCKSIZE, --blocksize BLOCKSIZE`: Number of frames for each mixing
152 step. 0 (default) lets the program choose.
153 * `-f FRAME_RATE, --frame-rate FRAME_RATE`: default 44100Hz
154 * `-x CHANNELS, --channels CHANNELS` : Number of channels per music (default
156 * `-s SAMPLE_WIDTH, --sample-width SAMPLE_WIDTH`: number of bytes per frame
158 * `--device DEVICE` : select another sound device.
159 * `--list-devices` : list available sound devices.
160 * `-- ARGS` : arguments for Kivy library.
164 **Warning: the format of the configuration file is still a work in progress and
165 may change without ensuring backward compatibility**
167 The file `config.yml` uses yaml syntax. Categories and sub-categories are
168 handled by space indentations (no tabs). Symbol `#` may be used for comments.
170 In case of error in the configuration file, an error message will show up.
171 Depending on its severity, Music Sampler may try to continue (ignoring
172 corresponding problems) or abort.
174 The file contains several sections:
194 The config section lets you store configuration parameters that you would
195 normally use in the command line parameters. The '-' in the long parameter name
196 should be replaced by '_' (e.g. '--music-path' -> 'music_path'). For toggles
197 (`debug`, `focus_warning`, `builtin_mixing`) use the version without 'no-' and
198 specify `true` or `false` as value. Note that command line arguments always take
201 ### `music_properties`
203 This section lets you define global properties for the musics.
209 name: My favorite music
211 Music "music1.mp3" is named "My favorite music". She is loaded at 140% of its
218 Music "music2.mp3" is loaded at 70% of its normal volume.
220 #### List of available options
221 - `name: My music` User-friendly name of the music, used in the interface
222 instead of the filename.
224 - `gain: x` Loads the music with that initial gain x. This lets you equalize all
225 your music at desired level, independently of the volume afterwards.
227 ### `key_properties`: drawing and properties of keys
229 This section lets you describe the drawing of the key: color, description. By
230 default, a key assigned to one or more actions is shown in green
242 The "esc" key is red, and text "STOP!" is shown on the second line. The key is
243 protected for 2 seconds after each stroke.
245 #### List of availale options
246 - `description`: the text on the key. Each item is shown on a line (no automatic
247 line break). First line is shown just next to the "key" name and is in bold.
248 On a standard screen, you may have about 3 lines visible (including the first
250 - `color: [r, g, b]`: the key color. r, g and b are the proportions respectively
251 of red, green and blue, and each value must be between 0 and 255
252 - `repeat_delay: x` (default 0) : protection delay. Once all its actions are
253 done, the key will remain disabled (semi-transparent and crossed) for that
254 amount of time (in seconds).
255 - `actions: list`: List of actions to run with the key.
257 #### `common` key property
259 A special entry `common` has its properties applying to all the keys. They can
260 be overriden individually.
262 ### `keys` : actions related to keys
264 This section lets you describe for each key, the list of actions associated to
265 it. Note that except for `wait` and some particular cases (see below), all the
266 actions are almost instantaneous.
268 *This section is deprecated and replaced by an `actions` key containing a list
269 in `key_properties` section for each key.*
285 Runs music "music1.mp3" at 70% of its maximum volume, at 10 seconds from the
286 start, then stops the music 5 seconds later with a 2 seconds fade out.
298 Make a cross fade of 5 seconds between "music1.mp3" and "music2.mp3"
314 Stops music "music1.mp3" with a 5 seconds fade out, waits for the end of the
315 fade out, plus 2 seconds, and then runs "music2.mp3" skipping the first minute.
331 Lower volume of "music1.mp3" while "noise.mp3" is played above it (twice). Then
332 the volume of the music comes back to normal.
347 Pauses "music1.mp3" for 10 seconds and reruns it afterward, seeking to 5 seconds
350 #### List of all the actions:
351 - `play` : start a music. Music Sampler only runs a music once (if you want to
352 have it playing several time concurrently, duplicate it or make symbolic
354 * `file: "music.mp3"` gives the played music (relative path).
355 * `fade_in: x` (optional) runs the music with x seconds fade in.
356 * `volume: x` (optional, default 100) sets the volume of the music.
357 * `loop: x` (optional, default 0) music should be repeated x times. Indicate
358 -1 for infinite loop. Note: x is the number of repetitions, thus the music
359 is actually played x+1 times.
360 * `start_at: x` (optional, default 0) start music skipping the first x
362 * `restart_if_running: true/false` (optional, default false) if the music is
363 already running, stop it and restart it.
364 - `stop` : stops a given music. Parameters:
365 * `file: "music.mp3"` (optional) gives the music to stop. If no music is
366 given, stops all of them.
367 * `fade_out: x` (optional) stops music with a x seconds fade out.
368 * `wait: true/false` (optional, default: false) when stopping with a fade
369 out, wait for the fade to finish before continuing to the next actions. If
370 the music stops naturally before the en of the fade out, the wait stops
371 there too. When several musics are stopped in fade out, the `wait` only
372 waits for the last one in the playlist (which can finish naturally before
374 * `set_wait_id: name` (optional, useless when `wait` is false) sets an id
375 `name` to the wait (see `interrupt_wait`). Any valid string may be used.
376 - `volume` : change the volume of a given music. Parameters:
377 * `file: "music.mp3"` (optional) which music to change. If no music is
378 given, the global volume is changed.
379 * `delta: true/false` (optional, default false) add/remove to the volume
380 instead of setting an absolute value.
381 * `value: x` if delta is false, sets the volume to x%. Note that this factor
382 is applied to the music already loaded (with the initial gain). If delta
383 is true, adds or remove the percentage to the current volume.
384 * `fade: x` (optional) the volume change is applied with a x seconds fade.
385 - `pause` : pause a music. Parameters:
386 * `file: "music.mp3"` (optional) gives the music to pause. If no music is
387 given, it applies to all playing musics.
388 - `unpause` : unpause a music. Parameters:
389 * `file: "music.mp3"` (optional) gives the msuic to unpause. If no music is
390 given, it applies to all paused musics.
391 - `wait` : wait for some time or for an event. Parameters:
392 * `file: "music.mp3"` (optional) wait for the end of music "music.mp3"
393 * `duration: x` (optional) wait x seconds. If `file` and `duration` are
394 given, wait the end of the music PLUS the `duration`.
395 * `set_wait_id: name` (optional) gives an id to the wait event (see
396 `interrupt_wait`). The id can be any valid string.
397 Note again that this action is one of the only action that is not almost
398 instantaneous. Use it wherever you need to make some time adjustments for other
400 - `seek` : seek to a specific position in a music. Parameters:
401 * `file: "music.mp3"` (optional) gives the music to seek. If no music is
402 given, applies to all playing musics.
403 * `delta: true/false` (optional, default false) If `delta` is true, the time
404 seek is relative. Otherwise, it is absolute.
405 * `value: x` If `delta` is true, then moves the music forward or backward by
406 x seconds. If delta is false, the music goes to that position. If the
407 music is fading (fade in or volume fade), the effect is immediately
408 interrupted. If the music is fading out, the "seek" is ignored. In case of
409 `loop`, a relative seek may jump to previous or next loop if possible,
410 while an absolute seek will jump to a position in the current loop.
411 - `stop_all_actions:` Interrupts all the running and pending actions. Note that
412 a started music (even with a `loop` option) is the result of an action that is
413 already finished and thus will keep playing (see `stop` for that). Parameters:
414 * `other_only: true/false` (optional, default false): if `other_only` is
415 true, the interruption is valid for all keys except the one that ran the
416 action. When false, it is thus useless to add actions after that one.
417 - `interrupt_wait`: stop a wait event (normal `wait` or fade out wait). The keys
418 that were waiting will move to the next actions. Parameters:
419 * `wait_id: name` (optional) gives the id of the `wait` to interrupt
420 (defined with `set_wait_id`, see actions `wait` and `stop`). If not given,
421 interrupts all wait events.
422 - `pause_wait`: pauses a wait event (only for a wait with duration). The key
423 that were waiting will keep waiting until the `wait` is unpaused. Parameters:
424 * `wait_id: name` (optional) gives the id of the `wait` to pause. If not
425 given, pauses all compatible wait events.
426 - `unpause_wait`: unpauses a paused wait event (only a wait with duration). The
427 countdown will resume for the corresponding keys. Parameters:
428 * `wait_id: name` (optional) gives the id of the `wait` to unpause. If not
429 given, unpauses all compatible wait events.
430 - `reset_wait`: resets a wait counter (only a wait with duration). If the wait
431 was paused, it will stay paused and start at the beginning once it is
432 unpaused. Parameters:
433 * `wait_id: name` (optional) gives the id of the `wait` to reset. If not
434 given, resets all compatible wait events.
435 - `run_command` : Run a command. Parameters:
436 * `command: my_command` : Gives the command to run.
437 * `wait: true/false` (optional, default false) if true, waits for the
438 command to finish (this wait is not interruptible by interrupt_wait)
440 ### `aliases` : define aliases
442 It is possible to define some aliases for the parameters. Those aliases are
443 internal to the configuration file. To give a nice name to a music, see
446 The aliases syntax is the following:
456 You can then use in other places of the configuration file a special argument
457 `include: alias1` or `include: [alias1, alias2]` instead of `param: value`. In
458 the case of several aliases that have identical elements, only the last one is
459 kept. In all cases, a value defined outside of an include takes precedence. See
467 file: "path/to/my/favourite/music.mp3"
474 `music1` is now an alias for `file: "path/to/my/favourite/music.mp3"`. You can
475 use `include: music1` at any place where you would have written `file:
476 "path/to/my/favourite/music.mp3"`. Aliases cannot be used in section
491 `blue` is an alias for color `[0, 0, 255]`. Wherever you need to specify `color:
492 [0, 0, 255]`, you may write `include: blue` instead.
506 `long_time` is an alias for a 42 seconds duration. Instead of `duration: 42`,
507 you may use `include: long_time`.
511 You'll find below a list of possible problems, and a possible solution. If you
512 find some other problems, please contact the author.
514 * The program starts and stops immediately.
516 It is usually a syntax error in the config file. In that case, the terminal
517 should give some informations.
521 It may be a latency problems (with slow computers). Try to adapt it to a higher
524 * Impossible to play more than one music at a time.
526 The system cannot mix the musics by itself. You may have a look at the device
527 list (`--list-devices`) and choose another. You may also try the integrated
528 mixer, but the result may not be very fluid (you will certainly need to adjust
529 blocksize and latency parameters if you do that)
531 If your system uses PulseAudio, it may be a configuration problem for the ALSA
532 plugin. In that case, try to put the following configuration in
533 `/etc/asound.conf` and restart your system. This is an empirical solution that
534 seems to have worked, there is no garanty that it will!
538 fallback "sysdefault"
541 description "Default ALSA Output (currently PulseAudio Sound Server)"
547 fallback "sysdefault"
550 * The terminal shows an error:
552 Exception in thread Thread-1:
553 Traceback (most recent call last):
554 File "threading.py", line 914, in _bootstrap_inner
555 File "threading.py", line 862, in run
556 File "kivy/input/providers/mtdev.py", line 219, in _thread_run
557 File "kivy/lib/mtdev.py", line 131, in __init__
558 PermissionError: [Errno 13] Permission denied: '/dev/input/event6'
560 This is a device permission error. It can be safely ignored.
562 * For other problems or bug, please see [Bug
563 Tracker](https://git.immae.eu/mantisbt/view_all_bug_page.php?project_id=1&sort=status%2Clast_updated&dir=ASC%2CDESC)
567 The musics in the examples come from [Jamendo](https://jamendo.com). The
568 complete version of those musics are available for free for a non-commercial
571 [Short Blues](https://www.jamendo.com/track/340173/short-blues)
573 [To the Fantasy war](https://www.jamendo.com/track/778560/to-the-fantasy-war)
575 The crocodile noise comes from
576 [Universal-Soundbank](http://www.universal-soundbank.com/).
578 This program was developped originaly to help handling music for shows of the
579 circus company [Les pieds jaloux](http://piedsjaloux.fr/). With no available
580 sound manager, the artists sometimes had to run from the scene to make the sound
581 transitions, making as little interaction as possible with the computed (one