descriptionA music player with actions binded to keys
ownerGitolite user
last changeMon, 26 Jun 2017 15:36:40 +0000 (17:36 +0200)
readme

Documenation in english

Documenation en Français

Bottom of documentation


Table of contents

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

If you use the compiled version of Music Sampler (cf. below for a download link), you need nothing else.

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

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

Compiled version

A compiled version can be created with pyinstaller:

pyinstaller music_sampler.spec

Downloads

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

Options available at launch

All the options below are optional; usually, running the program in the correct folder is enough. Most of the parameters can be defined also in the config file. The command line parameters always take precedence.

The following options are reserved for a more advanced use of Music Sampler, or in case of problem with the standard configuration:

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:

config:
  ...

aliases:
  ...

music_properties:
  ...

key_properties:
  ...

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

This section lets you define global properties for the musics.

Examples

  "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.

  "music2.mp3":
    gain: 0.7

Music "music2.mp3" is loaded at 70% of its normal volume.

List of available options

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

  '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

common key property

A special entry common has its properties applying to all the keys. They can be overriden individually.

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

'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.

'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"

'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.

'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.

'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:

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:

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

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".

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.

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.

It is usually a syntax error in the config file. In that case, the terminal should give some informations.

It may be a latency problems (with slow computers). Try to adapt it to a higher value (~0.1 seconds)

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"
}

This is a device permission error. It can be safely ignored.

About

The musics in the examples come from Jamendo. The complete version of those musics are available for free for a non-commercial use:

Short Blues

To the Fantasy war

The crocodile noise comes from Universal-Soundbank.

This program was developped originaly to help handling music for shows of the circus company Les pieds jaloux. 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).


Sommaire

Music Sampler

Description

Music Sampler est un lecteur de musique qui permet de pré-programmer des transitions musicales, qui peuvent ensuite être lancées à l'aide d'un simple appui sur une touche.

Pré-requis et installation

Si vous utilisez la version compilée de Music Sampler (cf. plus bas pour un lien de téléchargement), il n'y a rien d'autre à installer.

module version minimale commentaire
Cython 0.24 pour compiler Kivy
Kivy 1.9.1 certaines fonctionnalités nécessitent de compiler/installer avec USE_SDL2=1
Markdown 2.6.6 pour la documentation uniquement
pydub 0.16.4
Pygame 1.9.2.dev1 utilisée par Kivy
Pygments 2.1.3 pour la documentation uniquement
sounddevice 0.3.3
transitions 0.4.1
PyYAML 3.11

Le projet est également disponible via pip:

pip install music_sampler

Le programme utilise les polices Symbola et Ubuntu (Regular / Bold), qui doivent être disponibles, et la librairie portaudio:

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

Version compilée

Une version compilée peut être créée avec pyinstaller:

pyinstaller music_sampler.spec

Téléchargements

Utilisation

Tout le travail consiste à préparer les transitions dans le fichier de configuration config.yml.

Lancer ensuite le programme dans le dossier où se situe le fichier de configuration (voir plus bas pour une utilisation avancée). Une fenêtre représentant un clavier apparaît. Le rond orange dans le coin du clavier devient vert lorsque tout est chargé, ou rouge en cas de problème. Une touche grisée et barrée représente une touche non-utilisable pour le moment : soit parce que la musique est en cours de chargement (au lancement du programme, cela peut prendre un peu de temps sur certaines machines), soit parce qu'il y a une action en cours.

Un exemple de fichier de configuration est fourni, avec un certain nombre de touches et de transitions programmées (pour les trois musiques fournies), la syntaxe du fichier (expliquée plus bas) se comprend aisément en le regardant. De plus, certaines touches (par exemple 'ÉCHAP' pour tout arrêter) peuvent être gardées d'une fois sur l'autre.

Actions possibles

Options disponibles au lancement

Toutes les options au lancement sont facultatives ; la plupart du temps lancer le programme dans le bon dossier suffit. La plupart d'entre elles peuvent être définies également dans le fichier de config (à part --config bien sûr). Les arguments en ligne de commande ont toujours la priorité.

Les options suivantes sont plutôt réservées à un usage avancé de music_sampler, ou en cas de problème avec la configuration standard :

Configurer les touches

ATTENTION : le format du fichier de configuration est susceptible d'évoluer, sans garantie de rétrocompatibilité.

Le fichier config.yml utilise la syntaxe yaml. Les catégories et sous-catégories sont gérées par l'indentation par des espaces (mais PAS par des tabulations !). le # est un symbole de commentaire : tout ce qui suit ce symbole sur une ligne est ignoré.

En cas d'erreur dans le fichier de configuration, un message d'erreur s'affiche dans le terminal. Selon la "gravité" de l'erreur, music_sampler se lance en ignorant les actions erronées (en colorant éventuellement la touche en noir), ou ne se lance pas du tout.

Le fichier contient plusieurs sections :

config:
  ...

aliases:
  ...

music_properties:
  ...

key_properties:
  ...

keys:
  ...

config

La section config permet d'enregistrer les paramètres habituellement donnés en ligne de commande. Les '-' dans le nom du paramètre long doivent être remplacés par des '_' (par exemple '--music-path' -> 'music_path'). Pour les switches (debug, focus_warning, builtin_mixing), utilisez la version sans le 'no-' et spécifiez true / false en valeur. Notez que les arguments donnés en ligne de commande sont toujours prioritaires sur les valeurs du fichier.

music_properties : propriétés des musiques

Cette section sert à définir des propriétés globales des musiques.

Exemples

  "music1.mp3":
    name: My favorite music
    gain: 1.4

La musique "music1.mp3" est désignée par le nom "My favorite music". Elle est chargée à 140% de son volume normal.

  "music2.mp3":
    gain: 0.7

La musique "music2.mp3" est chargée à 70% de son volume normal.

Liste des options possibles

key_properties : affichage et propriétés des touches

Cette section sert à décrire l'affichage à l'écran des touches : couleur et texte. Par défaut, une touche "attribuée" à une ou plusieurs actions s'affiche en vert.

Exemples

  'ESC':
    description:
      - 
      - STOP !
    color: [255, 0, 0]
    repeat_delay: 2

La touche échap est de couleur rouge, et le texte "STOP !" est affiché sur la deuxième ligne. Si on appuie deux fois sur la même touche à moins de deux secondes d'intervalle, le second appui est ignoré.

Liste des options possibles

Propriété common

Une entrée spéciale common s'applique à toutes les touches. Les propriétés définies dans cette entrée peuvent être modifiées individuellement.

keys : actions sur les touches

Cette section sert à décrire, pour chaque touche, la liste des actions successives. Notez que la plupart des actions (hors wait et quelques cas particuliers, voir plus bas) sont quasi-instantanées.

Cette section est obsolète et remplacée par une clé actions contenant une liste dans la section key_properties pour chaque touche.

Exemples

'a':
  - play: 
      file: "music1.mp3"
      volume: 70
      start_at: 10
  - wait:
      duration: 5
  - stop:
      file: "music1.mp3"
      fade_out: 2

Lance la musique "music1.mp3" à 70% de son volume max, à 10 secondes du début, puis au bout de 5 secondes coupe la musique avec un fondu de 2 secondes.

'b':
  - stop: 
      file: "music1.mp3"
      fade_out: 5
      wait: false
  - play:
      file: "music2.mp3"
      fade_in: 5

Effectue un fondu enchaîné de 5 secondes entre "music1.mp3" et "music2.mp3"

'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

Coupe la musique "music1.mp3" avec un fondu de 5 secondes, attend la fin du fondu, puis attend encore deux secondes et lance la musique "music2.mp3", au temps d'une minute.

'd':
  - volume: 
      file: "music1.mp3"
      value: 50
  - play:
      file: "noise.mp3"
      loop: 1
  - wait:
      file: "noise.mp3"
  - volume:
      file: "music1.mp3"
      value: 100

Baisse le volume de "music1.mp3" pendant que le son "noise.mp3" est joué par dessus (deux fois). Le volume revient à la normale une fois que les deux écoutes du son "noise" sont terminées.

'e':
  - pause:
      file: "music1.mp3"
  - wait: 
      duration: 10
  - unpause:
      file: "music1.mp3"
  - seek:
      file: "music1.mp3"
      delta: true
      value: 5

Met en pause la musique "music1.mp3" pour 10 secondes et la relance après, en avançant de 5 secondes dans la musique.

Liste des actions possibles:

aliases : définir des alias

Il est possible de définir des alias pour les différents paramètres. Ces alias sont internes au fichier de configuration ; pour afficher un "joli" nom d'une musique, voir plutôt "music_properties".

La syntaxe est la suivante:

aliases:
  alias1:
    param: value
  alias2:
    param1: value1
    param2: value2

On utilise ensuite, dans le fichier de configuration, include: alias1 ou include: [alias1, alias2] à la place de param: value. Dans le cas de plusieurs aliases inclus contenant des éléments identiques, seul le dernier est pris en compte. Dans tous les cas, les alias ne sont pas prioritaires par rapport aux éventuels paramètres définis là où ils sont inclus. Voir les exemples ci-dessous.

Exemples

aliases:
  music1:
    file: "path/to/my/favourite/music.mp3"

keys:
  'a':
    play:
      include: music1

music1 est désormais un alias pour "path/to/my/favourite/music.mp3". À chaque fois qu'on veut écrire file: "path/to/my/favourite/music.mp3", on peut écrire à la place include: music1. Attention, dans la section "music_properties", les alias ne fonctionnent pas, et il faut écrire le nom du fichier complet.

aliases:
  blue:
    color: [0, 0, 255]

keys_properties:
  'a':
    description:
      - 
      - blue key
    include: blue

blue est un alias pour la couleur [0, 0, 255]. À chaque fois qu'on veut écrire color: [0, 0, 255], on peut écrire include: blue à la place.

aliases:
  long_time:
    duration: 42

keys:
  'b':
    wait:
      include: long_time
    play: 
      file: "music1.mp3"

long_time est un alias pour la durée 42 secondes. Au lieu d'écrire duration: 42, on peut écrire include: long_time.

Problèmes possibles

Sont listés ci-dessous une liste de problèmes rencontrés, avec des solutions proposées. Si vous en découvrez d'autre, contactez l'auteur pour les ajouter à la liste.

Il s'agit généralement d'une erreur de syntaxe dans le fichier de config. Dans ce cas, le terminal doit afficher quelques détails sur l'erreur en question (au moins la ligne correspondante).

Il peut s'agir d'un problème de latence (avec certains ordinateurs un peu lents). Essayez de changer la latence (par exemple, 0.1 seconde)

Le système n'arrive pas à mixer les musiques par lui-même. Vous pouvez essayer de regarder la liste des périphériques de son (--list-devices) puis en sélectionner un autre si disponible. Vous pouvez aussi essayer le mixeur intégré à music_sampler, mais les résultats ne sont pas toujours très fluides (ne pas hésiter à jouer avec les paramètres avancés comme latency et blocksize).

Si votre système utilise PulseAudio, il peut s'agir d'un problème de configuration du plugin ALSA. Dans ce cas, essayez de mettre la configuration suivante dans /etc/asound.conf, puis redémarrer la machine (solution empirique qui semble avoir fonctionné, sans garantie !):

pcm.!default {
  type pulse
  fallback "sysdefault"
  hint {
    show on
    description "Default ALSA Output (currently PulseAudio Sound Server)"
  }
}

ctl.!default {
  type pulse
  fallback "sysdefault"
}

C'est une erreur de permission d'accès à un périphérique, généré par la librairie kivy. Elle peut être ignorée et n'aura pas d'incidence.

Divers

Les extraits de musiques proposés en exemples proviennent de Jamendo. Les musiques (complètes) sont disponibles en libre téléchargement pour un usage non commercial :

Short Blues

To the Fantasy war

Le bruit de crocodile provient de Universal-Soundbank.

Cet outil a été développé à l'origine pour faciliter la gestion du son pour les spectacles de la compagnie circassienne Les pieds jaloux. N'ayant pas d'ingénieur son, les artistes eux-mêmes peuvent alors gérer leur musique lorsqu'ils ne sont pas sur scène : d'où la nécessité de préparer les transitions à l'avance et, au moment de la représentation, de réduire l'interaction avec la machine au minimum (une touche).

shortlog
2017-06-26  Ismaël BouyaChange "keys" hash to "key_properties" in config.yml heads/master master
2016-09-22  Ismaël BouyaMerge branch 'load_action'
2016-09-19  Ismaël BouyaDon't lock the application when failing while reloading... heads/load_action
2016-09-19  Ismaël BouyaDisable dead keys and enable capslock
2016-09-19  Ismaël BouyaCleanup key and action workflows
2016-09-19  Ismaël BouyaAdd load_all_musics flag and corresponding actions
2016-09-19  Ismaël BouyaUse @mainthread decorator where necessary
2016-09-19  Ismaël Bouyabump config.yml
2016-09-19  Ismaël BouyaFix configuring not resetting the key
2016-08-12  Ismaël Bouyawait actions are now pausable and resettable tags/1.2.3 1.2.3
2016-08-12  Ismaël BouyaFix common key properties not applying when property...
2016-08-12  Ismaël BouyaFix crash when click on unconfigured key
2016-08-12  Ismaël BouyaMake 'interrupt_wait' able to interrupt all waits
2016-08-12  Ismaël BouyaAdd config example
2016-08-12  Ismaël BouyaAdd config dump in debug mode
2016-08-12  Ismaël BouyaAdd a 'common' section in key properties
...
tags
3 years ago 1.2.3
3 years ago 1.2.2
3 years ago 1.2.1
3 years ago 1.2.0
3 years ago 1.1.0
3 years ago 1.0.2
3 years ago 1.0.1
3 years ago 1.0.0
heads
2 years ago master