tkcd(1)

NAME
TkCD - Tk/Tcl front end for cdplayer

SYNOPSIS
tkcd [-diagnostics] [-match %] [-nodb] [-noopt] [-plus_minus seconds] [-simple]

DESCRIPTION
TkCD is a simple GUI interface for the audio CD player cdplayer 2.0. TkCD allows you to use all the features of cdplayer while retaining an X interface. With TkCD/cdplayer, you have a choice of using either TkCD within X or cdplayer from the command line. TkCD will make use of a subset of information from workmandb databases from the workman OpenLook CD player. TkCD only understands a subset of the full range of workmandb qualifiers, enough to recognise a CD and produce a track index. Unlike workman only one database file is searched. TkCD uses approximate track matching to identify CD's, so it can recognise slightly remastered CD's (for example, where the inter-track intervuls have been altered). This makes it possible to ftp foreign CD databases and still recognise locally mastered CD's and vice versa. TkCD also creates an index file to speed up searches of large database. An index file is created the first time TkCD is run with a workmandb database. On subsequent runs TkCD will only rebuild the index if it is out of date with respect to its database file. You can use TkCD to build your own or add to an existing database. When a a new CD is added to the database TkCD avoids recomputing the entire index by storing new entries at the end of the index file. The index file will be re-ordered then next time you start TkCD (a reasonably cheap operation compared to rebuilding the index). Database entries added by TkCD should be compatable with workman, but may not be due to small timing information disparities between cdplayer and workman ( workman currently uses exact track matching). TkCD is a Tk/Tcl script, so the Tk shell wish must be installed in order to use TkCD. I built TkCD using Tcl 7.3 and Tk 3.6.

  OPTIONS

-diagnostics
    This option dumps out interesting internal info to stdout. During an index build it lists out the CD names to stdout. This may be useful when you're dealing with a corrupt database (the corruption will be after the last reported CD name). The status of CD player operations is reported. Database search progress and search results are detailed.

-match percent
    Specifies the percentage of tracks that must be matched for a CD match to be successfull.

-nodb
    Don't create a database or generate indexes into it. The default is to ask about creating an index if a database can be found. A database and prebuilt index will still be used if available.

-noopt
    Don't optimise the index by re-ordering it. Normally this is done every time you start TkCD (this might be useful if you've got a slow CPU).

-plus_minus seconds
    Specifies the variance allowed for a track to be called a match.

-simple
    Omit the artist, CD name and track title from the main display.

TkCD WINDOW
This window displays summary infomation concerning the CD and the state of the CD player. The top two display fields normally detail the artist, CD name, and current track name. If cdplayer reports any errors TkCD will display them in the first field. The following controls are available in the main TkCD window.

track entry
    You can enter a track in this field and it will be played when the play button is pressed. You can also press the ? track assist button, adjacent to the track entry field, to obtain a list of tracks. Selecting a track will cause it to be played immediately.

eject
    Ejects an Audio CD from the CDROM drive. Pressing eject will close an open tray on some drives. If there is no CD present, the result of pressing eject is drive dependent (eg. it may result in a tray retract).

play
    Plays the Audio CD track entered in the track entry field from the beginning.

pause
    Pauses the Audio CD currently in play. The pause indicator check-button will light up if pause has been activated. If the CD is not playing the button does nothing. To resume a paused CD, press the pause button a second time.

stop
    Stops play.

skip
    Skips the Audio CD to the beginning of the next track.

back
    Skips the Audio CD to the beginning of the previous track.

index
    Activates and deactivates a scroll-able Index window with a play button per track. The index panel allows you to enter new CD information into the database.

volume
    This slider bar adjusts the volume for the CD. Note, not all drives support this feature.

INDEX WINDOW
The index window provides you with a data entry form for entering names of artists, CD's, and tracks. It provides you with a scrollable area for entering track titles against track numbers and track times. To facilitate track identification, each track has a play button immediately adjacent to it. You navigate the fields by using tab and shift-tab, or the up and down arrows, or by pressing return. A value is not committed until you move out of the field. A common error is forgetting to press return on the last track. If a text entry is too long, you can sroll the entry field by using mouse button 2, or by using the left or right arrows. The following buttons are available at the bottom of the Index window.

Add button
    This will add new CD information to the end of the database and append an index entry to the TkCD index file. If TkCD mis-identifies a CD, you can type over the information on the index panel and press the add button to insert a new database entry. At the moment the only way to correct a database entry is to use a text editor. If you do this, when you next start TkCD, it will detect the out of date index file and ask your permission to build a new index from scratch.

Rebuild Index
    This button will force a rebuild of the entire index. Use it if your index has been damaged (eg ran out of disk space last time). TkCD will prompt before building an index file. During a build a status window will pop up and show you how the build is progressing. The status window periodically reports the last processed CD name and position in the main database. A slider scale indicates percentage complete. During a build all non index dependent functions remain available, so you can continue to play, skip, eject, etc while you wait.

Dismiss
    Dismiss the Index window.

TKCDRC
The optional Tcl files /usr/local/lib/tkcd/tkcdrc and ~/.tkcdrc are sourced one after the other. The following configuration options are available.

set lib libdir
    Library directory where bitmap directory can be found.

set matsushita_bugs 0/1
    The CD-ROM device driver for Kotobuki/Matsushita/Panasonic CR-5xx drives for Sound-Blaster ("Pro" or "16 ASP" or compatible) cards has problems for me under Linux 1.1.29 and 1.1.50. Set matsushita_bugs to 1 to work around these bugs by using combinations of other operations.

set simple_interface 0/1
    Omit CD name and track title from the main interface. Useful if you're not bothering with a database.

set no_db 0/1
    Don't use the database or create an index into it.

set no_opt 0/1
    Don't optimise the index to the database on startup.

set cd_sync_secs n_seconds
    How frequently to exec cdplayer to resync time with the cd drive (seconds).

set db_filename database_location
    Where the database file can be found.

set db_index_filename index_location
    Where to put tkcd index for the database. Must be a writable directory.

set db_meta_index_max n_tracks
    Number of meta index entries. Should be a guess a reasonable upper limit on the number of tracks on a CD. All CD's with greater than or equal to the maximum number of tracks/entries are pointed to by the last meta index entry.

set db_plus_minus n_seconds
    Required accuracy for a track to be counted as a matched track (seconds).

set db_match_ratio x
    Proportion of tracks that must match for a CD to be matched. For example 0.20 would mean only 20% of the tracks would have to be within db_plus_minus setting for a CD to be matched. N.B. tkcd does not stop on the first match, it tries to find a best match.

ENVIRONMENT

As for
    cdplayer.

FILES

/usr/local/lib/tkcd/bitmaps
    Directory where the button bitmaps are kept. This location can be altered by editing the script and altering the set of the lib variable.

/usr/local/lib/tkcd/tkcdrc
    Option configuration startup script. Sourced first.

~/.tkcdrc
    Optional configuration startup script. Sourced second.

~/.workmandb, /usr/openwin/lib/workmandb or /usr/local/lib/tkcd/workmandb
    Optional database file.

~/.tkcd_index
    Index into the database. The index file contains a track-count, seek-offset, and track-lengths (in seconds) for each CD. The index is ordered by the number of tracks on a CD. The index is headed by a meta index. The meta index is jump/seek offset into the index proper which is It resides in the first line of the index file and has a constant size. The last meta index entry is for everything with n or more tracks, and anything that has been added to the database during this session.

SEE ALSO
cdplayer(1) wish(1) workman(1).

BUGS AND LIMITATIONS
Please send any bug reports to hamilton@wcc.govt.nz (or michael@actrix.gen.nz). To avoid excessive overhead I don't continuously track the CD status during play. The status of a playing track is checked every two minutes (see the script for details) or when the track is due to complete. The status is also updated when ever you press a button. You can fool TkCD if you bypass it and use the manual controls or other CD player software. TkCD cannot update existing entries is a database. You can modify and then copy an existing entry by using the add button - this will write a new entry to the end of the database - but the old copy will also be present at its old location. If the database is updated outside of TkCD, the tkcd_index file has to be rebuilt. This should happen automatically, but you can also force it by removing the index file. TkCD's CPU overhead is quite small. TkCD and wish together consume a reasonable amount of memory (about 900k). Scrolling the Index Panel rapidly results in jerky movement due to excessive processing of focus in/outs on the index panel. At this time this remains a problem looking for a solution. The CD-ROM device driver for Kotobuki/Matsushita/Panasonic CR-5xx drives for Sound-Blaster ("Pro" or "16 ASP" or compatible) cards has problems for me under Linux 1.1.29. Here is a summary of the problems and the work-arounds I have applied:

Kernel Configuration
    Under linux 1.1.50 (and possibly other versions greater that 1.1.29) I've had to set the #define EJECT 1 in the kernel source file .../linux/drivers/block/sbpcd.c to #define EJECT 0 (zero) and rebuild the kernel. Otherwise both cdplayer and workman will open the drive at inappropriate moments - eg. whenever you run cdplayer.

Eject
    Issuing a cdplayer request will cause an open tray to retract. Normally TkCD uses "cdplayer status" to detect the status of the drive. When the Matsushita fixes are enabled TkCD will save the state of the tray. If TkCD believes the tray to be open it will not issue any cdplayer requests until you press another button. This fix works fine so long as you refrain from fooling TkCD by using the CD drives eject button. Another eject related problem is that eject will only work if the drive is actually playing a track. The fixes work around this problem by always issuing a play track 1 request before issuing an eject.

Play
    Issuing a play request while the drive is in the playing state has no effect. With the fixes enabled, pressing play will issue a stop request followed by a play request for the new track.

Skip
    Skip doesn't work, so TkCD simulates skip by doing a stop and then a play on the appropriate track.

End of CD
    After the end of the CD is reached, an incorrect status of playing instead of stopped is returned. TkCD is sometimes fooled by this (but not often).

AUTHOR
Michael Hamilton (michael@actrix.gen.nz or hamilton@wcc.govt.nz) A large chuck of the TkCD is an in-lined copy of fm.tcl a prototype forms widget/module I've written in order to learn more about Tk/Tcl. Comments and enhancements welcomed.

ACKNOWLEDGEMENTS
Mark Buckaway (mark@datasoft.com), Datasoft Communications author of cdplayer. Steven Grimm (koreth@hyperion.com), author of workman.

LICENSE
See the tkcd script for details.