====================================================================
		AWE VIRTUAL KEYBOARD ver.0.1.4
	Takashi Iwai  <iwai@dragon.mm.t.u-tokyo.ac.jp>
====================================================================

GENERAL NOTES
-------------

This is a virtual keyboard for AWE, MIDI and ALSA drivers.
It's a simple fake of a MIDI keyboard on X-windows system.
Enjoy a music with your mouse and "computer" keyboard :-)

The program requires Tcl7.5/Tk4.1 libraries.
This program supports:
  - AWE driver on OSS  (ver.0.4.3)
  - MIDI device on OSS
  - ALSA sequencer
Since the most of the part is written by Tcl/Tk script, it'll be not
so difficult to apply this program to other systems.


INSTALLATION
------------

1. Edit Makefile

You may need to modify Makefile for your system.
The following values can be configurable:

  - INSTALL_DIR
      Destination directory where the program will be installed.

  - USE_AWE
  - USE_MIDI
  - USE_ALSA
      Device selection.  Multiple devices are available.
      To disable a device, set the value 0.  Do not undefine it.
      At least one of them must have non-zero value.

  - TCLLIB
      Tcl library for linking, given as "-lxxx"
  - TCLINC
      Tcl include path option for cc, given as "-Ixxx"
  - TKLIB, XLIB
      Tk and X libraries (-lxxx)
  - TKINC, XINC
      Tk and X include path option (-Ixxx)
  - EXTRALIB
      Other required library (-lxxx)
      
2. Run make.

3. Install via "make install".


USAGE
-----

Load the soundfont via sfxload utility before using this program.
Then, just start vkeybd.  The following command line options are
accpted.

  --device mode
	Use the specified mode for output device.
	The argument are "awe", "midi" or "alsa", for AWE/OSS,
	MIDI/OSS and ALSA devices, respectively.
	Default is awe.
  --devfile file
	Specify the device file path for sequencer access.
	As default /dev/sequencer and /dev/snd/seq are used for OSS
	and ALSA, respectively.
  --keymap file
	Use the specified file as keymap file (see below)
  --preset file
	Use the specified file as preset list file (see below)
  --midi num
	Set OSS/MIDI device number.  Default is 0.
  --client num
	Set ALSA client number.  Default is 21.
  --port num
	Set ALSA port number.  Default is 0.
  --queue num
	Set ALSA queue number.  Default is 0.
	

The preset list file is used to describe the list of MIDI preset
names.  If the command line option is omitted, the default preset list
file "~/vkeybd.list", "~/.vkeybd.list" and "/etc/vkeybd.list" are
searched sequentially.  The preset list will appear when "Program"
toggle button is on, and you can select your favorite sound from the
list.

The visible three octave keys start from the key defined in the "KEY"
scale bar (as default 48, C4).  You can turn on and off the sound by
clicking the mouse button on the virtual keyboard.

Each key is mapped on your computer keyboard from 'z' to '\'.
To use the computer keyboard, you should turn off auto repeat on your
X display via "xset -r".
The key assignment can be changed by keymap file.  Each line of keymap
file consists of key symbol and midi note number offset separated by
space.  The key symbol is the X key symbol for assigned key, and note
offset is the shifted note number from note key of beginning of
keyboard, which is changed by "KEY" scalebar.  For example, if a line
contains "a 8", and "KEY" is 48, then MIDI note 56 will be played by
pressing the key "a".  The following files are searched as keymap
file: ~/vkeybd.key, ~/.vkeybd.key and /etc/vkeybd.key.  Otherwise, you
need to specify it by command line option.

The "SeqOff" button is ued to release the sequencer device from
virtual keyboard.  It's convinient to pause a little time for using
another program like MIDI player.

The "VEL" scale bar is used to change the velocity of the sound.
The right button from SeqOff is a controller selection button.
When this button is pressed, a pull-down menu appears, and you can
select the control event to be changed by the scale bar in the right
side of this button.  The "reset" item is used to reset all the
controller values to the default ones.

The "Chorus" and "Reverb" buttons are menu buttons to choose the
arbitrary chorus and reverb modes, respectively.
The scale bar in the right side of these buttons represents a virtual
pitch wheel.  "ClrPitch" button is used to reset the wheel position to 
normal.

The preset list file can be converted from soundfont file via sftovkb
utility included in this package.  For example,
	% sftovkb /usr/local/lib/sfbank/synthgm.sbk > vkeybd.list
The only command line argument is the soundfont file name.  This must
be a full path name.


COPYRIGHT
---------

Copyright (C) 1997-1999 Takashi Iwai

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
