The PRESS PLAY ON TAPE joystick-to-midi converter version 0.5
==============================================================


BACKGROUND:

This software was used by PRESS PLAY ON TAPE to trigger samples from a
sampler by MIDI triggered by game controllers. It will take standard
Windows joysticks and send MIDI messages.

Please note that this software was written for a very specific purpose
and has thus not been designed with anything but this in mind. Feel
free to use this software as you like, change it, rewrite it, be
inspired by it. It will probably never be made into a generally
useable program, but it should be easy to tweak to your needs if you
know a little about how to code Java.

LICENSE:

This software is just provided "as is" and for free as in Free
Beer. Feel free to use it in whichever maner you find useful. The
underlying joystick driver used is released under the "Artistic
License" --- see the license.txt file included under
com/centralnexus/input. The driver can be downloaded in full from here:

http://sourceforge.net/project/showfiles.php?group_id=14848&package_id=12060

INSTALLATION AND USAGE:

This software was made to run on Windows. The joystick driver used
also comes in a Linux version so porting should be perfectly possible
and straightforward.

Make sure you have Java installed and in your PATH. Connect all
joysticks before you start the program. Run the "run.bat" script. For
each joystick attached you will be given the option to specify MIDI
output, Midi channel, and preset button layout (currently hardcoded,
but easy to change (see below). When you have selected your prefered
settings, click the "Activate" button and the program will start to
run. It is not possible to change settings when activated.

SAMPLER

To play the samples we bought the program VSampler from
www.vsampler.com and set our program to fire MIDI intro this through a
virtual MIDI cable called "Speedsoft Midi Cable" which works as a
software MIDI connection. You could also route MIDI to an external
MIDI sampler/keyboard.


CUSTOMIZING THE PROGRAM:

For each controller you want to configure a "buttonmap" must be made
in the file ButtonToMidiMaps. Take a look at the existing examples to
see what is possible. Basically you can specify which MIDI message to
be sent upon key press and release. 

The events are handled in the file JoystickHandler.java in the two
callback methods:

* joystickAxisChanged(): Analogue controllers and also the directional
  pad on a PS2/XBox controller. There are three modes for using this:
  DRUM_MODE only sends MIDI ON message (we used that for the dancemat
  controller), GUITAR_PICK triggers whatever keys were pressed within
  the last 200ms when struck, and DIGITAL which is used for the
  directional pads. See the different constructors for AxisAction.java
  for more details.

* joystickButtonChanged(): Button pressed/released. There are two
  types of button presses: IMMIDATE_SEND (the default) and
  SEND_ON_PICK which is made to support the guitar controller as you
  only want to send the button pressed, when you strike the pick
  (which is the Y-axis). See ButtonAction.java for more details.

If you have any questions feel free to contact us. Write to
ppot@pressplayontape.com. If you use this software for something fun,
then write and tell us about it :)

December 2005
Jesper Holm Olsen
PRESS PLAY ON TAPE