Notes On The Soundplant 39 .keymap File Structure

Some users have asked about manually generating keymap files for tinkering purposes or as an accessible way to configure Soundplant for the visually impaired. Keymap files are not really meant to be human-readable - meaning they are not organized in the most human-friendly way - but they are fairly easily human editable - meaning you can open them in any text editor and change items like file paths and other properties. With some effort and technical know how, you can learn how to create your own keymap files and use Soundplant that way. The best place to start would be by downloading the example keymaps available here to use as a starting point and template.

• Keymap files are essentially a giant bracketed comma-delineated list of data containing within it 1 bracketed list of properties for each keyboard key. Each of these key property lists are preceded by a numeric code label that represents the key. Every key on the keyboard has a unique keycode label. See the bottom of this page for a table of all Soundplant keycodes and the corresponding keyboard key that they represent.


• The table of keycodes lists the 72 keys assignable in Soundplant. However, keymap files actually contain dummy entries for several other key codes beyond those 72, which are currently unused in Soundplant. You can ignore those additional entries, however keep in mind that they must remain in the keymap file or things won't work properly.


• Key properties (the labels that start with "#") have 4 different types of possible values: integers (whole numbers with no decimal point), floats (fractional numbers with a decimal point), strings (chunk of text enclosed in quotes), and lists (a comma-separated series of values enclosed in brackets). It is important to retain the proper formatting of these values. For example, the volume property #vol has a default value of 255 (which is the maximum). This is an integer which means that this property can never accept fractional values. So 100.5 would be an invalid value for this property but 101 is acceptable. The start offset property #mstarttime is a float (measured in milliseconds), so even if you want the sound to start playing from the beginning, the value has to be 0.00 and not 0. If you want the sound to start playing from the 5 second point the correct value would be 5000.00.


• Keymap files must have no line breaks until the end of the file. So all the important data must be on one single gigantic unbroken line, the first line in the file. Any deviation from this will break the keymap.


• There are a number of properties that need to be set a certain way for key entries that have sound file assignments in order for the keymap to load properly in Soundplant:
  • #fname - string - the full path to the sound file, required.
  • #mnum - integer - must be greater than 0 for the sound to load properly. Just setting it to 1 for any key with a sound is fine. Keys with no sound assigned should have this at 0.
  • #numloops, #loop - integer - to loop infinitely, #loop should be set to 1 and #numloops to 0. To not loop, #loop should be 0 and #numloops should be 1.
  • #mrateshift - float - pitch shift measured in semitones, with a range of -60.00 to 60.00. -12.00 means 1 octave lower, 12.00 means 1 octave higher.
  • #mpan - integer - 0 means center, -100 means panned all the way left, 100 means panned right
  • #mendtime - float - the point in the sound, in milliseconds from start, that you want the sound to stop playing. Typically you'd want this to be set to the full duration of the sound so that the sound plays to the end. As long as you keep #mendtime set to 0.00 AND #mduration set to 0.00, these values will be automatically set when loading the keymap so that the sound plays to the end.
  • #ramordisk - integer - sets whether the sound is loaded to RAM (1) or played from disk (2). Keys with no sound should have this value at 0.
  • #srk, #shiftsrk - integer - the keymode and shift+keymode of the key. 1=sustain, 2=restart, 3=kill, 4=mute, 5=pause, 6=fade.
  • #priority - integer - the channel priority of the key (see documentation for more info on how these settings work). 1=high, 2=default, 3=low.
  • #slave - integer - this setting can help to use RAM more efficiently when the same sound is assigned to multiple keys, however it may be easiest to keep this set at 0.
  • #waveformlist - list - contains amplitude data for drawing the waveform of the sound, best to keep this set to an empty list [] and Soundplant will generate the waveform at load time.
  • #waveformmnum - integer - related to #waveformlist, again best to keep this set to 0.
  • There are more properties than these but the rest are not as important or should be fairly self-explanatory.