
                            SID Known v1.04
                      A SID tune identifier tool

                  Copyright (c) 2010-2012 Wilfred Bos
                      Programmed by Wilfred Bos




INTRODUCTION
============

SID Known is a command line tool which you can use to identify SID tunes from
SID and PRG files.

This tool can be used if e.g. you want to know which SID tune is used in a
specific C64 demo or C64 game, or you have a SID tune found or ripped and you
want to know if it is already in your SID collection.

The tool was created initially for the High Voltage SID Collection crew to make
it easier to find double entries in the C64 music collection. Since this tool
was also requested by several people, the tool is now released and can be used
by everyone.

The tool creates and uses a small database which includes hashes from SID input
data. The tool already includes a database that is created from the latest HVSC
SID Collection (update #56).

The tool has two methods to identify SID music. The first method is based on
SID input data. The tool will internally play the SID tune or run the PRG file
for 3 minutes (as fast as possible) and then creates a hash of the generated
data and then tries to look it up in the database.

If the tune can't be identified, it will try to play the SID tune for another
clock speed (PAL or NTSC). If it then still can't be identified then it tries
the second method to identify the tune. The second method will check the memory
usage of the tune and will search for all the memory that is read in all the
SID tunes found in the specified HVSC location. It will create an index file
first to improve search speed.

NOTE: although the tool identifies most SID tunes correctly, it still can
identify a tune falsely. You should always check manually if the found tune is
the same as the tune that you searched for.


SYSTEM REQUIREMENTS
===================

Windows operating system (Windows 98 or higher).

Multi core CPU recommended.


USAGE
=====

Usage: sidknown <options> <input_filename>

<input_filename>

The input_filename can be any SID or PRG file. You may use wildcards to
process multiple SID and PRG files. You may want to use the -s option to
process subfolders as well. If you have spaces in the filename or in the
folder name then surround the filename with double quotes.

Examples:

*.sid
tune?.sid
"c:\my c64 music collection\sids\*.sid"
c:\hvsc\*.sid
demo1.prg
demo*.prg

<Options>
  -b: perform binary search when SID cannot be found via SID data

  Use the -b option to enable binary searches based on memory usage. This
  option requires you to specify the HVSC location via the -l option. It will
  index the HVSC collection first to speedup future searches. If an index file
  is already created then you don't need to specify the -l option anymore.
  It will only perform a binary search when the default method for identifying
  SID tunes didn't find any match.
  The binary search method is a little slower than the hash based search
  method. It can take a couple of seconds extra (depending on the performance
  of your machine). When the binary search method finds a match it will display
  the percentage of how much the tunes matches. Make sure you always check
  manually if the found match is correctly identified.

  -bo: perform binary search only

  Use the -bo option to force binary searches based on memory usage. With this
  option the hash based search will not be performed. Use this option only when
  you encounter a false positive and you want to check what the result would be
  via a binary search.

  -c{max_threads}: set the maximum CPU threads to be used [Default is all]

  Use the -c option to limit CPU thread usage. By default it will use all
  available CPU threads. This tool is optimized for running on multiple CPUs or
  on CPUs with multiple cores. The more CPU threads it can use, the faster the
  searches will be.

  -d{database_filename}: set database filename [Default database.txt]

  Use the -d option to specify the name and location of the database file. If
  you don't specify the -d option then it will search for the file database.txt
  in the same folder as where SID Known is located.

  -g: only generate hash for database

  Use the -g option to generate the hash database. With this tool a database
  file is already provided of the latest HVSC collection. This option you will
  only use when you want to create a database file yourself or when you want to
  recreate the database file for e.g. a new version of HVSC.
  Be aware that generating the hash database can take hours. If you want to
  have a newer database file then it is suggested to download the tool again.

  -i: index HVSC collection and write to disk to speedup future searches

  Use the -i option if you want to force creating or recreating the index file
  of the HVSC collection. Indexing the HVSC collection can take several minutes.
  You should only index the HVSC collection one time and not for every search
  you perform.
  When you use the -b option, the index file is automatically created. This
  option is only made to make it possible to recreate the index file.

  -l{hvsc location}: location of HVSC [Default C:\HVSC\C64Music]

  Use the -l option to specify the HVSC location which is needed for indexing
  the HVSC collection for binary searches. By default it will use the location
  "C:\HVSC\C64Music".

  -m: process multiple parts if present (only for PRG files)

  Use the -m option when you want to search multiple parts of PRG files. This
  option you can specify for e.g. demos which have multiple parts which can be
  skipped by pressing space or joystick buttons. The space bar and joystick
  button pressing will be done automatically when the tune is played for
  several minutes (provided with the -t option).

  -nf: only output filenames when no entry is found
  
  Use the -nf option when you want to process multiple PRG files and when you
  are only interested in PRG files where no SID match can be found.

  -s: include subdirectories

  Use the -s option if you want to search multiple SID and/or PRG files through
  multiple subdirectories.

  -t{minutes}: set the number of minutes to play a SID tune [Default 3 min]

  Use the -t option to specify the number of minutes the SID tune or PRG file
  should be played. By default SID tunes and PRG files are run for 3 minutes.
  If you change the number of minutes other than the default, then you need to
  regenerate the database for matching SID tunes based on SID input data.

  -w: wait for a key press before exiting

  Use the -w option if you want to pause the tool before exiting.


EXAMPLES
========

Create index file:
  sidknown -i -l"c:\hvsc\latest"

Identify multiple SID files in sub folders including binary search:
  sidknown -w -s -b *.sid
  sidknown -w -s -b "c:\hvsc\*.sid"

Identify multiple SID tunes in a PRG file:
  sidknown -w -b -m demo.prg

Create database file with hashes:
  sidknown -w -s -g *.sid >database.txt


RECOMMENDATIONS
===============

If a tune can't be identified, then make sure you have tried the -b (binary
search) option as well. Note that SID Known works best with SID files.
PRG files are supported but not all PRG files will work correctly if e.g. the
program tries to access the disk drive. In some cases it is better to first rip
the SID tune from a PRG and then run SID Known on the SID file to identify it.


YOUR HELP IS NEEDED
===================

SID Known can be used to identify music but it also helps to find out which
tunes are not in the High Voltage SID Collection. If you find music not found
by SID Known, it would be appreciated if you report this to the HVSC crew
(http://hvsc.de) or post it in one of the CSDb forums (http://csdb.dk) like
"SIDs that aren't in HVSC yet".

On the CSDb site (http://csdb.dk), you can upload C64 releases and with each
release you can specify which SID tunes are used in the release. You could help
improving the CSDb site by specifing which SID tunes are used in which release.
This info is valuable so we know when certain tunes were released for the first
time and in which releases the tunes were present in.


DISCLAIMER
==========

Use this software at your own risk.

SID Known comes with absolutely no warrenty. The author is not liable for any
damage in any event as a result of using SID Known.

If you experience any problem with SID Known, please let the author know.


THANKS
======

Thanks to iAN CooG for all the beta testing of SID Known, for the ideas to
improve it and for filtering the database.txt file with duplicates.

Thanks to Tli Sndor for the concept of the SID event driven C64 emulation
library which is used for this tool.


CONTACT INFORMATION
===================

Feel free to send me an e-mail for your feedback, questions or to report bugs.

email: wilfred_hvsc@xs4all.nl
