VMusic -- CD/Tape Music Collection Database
Bob van der Poel
14 March 2006
Version 2.7
VMusic
is a simple database program to catalogue and search
a collection of CDs (or, if you're into such things, cassette tapes,
or even Real Records).
Table of Contents
vmusic
[ -v
]
VMusic
is a simple program written in Python/Tkinter which will
catalogue, display, search and other manage a collection of music CDs.
It only operates in a GUI mode. There are no important options to start the program.
-v
Prints the version number.
This program was written because I needed to keep track of my ever
increasing collection of CDs (Guess I just responded to too many
of those free offers from BMG and Columbia House.)
The program was originally written (early in 1998) in tcl/tk. I needed the program,
didn't want to code a GUI in C or C++, and figured that tcl/tk was a neat
way to go. The program worked and I learned a lot about tcl/tk. The biggest
lesson learned after a year or more of doing updates to the program is that
tcl/tk isn't a programming language in which I find code easy to maintain.
So, when I read some nice things about Python I decided to give it a try.
So far, I'm more that happy. The Python/Tkinter version runs much faster
that the tcl/tk, and it appears that at this time (Summer of 2000) that
it'll be much easier to maintain.
If you used an older (tcl/tk) version of VMusic
you can convert
your old data file with the supplied program ``convert.tcl''. The program
assumes the default installation locations. Usage is simple: just type ``./convert.tcl''.
VMusic
has some limitations---mainly due to the fact that it reads
its entire database into memory. I currently have about 350
titles in my database, which results in a 200K database file. I figure
that if you have 2000 CDs the file will probably grow to a meg or
so ... still not unmanageable. However, if your CD collection gets
that big you'll probably want something better than this program.
The biggest problem with a large database is that search
times will slow, still with a phony 3000 entry database performance
was near instantaneous on a Celeron-330 running Linux.
The way the database permissions/locations are set right now VMusic
is really only useful the owner of the program. I have some thoughts about
making the database shareable between different users. Helpful, friendly
advise will be gladly accepted.
Installing this package should be pretty straightforward. The main
executable is a python script which gets installed in the usual
place. Everything assumes that you have python and tkinter installed.
If not, go to www.python.org
and get it. NOTE: The current version
of Vmusic
requires version 2.0 (or later) of Python.
All that needs to be done is:
- Create the getcdtimes executable.
- Install the executables and the docs.
- Install the default rc file (optional).
All this is set up in a makefile. Just type:
make
su root
make install
The default destination locations are set in the Makefile. If you
don't like them, change them. All this is for Linux (and most
probably most unicies). We don't do windows here, but patches are appreciated.
After installing the files, you may want to install a ``rc'' file. Simply
copy the enclosed file ``vmusic.rc'' to your root directory as ``.vmusicrc''.
It's pretty well commented...make changes if you need.
The first time you run VMusic
you should get a warning message
about the data file not being present. Let VMusic
create a
default database and continue on. However, if you get this
message and you've already stored data in the database you better
start looking to see where it went! Also, if you answer ``okay''
to the warning message VMusic
will attempt to create an empty
database. If this fails (most likely due to the fact that you
don't have a ``~/data'' directory) you will receive a helpful
message and the program will exit. If the proper directory does
exist you'll have to start checking file access permissions---have
fun.
When VMusic
is running the display will be divided into three
areas:
- The top of the screen will display a series of menu
buttons. The are activated in the normal manner.
- The left side of the screen will display a list of the
active titles. At the top of this box there is an entry box with
the label ``Find Record''. Typing a name into this box, followed
by the Enter key, will start a search of the active titles for
the name. Note that the disk name, composer and performer fields
are all checked NOTE: Not the individual track data is NOT checked.
- The right side of the screen will display the contents
of the currently selected title. At the top right of
this area there are three buttons:
- SAVE
- The option will prompt for a filename and save
the contents of the display (the data of the current record)
to a file. Due to the use of tabs this may or may NOT be all
that useful. However, it should be easy enough to post-process
this file ... just remember that the fields are delimited
by tabs.
- PRINT
- Just like save, but it prints to the printer
specified in the global variable ``printCmd''.
- EDIT
- Brings up the edit/entry screen with the contents
of the current display. This is a shortcut to the Edit-Edit-Record
menu option.
I'll go though the menus in physical order here. However, if you
want to get started skip ahead to the ``Edit-Add New Record''
entry.
- Display Records
- Present a list of all the titles in the database.
The displaybox used has the required ``ok'', ``print'' and ``save''
buttons. I won't mention these again.
- Category Recdisplay
- Presents a list of all the titles in
the database, sorted by their categories.
- Unformatted Database
- The entire contents of the database will be
displayed. The format for each record is:
- Record name
- Performer
- Composer
- Label
- Category
- CDDB ID
- Comment
- Date
- blank
- Song Artist Composer Time
Each field is delimited by a ``|''character.
This repeats for each entry.
- x.
- -----
The ``-----'' line indicates the end of a record. It
contains exactly 5 ``-''s.
The idea behind all this is to create a file which
you might process using python, awk, perl, etc. Let us
know if you find this useful (it will probably be
deleted in a future version in favor of the ``Write
ASCII Database'').
- CD-Jacket
- This option let's you create a file suitable for
printing a cover
for a CD jewel box via Latex. The popup dialog should be obvious.
(Note that the default extension ``.tex'' will be added to
the filename,
unless you specify a different extension.)
You'll most likely want to make some cosmetic changes to the generated
file. We'll leave that as an exercise for the reader ...
but the generated file will produce a usable inside booklet
and back cover. You'll need
the rotate package for Latex, but I think this is pretty standard in
most distributions so shouldn't be a problem. Also, you'll need the
array package, available at your favorite CTAN site. And if you select
the 2column option, you'll need the multicol package as well.
- CD-Label
- If you have some of those circular sticky labels for your
homemade CDs you might give this option a try. It produces a fairly
simple Latex file which works for me. The ``circles'' are larger than
the label, so shouldn't appear on it. I use a laser printer and my
labels don't feed properly, so I have sheet of lettersize paper with a
dummy label printed on it---I just tape a real label to the paper and
feed that though. Your milage may vary a lot with this option.
(Note that the default extension ``.tex'' will be added to the
filename,
unless you specify a different extension.) You'll
need pstricks for this to work, but this appears to be pretty standard
in the Latex world so shouldn't cause too many problems.
The default vertical and horizontal offsets are set for label stock
I use which has a disc label at the top left and bottom right. I
just rotate the sheet for the second label. If you need to change
the offsets, do so in your .vmusicrc file.
- Write Ascii Database
- This option creates an ascii (human readable)
copy of the database. The big difference between this option and
``File-Unformatted-Database'' is that VMusic
can read this file.
See the file ``ASCIIFILE'' for details on the format.
- Quit
-
The only way you should quit the program. When selected the
database file will be updated and VMusic
will end.
When saving VMusic
creates a pickle-type, binary file
which is readable only by other Python programs. If you need
to read the database with another program use the
``File-Unformatted-Database''
or the ``File-Write Ascii Database'' options.
- Add New Record
- The Edit window will be created and you can
now enter data for a new CD. First off enter the name of the CD, the
label, click on the category name and select the correct one, and
enter a comment if you want.
The composer and performer fields are there mainly for CDs which
are by one performer and/or composer. The only problem with relying
on these fields is that if you are searching for a track by a certain
composer/artist it won't be found if you rely on this info since
the info-search function checks track data, not the header data.
On the other hand, the ``Find Record'' function does check the
header data.
Note that the date is auto-filled for the current date in the format:
yyyy/mm/dd. This format was selected to make possible sorting by
date easier, if you're into such minutiae.
Next, enter data for each entry. You are limited to 86 entries
per CD.
When entering data the following keys are functional:
- ENTER or TAB
- moves to the next entry field
- SHIFT ENTER
- moves to the previous entry field
- DOWN ARROW
- moves to the next line
- UP ARROW
- moves to the previous line
- PAGE DOWN
- moves to the next page of the display
- CONTROL-C
- copies the data from the field ABOVE the
current entry. Handy if the composer/artist
for the current entry is repeated.
You can also move around using the mouse pointer.
VMusic
uses the time information when displaying a record in the
display window. For it work properly, you must enter time values
in a MINUTES:SECONDS format with a colon separator. If this is
done, the total of the times entered will be displayed at the
bottom of the record display.
(Mostly) for classical recording, you can preface the name
of a track with a leading ``-'' (a single hypen). In this
case the display for the information will be indented by
a series of spaces. For example:
The Planets: I Mars
-II Venus
-III Mercury
would be listed in the display window as:
The Planets: I Mars
II Venus
III Mercury
- ScanTimes
- Since entering time data is a bit of a pain,
plus the fact that some CD inserts don't list times,
VMusic
has a ``ScanTimes'' button. When
pressed, this button will fork a program to gather
the time information on a CD in your player. By default,
the name of the program is ``getcdtimes''. The source
for this program is included in this distribution. If you
wish to change the name of this program,
it's easy to do in the init file, ~/.vmusicrc.
If the variable ``ejectCD'' is set, a program will be
forked to eject the current cd from the drive. By default
this variable is set to ``eject''.
If the cddb database has an entry for the scanned disk,
you will receive a prompt asking if you
want the disk name and song titles updated from the cddb
database.
Agreeing to this will overwrite existing data.
The following information is parsed from a CDDB database entry:
disk title, extended title (comment), and track info. The
category is set from the directory name or the DGENRE entry,
if present.
After parsing a CDDB entry, VMusic
notices lines
which may have both the song title and the artist or
composer.
Unfortunately, CDDB doesn't really support such things,
but some entries are in the format:
- Big Guy / My Song
- The Song / Some Singer
- A Song - Big Name Band
If any of these conventions are found a dialog will open.
You can
``Ignore'' the option, or select ``Name/Artist'' or
``Artist/Name'',
etc. You, a real human, is much more capable of
determining the proper split order. Hint: if you have
both composer and artist info in the fields you might want to
try splitting out the artist, reading the disk a second time,
splitting the composer, and then editing the results to remove
the extra information. Not ideal, but perhaps quicker than
a lot of typing.
NOTE: It is not possible to have entries without a ``name''.
Any entry data with data in the artist, composer or time
fields without a name will be discarded when you exit the
edit screen.
- Insert
- Insert a blank row. Just enter
the number of the row to insert.
- Delete
- Delete a row of data. Enter the number of the
row to delete. Caution: this cannot be undone!
- Help
- Displays a few common entry/edit options and
problems.
- Apply
- Writes the new/modified data into the database
(well,
in memory ... the data doesn't get saved to disk
until you exit the program).
- Cancel
- Discards the changes you just made.
- Edit Record
- This is the same as the previous section, but now
you're editing an existing record. Same things apply.
- Duplicate Record
- Again, the same as the two previous entries, but instead
of replacing an existing record, the finished entry will be a new one. Sort
of a combination of New and Edit. This is intended to be used in the case
where you have two or more similar records. You enter the first one, then
duplicate it and edit that instead of typing everything from scratch.
- Delete Record
- As expected, this option will delete the current
record from the database. Since you can't undo this action
you are asked to confirm your actions twice. Hope that's enough
warning!
- Edit-Categories
- This option will bring up a listbox with
the names of all the current categories. You can change the
categories simply by moving the mouse cursor over a name
and pressing the left mouse button. At this point you will
get a popup menu with the following options:
- Add New
- Enter the name of the new category. A check is
done for duplicates, and the first letter of each word
in the name is capitalized.
- Delete
- Delete the selected category. A check is
made to ensure that this category isn't being
used by any current record. If it is, the deletion
will be cancelled. Note that even though you
made delete an unused category, if it is one
of the predefined categories it will reappear
the next time your run VMusic.
- Rename
- Prompts for a new name. Duplicates are not
permitted. All the records with this category
name will be modified.
- Stats
- Gives some statistics about the usage of
the selected category.
- Find
- Enter the search terms in the pop up window. The search always
works as a ``OR'' search. In other words, each field with data will
be searched. If any field matches, it will be considered a
match. The searches are always done in a case-insensitive manner.
Only the records currently being displayed (due to the
category limit option) are searched,
No wildcard matching is done. This greatly speeds things up, makes
my life simpler, and is an option which I can really live without.
If it's a problem for you, well you have source
When a record with a match is found it is displayed, with
the matches highlighted.
As a shortcut this option is bound to the Control-F key.
If you click the ``Report'' button at the bottom of the
dialog, a list of the matching records will be displayed
in text window which you can save or print.
- Find-Next
- Does a search for the next occurrence of the match.
This is bound to the Control-N key.
- Statistics
- Displays the number of records, etc. in a pop up window.
- Name
- The popup window has an entry box and a ``Cancel'' button. As you
expect, the ``Cancel'' button cancels the option.
If you type something into the entry box, the records in the left
box will be limited to those which contain the string you entered
in their names. This makes it easy to display/search only your
``Animals'' or ``Bach'' CDs.
If you just press ``Enter'' with no data the command will be
ignored.
- Performer
- Same as above, but this time the limit is done on the
``performer'' information in the record header. Note, the performer
data for each track is not used here.
- Composer
- Same, again, but this time we use the ``composer'' field.
- Label
- Do we need to repeat? Same, but this time we use the ``label'' field.
- Exclude Name
- This is exact opposite of Limit-Name. You get the same popup
window, but the names matching your entry will NOT be displayed.
- Exclude Performer
- Surely you know what this does.
- Exclude Composer
- And this is obvious?
- Exclude Label
- Well?
- Category
- In the popup window you can select which categories you want
activated. By default, none are. This effects the info-find
and info-report options.
The ``Select-all'' button selects all the categories; the ``Clear''
button unselects all of them. This makes it easier to highlight
the group(s) you want. Pressing the ``Apply'' button updates the
display; ``Cancel'' does just that.
- Display-All
- Undoes the effects of all previous Limits; it forces
the display of all the records.
- Name
- This option sorts the namelist (on the left of the screen)
in its normal order. Really, it's just there to undo the results of
the next two options.
- Composer
- This sorts the namelist in order based on the Performer and
Name fields in each record. Note that records with no performer data
in the header (the indvidual track data is not used) will be sorted
at the top of the list. So, this option really only makes sense if you
normally have performer data in the record header. This option is not
saved, so you'll have to re-sort whenever you want this to take effect.
- Performer
- Obviously, the same as the previous option, but this time we
use the performer name, rather than the composer.
This section sets various options, all saved in your .vmusicrc file. You
can always just manually edit the rc file, but using the built in options
should ensure that you don't make any mistakes.
- Font Face
- Lets you select between some standard font faces. After
selecting a new face the name list and item display will be updated;
however, the menus will not. You'll have to save and restart to really
see what's going on.
- Font Size
- Lets you select the base size for the display. As above,
the real results won't be visible until you save and restart.
- Width Options
- This presents a series of scales. The first row represents
the widths of the columns used in the edit screen. The second row
represents the relative widths of the list/display areas. Resetting
these values have no effect until you save and restart.
- String Options
- Changing the first option is NOT recommended! The others
represent the programs to read timing information from a CD and
to eject a CD, and the base location of the CDDB database. Changing
these values will have an immediate effect.
- Save Options
- Writes or updates a new .vmusicrc file in your home directory.
- Missing Timing
- This option creates a list of record names which
have any tracks without timing info.
- Missing Label
- This option creates a list of records names which don't
have label info in the header.
- Missing CDDB
- This option creates a list of record names which
do not have CDDB id in the header.
- Missing CDDB Offsets
- List of records without the CDDB offsets.
- Missing Performer
- List of Records with a performer. Note that
you might not want this information.
- Missing Composer
- Obvious? Well, it does apply to the ``composer''
field in the header.
- Missing Performer
- This has to be obvious.
- Update CDDB
- Updates the local CDDB database. The primary (first)
directory in your cddbDir list is used as a destination. The
entries will be placed in sub-directories based on the category
or genre of each record. This information can be read by
programs such as grip and xmcd.
- About
- Displays the author name, version number, etc.
- Help
- Attempts to display a formatted man page in a display box.
If the program ``rman'' is not present this command will fail.
Rman is available from
ftp://ftp.cs.berkeley.edu/ucb/people/phelps/tcltk/rman.tar.Z.
When VMusic
first starts up and reads a database file into memory
it creates a lockfile in the same directory as the database file. This file
is usually ``~/data/vmusic/vmusic2.lock''.If this file is found (before reading
the database) it indicates to VMusic
that another incarnation of the
program is using the database file. This means that two or more different users
(or the same user running 2 different incarnations of the program)
could modify that database and attempt to write conflicting changes to the file.
For this reason, if the lockfile is found VMusic
disables the editing
functions for the current user. If you are the only user and find that the editing
functions have been disabled, then you may need to manually delete the lockfile (this
may happen if you exit the program prematurely due to a power failure, etc.).
The lockfile mechanism used is naive and primitive. However, it should serve in most
cases.
If a user other than the owner of database file access that file, the editing functions
are disabled. Note that this probably won't happen since in order to access the
database the ``other user'' needs to have permission to:
- Read the database file, and
- Create a lockfile in the same directory as the database file.
In addition, the default directory is set to ``~/data'',which will force
the ``other user'' into her own directory tree.
If you want to share database
files you should set the directory path to a constant (ie: ``/usr/local/share/vmusic/vmusic2''), set the owner of the database to a
trusted uid, and ensure that any .vmusicrc files are updated to the correct database
filename. This should permit all users to read the database, but only the
owner to modify it.
Some keyboard shortcuts have been implemented for common operations
(when the main window has keyboard focus):
- Alt-Q
- Exits the program.
- Alt-F
- Enter the find dialog.
- Alt-N
- Find the next occurrence of find.
- Alt-R
- Create a new record.
- Alt-E
- Edit the current record.
The following files are used by VMusic:
- /usr/local/bin/vmusic:
- the executable.
- getcdtimes:
- the optional program to calculate a CDDB id and extract the
timing information from a CD.
- ~/data/vmusic/vmusic2.bin:
- a ``picked'', binary copy of the database.
- ~/data/vmusic/vmusic2.bak:
- a backup copy of the previously modified
database (binary).
- ~/data/vmusic/vmusic2.dat:
- an optional ascii (text) database which is read
on startup if it is newer than the binary (.bin) version (or if the
.bin version does not exist).
- eject:
- the optional program to eject a CD from a drive.
- man:
- the program to print a man page. Needed to display help.
- rman:
- the program to convert a printed man page to plain text. Needed
to display help.
- /usr/local/man/man1/vmusic.1:
- the man page.
- ~/.vmusicrc:
- the optional initialization file.
None that I know of. However, the multiuser access and filelocking have
not been heavily tested. Please report any problems to me: bvdp@xplornet.com
The programs VMusic
and getcdtimes were written by Bob van der Poel
in 1998-2003 and are copyright Robert van der Poel, 1998-2003.
They can be freely distributed according to the terms of the GNU
General Public License (see the file ``COPYING'').
If you enjoy the program, make enhancements, find bugs, etc. send
me a note: bvdp@xplornet.com
Or a postcard (or even money) to PO Box 355, Porthill, ID 83853.
Current version maintained at: http://users.xplornet.com/~bvdpoel
This document reflects version { 2.7 } of VMusic.
This document was auto generated with Latex2man
from LaTeX source.