documentation_en.md

   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 To compile Kivy with the SDL2 library, you need some packages:
  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. Most of the parameters can be defined also in the config file.
 100 The command line parameters always take precedence.
 101
 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
 108     default)
 109   * `-V, --version`: show current version and exit (only for the compiled
 110     version)
 111   * `-L, --language`: change application language. Current languages: fr, en
 112     (default 'fr')
 113   * `--focus-warning, --no-focus-warning`: show / don't show warning when focus gets
 114     lost (default is to show it)
 115
 116 The following options are reserved for a more advanced use of Music Sampler, or
 117 in case of problem with the standard configuration:
 118
 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
 123     (default "high")
 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
 128     2, for stereo)
 129   * `-s SAMPLE_WIDTH, --sample-width SAMPLE_WIDTH`: number of bytes per frame
 130     (default 2).
 131   * `--device DEVICE` : select another sound device.
 132   * `--list-devices` : list available sound devices.
 133   * `-- ARGS` : arguments for Kivy library.
 134
 135 ## Configure keys
 136
 137 **Warning: the format of the configuration file is still a work in progress and
 138 may change without ensuring backward compatibility**
 139
 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.
 142
 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.
 146
 147 The file contains several sections:
 148
 149     :::yaml
 150     config:
 151       ...
 152
 153     aliases:
 154       ...
 155
 156     music_properties:
 157       ...
 158
 159     key_properties:
 160       ...
 161
 162     keys:
 163       ...
 164
 165 ### `config`
 166
 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
 172 precedence.
 173
 174 ### `music_properties`
 175
 176 This section lets you define global properties for the musics.
 177
 178 #### Examples
 179
 180     :::yaml
 181       "music1.mp3":
 182         name: My favorite music
 183         gain: 1.4
 184 Music "music1.mp3" is named "My favorite music". She is loaded at 140% of its
 185 normal volume.
 186
 187     :::yaml
 188       "music2.mp3":
 189         gain: 0.7
 190
 191 Music "music2.mp3" is loaded at 70% of its normal volume.
 192
 193 #### List of available options
 194 - `name: My music` User-friendly name of the music, used in the interface
 195   instead of the filename.
 196
 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.
 199
 200 ### `key_properties`: drawing and properties of keys
 201
 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
 204
 205 #### Examples
 206
 207     :::yaml
 208       'ESC':
 209         description:
 210           -
 211           - STOP!
 212         color: [255, 0, 0]
 213         repeat_delay: 2
 214
 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.
 217
 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
 222   one)
 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).
 228
 229 #### `common` key property
 230
 231 A special entry `common` has its properties applying to all the keys. They can
 232 be overriden individually.
 233
 234 ### `keys` : actions related to keys
 235
 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.
 239
 240
 241 #### Examples
 242
 243     :::yaml
 244     'a':
 245       - play:
 246           file: "music1.mp3"
 247           volume: 70
 248           start_at: 10
 249       - wait:
 250           duration: 5
 251       - stop:
 252           file: "music1.mp3"
 253           fade_out: 2
 254
 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.
 257
 258     :::yaml
 259     'b':
 260       - stop:
 261           file: "music1.mp3"
 262           fade_out: 5
 263           wait: false
 264       - play:
 265           file: "music2.mp3"
 266           fade_in: 5
 267
 268 Make a cross fade of 5 seconds between "music1.mp3" and "music2.mp3"
 269
 270     :::yaml
 271     'c':
 272       - stop:
 273           file: "music1.mp3"
 274           fade_out: 5
 275           wait: true
 276       - wait:
 277           duration: 2
 278       - play:
 279           file: "music2.mp3"
 280       - seek:
 281           file: "music2.mp3"
 282           delta: false
 283           value: 60
 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.
 286
 287     :::yaml
 288     'd':
 289       - volume:
 290           file: "music1.mp3"
 291           value: 50
 292       - play:
 293           file: "noise.mp3"
 294           loop: 1
 295       - wait:
 296           file: "noise.mp3"
 297       - volume:
 298           file: "music1.mp3"
 299           value: 100
 300
 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.
 303
 304     :::yaml
 305     'e':
 306       - pause:
 307           file: "music1.mp3"
 308       - wait:
 309           duration: 10
 310       - unpause:
 311           file: "music1.mp3"
 312       - seek:
 313           file: "music1.mp3"
 314           delta: true
 315           value: 5
 316
 317 Pauses "music1.mp3" for 10 seconds and reruns it afterward, seeking to 5 seconds
 318 later.
 319
 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
 323   link). Parameters:
 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
 331       seconds.
 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
 343       the others).
 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
 369 actions.
 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` (optional) gives the id of the `wait` to interrupt (defined with
 390       `set_wait_id`, see actions `wait` and `stop`). If not given, interrupts
 391       all wait events.
 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)
 396
 397 ### `aliases` : define aliases
 398
 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
 401 "music_properties".
 402
 403 The aliases syntax is the following:
 404
 405     :::yaml
 406     aliases:
 407       alias1:
 408         param: value
 409       alias2:
 410         param1: value1
 411         param2: value2
 412
 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
 417 below examples.
 418
 419 #### Examples
 420
 421     :::yaml
 422     aliases:
 423       music1:
 424         file: "path/to/my/favourite/music.mp3"
 425
 426     keys:
 427       'a':
 428         play:
 429           include: music1
 430
 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
 434 "music_properties".
 435
 436     :::yaml
 437     aliases:
 438       blue:
 439         color: [0, 0, 255]
 440
 441     keys_properties:
 442       'a':
 443         description:
 444           -
 445           - blue key
 446         include: blue
 447
 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.
 450
 451     :::yaml
 452     aliases:
 453       long_time:
 454         duration: 42
 455
 456     keys:
 457       'b':
 458         wait:
 459           include: long_time
 460         play:
 461           file: "music1.mp3"
 462
 463 `long_time` is an alias for a 42 seconds duration. Instead of `duration: 42`,
 464 you may use `include: long_time`.
 465
 466 ## Troubleshooting
 467
 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.
 470
 471 * The program starts and stops immediately.
 472
 473 It is usually a syntax error in the config file. In that case, the terminal
 474 should give some informations.
 475
 476 * The music sizzles
 477
 478 It may be a latency problems (with slow computers). Try to adapt it to a higher
 479 value (~0.1 seconds)
 480
 481 * Impossible to play more than one music at a time.
 482
 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)
 487
 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!
 492
 493     pcm.!default {
 494       type pulse
 495       fallback "sysdefault"
 496       hint {
 497         show on
 498         description "Default ALSA Output (currently PulseAudio Sound Server)"
 499       }
 500     }
 501
 502     ctl.!default {
 503       type pulse
 504       fallback "sysdefault"
 505     }
 506
 507 * The terminal shows an error:
 508
 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'
 516
 517 This is a device permission error. It can be safely ignored.
 518
 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)
 521
 522 ## About
 523
 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
 526 use:
 527
 528 [Short Blues](https://www.jamendo.com/track/340173/short-blues)
 529
 530 [To the Fantasy war](https://www.jamendo.com/track/778560/to-the-fantasy-war)
 531
 532 The crocodile noise comes from
 533 [Universal-Soundbank](http://www.universal-soundbank.com/).
 534
 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
 539 key).