---------------------------------------------------------------------
Note: These modifications are now integrated into the sources, so you
don't need to patch them, just uncomment the appropriate lines in
the Makefile.    ..tt
---------------------------------------------------------------------


This is the README file of TkMidity Ver.1.3, Tcl/Tk interface for
TiMidity MIDI Converter/Player.

TkMidity realizes the Tk interface panel communicating with true
TiMidity program. By using Tk, you can enjoy a beautiful Motif-like
window without Motif libraries.


* CONTENTS

This archive contains the following files:

README.tk	- this file
tkmidity.patch	- a small patch to timidity-0.2h including fixes for
		  tiny bugs 
tk_ctl.c	- a new source file for tk-interface
tkmidity.ptcl	- main tcl/tk source to be preprocessed
tkpanel.tcl	- main control panel tcl/tk script
browser.tcl	- file browser
misc.tcl	- miscellaneous subroutines
tkbitmaps/*.xbm	- bitmap files for TkMidity
tkmidity.ad	- (gray background) resources for TkMidity


* INSTALLATION

- Extract all files on timidity 0.2h source directory
- Apply tkmidity.patch
- Modify Makefile (especially check the wish program name in Makefile)
- Just "make" it.
- Install it by "make install".
- Enjoy!


* USAGE

There are four modes newly featured to TiMidity; repeat, shuffle,
auto-start and auto-exit modes. Repeat mode plays musics after all
files are finished repeatedly. Shuffle mode means the random pick-up
playing. When Auto-start is on, the TkMidity begins playing music as
soon as program starts. Auto-exit means to quit TkMidity automatically
after all songs are over. Each setting can be saved by Save Config
menu.

You can change the display configuration in Displays menu. This
configuration also can be saved on the start-up file by Save Config
menu.

The version 1.3 supports File Open/Close menus, and direct keyboard
control. You can append arbitrary files from file browser. The
shortcut key actions are as follows:

	[Enter]		: Start Playing
	[Space]		: Pause / Start Again
	[c]		: Stop Playing
	[q]		: Quit TkMidity
	[p] or [Left]	: Previous File
	[n] or [Right]	: Next File
	[v] or [Down]	: Volume Down (10%)
	[V] or [Up]	: Volume Up (10%)
	[F10]		: Menu Mode
	[Alt]+[Any]	: Select Each Menu


* PROGRAM NOTES

This version supports both Tcl7.4/Tk4.0 and TclX7.3/Tk3.6 with
addinput. Unfortunately random function is omitted in the normal Tcl
library, I wrote a simple hack to invoke bash from the tcl script.
But this dirty trick should cause an overhead. If you know more smart
solution, please teach me. 

If you have only Tcl7.3 base wish (like included in Slackware 2.x),
the extended Tcl (TclX) and addinput patch are required to handle i/o
between tcl and timidity. Fortunately in the normal Linux distribution
by Slackware, this patch is already included. If you don't have this
patch, please get it via a-ftp, etc. Since Tcl7.4 base wish has
another function to handle i/o, the patch above is not necessary.
The original addinput patch can be obtained from:
	ftp.neosoft.com:~ftp/pub/distrib
or 
	harbor.ecn.purdue.edu:~ftp/pub/tcl/extensions


* TROUBLE SHOOTING

- The program says many RC_UNKNOWN ... and dies.

Possibly, the trouble of communication between TiMidity and Tk
interpreter. Please check the wish program name in your Makefile.
The default is "wishx" (not "wish").

Start the Tk panel directly from command line as:
	% wishx -f /usr/local/lib/timidity/tkmidity.tcl
The Tk window will appear and tell a words "NEXT" on console.
Then you can start TiMidity successfully.

- Tk panel appears, but "Pipe Broken" message pops up.

This occurs when the non-existing file is selected to play. 
The ver.1.3 script verifies the existence of the file before pass to
TiMidity, but occasionally this could happen...


		Takashi Iwai	<iwai@dragon.mm.t.u-tokyo.ac.jp>
				<http://bahamut.mm.t.u-tokyo.ac.jp/~iwai/>
