FreeDB (CDDB) support for OS/2 CD-Player

Version: 0.46

-> Quick start -> Submitting -> Download -> History -> Known issues -> Reference -> Details -> Contact

This font indicates things you can type in.
Italic in addition indicates parameters, which have to be replaced by meaningful values.


Quick start

Reqirements

Installation / configuration

automatically:
Copy the CMD scripts and the .DLL files[1] and optionally this documentation to some directory you like[2].
Execute install.cmd from there and follow the instructions. Note that the install script is not very well tested so far.
manually, via Internet:
Copy the CMD script and the .DLL files[1] to some directory you like[2].
Set up the CDDB server once: CDDBMMCD -w -sserver, where server is the name of the CDDB server.
Example: CDDBMMCD -w -sfreedb.freedb.org
or CDDBMMCD -w -shttp:\\freedb.freedb.org -Pproxyserver behind a firewall
manually, with a local database:
Copy the CMD script and the .DLL files[1] into the directory of the local CDDB database (where the folders misc, rock etc. resides)[2].

Usage

Use the program objects created by the install script or run CDDBMMCD manually:
with a dial up connection:
with audio CD in your CD-ROM drive: CDDBMMCD -oc
later, when you are online: CDDBMMCD -oQo
otherwise:
Simply execute the script with a audio CD inside the CD-ROM.

Hints

Notes:

  1. Developers may already have the file GCC30M.DLL (gcc 3.0 multi threaded runtime) in the libpath. In this case the file is not required.
  2. The submit feature will not work on FAT volumes, i.e. 8.3 file names.
  3. I switched to Object REXX so long ago that I do not know any longer whether cddbmmcd works witch classic REXX or not.
  4. Cddbmmcd uses some REXX extensions written in C mainly for serious performance reasons. They require the gcc libraries.


Submit and update records

Submitting CDDB records is somewhat different from the other stuff. First of all it usually does not work in batch mode. The procedure is always in three steps:

  1. Initiate a new (1) or updated (2) CDDB record by either
    (1) entering the disc information in the OS/2 CD-player after you a CDDB lookup for this CD was unsuccessful or
    (2) modifying the previously loaded information in the OS/2 CD-Player. CDDBMMCD supports revision automatically.

  2. Create the submit records with CDDBMMCD using the

  3. action codes u for new records (1) or a for updates (2):
    CDDBMMCD -oua. You will be asked for the cddb category in case of new records.

    Before creating any submit record be sure to enter the information in the OS/2 CD player according to the rules for cddb entries. They are roughly:

    Additionally there exists a special, CDDBMMCD-specific syntax extension to access some meta information:

    These meta information is always parsed when creating a submit record. It will be kept in case of update records.

    The DGENRE field of cddb protocol level 5 is not supported. However, it is kept in case of updates.

  4. Submit the created CDDB records with CDDBMMCD -os or CDDBMMCD -oS. The first one will send you an e-mail with the result of your submission without modifying the freedb database. Only the latter one will really update the database, if the information is accepted by the server, of course.

    It is strongly recommended to perform a test submission if you use the submit feature first. Also keep in mind that this software is still beta and you are responsible for your submissions. So it is a good advise to view the submit records manually before you send them to a freedb server. To force a resubmission use -oU.

    Note that CDDB submissions to the 'official' freedb servers must use the http protocol. cddbp submits are always rejected.


Download

This program is distributed under the terms of the GNU GENERAL PUBLIC LICENSE.

ZIP file with source and this guide: Version 0.46


History

Version 0.46 (Jan. 7, 2005)
Version 0.45 (Mar. 1, 2004)
Version 0.44 (Aug. 19, 2003)
Version 0.43 (25.05.2003)
Version 0.42beta (12.05.2003)
Version 0.41beta (21.12.2002)
Version 0.4beta
Version 0.34
Version 0.33
Version 0.32
Version 0.31
Version 0.3
Version 0.21
Version 0.2
Version 0.1 (first release)

Known issues

Known bugs

Problem
Work around
Comment
The OS/2 CD-player may crash with an error message if CDDBMMCD is accessing a CD device during the OS/2 player recognizes a new CD. Restart the CD player. This is a problem of the OS/2 CD-player and may not be fixed here.
When the CD player's database contains a large number of entries CDDBMMCD becomes very slow. Always start the OS/2 CD player before executing CDDBMMCD. The problem is the way how the REXX function SysIni works. It always opens and closes the file every time it is called. Only if another application holds the profile open the corresponding OS/2 API call is fast.

ToDo

Add meaningful icons
Since there is an installer available it should add more meaningful icons to the created objects.
Dialog for inexact matches
Inexact matches are currently handled automatically. This does what you expect in most cases. But there are situations where this is not sufficient, e.g. CDs with 2 or less tracks.
Work around for CDs with 'copy protection', which come into vogue.
It significantly depends on your hardware what's happening there.
Automatic update for newly inserted CDs
It would be much more comfortable if the script need not to be invoked manually. However, my knowledge about SOM ends slightly after these three letters. But if somebody would like to do it...
Handle CD categories
The cddb uses categories to classify the CDs. Unfortunately, these categories are not used in a very meaningful way. So I did not implement them. Only for new submissions you will be asked for it.
Ambiguous CDDB IDs
The CDDB IDs are hashes are not necessarily unique. If somebody tells me how this is handled by the CDDB, I will implement it. This might apply to the MMPM CD player, too. But this is somewhat more unlikely. However, there is no help in case of the latter.

Reference

The options apply according to the following (decreasing) precedence:

  1. command line options
  2. options saved in the profile (CDDBMMCD.INI)
  3. default values
option
description
default
-ddevice or
--device=device
MCI name of the CD-Audio device to query (for TOC).
Multiple devices may may be separated by comma.
cdaudio
-lpath or
--local=path
Path to a local CDDB. This path should point to the directory where the subdirectories rock etc. are located. -l- or --nolocal disables the use of a local CDDB. .
current directory
-ttype or
--type=type
Type of the local CDDB. S[tandard] or W[indows] or [auto].
see also standard version vs. windows version
standard
-sserver or
--server=server
Name or IP of the CDDB server.
Multiple servers may be entered comma delimited (without blanks). The entries have the form: [protocol:\\]server[:port][1]. Protocol is one of cddb (default) or http, port is by default 8880 (cddb) or 80 (http) respectively. -s disables server queries.
no server
-Pproxy oder
--proxy=proxy
Name or IP of the HTTP proxy. A Proxy puthentication is currenty not supported.
Syntax: proxy[:port]. Port defaults to 80.
no proxy
-uusername or
--user=username
User name for cddb hello. %USER%
-hhostname or
--host=hostname
Host name for cddb hello. %HOSTNAME%
-eemail or
--email=email
Your e-mail address for submits via http protocol. none
-o[+|-]op-codes or
--op=[+|-]op-codes
One or more of the following actions may be specified:
Check currently inserted CD.
C Check currently inserted CD and generate query even if data is already
q Execute CDDB query (local and/or server).
Q Execute delayed queries.
o Retry all unsuccessful queries which are older than one month.
O Retry all unsuccessful queries.
u Create submit record, if one of the unsuccessful queries is entered in the OS/2 CD player in the meantime.
U Force the creation of an update record for currently inserted CD.
a Automatically create update records for CDs where the information is modified.
R Force the recreation of all pending upload records.
s Submit the previously created records to the (first) cddb server in test mode. In case of a test submission the internal state of the cddb record is kept. The test submission will be repeated on the next run of CDDBMMCD.
This is not supported by the cddb protocol and a no-op in this case.
S Submit the previously created records to the (first) cddb server
Be sure to have read the section submit and update before submitting anything.
A leading + or - indicates that the following instructions should be added to respectively removed from the current list.
cqQo
-zpath or
--uploadpath=path
Path for temporary storage of the upload files. This must include the trailing path separator. .\
-vlevel or
--verbose=level or
-v or --verbose
Set output detail level.
Show fatal errors only. (These which cause the application to abort.)
1 Show all errors.
2 Show warnings and errors.
3 Show information messages, too. Also selected by -v or --verbose. (default)
4 and more  Show debug messages, too.
2
-w or
--write
Save all settings (unless otherwise noted) as new defaults to the profile. This setting will not perform any other action than updating the profile.[3]
--reset Reset all configuration options in the profile. This will not effect the meta information about your CDs.
advanced option

description
default
-pfile or
--profile=file
Profile for CDDBMMCD. Of course, this may not be saved using -w. scriptpath\
CDDBMMCD.INI
[2]
--ext Enable translation of extended information in the xmcd records. Extended information will be appended in {} brackets. See syntax extensions. Use --ext=0 to disable the translation explicitly.
This option applies to the CDDB lookup and the creation of update records. In the latter case the previous information from the last xmcd revision is kept. Change this option with care, because if you perform a CDDB lookup with this option disabled and then create the upload packet of the same CD with this option enabled the extended information get lost in the public database.
disabled
--codepage=CP Codepage for the cddb database and/or server. All information is translated from CP when parsing an xmcd structure and translated to CP when creating an upload package. 1004
-fthreshold or
--fuzzy=threshold
Execute fuzzy search, if no exact match is found. The threshold defines the number of frames which each TOC entry may deviate. -f0 disables fuzzy search. This does only apply to local database lookups. 41
--windbdelta=num If the windows database version is selected by --type this parameter defines the maximum hash range of one database file. Example: with --windbdelta=1 a lookup for the disc id e311f20f will search for files named e3toe3, e2toe3 and e3toe4 but not for e.g. e2toe4 or e0toe3, because they use a larger range. 6
--hddvscpu=bytes Threshold in bytes where the binary search algorithm of the Win database lookup turns into a linear search. Increasing this value from the default (10k) will increase the CPU load while decrease the HDD seek load and vice versa. 10000
--cdextra=bool Enable/disable the CD-Extra work around. When enabled CDDBMMCD looks beyond the number of tracks reported by the CD-ROM manager. These are usually non-audio tracks. Normally there is no reason to turn this option off. 1 (enabled)
--caseadj Convert all titles to upper-/lowercase automatically before storing them in the CD player's database. This is intended for CDDB records which are completely in lower- or uppercase. Usually this option does it's job well. But you should always have a look to the result, because on acronyms and some other stuff it is likely to fail.
It is a good idea to upload an update after you corrected the (wrong) information.
This option cannot be saved permanently in the profile with -w.
--trackfix=level Apply fixes to each track title before storing them in the CD player's database. This is intended for malformed CDDB records, most commonly compilations with various artists.
The following level values are supported:
Swap artist and title and replace " - " by " / ".
2 Only replace " - " by " / ".
4 Strip track numbers in the form "01 " from the front of the track titles.
The different levels cannot be combined with several --trackfix options.
It is a good idea to upload an update after you corrected the (wrong) information.
This option cannot be saved permanently in the profile with -w.
--special=command This option is used to take some special actions, mainly for maintance purposes. When used the normal operation (-o) is not executed at all. The commands may be followed by additional arguments separated with comma. If the command or the arguments contain spaces the whole option must be quoted, e.g.: "--special=UpdateWinDB,'freedb-update-20030201-20030302.tar.bz2'"
The folowing commands are supported:
UpdateWinDB,'updatefile' Merge a freedb update file into an existing instance of the windows version of the freedb database. The update file may be in either .tar, .tar.gz or .tar.bz2 format. However, you must have the required decompression utilities installed (tar, gzip, bzip2). You will find all of them at hobbes.
If you specify a directory (which must end with \) instead of an update file the decompression step is skipped and the xmcd files in the subdirectories (with the cddb category names) are used directly.
The update procedure is rather slow because the whole database have to be recreated. The updater will not check the revision tegs of the xmcd records. It will always overwrite existing records.
ResetMD5  Recalculate all stored MD5 checksums. This will prevent the creation of any upload record for now.
ReenterUpload,'filename' This action will try to recreate the database state of an already submitted xmcd record. This is particularly useful if a submission failed in a way that CDDBMMCD cannot detect.
Be careful with this option, because the exact CD length must be guessed in this case.
StoreFile,'filename' This action will store the information from a xmcd data file in the CD-players ini and the internal database.
Be careful with this option, because the exact CD length must be guessed in this case.
DumpStatus,'filename' Dumps all meta information about CDs from the cddbmmcd profile into a human readable text file.
This option cannot be saved permanently in the profile with -w.
--client=string Overwrite client string at cddb hello. cddbmmcd/2 version
--proto=level cddb protocol level.
You should neither play with this option nor expect it to work in all circumstances.
5

Notes:

  1. Because of peculiarities of OS/2 Classic REXX it is impossible to pass a URL in the command line. REXX stops at the first occurrence of //. Hence the URL has to be entered with backslashes. This does not apply to Object REXX; however, \\ works anyway.
  2. This has changed with version 0.4. Previously the current working directory (.\) was used.
  3. This has changed with version 0.41. Previously the selected operations were executed too.


Further details

How CDDBMMCD works

  1. It opens the CDAUDIO device fetches the TOC of the currently loaded CD. A possibly running playback is temporarily suspended.
  2. It checks if the CD is already known.
    If not, the CD is marked for a CDDB lookup.
  3. A list of CDDB queries to execute is prepared. Besides the current CD this contains unsuccessful queries which are more than one month ago (retry).
  4. If selected, a local CDDB lookup is executed. First the CDDB disk ID is calculated. Now all direct sub folders of the local CDDB path are searched for matching files. If no exact match is found, a second search algorithm starts: fuzzy search. All files with logically similar CD IDs are inspected (hash ±10, length ±1). The TOC of each file is compared with a precision of 40 frames. Different lead ins are ignored.
    The latter only works with CDs that have at least 2 tracks.
  5. If the local database lookup was unsuccessful or disabled, the query is sent to the list of CDDB server(s) (if any) in order of appearance.
  6. If the search was successful, the MMCD key is calculated and the Information is stored to the CDP.INI. This file is located automatically in the current MMOS2 folder.
  7. The database and CDP.INI is searched for CDs which have been queried unsuccessful at least once and where the information is entered manually in the meanwhile.
    The search also checks for CDs where the stored information is modified through the OS/2 CD player since the last query.
  8. For any of the matching entries of the last two steps update records are created. In case of modified entries they will have a revision tag. For new entries it is usually required to enter the category name. You will be asked for it.
  9. The update records are sent to the cddb server.

Local CDDB: standard version vs. Windows version

There are two versions of the freedb. The native and a Windows version (freedb-win*).
In the original each file is one CD. The filenames are 8 digit hex numbers, e.g. d70b6b11. It contains folders with 70000 and more files. This overloads every FAT file system. OS/2 (with HPFS) is capable of this, but you may use the Win version, too.
In the Win variant files with similar initial digits are consolidated. They have the form 00to01 ...

original
Windows variant
+ incremental update quite fast - incremental update slow[1]
- significant file system overhead
(even with HPFS which has 512 bytes per allocation unit)
+ space saving
+ significantly faster access - slow access, especially in case of fuzzy searches[2]
+ possible on FAT volumes

Notes:

  1. CDDBMMCD can perform incremental updates using the --special option. There is also an incremental update utility for Windows available. However, I don't know if this is helpful with OS/2. Maybe it works using ODIN.
  2. Because the files of the windows database version are grouped by the hash value, it is much likely that a fuzzy search will scan about 10% of the hole database. I do not recommend the windows database for fuzzy searches unless you have a very fast PC.

Format of the MMPM CD info file

The MMPM CD player stores the information about CDs in the file CDP.INI in the MMOS2 folder. This file is in binary OS/2 profile format and should be accessed by the suitable profile functions.

The applications are the CD keys, calculated as follows:

MMSSmmss.ff     Example: 46043612.40
MM
total length of the CD, minutes [00..99]
SS
total length of the CD, seconds, truncated [00..59]
mm
total length of the CD minus length of the last track, minutes [00..99]
ss
total length of the CD minus length of the last track, seconds [00..59]
ff
total length of the CD minus length of the last track, frames (1/75 s) [00..74]
CDs with only one track have mmss.ff = 0000.00.
Within this applications the following values are defined:
IMMCDDiscTitle  CD title, ASCII
1 title track 1, ASCII
2 title track 2, ASCII
...
Note that there are other keys which are not touched by CDDBMMCD to store e.g. the last continue point.
Beyond this built-in keys CDDBMMCD stores some additional meta information here. This keys are ignored by the MMOS2 CD player. There are no known interactions.
CDDBCategory  category of the cddb data. Discontinued since version 0.42, see CDDBmeta.
CDDBRevision  revision of the cddb record. Discontinued since version 0.42, see CDDBmeta.
CDDBMD5 MD5 checksum of the cddb record. Discontinued since version 0.42, see CDDBmeta.
This information is used to determine updates through the CD player's GUI automatically. The hash is created from the information as stored in the CD player's database. The CD title and the track titles are concatenated with a null byte as delimiter.
CDDBmeta  Summary of meta data. Since CDDBMMCD version 0.42 all of the above informations is stored in one key. The format is:
MD5-Hash category revision
The field delimiter is a null byte. Informations from older versions will be converted silently on demand. The old style information will be removed in this case.

Format of the CDDBMMCD profile

Application key: Settings

Value
Meaning
Command line option
CDAudioDevice Space separated list of CDaudio device names. -d
CDDBservers List of CDDB servers, delimited with blanks. -s
CDDBType Kind of CDDB query
L local database lookup
S server lookup
LS  both
-l, -s
CDExtraWA CD extra work around, boolean {0|1} --cdextra
CDPiniLocation  Path to the internal database of the MMOS/2 CD player.
ClientString Name and version of the client program used at cddb hello, delimited by a blank. --client
Codepage Codepage of xmcd records. --codepage
EMail Email address for submissions. -e
EXTFields Enables the bidiretional converion of the extended fields in the xmcd records, boolean {0|1}. -ext
FuzzyThreshold Threshold for fuzzy search. -f
HDDvsCPU Threshold in bytes where the binary search algorithm of the Win database lookup turns into a linear seach. --hddvscpu
Hostname Hostname used at cddb hello. -h
LocalCDDBPath Path to the local CDDB. -l
LocalCDDBType Type of the local CDDB. -t
OperationCodes List of functions to execute. -o
ProtocolLevel Protocol level for cddbp and http. --proto
ProxyServer HTTP proxy address -P
UploadDataPath Path where the upload files for submissions are stored. -z
Username Username used at cddb hello. -u
Verbose Level of detail for screen output. -v
WinDBDelta Maximum range of hash values in one file of the Win database version. --windbdelta
Application key: PendingCDs
Here is the state information about previously checked CDs stored. The name of the values is the table of contents of the CD. The assigned data is the state information.

The TOC is coded as follows:
· number of audio tracks
·  total CD length in frames
· first frame of track 1
· first frame of track 2
...
· first frame of track n
· last frame of track n +1
The items are delimited with blanks.
In case of CD Extra the number of tracks is only the number of audio tracks. The real number of tracks is the number of words in the string -3.

The state is one of:
1 CD is to be queried.
2 time CDDB query was unsuccessful at time.
(Unix time format = seconds since 01/01/1970)
3 CD information successfully stored.
4 filename Upload packet is ready.

Application key: Internal
Value
Meaning
CDDBMMCDVersion Last used version of CDDBMMCD.
If CDDBMMCDVersion is less than the current CDDBMMCD version, the profile is migrated to the new version, if neccessary.
If CDDBMMCDVersion is higher than the current CDDBMMCD version, a warning is generated. A back conversion is not supported. The application may not work as expected.

Contact

Suggestions, help, complaints (but not too much:-): Mail address: mueller-at-maazl-dot-de

Original homepage: http://www.maazl.de/project/cddbmmcd/index.html