The AdvanceSCAN roms manager

1 Synopsis

advscan [-c, --cfg CONFIG] [-r, --rom] [-s, --sample]
    [-k, --disk] [-a, --add-zip] [-b, --add-bin]
    [-d, --del-zip] [-u, --del-unknown]
    [-g, --del-garbage] [-t,--del-text]
    [-n, --print-only] [-p, --report]
    [-f, --filter FILTER]
    [-v, --verbose] < info.lst/xml

advscan [-R, --rom-std] [-S, --sample-std]
    [-K, --disk-std]< info.lst/xml

advscan [-i, --ident] files... < info.lst/xml

advscan [-l, --bbs] < info.lst/xml

advscan [-e, --equal] < info.lst/xml

advscan [-h, --help] [-V, --version]

2 Description

advscan is a command line utility for maintaining a zipped archive of roms and sample zip archive for the MAME, MESS, xmame, AdvanceMAME, AdvanceMESS and Raine emulators. The goal of advscan is to obtain a complete and perfect rom and sample zip archive with differential merging.

Differential merging means that any game has its zip archive, which contains all the rom files, which are not already in the parent zip archive (if exists).

advscan has these features:

Directly read, writes zip archives without decompressing and recompressing them for best performance.
Add, copy, move and rename files in the zip archives. Any rom that you have is placed automatically in the correct zip.
Recognizes the text files added by rom sites and delete them.
Recognizes the text files added by the rom dumpers and keep or delete them as your choice.
It's safe. On all the zip operations any file removed or overwritten is saved in the `rom_unknown' `sample_unknown' directories and keep for future uses. This will prevent any unwanted remove operation.

but also has these misfeatures:

Supports only rom and sample archives zipped.
Supports only rom organized with differential merging.
Doesn't support .chd files in subdirectories.

3 Options

-c, --cfg CONFIG

Select the configuration file. If not specified is assumed the file `advscan.rc' in the current directory.

< info.lst/xml

To operate advscan needs always as input a rom information file. It can be generally created with the -listinfo/-listxml (MAME) or -gameinfo (Raine) options of the emulator. If the first not space char of the file is a `<', the file is assumed to be xml, otherwise it's assumed to be the old listing format.

-r, --rom

Operates on roms (.zip files). All the next commands will operate on your romset.

-s, --sample

Operates on samples. All the next commands will operate on your sampleset.

-k, --disk

Operates on disks (.chd files). All the next commands will operate on your diskset.

-a, --add-zip

Add the missing rom zips. Any missing zip archive for which at least one rom is available will be created.

-b, --add-bin

Add, rename and substitute all the necessary files in the existing zip archives. No new zip archives are created, only the already present zip files are modified. No file is deleted. Anyway, some files may be overwritten. Any file overwritten is saved in the `rom_unknown' or `sample_unknown' directory in a zip archive with the same name of the original one.

-d, --del-zip

Remove any unknown zip or chd archive. Any archive removed is saved in the `rom_unknown', `sample_unknown' or `disk_unknown' directory.

-u, --del-unknown

Remove any unknown file from the existing zip archives. Any file removed is saved in the `rom_unknown' or `sample_unknown' directory in a zip archive with the same name of the original one. Only binary files are removed, all the text files are keep.

-g, --del-garbage

Remove any garbage file from the zip archives. A garbage file is an advertising text file added generally by a rom site. The files removed are not saved.

-t, --del-text

Remove any text file from the zip archives. Any file removed is saved in the `rom_unknown' or `sample_unknown' directory in a zip archive with the same name of the original one.

-R, --rom-std

Shortcut for the options -rabdug. It does all the previous operations on roms except removing text files.

-S, --sample-std

Shortcut for the options -sabdug. It does all the previous operations on samples except removing text files.

-K, --disk-std

Shortcut for the options -kd. It moves any unknown disk file in the disk_unknown directory.

-n, --print-only

Don't modify anything, it only shows operations. This option prevents any changes made by the previous commands. The operations are only printed and NOT executed.

-p, --report

Write an extensive text report with the list of good, bad and missing roms or/and samples. The content of any zip archive with missing files is printed. You must also specify the -r or/and -s options.

-P, --report-file

Write a small text report with information on the present files, listing incomplete, duplicate or missing required zips.

-f, --filter FILTER

Apply a specific filter at the rom list. Check the FILTERS chapter for a detailed list of filters available.

-v, --verbose

Print a more verbose report. The content of any zip archive is printed also if it contains at least one not rom file.

4 Information Options

The following options are used only to print information. These options don't need or read the configuration file.

-i, --ident files...

Identify the files specified. Only the information present in the info file is used.

-l, --bbs

Print a standard `.bbs' files with the description of all the roms in the info file.

-e, --equal

Print a list of all the duplicate roms present in the info file. Only the information present in the info file is used.

-h, --help

Print a short help screen.

-V, --version

Print the program version.

5 Identification

Rom files are identified by their crc and size. The roms are not really decompressed, but the crc value stored on the zip archives is used. If a rom has an incorrect crc or size, but it has a correct name, it's maintained if doesn't exist a valid alternative.

Sample files are identified only by their names. This limits the possible operations. Essentially advscan can report only missing samples.

Garbage files are identified by their size and crc.

All the others files are identified with this algorithm:

If the name is like *.sam, *.wav it's considered an unknown binary file.
If the name is something like *.doc, *.txt, *.nfo, *.diz, readme.* it's considered a text file.
If the size is a power of 2 it's considered an unknown binary file.
It's considered a text file.

6 Configuration

To run advscan you need two files. The rom information file and the configuration file.

The rom information file is the file that contains the information of all the roms used by the emulator. It can be made with the command:

advmame -listxml > info.xml

This file is expected as input of advscan. So, you can use this command:

advscan [options] < info.xml

Or combine the two commands together:

advmame -listxml | advscan [options]

The configuration file is a text file that describes your directories structure. You can use absolute path or relative path. Relative path is relative to the current directory from where you run advscan.

In Unix the PATH separator is `:'. In DOS and Windows the PATH separator is `;'. The following options are expressed with the Unix format.

rom PATH:PATH...
List of paths where the roms are placed. These are the zip archives, which are modified and fixed.

rom_new PATH
Single path where the new created zip archives are placed. It's STRONGLY suggested to put this path ALSO in the `rom' specification. Otherwise at the next run the zip archives are recreated.

rom_import PATH:PATH...
List of directory trees where other roms files are placed. These are used for importing rom file missing in rompath. These files are only read and never modified in any way. It's very useful to insert here any rom directories of any other arcade emulators. When a new game will be supported the rom archive will be made automatically.

rom_unknown PATH
Single path where unknown rom zip archives will be moved. In this directory is inserted any rom file removed from the rom zip archives. However, any rom file is automatically deleted by advscan if it's duplicated in an archive listed on the `rom' or `rom_import' options.

sample PATH:PATH...
List of paths where the samples are placed. These are the zip archives, which are modified and fixed.

sample_unknown PATH
Single path where unknown sample zip archives will be moved. In this directory is inserted any sample file removed from the sample zip archives.

disk PATH:PATH...
List of paths where the disks are placed. These are the chd archives.

disk_unknown PATH
Single path where unknown disk chd archives will be moved.

If the -c option is not specified the configuration file is read from ./advscan.rc.

The files advscan.rc.linux and advscan.rc.dos are two examples of configuration files.

7 Damaged Files

If a damaged .zip or .chd file is detected, it's renamed with a new name appending the extension ".damaged". For .chd file it may happen that the file is a disk image with an old format.

If the rename operation isn't possible the program aborts.

Please note that the program doesn't execute an extensive test to detect damaged files.

8 Filters

As default advscan uses all the rom definitions, including also unplayable games. If you prefere you can use only a subset of the roms defined with the --filter option.

The filters available are:

working Use only working roms. A working rom is a rom reported working or a rom needed by another working rom. A rom is reported working if it isn't marked with the "preliminary" flag in the driver, video or sound. This should be the preferred filter which only store playable games.

preliminary Use only roms which are not in the "working" subset.

working_parent Use only working parent roms from the "working" subset excluding clones. If a parent rom is not working but it has a working clone, both the parent and the clone are used. This is the preferred filter if you want only one working game for any parent/clones group.

working_clone Use only roms which are in the "working" subset but not in the "working_parent" subset.

For example, if you want to keep preliminary and working roms in different directories, you can setup two different advscan.rc files with different directories but sharing the `rom_unknown' dir to allow automatic rom moving between the two sets. If this is your configuration, to update your romset, you need to run advscan three times:

on working set To export preliminary roms in the rom_unknown dir.

on preliminary set To import preliminary roms and export working roms in the rom_unknown dir.

on working set To import working rom from the rom_unknown dir.

For example:
advscan -R -c advscan-wrk.rc -f working < advmame.xml > rom_wrk.log advscan -R -c advscan-pre.rc -f preliminary < advmame.xml > rom_pre.log advscan -R -c advscan-wrk.rc -f working < advmame.xml > rom_wrk.log

9 Report Format

The report generated with the -p option contains some text tag explained here:

rom_good

A recognized good rom. The rom is recognized by its name, crc and size.

rom_bad

A recognized bad rom with an incorrect size or crc. The rom is recognized by its name.

rom_miss

A missing rom.

disk_bad

A recognized bad disk with an incorrect hash. The disk is recognized by its name.

nodump_good

A fake "NO GOOD DUMP KNOWN" rom. The rom is recognized by its name, size and crc.

nodump_miss

A missing "NO GOOD DUMP KNOWN" rom. It's the normal condition, a no dump rom must be missing.

nodump_bad

A recognized bad "NO GOOD DUMP KNOWN" rom. The rom is recognized by its name.

sound_good

A recognized good sound sample. The sample is recognized by its name.

sound_miss

A missing sound sample.

text

An unknown text file.

binary

An unknown binary file.

garbage

A recognized garbage file. A garbage file is an advertising text file added generally by a rom site. The file is recognized by its name, size and crc.

10 Examples

For the generic use you need to run advscan with the options:

advscan -R < info.xml

This command will fix your rom collection (without removing the precious text files).

To check in advance all the operations that will be done you can use the command:

advscan -R -n < info.xml

which only show the operations.

To only generate an extensive report of your rom set you can use the command:

advscan -r -p < info.xml > report.txt

To increase the verbosity of the printed information you can add the -v switch.

11 Copyright

12 See Also

advdiff(1)

	working	Use only working roms. A working rom is a rom reported working or a rom needed by another working rom. A rom is reported working if it isn't marked with the "preliminary" flag in the driver, video or sound. This should be the preferred filter which only store playable games.
	preliminary	Use only roms which are not in the "working" subset.
	working_parent	Use only working parent roms from the "working" subset excluding clones. If a parent rom is not working but it has a working clone, both the parent and the clone are used. This is the preferred filter if you want only one working game for any parent/clones group.
	working_clone	Use only roms which are in the "working" subset but not in the "working_parent" subset.

	on working set	To export preliminary roms in the rom_unknown dir.
	on preliminary set	To import preliminary roms and export working roms in the rom_unknown dir.
	on working set	To import working rom from the rom_unknown dir.