White Key

Software wavetable MIDI player

Introduction

Welcome to the White Key home page.

White Key is a small program that plays back MIDI files through digital audio by using audio samples (WAV files) or SoundFonts (SF2 files). White Key is available for RISC OS, Linux and other operating systems. The latest version is available on the download page.

Known problems with the latest release:
This is the first release of a Linux version. It has not been tested with different kernels or releases. This is the first release of a Windows 95 version, and only command line based. It has not been tested under Windows NT. Stereo-SoundFonts are handled like Mono-SoundFonts. Portamento and modulation are still experimental.

Documentation

The White Key MIDI Player

I General

I-I Status

White Key is a Shareware Program. If you like it, use it very often or are incredibly rich, you should send me a fistful of bucks. The amount shall correspond to usefulness, but be at least five Euro for gainfully employed persons. You don't buy anything additional with this money, it's for the version of White Key you already have. Use of the program is absolutely free of charge for a 30 day period if it is not used commercially.

I-II Copyright

You may copy this program freely and as often as you want, as long as you do not take money for it. You should not make changes to any files or data in the package, or note it clearly somewhere (e.g. in a text file). All foreign product names like Yamaha, Soundblaster, SoundFont and Sound Forge are copyrighted by their owners. The default sample library is based on audio samples from a Yamaha keyboard. I don't know about the copyright, and if you don't have information about it, you should assume that they're also under some copyright. The same applies to the example MIDI files.

II Disclaimer

No responsibility will be taken for any loss of data and/or money as a result of use or misuse of the White Key package.

1. Introduction

1.1. What is White Key?

White Key is a small program that plays back MIDI files through digital audio by using audio samples (WAV files) as well as SoundFonts. This may produce results far better than OPL3 and other crap (even at 8000 Hz), comparable to Wavetable Soundcards and even cheap Keyboards. White Key has the ability to use user-specified samples, so the results may be even better than with middle-class keyboards. Always note: White Key was not intended to be a professional application.

1.2. Features

1.2.1. What White Key is able to do

White Key emulates

the maximum possible number of MIDI file tracks (which is 65535)
the maximum possible number of MIDI channels (16) with drums on channel 10
an infinite number of polyphonic voices on each track and channel
128 Banks with 128 MIDI instruments plus 128 drums on 128 drum sets (giving an overall of more than 2 million instruments)
most important controller changes like program change, main volume and panorama
variable range pitch wheel

White Key uses

8 bit/16 bit mono/stereo WAV-files
optional sampler information in-file for sustain and release loops (smpl section)
optional envelope information in file (private in-comment format)
SoundFonts (version 2.0)

Whie Key produces

internal 24 bit effective stereo sound
8 bit or 16 bit linear or logarithmic stereo or mono sound, depending on your hardware
8 bit logarithmic stereo sound for RISC OS machines

1.2.2. What White Key isn't able to do

at current time

emulate rarely used controller changes
proper emulation of modulation
proper emulation of portamento time, there doesn't seem to be a standard
provide support for 16 bit sound extensions on RISC PC, since 8 bit log is quite sufficient for producing a nice High Fidelity stereo wave

possibly at any time

single key and polyphonic aftertouch
most control changes and all RPN/NRPN messages not mentioned yet
adding complex effects like echoes, filters or 3D-processing

2.Application

2.1. Playing a MIDI song

2.1.1. RISC OS

(If you use the command line, read the DOS section.)
When you double click on the WhiteKey application, it will intall itself on the icon bar. The Help application will explain the rest to you. If your MIDI files are of type 'MIDI' (fd4), you may double click on a song to start replay.

2.1.2. DOS and others

You start replay of a MIDI song file with just entering the name of the program (normally whitekey), followed by the name of the file (e.g. song.mid). This will use the default samples for playback. First all needed samples will be loaded, and then playback starts. Furthermore you can specify one ore more options (separated with spaces) before the MIDI file name. Possible calls could look like this:
whitekey -i -r16000 -v80 -idfC:\WK\IDF2.TXT C:\MIDI\CHOPIN.MID
whitekey -b -sfSOUNDFONT/GM.SF2 MIDI/HYMN.MID

2.2. Possible options

2.2.1. Samplerate

Do playback with a user-defined sample rate (in Hz), useful values are from 4000 to 48000, White Key selects the nearest possible rate for your hardware. The higher the rate, the better is the output quality, but the more calculation time is needed.
The command syntax is
-r<number>

2.2.2. Volume

The produced Sound may seem too quiet (or possibly too loud). Normally the volume is 100 (in Percent) but you can change loudness from 0 to something like 200 or even more, but there may occur oversteering or even wrong output with very high volumes. This switch is especially useful when output is to an 8 bit linear sound system and input are very quiet samples (as the standard samples are). In general you should avoid using this option, remember that you have some knobs on your sound equipment.
The command syntax is
-v<number>

2.2.3. Instrument Definition File

You can specify file names with this option. These will then be used as Instrument Definition Files, and must be of the expected format.
The command syntax is
-idf<filename>

2.2.4. Bank Disable

Every program change on drum channels and all bank switches will be ignored. This option is recommended with the default Instrument Definition File.
The command syntax is
-b

2.2.5. Undefined Instruments

No errors will be generated if an instrument's location is not defined, instead these instruments simply won't get played.
The command syntax is
-i

2.2.6. No Fade Out

Any 'release' envelope definition inside the source samples will be ignored. Activate this switch to prevent sounds from continuing after the note off event. This 'Tracker-style' behaviour is especially useful for very slow machines when playing instruments that normally do have a long fade out time.
The command syntax is
-x

2.2.7. Output to File

White Key has the ability to redirect it's output to a WAV file instead of the audio hardware. Note that when playing with CD Quality you need 10 MB disc space per minute. You can also change the output format, standard is 16 bit stereo, available are 8 / 16 bit mono / stereo.
The command syntax is ( [...]=optional )
-o<filename> [-fm8] [-fm16] [-fs8] [-fs16]

2.2.8. Reiteration

The song will be played repeatedly if this option is used.
The command syntax is
-loop

2.2.9. SoundFonts

2.2.9.1. SoundFont file

When this option is specified, White Key uses the instruments from the given SoundFont for song replay.
The command syntax is
-sf<filename>

2.2.9.2. Bank shift

Although SoundFonts specify a sound bank number for each intrument, these values do not always correspond to those used in the song. Such deviations can be corrected when using this option. The given value will be added to all bank statements in the SoundFont, leading to a upward shift of the sound banks. A common value is '1', which protects the default instrument bank against overwrite. The value '0' corresponds to normal behaviour.
The command syntax is
-shift<number>

2.2.10. Option file

Instead of the command line you can use a text file to hand over parameters to White Key. Within this file each option must start at the beginning of a new line.
The command syntax is
-@<filename>

2.3. The Instrument Definition File

2.3.1. Use

The Instrument Definition File (IDF) tells White Key where to find the sample for a given MIDI program and bank number. It does this in delivering a filename for each possibly used MIDI instrument.

2.3.2. Format

2.3.2.1. Keywords

The IDF is a text file with a special structure: There are two required keywords: #begin and #end. The first marks the start of the instrument search list, the second terminates it. Between them there may be a variable number of lines with the following format:
<bank>, <program>[, <key>]: <path>
Where <bank> is a number greater or equal 1, specifying the sound bank (1 is standard), <program> is a number specifying the program number (1 to 128), and <key> tells the drum key (1 to 128 for MIDI note C0 through G10 on channel 10), only necessary when defining drums. <path> is the path and filename of the respective sample, it can have the standard format for your system, or a system independent form where a double space represents the 'directory' character and a single space the 'extension' character. Note that there must be exactly one space between the colon and the <path> element. There's also one optional keyword: #path <include path>. This may be located before the #begin keyword. <include path> is the system dependent format of a directory where the samples will be searched first. Note that this will always end with the 'directory' character for your system. The path of the IDF will be added to the include list automatically.

2.3.2.2. Example

This is an example for a small IDF, how it could look like on a DOS computer. The MIDI instrument 'Acoustic Grand Piano' will use the file C:\SAMPLES\PIANO1.WAV , the equivalent of 'Tuba' on bank 2 will use C:\SAMPLES\SPECIAL\ELECSND.WAV, and the percussion 'Low Tom' will use C:\SAMPLES\DRUMS\TOM\LOWTOM.WAV :

	

	#path C:\SAMPLES\	

	#begin	

	1,  1: PIANO1 WAV	

	2, 59: SPECIAL  ELECSND WAV	

	1,1,46: DRUMS  TOM  LOWTOM WAV	

	#end

3.Operation

3.1. Speed

3.1.1. General

White Key makes a tradeoff between speed and quality, where none of both is preferred.

3.1.2. The main calculations

White Key has to do many calculations on each sample, there are mainly two multiplications needed to produce a variable volume and variable panorama position sample from a mono sample. This calculations apply to each bit of sample data, so the possible sample rates depend on how fast your machine (your CPU) is, and how many voices are playing simultaneously.

3.1.3. The 'Stepper-Algorithms'

To prevent less used calculations from occuring every time and possibly doing nothing but killing performance, there has been implemented a special manner how these are handled. Things like envelope changes and even the MIDI event trace are called less often than a sample has to be calculated (in the moment with a 100Hz frequency). The only disturbing audible effect may be a 'knacking' or short noise when fast envelope changes are to be done.

3.2. Known problems

White Key uses a library of sound routines which are progressing permanently. At any time there are little bugs and problems when special situations occur. Don't expect White Key to work with any kind of invalid input data.
It is known that

very small or very large values in the envelope definition produce undesired results, this is because of the internal number and stepper arithmetics
The DOS sound output routines fail on some Soundblaster compatibles, and may crash your machine
the RISC OS version occasionally starts playing without audible output
the RISC OS version tries to restore the previous sound channel handler when the program exits, since this is not conform with RISC OS, you should be careful with other sound applications running at the same time

You should also have a look at the other sections, epecially 'What White Key isn't able to do'.

3.3. Technical details

3.3.1. Input Samples

White Key should accept any standard RIFF audio sample files of these formats:

8 bit linear unsigned mono
8 bit linear unsigned stereo
16 bit linear signed mono
16 bit linear signed stereo

Note that panorama effects will not affect playback of stereo samples. The samples may contain up to two loop definitions in the format produced e.g. by Sound Forge. All other possible extensions won't affect the playback, except if you use the private envelope definition inside the 'comment' section.

3.3.2. The private envelope definition

The comment section of a sample may contain special keywords for defining an envelope curve for the sample. The format is explained with this example:



		normal comment line, next line contains keyword

	#attack { 0.1, 1.0 } comment continues

		the latter line will cause the volume of the sample to be raised from 0 to 100% (=1.0) (of the MIDI note on velocity) in 1/10th of a second

	#attack { 2.0, 0.5 }

		it will then lower the volume to half (50% or 0.5) of the 'note on' value within 2 seconds

	#attack { 8.0, 0.0 } and fade out within the next 8 seconds

		normally the sound will be muted immediately at a 'note off' event but we want a nice fade out:

	#release { 0.05, 0.5 } halve current volume after note off event within 1/20th s, and then several times again

	#release { 0.05, 0.25 }

	#release { 0.05, 0.125 }

		there are no more release keywords, so the volume will keep on fading with the current speed, and stop the sound after reaching zero.

Both keywords are absolutely optional, but you should note that in most MIDI files percussion instruments are followed by a note off event immediately after the note on, so you will just hear a short part of the whole sample. If using own drums you should find a way of adding the following comment to the sample:



	#release { ignore }

This is the preferred form of a 'dont mute'.

3.3.3. Output restrictions

White Key's sound system works with a 32 bit stereo internal format, which is 24 bit effective. This means that if values get greater than 24 bit, the next 8 bits are 'cut off', which is known as oversteering. If values become even greater than 32 bit, it will produce errorneous output. With volume set to normal (100%), using samples which exploit the full possible range and are played at maximum possible MIDI volume and velocity, oversteering can't occur if playing up to 4 voices at one time in the middle panorama position, or up to 2 voices at one time in the same extreme left or right panorama position. No errors can occur until you play more than 512 voices at one time together. Normally such extremes are never reached and so you can rely on the standard settings being quite sufficient for most MIDI songs.

4. Support

4.1. General

White Key is not intended to be supported or updated frequently, as long as there is no need for it. If there is a large response to the program and people pay their Shareware fees, this may change in the future.

4.2. Credits

White Key is part of the Flammpunkt project. Coding, RISC OS front end and documentation by Diamond/MSC. Default sound library sampling and noise reduction by AssIt/MSC. Default sound library optimization by Diamond/MSC.

4.3. Contacting the author

The White Key homepage is at
http://www.informatik.hu-berlin.de/~csaszar/whitekey.html
My e-mail address (for comments, bug reports etc.) is
csaszar@informatik.hu-berlin.de
This is true as long as the White Key homepage is accessible. My postal address (for sending greetings, money etc.) can be found inside the package.


		© Copyright David Császár Last update: 11/1999