WhereIsIt? version 3.96
Copyright (c) 1997-2009 Robert Galle
All Rights Reserved


CDDA PLUGINS MODULE
===================

This module contains three plugins related to handling CDDA audio CD disks,
including extracting description details based on CD-TEXT information,
querying a CDDB server locally or over the Internet for audio CD details,
and extracting disk information from either CDPlayer.ini file, or .CDA audio
track files themselves.

Installing The Module
---------------------
Copy the "CDDAPlugin.dll" file in subfolder "Plugins" in WhereIsIt's main
folder, for example, "C:\Program Files\WhereIsIt\Plugins". When WhereIsIt is
run the next time, it will recognize and include the new plugin module. You
can further setup or adjust settings for each individual plugin through their
own setup dialogs.

------------------------------------------------------------------------------

AUDIO CD-TEXT DESCRIPTION PLUGIN
================================

This plugin can import the CD-Text details, available on many Audio CDs today,
especially those issued by Sony Music over the last few years. CD Text details
most often include disk name and artist, disk ID, and title/performer info
for each track on the CD. Less common details are lyrics authors, composers,
arrangers, custom messages from either of those, etc. If available, this
plugin will import those as well.


Limitations And System Requirements
-----------------------------------
Of course, you need a CD-ROM/CD-R/CD-RW/DVD drive capable of reading CD-Text
information. Not all drives are capable of that, although most of newer drives
shouldn't have any problems.

You also need to have a valid ASPI driver (wnaspi32.dll) available on your 
system, if you are using Windows 9x/ME. It is very likely you have it in place 
already, Windows 9x/Me provides one by default. If you don't have it, you can 
download it from Adaptec (http://www.adaptec.com), or use a link on WhereIsIt's 
download page. Note that certain third-party ASPI drivers, commonly shipping 
with CDR software are not standard and can cause problems in WhereIsIt and other 
applications using ASPI layer. If you are experiencing problems accessing CD-ROM 
or removable drives in WhereIsIt, re- installing the original Adaptec ASPI 
drivers may often help to resolve the issue.
Windows NT/2000/XP users do not need to have ASPI available, as SPTI is used 
instead on those systems.

The Audio CD plugin currently comes with some limitations as well. There is
very little documentation available on CD-Text implementation, and basically
none of it from official sources.
The plugin does not handle CD-Text stored in Double Byte Character Code (DBCC)
format, nor does it support CD-Text info stored in multiple languages (the
first language is used in this case). Plugin will only import CD-Text stored
in the TOC of audio CDs - some rare implementations store CD-Text in the data
area of audio CD, those are not supported by this plugin.

How To Use It
-------------
There are no specific actions necessary to active or use the CD-TEXT plugin.
As with all plugins, make sure that plugin's priority is set accordingly
compared to other plugins that can also try to import details about audio CDs.

In order to setup the available settings of Audio CD Text plugin, select
"Description Settings" option in program's "Settings" menu, select to view
available plugins, highlight the "Audio CD Text" plugin on the list, and
click the "Configure" button. This will bring up plugin's own setup dialog.

------------------------------------------------------------------------------

CDDB AUDIO CD PLUGIN
====================

In order to use this plugin for remote CDDB queries, you must have an
active Internet connection at the time this plugin is being used, and the
Wininet.dll library available on your system. The latter shouldn't be a
problem unless you are using one of the earliest version of Windows 95
(pre-OSR2). In order to use a local CDDB database, you need to have it
downloaded and installed on your disk, and CDDB plugin must be configured
by specifying the path where local CDDB database is available, and the
format of CDDB database (Windows / Unix type). Additional options are
available in plugin's setup dialog.

Installed and functioning ASPI driver is highly recommended, although not
necessary. Please note that if your Audio CD is being used by some other
application at the time WhereIsIt scans it (for example, it is being played
by a CD Player software), chances are that WhereIsIt may not be able to
access the CD and retrieve the necessary CDDB details to be used with
queries. Options related to CDDB queries are not available for CDs missing
this information.

As there is more than one plugin in the package capable of handling audio
CD disks, take care how do you set plugins priority. As all other plugins,
audio plugins are executing one by one based on their assigned priority,
until one of them can provide a description. If you want to import CDDB data,
make sure the CDDB plugin has higher priority than Audio CD Tracks plugin,
otherwise a generic audio track data will be imported by Audio CD plugin
instead. Similary, if CD-Text plugin has higher priority than CDDB plugin,
CDDB plugin will only get to be used if audio CD does not contain CD-Text,
or the CD-Text plugin wasn't able to retrieve it for some reason.

The CDDB plugin is set to use the free freedb.org servers instead of the
commercial CDDB.com database. The CDDB server address to be used is user-
configurable and can be set in plugin's config dialog (you can retrieve
the list of all available freedb mirrors from the http://freedb.freedb.org
server, or by visiting the http://www.freedb.org web site.

In some cases CDDB server can return inexact hits, or multiple hits. This
plugin will by default ignore them both and rather leave the description
empty than taking chances to import details for the wrong CD. Alternatively,
you can also setup the CDDB plugin in its config dialog to stop in such
cases and present to user a dialog where he can select appropriate entry
out of possible ones as presented by CDDB server. Please note that enabling
such options may interfere with scanning the media, and may cause problems
if program is expected to work on its own, for example with scheduled auto-
matic updates.
Cases of multiple hits are fairly rare to encounter though, large majority
of entries in CDDB database are unique.

The CDDB plugin can also use a local CDDB database, available on your hard
drive. If you want to enable local CDDB database, you need to enter a path
to where a local CDDB database is located in plugin's settings. Both Windows
and Unix formats of local CDDB database are supported. The CDDB plugin can
optionally use local CDDB database for queries (therefore it is not necessary
to be connected to the Internet), or it can store successfully retrieved
remote CDDB queries to the local database as well, making them available
offline the next time they are needed. Please note that local CDDB queries
are more basic that remote queries - close (fuzzy) matches are not supported
with local CDDB queries.

You can download the whole CDDB database from the http://www.freedb.org, in
either of the two formats available and supported. The Windows format
database is recommended for most cases.

Notes
-----

The CDDB plugin returns CDDB revision level as a part of disk's description.
While this detail is not of much use to users, it is needed when posting
updated disk details back to CDDB server. Entries missing revision level info
are automatically submitted with revision level 0, meaning they can not be
used to replace existing disk data in CDDB database. If you plan to be
submitting updated disk details to CDDB database, please leave the revision
level detail in place for best results.

------------------------------------------------------------------------------

AUDIO CD TRACK FILES
====================

This is a simple plugin that can just about always provide a description,
therefore it should have the lowest priority out of the three. It will first
try to locate a matching audio CD details in the CDPlayer.ini, and if one
available, it will import track details from there. Otherwise, the simulated
Trackxx.cda file is parsed, retrieving its track number on the CD, and play
time for that track as a description.

------------------------------------------------------------------------------

1.27 (10. March 2009)
---------------------  
+ Allowed CD-TEXT importing for some other, non-Audio CD media types.

1.26 (2. October 2008)
----------------------  
* Fixed a problem with incorrect custom formatted descriptions.

1.25 (13. June 2008)
--------------------
+ Added support for storing settings to configuration files.

1.24 (9. October 2007)
----------------------
+ Added FreeDB Protocol Level 6 support (Unicode).

1.23 (11. July 2007)
--------------------
+ Added the option to include track numbers in custom formatted descriptions 
  to all three plugins

1.21 (21. May 2004)
-----------------------
* Fixed a few details related to handling custom formatted descriptions
+ Updated freedb mirror sites list

1.20 (17. October 2002)
-----------------------
+ All three plugins now have the option of custom formatted descriptions.

1.14 (1. January 2002)
----------------------
+ Added SPTI support for the CD Text plugin. ASPI is now no longer used or
  required when running on Windows NT, 2000, or XP. ASPI layer is still used
  and required for the CD Text plugin when running on Windows 9x/ME.

1.13 (21. October 2001)
-----------------------
+ Added an option to include audio track number in alias names for the generic
  Audio CD plugin.

1.12 (18. September 2001)
-------------------------
+ Updated the MP3 and WAV Audio Files plugin, certain small WAV files with no 
  data information were confirmed to cause problems when handled by this plugin 
  and could cause scanning to abort. 

1.11 (12. July 2001)
--------------------
+ Improved the CDDB plugin to handle the new level 5 protocol, introducing
  genre and year information to CDDB entries.

1.10 (23. June 2001)
--------------------
+ Lots of changes, buxfixes and improvements to the new CDDB plugin, to
  ensure proper compatibility with the freedb.org database and other programs
  that may be using it locally. The CDDB plugin is now officially certified
  by freedb.org for freedb compatibility.

1.00 (11. June 2001)
--------------------
+ initial release in current form, combining all three audio CD plugins
  together as a standalone module. The CDDB plugin has gone through a major
  rewrite in this release, and the CD-TEXT plugin is fairly new as well,
  just out of beta.


---------------------------------------------------------------------------
The DescAPI and CDDAPlugin.dll module are an integral part of the WhereIsIt
software package and as such a copyrighted material. Using or distributing
these librarires for any purpose other than running them as a part of
WhereIsIt is prohibited and in violation of copyright laws.
---------------------------------------------------------------------------  