From faed2fa84ff988067532ae880df1ca00efb6a993 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Isma=C3=ABl=20Bouya?= Date: Thu, 11 Aug 2016 21:36:12 +0200 Subject: Add english documentation --- documentation_en.md | 520 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 520 insertions(+) create mode 100644 documentation_en.md (limited to 'documentation_en.md') 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 @@ +[TOC] + +# Music Sampler + +## Description + +Music Sampler is a music player which associates each key on the keyboard to a +set of actions to run. + +## Dependencies and installation + +- You need ffmpeg installed. For that, you can use package `libav-tools` (debian): + + sudo apt-get install libav-tools + +If you use the compiled version of Music Sampler (cf. below for a download +link), you need nothing else. + +- To use sources, the following modules are required: + +| module | minimum version | note | +| ----------- | ---------------- | ------------------------------------------------------------- | +| Cython | 0.24 | to compile Kivy | +| Kivy | 1.9.1 | some features require to build/install with flag `USE_SDL2=1` | +| Markdown | 2.6.6 | for documentation only | +| pydub | 0.16.4 | | +| Pygame | 1.9.2.dev1 | used by Kivy | +| Pygments | 2.1.3 | for documentation only | +| sounddevice | 0.3.3 | | +| transitions | 0.4.1 | | +| PyYAML | 3.11 | | + +The project is also available via `pip`: + + pip install music_sampler + +The program makes use of fonts "Symbola" and "Ubuntu" (Regular / Bold), that +must be available on your system, as well as the `portaudio` library: + + sudo apt-get install ttf-ancient-fonts ttf-ubuntu-font-family portaudio + +Pour compiler kivy avec la librairie SDL2, il faut certains paquets installés: + + sudo apt-get install libsdl2-dev libsdl2-image-dev libsdl2-mixer-dev libsdl2-ttf-dev + +cf [Installation +Kivy](https://kivy.org/docs/installation/installation-linux.html) + +## Compiled version + +A compiled version can be created with `pyinstaller`: + + :::bash + pyinstaller music_sampler.spec + +## Downloads + +- An example configuration together with some music examples can be found on + [owncloud](https://outils.immae.eu/owncloud/index.php/s/kSrIe15G1AiZ9YF) +- A precompiled version of `music_sampler` can also be found + [in the same folder](https://outils.immae.eu/owncloud/index.php/s/kSrIe15G1AiZ9YF/download?path=%2F&files=music_sampler) + (beware, it might not be up-to-date, please run the program with `-V` to see + its corresponding version) + +## Usage + +The whole job consists in preparing all the transitions in the configuration +file `config.yml`. + +The program should then be run in the folder in which the configuration file +lies (see below for an advanced use). A window with a keyboard appears. The +orange circle in the upper-right corner of the keyboard becomes green one every +music is loaded (or red in case of problem). A key is semi-transparent and +crossed when it is not usable at the moment: either because a music handled by +this key is not loaded yet (it may take some time when the program launches), or +because it has an action running. + +An example configuration file is given with some keys and transitions. The +structure of the file (explained more in details below) should be easy to +understand just by looking at it. + +### Possible actions + + - Clic on a key: shows the associated actions in the bottom-left block of the + app. + - Key stroke: if available, runs the actions associated to this key. When a + key has currently running actions, his surround is black. Note that an + action like "play a music" is almost instantaneous as it is considered + "done" as soon as the music started playing. + To prevent accidents in case of repeated stroke on a key, `Music Sampler` + won't rerun the actions associated to that key if they are not already + finished. + - Ctrl+C or Ctrl+Q: leaves the program. + - Ctrl+R: reloads the configuration file + +### Options available at launch + +All the options below are optional; usually, running the program in the correct +folder is enough + + * `-h, --help`: shows a list of available options + * `-c CONFIG, --config CONFIG`: gives the configuration file to load (by + default, `config.yml` in the current folder). + * `-p MUSIC_PATH, --music-path MUSIC_PATH`: gives the path to find the musics + (by default, the current folder) + * `-d, --debug`: show debug informations in the terminal (disabled by default) + * `-V, --version`: show current version and exit (only for the compiled + version) + * `-L, --language`: change application language. Current languages: fr, en + (default 'fr') + * `--no-focus-warning`: don't show warning when focus gets lost. + +The following options are reserved for a more advanced use of Music Sampler, or +in case of problem with the standard configuration: + + * `-m, --builtin-mixing`: make the sound mixing locally. By default, Music + Sampler will let the system do it and open one channel per music loaded. Use + it only if the system cannot handle it. + * `-l LATENCY, --latency LATENCY`: "low", "high" or a number of seconds + (default "high") + * `-b BLOCKSIZE, --blocksize BLOCKSIZE`: Number of frames for each mixing + step. 0 (default) lets the program choose. + * `-f FRAME_RATE, --frame-rate FRAME_RATE`: default 44100Hz + * `-x CHANNELS, --channels CHANNELS` : Number of channels per music (default + 2, for stereo) + * `-s SAMPLE_WIDTH, --sample-width SAMPLE_WIDTH`: number of bytes per frame + (default 2). + * `--device DEVICE` : select another sound device. + * `--list-devices` : list available sound devices. + * `-- ARGS` : arguments for Kivy library. + +## Configure keys + +**Warning: the format of the configuration file is still a work in progress and +may change without ensuring backward compatibility** + +The file `config.yml` uses yaml syntax. Categories and sub-categories are +handled by space indentations (no tabs). Symbol `#` may be used for comments. + +In case of error in the configuration file, an error message will show up. +Depending on its severity, Music Sampler may try to continue (ignoring +corresponding problems) or abort. + +The file contains several sections: + + :::yaml + aliases: + ... + + music_properties: + ... + + key_properties: + ... + + keys: + ... + + +### `music_properties` + +This section lets you define global properties for the musics. + +#### Examples + + :::yaml + "music1.mp3": + name: My favorite music + gain: 1.4 +Music "music1.mp3" is named "My favorite music". She is loaded at 140% of its +normal volume. + + :::yaml + "music2.mp3": + gain: 0.7 + +Music "music2.mp3" is loaded at 70% of its normal volume. + +#### List of available options +- `name: My music` User-friendly name of the music, used in the interface + instead of the filename. + +- `gain: x` Loads the music with that initial gain x. This lets you equalize all + your music at desired level, independently of the volume afterwards. + +### `key_properties`: drawing and properties of keys + +This section lets you describe the drawing of the key: color, description. By +default, a key assigned to one or more actions is shown in green + +#### Examples + + :::yaml + 'ESC': + description: + - + - STOP! + color: [255, 0, 0] + repeat_delay: 2 + +The "esc" key is red, and text "STOP!" is shown on the second line. The key is +protected for 2 seconds after each stroke. + +#### List of availale options +- `description`: the text on the key. Each item is shown on a line (no automatic + line break). First line is shown just next to the "key" name and is in bold. + On a standard screen, you may have about 3 lines visible (including the first + one) +- `color: [r, g, b]`: the key color. r, g and b are the proportions respectively + of red, green and blue, and each value must be between 0 and 255 +- `repeat_delay: x` (default 0) : protection delay. Once all its actions are + done, the key will remain disabled (semi-transparent and crossed) for that + amount of time (in seconds). + +### `keys` : actions related to keys + +This section lets you describe for each key, the list of actions associated to +it. Note that except for `wait` and some particular cases (see below), all the +actions are almost instantaneous. + + +#### Examples + + :::yaml + 'a': + - play: + file: "music1.mp3" + volume: 70 + start_at: 10 + - wait: + duration: 5 + - stop: + file: "music1.mp3" + fade_out: 2 + +Runs music "music1.mp3" at 70% of its maximum volume, at 10 seconds from the +start, then stops the music 5 seconds later with a 2 seconds fade out. + + :::yaml + 'b': + - stop: + file: "music1.mp3" + fade_out: 5 + wait: false + - play: + file: "music2.mp3" + fade_in: 5 + +Make a cross fade of 5 seconds between "music1.mp3" and "music2.mp3" + + :::yaml + 'c': + - stop: + file: "music1.mp3" + fade_out: 5 + wait: true + - wait: + duration: 2 + - play: + file: "music2.mp3" + - seek: + file: "music2.mp3" + delta: false + value: 60 +Stops music "music1.mp3" with a 5 seconds fade out, waits for the end of the +fade out, plus 2 seconds, and then runs "music2.mp3" skipping the first minute. + + :::yaml + 'd': + - volume: + file: "music1.mp3" + value: 50 + - play: + file: "noise.mp3" + loop: 1 + - wait: + file: "noise.mp3" + - volume: + file: "music1.mp3" + value: 100 + +Lower volume of "music1.mp3" while "noise.mp3" is played above it (twice). Then +the volume of the music comes back to normal. + + :::yaml + 'e': + - pause: + file: "music1.mp3" + - wait: + duration: 10 + - unpause: + file: "music1.mp3" + - seek: + file: "music1.mp3" + delta: true + value: 5 + +Pauses "music1.mp3" for 10 seconds and reruns it afterward, seeking to 5 seconds +later. + +#### List of all the actions: +- `play` : start a music. Music Sampler only runs a music once (if you want to + have it playing several time concurrently, duplicate it or make symbolic + link). Parameters: + * `file: "music.mp3"` gives the played music (relative path). + * `fade_in: x` (optional) runs the music with x seconds fade in. + * `volume: x` (optional, default 100) sets the volume of the music. + * `loop: x` (optional, default 0) music should be repeated x times. Indicate + -1 for infinite loop. Note: x is the number of repetitions, thus the music + is actually played x+1 times. + * `start_at: x` (optional, default 0) start music skipping the first x + seconds. + * `restart_if_running: true/false` (optional, default false) if the music is + already running, stop it and restart it. +- `stop` : stops a given music. Parameters: + * `file: "music.mp3"` (optional) gives the music to stop. If no music is + given, stops all of them. + * `fade_out: x` (optional) stops music with a x seconds fade out. + * `wait: true/false` (optional, default: false) when stopping with a fade + out, wait for the fade to finish before continuing to the next actions. If + the music stops naturally before the en of the fade out, the wait stops + there too. When several musics are stopped in fade out, the `wait` only + waits for the last one in the playlist (which can finish naturally before + the others). + * `set_wait_id: name` (optional, useless when `wait` is false) sets an id + `name` to the wait (see `interrupt_wait`). Any valid string may be used. +- `volume` : change the volume of a given music. Parameters: + * `file: "music.mp3"` (optional) which music to change. If no music is + given, the global volume is changed. + * `delta: true/false` (optional, default false) add/remove to the volume + instead of setting an absolute value. + * `value: x` if delta is false, sets the volume to x%. Note that this factor + is applied to the music already loaded (with the initial gain). If delta + is true, adds or remove the percentage to the current volume. + * `fade: x` (optional) the volume change is applied with a x seconds fade. +- `pause` : pause a music. Parameters: + * `file: "music.mp3"` (optional) gives the music to pause. If no music is + given, it applies to all playing musics. +- `unpause` : unpause a music. Parameters: + * `file: "music.mp3"` (optional) gives the msuic to unpause. If no music is + given, it applies to all paused musics. +- `wait` : wait for some time or for an event. Parameters: + * `file: "music.mp3"` (optional) wait for the end of music "music.mp3" + * `duration: x` (optional) wait x seconds. If `file` and `duration` are + given, wait the end of the music PLUS the `duration`. + * `set_wait_id: name` (optional) gives an id to the wait event (see + `interrupt_wait`). The id can be any valid string. +Note again that this action is one of the only action that is not almost +instantaneous. Use it wherever you need to make some time adjustments for other +actions. +- `seek` : seek to a specific position in a music. Parameters: + * `file: "music.mp3"` (optional) gives the music to seek. If no music is + given, applies to all playing musics. + * `delta: true/false` (optional, default false) If `delta` is true, the time + seek is relative. Otherwise, it is absolute. + * `value: x` If `delta` is true, then moves the music forward or backward by + x seconds. If delta is false, the music goes to that position. If the + music is fading (fade in or volume fade), the effect is immediately + interrupted. If the music is fading out, the "seek" is ignored. In case of + `loop`, a relative seek may jump to previous or next loop if possible, + while an absolute seek will jump to a position in the current loop. +- `stop_all_actions:` Interrupts all the running and pending actions. Note that + a started music (even with a `loop` option) is the result of an action that is + already finished and thus will keep playing (see `stop` for that). Parameters: + * `other_only: true/false` (optional, default false): if `other_only` is + true, the interruption is valid for all keys except the one that ran the + action. When false, it is thus useless to add actions after that one. +- `interrupt_wait`: stop a wait event (normal `wait` or fade out wait). The keys + that were waiting will move to the next actions. Parameters: + * `wait_id: name` : gives the id of the `wait` to interrupt (defined with + `set_wait_id`, see actions `wait` and `stop`). To interrupt several waits, + use the same action several times. +- `run_command` : Run a command. Parameters: + * `command: my_command` : Gives the command to run. + * `wait: true/false` (optional, default false) if true, waits for the + command to finish (this wait is not interruptible by interrupt_wait) + +### `aliases` : define aliases + +It is possible to define some aliases for the parameters. Those aliases are +internal to the configuration file. To give a nice name to a music, see +"music_properties". + +The aliases syntax is the following: + + :::yaml + aliases: + alias1: + param: value + alias2: + param1: value1 + param2: value2 + +You can then use in other places of the configuration file a special argument +`include: alias1` or `include: [alias1, alias2]` instead of `param: value`. In +the case of several aliases that have identical elements, only the last one is +kept. In all cases, a value defined outside of an include takes precedence. See +below examples. + +#### Examples + + :::yaml + aliases: + music1: + file: "path/to/my/favourite/music.mp3" + + keys: + 'a': + play: + include: music1 + +`music1` is now an alias for `file: "path/to/my/favourite/music.mp3"`. You can +use `include: music1` at any place where you would have written `file: +"path/to/my/favourite/music.mp3"`. Aliases cannot be used in section +"music_properties". + + :::yaml + aliases: + blue: + color: [0, 0, 255] + + keys_properties: + 'a': + description: + - + - blue key + include: blue + +`blue` is an alias for color `[0, 0, 255]`. Wherever you need to specify `color: +[0, 0, 255]`, you may write `include: blue` instead. + + :::yaml + aliases: + long_time: + duration: 42 + + keys: + 'b': + wait: + include: long_time + play: + file: "music1.mp3" + +`long_time` is an alias for a 42 seconds duration. Instead of `duration: 42`, +you may use `include: long_time`. + +## Troubleshooting + +You'll find below a list of possible problems, and a possible solution. If you +find some other problems, please contact the author. + +* The program starts and stops immediately. + +It is usually a syntax error in the config file. In that case, the terminal +should give some informations. + +* The music sizzles + +It may be a latency problems (with slow computers). Try to adapt it to a higher +value (~0.1 seconds) + +* Impossible to play more than one music at a time. + +The system cannot mix the musics by itself. You may have a look at the device +list (`--list-devices`) and choose another. You may also try the integrated +mixer, but the result may not be very fluid (you will certainly need to adjust +blocksize and latency parameters if you do that) + +If your system uses PulseAudio, it may be a configuration problem for the ALSA +plugin. In that case, try to put the following configuration in +`/etc/asound.conf` and restart your system. This is an empirical solution that +seems to have worked, there is no garanty that it will! + + pcm.!default { + type pulse + fallback "sysdefault" + hint { + show on + description "Default ALSA Output (currently PulseAudio Sound Server)" + } + } + + ctl.!default { + type pulse + fallback "sysdefault" + } + +* The terminal shows an error: + + Exception in thread Thread-1: + Traceback (most recent call last): + File "threading.py", line 914, in _bootstrap_inner + File "threading.py", line 862, in run + File "kivy/input/providers/mtdev.py", line 219, in _thread_run + File "kivy/lib/mtdev.py", line 131, in __init__ + PermissionError: [Errno 13] Permission denied: '/dev/input/event6' + +This is a device permission error. It can be safely ignored. + +* For other problems or bug, please see [Bug + Tracker](https://git.immae.eu/mantisbt/view_all_bug_page.php?project_id=1&sort=status%2Clast_updated&dir=ASC%2CDESC) + +## About + +The musics in the examples come from [Jamendo](https://jamendo.com). The +complete version of those musics are available for free for a non-commercial +use: + +[Short Blues](https://www.jamendo.com/track/340173/short-blues) + +[To the Fantasy war](https://www.jamendo.com/track/778560/to-the-fantasy-war) + +The crocodile noise comes from +[Universal-Soundbank](http://www.universal-soundbank.com/). + +This program was developped originaly to help handling music for shows of the +circus company [Les pieds jaloux](http://piedsjaloux.fr/). With no available +sound manager, the artists sometimes had to run from the scene to make the sound +transitions, making as little interaction as possible with the computed (one +key). -- cgit v1.2.3