X-Git-Url: https://git.immae.eu/?p=perso%2FImmae%2FProjets%2FPython%2FMusicSampler.git;a=blobdiff_plain;f=documentation_en.md;h=17b8c87dd1d12fc6a21fd50b38a94f16131ea19a;hp=87b9bd723a05784e7f5e7e5efe46bfb72b6a4292;hb=HEAD;hpb=faed2fa84ff988067532ae880df1ca00efb6a993 diff --git a/documentation_en.md b/documentation_en.md index 87b9bd7..2f570e1 100644 --- a/documentation_en.md +++ b/documentation_en.md @@ -9,6 +9,8 @@ set of actions to run. ## Dependencies and installation +(See next section for Windows installation) + - You need ffmpeg installed. For that, you can use package `libav-tools` (debian): sudo apt-get install libav-tools @@ -39,13 +41,38 @@ 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: +To compile Kivy with the SDL2 library, you need some packages: 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) +## Windows installation + +Following processed worked to install music sampler in a Windows +machine: + +- [Install python 3.9.\* (take 64bit version!)](https://www.python.org/downloads/windows) +- In a command shell (`cmd.exe`), run: + + pip install music_sampler + pip install docutils pygments pypiwin32 PySDL2 kivy.deps.sdl2 kivy.deps.glew + +- [Install ffmpeg (64bit, static)](https://ffmpeg.zeranoe.com/builds/) + and put the content of folder `bin` in the same folder as music and configs. +- [Download Ubuntu font](https://www.1001fonts.com/ubuntu-font.html) + and install Ubuntu-R and Ubuntu-B (Regular and Bold) *for all users* (right clic on the font) +- [Download Symbola font](https://fontlibrary.org/en/font/symbola) + and install it *for all users* (right clic on the font) +- Write a `run.bat` file with: + + :::bash + @echo off + music_sampler + +- Run this `run.bat` when you need it. + ## Compiled version A compiled version can be created with `pyinstaller`: @@ -96,26 +123,29 @@ understand just by looking at it. ### Options available at launch All the options below are optional; usually, running the program in the correct -folder is enough +folder is enough. Most of the parameters can be defined also in the config file. +The command line parameters always take precedence. * `-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) + * `--no-debug, --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. + * `--focus-warning, --no-focus-warning`: show / don't show warning when focus gets + lost (default is to show it) 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. + * `--no-builtin-mixing, --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 @@ -127,6 +157,7 @@ in case of problem with the standard configuration: (default 2). * `--device DEVICE` : select another sound device. * `--list-devices` : list available sound devices. + * `--load-all-musics` : load all the music when starting (default True) * `-- ARGS` : arguments for Kivy library. ## Configure keys @@ -144,6 +175,9 @@ corresponding problems) or abort. The file contains several sections: :::yaml + config: + ... + aliases: ... @@ -156,6 +190,14 @@ The file contains several sections: keys: ... +### `config` + +The config section lets you store configuration parameters that you would +normally use in the command line parameters. The '-' in the long parameter name +should be replaced by '_' (e.g. '--music-path' -> 'music_path'). For toggles +(`debug`, `focus_warning`, `builtin_mixing`) use the version without 'no-' and +specify `true` or `false` as value. Note that command line arguments always take +precedence. ### `music_properties` @@ -211,6 +253,12 @@ protected for 2 seconds after each stroke. - `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). +- `actions: list`: List of actions to run with the key. + +#### `common` key property + +A special entry `common` has its properties applying to all the keys. They can +be overriden individually. ### `keys` : actions related to keys @@ -218,6 +266,8 @@ 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. +*This section is deprecated and replaced by an `actions` key containing a list +in `key_properties` section for each key.* #### Examples @@ -299,6 +349,8 @@ Pauses "music1.mp3" for 10 seconds and reruns it afterward, seeking to 5 seconds later. #### List of all the actions: +- `comment`: does nothing, but shows a comment in the action windows + * `message: "some text"` the message to show - `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: @@ -367,13 +419,29 @@ actions. 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. + * `wait_id: name` (optional) gives the id of the `wait` to interrupt + (defined with `set_wait_id`, see actions `wait` and `stop`). If not given, + interrupts all wait events. +- `pause_wait`: pauses a wait event (only for a wait with duration). The key + that were waiting will keep waiting until the `wait` is unpaused. Parameters: + * `wait_id: name` (optional) gives the id of the `wait` to pause. If not + given, pauses all compatible wait events. +- `unpause_wait`: unpauses a paused wait event (only a wait with duration). The + countdown will resume for the corresponding keys. Parameters: + * `wait_id: name` (optional) gives the id of the `wait` to unpause. If not + given, unpauses all compatible wait events. +- `reset_wait`: resets a wait counter (only a wait with duration). If the wait + was paused, it will stay paused and start at the beginning once it is + unpaused. Parameters: + * `wait_id: name` (optional) gives the id of the `wait` to reset. If not + given, resets all compatible wait events. - `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) +- `load_music/unload_music` : load/unload a music from memory. Useful + with `load_all_musics` option only + * `music: "music.mp3" the music to load/unload ### `aliases` : define aliases