Tk3play - version 1.00 - 4/22/97
Home Page: http://desmodus.biom.cornell.edu/tk3play/

Plays mpeg layer I, II, and III audio files with a Tk interface.
Please see the file Troubleshoot if you have trouble getting tk3play
to work.

I'm always open to suggestions on ways to improve tk3play.

Changes:
Version
1.00b   - Bugfix: name changed from mpg123 to mpg123-m during
          PLAYER variable initialization.

1.00a   - mpg123 is now the decoder.  Should be able to decode with 
	  486-100.  Even if you have less you should be able to use
          mpg123's single channel or downsample mode to run on a 486-66.
          Add the necessary options to the PLAYER variable in your 
          ~/.tk3playrc file. You can still choose to use l3dec to 
          decode low bitrate streams (64 kbit, 56 kbit, ... are 
          currently not supported by mpg123).

	- New Playlist feature:  Right clicking on a directory in the
          directory window adds an *.mp* entry to the playlist.  If 
          the plylist had no name, the name of the directory becomes
          the name of the playlist. (Good for albums when the directory
          is the name ofthe album.)

	Bug Fixes:
	- Clear & Replace now clear the playlist name.

	- Trying to save empty playlists now does nothing.

	- Directory entry box in the playlist editor works.

0.97	- A statically linked executable is now installed by default
          (make cleaninstall).  If you have tcl7.6 installed and 
          previous versions of tk3play worked, you can install the
          smaller script version of tk3play by doing 
          make uninstall; make install-script

	- You can now select either maplay or l3dec to decode.
          (Set this in system.tk3playrc or ~/.tk3playrc)
          I found maplay would crash occasionally, causing tk3play 
          to jump to the next song.  l3dec seems more stable.  
          l3dec can also decode lower bitrate streams 64 kbit/s, 
          56 kbit/s, etc...  Maplay can't (yet).

	- l3dec won't decode filenames with spaces.  This problem
          is overcome by creating the symbolic link ~/.tk3play/tmplink
          which points to the filename to be played.
          l3dec then plays the link.  Don't delete this file if l3dec
          is currently playing it!

	- playedit is no longer a separate executable.  A playedit.tcl
          script is sourced by tk3play on startup.

	- Total & Remaining buttons now work even if you're not
          playing a song.

	- The ~/.tk3play directory is created automatically the first
	  time you start tk3play.

	Changes to the Playlist Editor:

	- Double clicking in the File box automatically appends
          the song to the playlist.

	- The playlist box scrolls to the bottom after an append so
          you can see the newly appended songs.

	- Double clicking the playlist box automatically brings
          up the edit dialog.

        - The edit dialog now allows you to change the position
          of the song in the playlist.

	- Fixed minor bugs with the directory and file entry boxes.

0.96    - The new playlist editor requires Tcl/Tk 7.6/4.2.
          The documentation has been updated to reflect this.

0.95	- Tk3play w/ playlist editor.  
          tkbrowse is no longer used.
          Please send your suggestions for improvements with the 
          playlist editor!
          Please let me know when you find bugs too.  Thanks.

        - Filenames with spaces are handled properly.

        - Upper and lower case "mp" extension filenames are now
          recognized.  Previously the extension had to be lower case
          otherwise, you would get an "... appears to be a invalid 
          mpeg" error.

        - Added 'make cleaninstall' which deletes your current 
          installation (if any), then installs the new one.

        - Added Troubleshoot file.

0.91    - Converted Repeat and Shuffle buttons into one easier to use
          toggle (Normal, Repeat All, Repeat Track, Shuffle)

        - Resize Button to "minimize display".  Window size can be
          toggled between any number of sizes which are specified in
          your ~/.tk3playrc file.  Bugs - The tk3play window jumps 
          after the first resize and after you have moved the window.  
          This may depend on your particular window manager.

        - Bugs in tkbrowse fixed.  A few more instructions for using
          tkbrowse and loading tracks/playlists are now included in
          the Use: section below.

	- If a mpeg track is not stereo, "Mono" is now displayed in 
          green instead of red.

        - The width of the track and time fields have been increased to
          handle up to 999 and 999:59 respectively.

	- Multiple files can be specified on the command line.  All files
          before the last playlist specified are not loaded.  See Use:
          instructions below.

        - An autoplay option can be set in the ~/.tkplayrc file.  
          If set to 1, the tk3play will startup playing the first song, if
          one has been specified on the command line.  This option has no 
          effect on tk3play operation after tk3play has started.

0.90    - maplay is now used to decode!  The source is included and
          is just as fast as l3dec.  No more shareware requirement.
          Currently only 96, 112, 128, and 256 kbit/s layer III 
          streams are supported.  I haven't tested layer II and 
          layer I support yet.

        - Supports single file playing (file can be specified 
          on the command line or through a file browser).

	- Playlists support a pausing feature which allows you
          to specify a pause between songs.

        - System and user rc files are read to allow customizations.

	- All source code is included and has been put under GNU's
          General Public License (see the file COPYING for details)

0.62    Playlist bug fix.  Now you can run even if you don't have a 
        ~/.tk3playlists directory.

0.61    Increased usability of playlists.  You can now use wildcards
        to specify files in the playlist.  Filenames with wildcards
        get globbed and the resulting list of files gets added to 
        the playlist alphabetically.  Extra spaces at the end of the
        filenames no longer cause errors.

        Playlist files are now searched for in the current directory 
        and then the directory ~/.tk3playlists.  Placing your playlists
        in this directory means you no longer need to type the full
        path.  The playlist directory can be customized by changing the
        PLAYLISTDIR variable set at the top of the tk3play script.


Tk3play is a front end to the mpg123 command-line decoder.  
It controls mpg123 | bwavplay pipeline to play mpeg audio.
Currently the audio support provided in mpg123 is not used, but I
plan to use it in the future.  This should make tk3play portable
to other unixes.

Bwavplay is a customized version of wavplay that allows buffering 
pcm samples in memory.  Mpg123 is now used to decode mpeg audio 
files.  It includes support for layer I, II, and 96-256 kbit/s 
layer III streams.  I've modified mpg123 for use with tk3play:

 - reformated output to be similar to l3dec (Easiest way to support
   both mpg123 and l3dec).
 
I've modeled the front end after WinPlay3 and have incorporated most
of its features.  I've also added a scale to allow jumping to any part 
of the song.  It might now be possible to open a TCP/IP connection
to play mp3's over the net using mpg123, but I haven't tested it yet.  
There are lots of other little features which need to be added as well.

To install:
	    Untar and take a look at the makefile.  Referenced to the 
            static version of tk3play refers to a distribution which 
            contains a statically linked tk3play executable.  If you
            don't have Tcl/Tk and TclX installed on your system you should 
            get the static version (currently tk3play-static1.00a.tar.gz).

         1. 'make cleaninstall' cleans out any old installations and installs
            the new version.  If you did not download the static version
            of tk3play then you must have Tcl 7.6 / Tk 4.2 as well as
            TclX 7.6 installed on your machine.  The static version of
            tk3play should work no matter what version of Tcl/Tk you have
            or even if you don't have any version installed.

         2. 'make uninstall' will remove the files associated with
            the current installation of tk3play.  With the static
            version 'make uninstall' does not remove the Tcl library 
            directories (in /usr/local/lib).  If you know you don't 
            need them you have to remove them manually.

            I suggest using 'make cleaninstall'.

         3. If you have a customized ~/.tk3playrc file from an older
            version of tk3play, check the new 
            /usr/local/lib/tk3play/system.tk3playrc for new 
            configuration options.

            I've included elf binaries, if you want
            to compile the programs yourself, 'make exe' will compile
            the executables.  You'll need to get statically linked 
            tcl, tk, tclx libraries to compile the statically linked
            version of tk3play.

To use:
            If tk3play doesn't work see the Troubleshoot file
            included in the distribution.  See the tk3play manpage
            more more detailed information.

	1.  A system wide startup defaults file,  
            system.tk3playrc was placed in /usr/local/lib/tk3play
            during installation.
            You can copy this to ~/.tk3playrc for individual
            customization.

	2.  Type 'tk3play [playlist | mpeg_file ...]'.  Tk3play will 
            load the playlist or mpeg files you've specified on the 
            command line.  If a file specified on the command
            line is not in the current directory the directory ~/.tk3play
            is searched.  If you didn't type any files, the playlist
            editor window is automatically opened.

	    The playlist contains 
            a list of mpeg files to be played.  More than one file can be 
            specified on the command line.  Playlist files replace any
            previously loaded files.  Regular mpeg audio files are added
            to the end of the in memory playlist.  Songs will be played in 
            the order specified in the last playlist.

            Playlists can contain wildcard characters.
            Lines in the playlist can optionally contain a pause value
            as the first entry.  This value specifies the amount of 
            time to pause after finishing the previous song, before 
            starting the current song.  A sample playlist file is included
            in the file 'samplelist'.

	3.  Loading tracks using the playedit window: 
            Press "Playlist" in the main tk3play window to open
            the playlist editor. 

            If you select a playlist, the playlist editor will 
            try to load all the songs in the playlist.
            You can use Shift-click and Control-click to select
            multiple files.  The \/ and /\ next to the Replace,
            Append, and Remove buttons are supposed to be arrows
            giving you a sense of the file movement.

            If you find the playlist editor confusing or have
            have suggestions for improving it please
            let me know.

        4.  Many other options can be specified in the rc file.
            See the documentation in system.tk3playrc.  This file
            is placed in /usr/local/lib/tk3play by default and
            can be copied to ~/.tk3playrc so users can make individual
            changes.

        5.  As stated in the mp3play README:

	    " Hope your computer is godawful fast (my PPro 200 handles it
	      very nicely :)  brings load to 0.5) "

            It uses about 75 percent of my Cyrix P166 (l3dec decoding).
            Slower machines may notice some crackles, especially 
            when play is starting.  Pentiums are a must.
	    (It only uses 70 percent with the new maplay decoder :)

	    Update: The new mpg123 only uses 43 percent of my Cyrix P166!

	    Let me know if faster decoders become available.

Bugs:

        If the mouse is off the scale when the button is released,
        the jump is canceled.  (Actually meant to be a feature but
        I may change it back.)

        Unless you've fixed the permissions only root can opening the
        audio device (/dev/dsp) for writing.  If your not worried
        about security 'chmod 666 /dev/dsp' should fix it.
	Setting the setuid bit on bwavplay might work too, but
        I'm not sure how secure this is.

	Most error messages are sent to stdout instead of popping
        up in window.

	The tk3play window jumps on the first resize and after 
        you have moved the window.  
        This may depend on your particular window manager.

	Tons more, I'm sure.  Please let me know.


Credits:

	Michael Hipp (Michael.Hipp@student.uni-tuebingen.de) and 
        Oliver Fromme (oliver.fromme@heim3.tu-clausthal.de)
        - wrote the wicked fast mpg123 decoder.

	Jeff Tsay (ctsay@pasteur.eecs.berkeley.edu) - added Layer III 
	optimizations and created the maplay 1.2+ for Windows.

	Timo Jantunen (timo.jantunen@hut.fi) - added layer III 
	optimizations (from Jeff Tsay's maplay) and playlist features to 
	the UNIX version of maplay. 

	Tobias Bading (bading@cs.tu-berlin.de) - wrote original maplay.


Brian Foutz
bef2@cornell.edu
