# Soundplant beta 6-12-99

Introduction & Features

Installation & Requirements

Usage Instructions

-main screen

-configuration screen

-more remarks

Usage Hints

Author's Message / About

Note on the limitations of the computer keyboard

.ini File

Manually Editing .keymap Files

Known Bugs & Other Issues

Support the Author / Invest in Soundplant

Contact

Planned / Considered for Future Versions

Legal Stuff

### Introduction & Features

Soundplant is a self-contained digital audio performance program. It turns the computer keyboard into a fully customizable sample-triggering device, allowing the assignment of sound files of unlimited length to keyboard keys, with no external devices needed and no MIDI involved. It can be used to add a live track to an already made song, to mix together tracks in realtime, to create music or loops from scratch, as a drum pad, or as a performance or installation tool; because it is not a synthesizer and instead uses your own digital samples, Soundplant is a virtually limitless electronic instrument. A simple graphic interface provides for point-and-click configuration of each key, including several options which control the way each sound is to be played; keyboard configurations can be saved and loaded. Here is a list of features:

- 50 keyboard keys can be used to trigger sounds, all with very low latency
- capable of playing 8 stereo or mono samples simultaneously (i.e., 8 * (L+R) = 16 channel polyphony) at 16-bit, 44.1 KHz mixed stereo output
- samples can be played from disk, allowing for minimal RAM usage and unlimited sound length; RAM management can be completely controlled by the user
- a true performance program in which sounds can be played and triggered even during configuration
- no MIDI needed or involved; only a sound card is required, preferably one compatible with DirectX (Quicktime 3 or greater is used for sound mixing if DirectSound is not available)
- customizable sound triggering, allowing for looping, sustains, restarts, muting, and off-triggering
- on-screen display of the keyboard can be color-coded to create visual metaphors
- plays .wav and .aif files; those who support this freeware will get a special .mp3-playing version
- saves and load keyboard configurations as .keymap files

### Installation & Requirements

No formal installation is required; simply extract the files contained in the archive into a directory. To start the program, run Soundplant.exe. If desired, create a start menu shortcut to this file. A Windows 9x machine and a sound card are required (but it probably works under NT, too). The program runs optimally when using a 266MHz or better CPU, a full duplex PCI sound card, and at least 32 MB RAM; but it also runs acceptably on much lesser-configured systems.

### Usage Instructions

Aside from a few items, Soundplant is largely self-explanatory; simply use the mouse to select a keyboard key, select a sound file for that key, and play around with the options. Pressing that keyboard key will then cause the sound to play (from any screen in the program). What follows is an attempt at giving a detailed explanation of the usage of Soundplant. The least obvious items probably come up in the Configuration Screen section.

The program contains two main screens: the keyboard page, and the configuration page. Each of the 50 assignable keyboard keys has its own configuration page, but they all have the same options. Always at the top of the screen is the sound channels meter, which gives a real time indication of how many of the program's 8 stereophonic sound channels are in use (if all 8 are being used and an additional sound is triggered, the least recently triggered sound will automatically be eliminated from the mix to make room for the new sound). The Backspace key is a universal silence key which stops all currently playing sounds.

#### Main Screen

The keyboard page, which could be said to be the program's main screen, provides an overview of all of the usable keyboard keys. Each key can be color coded (in the configuration screen) for ease of reference. Clicking on any key will bring up the configuration screen for that key. Holding down the right mouse button on a key will bring up a temporary display at the bottom of the screen which provides a snapshot of that key's configuration. This display includes all relevant information: the assigned file name, its loading configuration (disk- or RAM-based), its loop setting, and its mode (all of this will be further explained in the next paragraph). A row of buttons in the middle of the screen provides standard file operations. Keyboard configurations can be saved and loaded as .keymap files. These are small text files which contain references to the locations of the assigned sound files; they do NOT contain audio data. Pressing the New button will reset all configurations and blank all sound file assignments. Help displays this file.

#### Configuration Screen

In addition to clicking on the key in the keyboard screen, you can also get to this screen by holding down Ctrl and pressing the desired keyboard key; this works from within the configuration screen as well (this does not work with all keys, please see the known bugs section). This page sets some basic options for the playing back of assigned sounds. First, a sound file must be selected using the open button. As soon as a file is selected, it can be triggered by the keyboard key.

Disk-based/RAM-based: Leaving sounds set to disk-based (default) will use the least amount of cpu resources; but sounds played from disk may not trigger as quickly/accurately as RAM-based ones. The main difference between these two settings, aside from program performance issues, is that sounds can only be set to loop if they are first set to RAM-based. When RAM-based is selected, Soundplant immediately attempts to load the file into RAM; this may take a few seconds depending on the size of the file and speed of the computer (if there is not enough free RAM, an error message will appear and the sound will be reset to disk-based). Generally, smaller files should be set to RAM-based, and longer ones to disk-based; though specific situations will certainly require otherwise, and there is little noticeable difference between playing very small sound files as disk- or RAM- based.

Loop: Can only be activated if the sound has been set to RAM-based. Sounds set to loop will do so ad infinitum until they are killed.

Mode: This setting affects how Soundplant will respond if the key is pressed after the sound has already been triggered previously and is still playing. In Sustain mode (default), Soundplant will simply trigger another instance of the sound over the mix, creating a delay effect. In Restart mode, Soundplant will stop the sound that was playing and restart the sound playing from the beginning. In Kill mode, Soundplant will stop the sound from playing altogether. In Mute mode, the sound will be muted, but remain playing (and occupying a sound channel) at zero volume; pressing the key again will un-mute the sound if it has not already finished playing. In Mute mode, the key becomes a mute/un-mute toggle switch (this works with looped sounds, too).

Color: Select a color which determines how the key will appear on the main keyboard screen. The default color for newly loaded sounds will be the color most recently selected.

Check Free RAM: Clicking this button results in a report of the computer's up-to-the-millisecond current free RAM. This is useful for determining whether or not sound files should be loaded to RAM as well as getting an idea of the cpu's overall resources at any given time. The amount reported includes virtual memory; for the most part, Soundplant does not differentiate between virtual and physical RAM.

Copy, Edit: These two buttons are to be used for the editing of audio files in external programs. You may find that work will often need to be done in an audio editor in order to fine tune (literally and figuratively) your sound files. The Edit button initially prompts for the selection of an executable audio-editing program file; once one is selected, it will be saved in the keymap file (i.e., different keymap projects can have different assigned editing programs). The Edit button will launch the selected program and attempt to have it load the selected sound file, though the loading part may not always work (see the known bugs section). The Copy button attempts to copy the audio data of the selected file into the Windows clipboard, so that it can then be pasted manually into an audio editing program. This is more reliable than the Edit button, but also has some issues of its own. The copy function is especially helpful if you want to create new, edited/processed versions of a sound.

#### More Remarks...

Soundplant plays its sound through whichever sound device is selected as the Windows default. You should be able to record the output of this program internally by setting your full duplex sound card's input to 'loopback' or 'wave out' and using any audio editing/recording program (see bugs section for issues related to recording). When I describe this program as 'stand-alone,' I refer to the fact that it requires no external devices and involves no MIDI; but in order to get the most out of this program, an audio editing application obviously must be kept handy in order to create and/or edit the samples you will use with Soundplant. You will get even more use value out of this utility by using the music that you create with Soundplant in conjunction with other sound applications and vice-versa.

That's all there is to know for now. You may want to take a look at the planned future features section.

### Usage Hints

Here are a few ideas to help get you started thinking in terms of the potential of Soundplant:

- you have an unlimited universe of sounds available to you; use a healthy mix of found sounds, real instruments, synthesized instruments, processed sounds and instruments, single notes, chords, phrases, melodies, effects, voice, ambience, other music/media, etc...
- assign the same sound at different pitches to different keys (use an audio editor to save copies of the sound at different pitches), creating a custom scale or customizable chord sequences.
- assign the same or similar sounds with different effects at different keys; employ techniques of slight variation to make your keymap a unique playable instrument.
- use with drum sounds and beat fragments to create a drum pad and manually create beats or drum loops, or add a drum track to another track.
- use a healthy mix of long tracks, loops, and short sounds; keep in mind that by using disk-based mode, the length/size of your assigned sounds is limited only by your disk space.
- use samples that are timed to loop in sync with each other (for example, use a tracking program or Sonic Foundry Acid to create waves out of individual tracks from a looped sequence) in conjunction with the mute mode and use mute/un-mute to bring in and out each track, thereby mixing the song in realtime.
- take advantage of the option to configure sounds while playing them; for example, to terminate a looping sound set to mute, sustain, or restart, simply change the setting of that key to 'kill' and press the key.
- great for adding live 'solo' tracks to otherwise pre-programmed songs, such as those created with tracking programs.
- think of Soundplant as a digital instrument; abandon all established notions of pre-digital music and scales, tonal systems, harmonics, instrumentation, etc...

### Author's Message / About

This program was written to fill what I saw as a gap in low budget sound software for the pc. It was inspired partly by tracking programs such as Scream Tracker and Impulse Tracker which as a secondary function allow the user to play samples using the keyboard; by those old, single button professional samplers used in old-school rap; by a program that I saw on an Amiga years ago which had a similar function (and also worked with video), the name of which I can not remember and possibly never knew; and by consumer level sampling keyboards. I intended to keep it simple so that all the user would need would be some good samples and some good ideas. I am a multimedia artist and not a programmer; for this project, I found Macromedia Director to have the perfect combination of artist-friendliness and complex functionality through Lingo. This first release version of Soundplant was produced between January and June of 1999 in Buffalo, NY, USA.

### Note on the limitations of the computer keyboard

Unfortunately, when any key is held down continuously, Soundplant detects multiple key presses (at rates which differ between computers) and reacts accordingly. This is a main difference between the Soundplant program and an actual sampling keyboard; there is no touch sensitivity or note-sustaining by key depressing involved (but see the planned future features section). However, you can get some interesting delay effects by experimenting with this, especially in conjunction with the mute and sustain modes. With regards to simultaneously pressing multiple keys (what you might call 'chords'), you may find that certain keys do not respond well to this; generally, you won't be able to press more than 4 or 5 keys simultaneously as a 'chord.' This will vary among different keyboards and computers. You may initially find it awkward making live music using the computer keyboard, but you'll get used to it; there are advantages as well as disadvantages over similar music-making systems.

### Soundplant.ini

The ini file is self-documenting and contains some settings which can be toyed with if you are having sound output problems. There is a parameter controlling which sound device on the system to use for sound output, although I have not gotten it to work correctly for me (the program always seems to use the default sound device) and I don't know anyone else with multiple sound cards to test this with. Let me know if you have any success with this setting. There is also a setting which controls (limits) the fidelity of the mixed sound output (and thereby controls/limits overall cpu resource usage). This is set by default to the highest quality.

### Manually Editing .keymap Files

Keymap files created by Soundplant are standard text files which contain no line feeds. They represent a database of all of the keyboard keys and all of the attributes of the assigned sounds, and they can be edited manually in a program like Notepad. This may be necessary if you want to restore a keymap whose sound files you have moved or renamed or if you have moved to a different computer. Basically, the keymap file contains one giant bracketed list [] inside of which are many smaller bracketed lists, one for each key (ie [#a: [...], #b: [...], #c: [...], #d: [...], etc.]). Each of these lists contains several property definitions preceded by a #. The property of concern will be #fname, which defines the file path of the assigned sound. If you need to change the file path, just replace the text that is there with the new path. Simply follow the syntax of the other lists in the file: the path must be in quotes and must be the full path and filename. Note that the enter key is #return, the period (.) key is #period; every other key has a self-explanatory name within the list. You may also want to change your selected external editing program. To do this, just find the list in the keymap file called #extapp (it should be close to the very end of the file) and edit the application path name. All of these instructions will make a lot more sense after you view the text of a keymap file.

### Known Bugs and Other Issues

External Editing Function

Though clicking this button will always cause the selected program to be launched, files whose name or path contain space characters won't open in the editing program (and may result in a harmless 'file not found' error from that program). There is a way around this is: while initially selecting a sound file assignment for a key, in the 'Open' dialog box, manually enter in the name & path of your sound file in 8.3 format (i.e., c:\mysoun~1\wavs\sequen~1\electr~1.wav). This will allow the file to be opened in the editing program regardless of its Windows 95 filename. Otherwise, you could just use the Copy button and paste the audio data into your editing program, especially if you were planning on saving a new copy of the sound anyway (read about issues with the copy function below). The selected editing program path is saved with the .keymap file, and .keymap files can be edited fairly easily (see Manually Editing keymap Files).

Copy to Windows Clipboard Function

I have had trouble pasting copied files into one particular editing program: Cool Edit Pro (the program indicates that data is in the clipboard, but does not respond to the paste command). Since that program happens to be my preferred editor, I will try to get in touch with Syntrillium to try and resolve this issue; I have not found this to be an issue with other editing programs, such as GoldWave. Be aware that the copy function consumes ram, so be careful when copying larger files to the clipboard; a program crash may occur while attempting to copy a sound file whose size outweighs the available ram. Files that have already been loaded to RAM (i.e., set to RAM-based) will obviously take less time to copy to the clipboard than disk-based ones.

Recording Issues

This program does not come with its own recording feature, and therefore an audio recording/editing program must be used to internally record the sound output of Soundplant. If your sound card does not have an internal recording function, try using a program which simulates one such as Virtual Audio Cable. I have found that some ISA sound cards may not be able to properly record the output of Soundplant internally (sound play becomes distorted while loopback recording is taking place [but this creates some interesting effects in its own right!]). Sorry about this, currently it is not fixable...

Quitting

Several key combinations quit the program: ctrl-[, Esc, Alt-F4, as well as the exit button and file menu command; but quiting by clicking on the x in the top right hand corner of the window may not always properly bring up a "save before quitting?" dialog box and therefore may quit immediately. This isn't a huge issue, but be aware that using that quitting method may eliminate the failsafe which prevents you from accidentally quitting without saving your work.

Sounds With Odd Sample Rates

For best results, use sounds that are 8- or 16-bit depth, with a sampling rate of 44.1, 22.050, or 11.025 KHz. Sound files with sample rates that do not match one of these three rates will have their sample rate rounded off to the closest rate and thus play either slower or faster than they are supposed to. Sound output mixes most efficiently and seems to sound best if all samples played at any given time are of the same sample rate and bit depth. Because all sounds are upsampled for the final 44.1 khz mix, you may occasionally find that a low quality sound will sound better in the Soundplant mix if you first manually upsample the sound yourself in an audio editing program (rather than let DirectSound try to do this processing in realtime). Note that trying to mix many low quality samples (i.e. 8 bit and / or low sample rates) often results in even lower quality output.

Ctrl + key Issues

I added this feature to make it easier to quickly configure multiple keys, but a bunch of keys do not work with it: the entire top row (numbers, `, -, =), the bracket keys (ctrl-left bracket will bring up a quit dialog [!] and ctrl-right bracket generates a non-fatal error message), comma, /, \ (non-fatal error message), tab, space, enter (brings up J config screen because ctrl-J = line feed).

Miscellaneous Issues

Although I doubt that the degree is a significant one, I should note that the keys with the fastest reaction-time are (the difference is less than one 60th of a second): enter, space, tab, period, followed by everything else (in that order).

Certain keys which are not supported by the program generate harmless error messages when pressed: all function, edit, arrow, and Windows OS keys; and a couple of combination keys with shift and control.

The program's display may appear awkward if the Windows system font size setting (display properties -} settings -} advanced -} general) is set to large or a custom size (i.e., not the default setting). A few pixels will be cut off at the bottom of the screen, but this does not affect the functioning of the program.

This program is untested on Windows NT but may work fine on that platform anyway (please let me know your experiences). For sound mixing, Soundplant defaults to using DirectSound; if this is not available, the program will try to load Quicktime 3 or greater (available free from Apple). Using Quicktime mixing will decrease program performance slightly, but is still acceptable. If neither of these options are available, Soundplant will use its internal mixing routines (by Macromedia) which give unacceptable reaction times (but it will still work).

Email bug reports to keymap@hotmail.com.

### Invest in the Development of Soundplant / Support the Author

This program beta version is freeware. If you enjoy using this program and have significant disposable income, a donation of any amount (...how about $5 - $40) or in the form of any useful and/or valuable commodity or equipment would be greatly appreciated and would be applied towards improving this program in the future (see planned improvements section). You could also just mail-order a cd of music and interactive artwork by the author, or even hire the author to create an interactive multimedia program. Either option would help support the author and entitle you to upgrade notices as well as a special enhanced version of Soundplant which includes mp3 support. This special version can be emailed or snail-mailed to you on floppies or a cd-rom. Additionally, I should note that at some point if I add enough features I may want to actually sell this program; but anyone who supports Soundplant at this early stage will never have to pay for an upgrade. Please see the next section.

### Contact

Please send all bug reports, questions, problems, comments, suggestions, criticisms, reactions, etc. to:

keymap@hotmail.com

I would love to hear about your experiences using this program, especially in an actual live performance/installation environment.

Although I would prefer that you check with me by email for a current address before sending me something by postal mail, here is a permanent address to which all donations or special packages can be directed with confidence that I will eventually receive it (but it is not my home address):

Marcel Blum

433 Prospect Avenue

Staten Island, NY 10301

USA

Check the web site for updates at http//members.tripod.com/~keymap/

Although all of these features may not be fully in place by the time you read this, I plan to include on this website: the very latest version of Soundplant; news and updates; links to an anonymous ftp site for uploading songs you made with Soundplant (I will choose the best songs feature them on the Soundplant website as a demonstration of the program); music and other artwork made by the author of the program.

### Planned / Considered for Future Versions

- more stereo sound channels (aiming for 32 channel polyphony, i.e. adding 8 more stereo channels)
- real time display of what sounds are playing, which ones are muted
- support for additional keyboard keys: function, arrow, and edit keys
- modifier keys (shift, alt) will have special functions taking advantage of ability to hold key down; i.e., these keys will be more like a regular music keyboard because the program will keep track of whether or not they are being pressed and held down
- internal architecture will be further optimized; this should increase performance of program and make all keys have equal reaction times
- volume and fade controls
- Mac version!
- addition of a "priority" setting for assigned sounds which will allow control over how the program reacts if all sound channels are being used and a new sound is triggered (currently the least recently triggered sound is automatically killed in this situation to allow room for the new sound). This won't be as much of a problem when more sound channels are added, but will fix the problem of sounds being unintentionally or accidentally terminated.
- incorporate sound file properties so that their length and types can be displayed
- if I really have time... add a sequencer!
- add a general program config screen to set items such as default directories and desired sound mixing method.

### Legal Stuff

This software has not been tested on a wide variety of machines; the user of this software acknowledges this and takes on all risks involved with the use of this software. Though there are no known harmful aspects of this program, the author can not be held responsible for any unintentional damage to end-user equipment or body parts resulting from the use of this program.

This program is freeware; it may be freely redistributed provided that the original archive contents remain intact. Please notify the author before redistributing on any fixed media (such as CD-ROM).

###### June 12, 1999

###### (c) Marcel Blum