Audio:PSID - Perl module to handle SID files.

Member functions

BUGS
TO DO LIST
COPYRIGHT
VERSION
SEE ALSO

NAME

Audio:PSID - Perl module to handle SID files (Commodore-64 music files).

SYNOPSIS

    use Audio::SID;

    $mySID = new Audio::SID('-filename' => 'Test.sid') or die "Whoops!";

    print "Title = " . $mySID->get('title') . "\n";

    print "MD5 = " . $mySID->getMD5();

    $mySID->set(author => 'LaLa',
                 title => 'Test2',
                 released => '2001 Hungarian Music Crew');

    $mySID->validate();
    $mySID->write('-filename' => 'Test2.sid') or die "Couldn't write file!";

    @array = $mySID->getFieldNames();
    print "Fieldnames = " . join(' ', @array) . "\n";

DESCRIPTION

This module is designed to handle SID files (usually bearing a .sid extension), which are music player and data routines converted from the Commodore-64 computer with an additional informational header prepended. For further details about the exact file format, see description of all SID fields in the SID_file_format.txt file included in the module package. For information about SID tunes in general, see the excellent SIDPLAY homepage at:

http://www.geocities.com/SiliconValley/Lakes/5147/

For PSID v2NG documentation:

http://sidplay2.sourceforge.net

You can find literally thousands of SID tunes in the High Voltage SID Collection at:

http://www.hvsc.c64.org

This module can handle PSID version 1, PSID version 2/2NG and RSID files. (Version 2 files are simply v2NG files where v2NG specific fields are set 0, RSID (RealSID) files are PSID v2NG files with the magicID set to 'RSID' and with some additional restrictions on certain field values.) The module was designed primarily to make it easier to look at and change the SID header fields, so many of the member function are geared towards that. Use $OBJECT->getFieldNames() to find out the exact names of the fields currently recognized by this module. Please note that fieldnames are case-sensitive!

Member functions

PACKAGE->new()

Usage:

PACKAGE->new(SCALAR) or PACKAGE->new('-filename' => SCALAR) or PACKAGE->new(FILEHANDLE) or PACKAGE->new('-filehandle' => FILEHANDLE) or PACKAGE->new('-filedata' => SCALAR)

Returns a newly created Audio::SID object. If no parameters are specified, the object is initialized with default values. See $OBJECT->initalize() below for initialization details.

If SCALAR or FILEHANDLE is specified (with or without a name-value pair), an attempt is made to open the given file as specified in $OBJECT->read() below. If SCALAR is specified with '-filedata', SCALAR is assumed to contain the binary data of a SID file. Upon failure no object is created and new returns undef.

OBJECT->initialize()

Initializes the object with default SID data as follows:

    magicID => 'PSID',
    version => 2,
    dataOffset => 0x7C,
    songs => 1,
    startSong => 1,
    title => '<?>',
    author => '<?>',
    released => '20?? <?>',
    data => '',

Every other SID field (loadAddress, initAddress, playAddress, speed, flags, startPage, pageLength and reserved) is set to 0. FILENAME is set to '' and the filesize is set to 0x7C.

PACKAGE->read()

Usage:

PACKAGE->read(SCALAR) or PACKAGE->read('-filename' => SCALAR) or PACKAGE->read(FILEHANDLE) or PACKAGE->read('-filehandle' => FILEHANDLE) or PACKAGE->read('-filedata' => SCALAR)

If SCALAR or FILEHANDLE is specified (with or without a name-value pair), an attempt is made to open the given file. If SCALAR is specified with '-filedata', SCALAR is assumed to contain the binary data of a SID file.

If no parameters are specified, the value of FILENAME is used to determine the name of the input file. If that is not set, either, the module is initialized with default data and read() returns an undef. Note that SCALAR and FILEHANDLE here can be different than the value of FILENAME! If SCALAR is defined, it will overwrite the filename stored in FILENAME, otherwise it is not modified. So, watch out when passing in a FILEHANDLE, because FILENAME will not be modified!

If the file turns out to be an invalid SID file, the module is initialized with default data and read() returns an undef. Valid SID files must have the ASCII string 'PSID' or 'RSID' as their first 4 bytes, and either 0x0001 or 0x0002 as the next 2 bytes in big-endian format.

If the given file is a PSID version 1 file, the fields of flags, startPage, pageLength and reserved are set to undef.

PACKAGE->write()

Usage:

PACKAGE->write(SCALAR) or PACKAGE->write('-filename' => SCALAR) or PACKAGE->write(FILEHANDLE) or PACKAGE->write('-filehandle' => FILEHANDLE)

Writes the SID file given by the filename SCALAR or by FILEHANDLE to disk. If neither SCALAR nor FILEHANDLE is specified (with or without a name-value pair), the value of FILENAME is used to determine the name of the output file. If that is not set, either, write() returns an undef. Note that SCALAR and FILEHANDLE here can be different than the value of FILENAME! If SCALAR is defined, it will not overwrite the filename stored in FILENAME.

write will create a version 1 or version 2/2NG SID file depending on the value of the version field, and an RSID file if the magicID is set to 'RSID', regardless of whether the other fields are set correctly or not, or even whether they are undef'd or not. However, if $OBJECT->alwaysValidateWrite(1) was called beforehand, write will always write a validated PSID v2NG or RSID SID file. See below.

$OBJECT->get([SCALAR])

Retrieves the value of the SID field given by the name SCALAR, or returns a hash of all the recognized SID fields with their values if called in an array/hash context.

If the fieldname given by SCALAR is unrecognized, the operation is ignored and an undef is returned. If SCALAR is not specified and get is not called from an array context, the same terrible thing will happen. So try not to do either of these.

For backwards compatibility reasons, ``copyright'' is always accepted as an alias for the ``released'' fieldname and ``name'' is always accepted as an alias for ``title''.

$OBJECT->getFileName()

Returns the current FILENAME stored in the object.

$OBJECT->getFileSize()

Returns the total size of the SID file that would be written by $OBJECT->write() if it was called right now. This means that if you read in a version 1 file and changed the version field to 2 without actually saving the file, the size returned here will reflect the size of how big the version 2 file would be.

$OBJECT->getRealLoadAddress()

The ``real load address'' indicates what is the actual Commodore-64 memory location where the SID data is going to be loaded into. If loadAddress is non-zero, then loadAddress is returned here, otherwise it's the first two bytes of data (read from there in little-endian format).

$OBJECT->getSpeed([SCALAR])

Returns the speed of the song number specified by SCALAR. If no SCALAR is specified, returns the speed of song #1. Speed can be either 0 (indicating a vertical blank interrupt (50Hz PAL, 60Hz NTSC)), or 1 (indicating CIA 1 timer interrupt (default is 60Hz)).

$OBJECT->getMUSPlayer()

Returns the value of the 'MUSPlayer' bit of the flags field if flags is specified (i.e. when version is 2), or undef otherwise. The returned value is either 0 (indicating a built-in music player) or 1 (indicating that data is a Compute!'s Sidplayer MUS data and the music player must be merged).

$OBJECT->isMUSPlayerRequired()

This is an alias for $OBJECT->getMUSPlayer().

$OBJECT->getPlaySID()

Returns the value of the 'psidSpecific' bit of the flags field if flags is specified (i.e. when version is 2) and the magicID is 'PSID', or undef otherwise. The returned value is either 0 (indicating that data is Commodore-64 compatible) or 1 (indicating that data is PlaySID specific).

$OBJECT->isPlaySIDSpecific()

This is an alias for $OBJECT->getPlaySID().

$OBJECT->isRSID()

Returns 'true' if the magicID is 'RSID', 'false' otherwise.

$OBJECT->getC64BASIC()

Returns the value of the 'C64BASIC' bit of the flags field if flags is specified (i.e. when version is 2) and the magicID is 'RSID', or undef otherwise. The returned value is either 1 (indicating that data has a BASIC executable portion, or 0 otherwise.

$OBJECT->isC64BASIC()

This is an alias for $OBJECT->getC64BASIC().

$OBJECT->getClock()

Returns the value of the 'clock' (video standard) bits of the flags field if flags is specified (i.e. when version is 2), or undef otherwise. The returned value is one of 0 (UNKNOWN), 1 (PAL), 2 (NTSC) or 3 (EITHER).

$OBJECT->getClockByName()

Returns the textual value of the 'clock' (video standard) bits of the flags field if flags is specified (i.e. when version is 2), or undef otherwise. The textual value will be one of UNKNOWN, PAL, NTSC or EITHER.

$OBJECT->getSIDModel()

Returns the value of the 'sidModel' bits of the flags field if flags is specified (i.e. when version is 2), or undef otherwise. The returned value is one of 0 (UNKNOWN), 1 (6581), 2 (8580) or 3 (EITHER).

$OBJECT->getSIDModelByName()

Returns the textual value of the 'sidModel' bits of the flags field if flags is specified (i.e. when version is 2), or undef otherwise. The textual value will be one of UNKNOWN, 6581, 8580 or EITHER.

$OBJECT->set(field => value [, field => value, ...] )

Given one or more field-value pairs it changes the SID fields given by field to have value.

If you try to set a field that is unrecognized, that particular field-value pair will be ignored. Trying to set the version field to anything other than 1 or 2 will result in criminal prosecution, expulsion, and possibly death... Actually, it won't harm you, but the invalid value will be ignored. The same is true for the magicID field if you try to set it to anything else but 'PSID' or 'RSID'.

Whenever the version number is changed to 1, the flags, startPage, pageLength and reserved fields are automatically set to be undef'd, the magicID is set to 'PSID' and the dataOffset field is set to 0x0076.

Whenever the version number is changed to 2, the flags, startPage, pageLength and reserved fields are zeroed out if they are not set, yet.

Whenever the magicID is changed from 'RSID' to 'PSID' or vice versa and flags is not specified at the same time, the psidSpecific field for PSID or the C64BASIC field for RSID is set to 0.

Whenever the magicID is set to 'RSID', the loadAddress, playAddress and speed fields are set to 0, plus the 'psidspecific' bit in the flags field is also set to 0. If loadAddress was non-zero before, its value is prepended to data.

If you try to set magicID, flags, startPage, pageLength or reserved when version is not 2, the values will be ignored. Trying to set dataOffset when version is 1 will always reset its value to 0x0076, and dataOffset can't be set to lower than 0x007C if version is 2. You can set it higher, though, in which case either the relevant portion of the original extra padding bytes between the SID header and the data will be preserved, or additional 0x00 bytes will be added between the SID header and the data if necessary.

For backwards compatibility reasons, ``copyright'' is always accepted as an alias for the ``released'' fieldname and ``name'' is always accepted as an alias for ``title''.

$OBJECT->setFileName(SCALAR)

Sets the FILENAME to SCALAR. This filename is used by $OBJECT->read() and $OBJECT->write() when either one of them is called without any arguments. SCALAR can specify either a relative or an absolute pathname to the file - in fact, it can be anything that can be passed to a FileHandle type object as a filename.

$OBJECT->setSpeed(SCALAR1, SCALAR2)

Changes the speed of the song number specified by SCALAR1 to that of SCALAR2. SCALAR1 has to be more than 1 and less than the value of the songs field. SCALAR2 can be either 0 (indicating a vertical blank interrupt (50Hz PAL, 60Hz NTSC)), or 1 (indicating CIA 1 timer interrupt (default is 60Hz)). An undef is returned if neither was specified.

$OBJECT->setMUSPlayer(SCALAR)

Changes the value of the 'MUSPlayer' bit of the flags field to SCALAR if flags is specified (i.e. when version is 2), returns an undef otherwise. SCALAR must be either 0 (indicating a built-in music player) or 1 (indicating that data is a Compute!'s Sidplayer MUS data and the music player must be merged).

$OBJECT->setPlaySID(SCALAR)

Changes the value of the 'psidSpecific' bit of the flags field to SCALAR if flags is specified (i.e. when version is 2) and the magicID is 'PSID', returns an undef otherwise. SCALAR must be either 0 (indicating that data is Commodore-64 compatible) or 1 (indicating that data is PlaySID specific).

$OBJECT->setC64BASIC(SCALAR)

Changes the value of the 'C64BASIC' bit of the flags field to SCALAR if flags is specified (i.e. when version is 2) and the magicID is 'RSID', returns an undef otherwise. SCALAR must be either 1 (indicating that data has a C64 BASIC executable portion) or 0 otherwise. Setting this flag to 1 also sets the initAddress field to 0.

$OBJECT->setClock(SCALAR)

Changes the value of the 'clock' (video standard) bits of the flags field to SCALAR if flags is specified (i.e. when version is 2), returns an undef otherwise. SCALAR must be one of 0 (UNKNOWN), 1 (PAL), 2 (NTSC) or 3 (EITHER).

$OBJECT->setClockByName(SCALAR)

Changes the value of the 'clock' (video standard) bits of the flags field if flags is specified (i.e. when version is 2), returns an undef otherwise. SCALAR must be be one of UNKNOWN, NONE, NEITHER (all 3 indicating UNKNOWN), PAL, NTSC or ANY, BOTH, EITHER (all 3 indicating EITHER) and is case-insensitive.

$OBJECT->setSIDModel(SCALAR)

Changes the value of the 'sidModel' bits of the flags field if flags is specified (i.e. when version is 2), returns an undef otherwise. SCALAR must be one of 0 (UNKNOWN), 1 (6581), 2 (8580) or 3 (EITHER).

$OBJECT->setSIDModelByName(SCALAR)

Changes the value of the 'sidModel' bits of the flags field if flags is specified (i.e. when version is 2), returns an undef otherwise. SCALAR must be be one of UNKNOWN, NONE, NEITHER (all 3 indicating UNKNOWN), 6581, 8580 or ANY, BOTH, EITHER (all 3 indicating EITHER) and is case-insensitive.

$OBJECT->getFieldNames()

Returns an array that contains the SID fieldnames recognized by this module, regardless of the SID version number. All fieldnames are taken from the standard SID file format specification, but do not include those fields that are themselves contained in another field, namely any field that is inside the flags field. The fieldname FILENAME is also not returned here, since that is considered to be a descriptive parameter of the SID file and is not part of the SID specification.

$OBJECT->getMD5([SCALAR])

Returns a string containing a hexadecimal representation of the 128-bit MD5 fingerprint calculated from the following SID fields: data (excluding the first 2 bytes if loadAddress is 0), initAddress, playAddress, songs, the relevant bits of speed, and the value of the clock field if it's set to NTSC and SCALAR is zero or not defined. If SCALAR is a nonzero value, the MD5 fingerprint calculation completely ignores the clock field, which provides backward compatibility with earlier MD5 fingerprints.

The MD5 fingerprint calculated this way is used, for example, to index into the songlength database, because it provides a way to uniquely identify SID files even if the textual credit fields of the SID file were changed.

$OBJECT->alwaysValidateWrite(SCALAR)

If SCALAR is non-zero, $OBJECT->validate() will always be called before $OBJECT->write() actually writes a file to disk. If SCALAR is 0, this won't happen and the stored SID data will be written to disk virtually untouched - this is also the default behavior.

$OBJECT->validate()

Regardless of how the SID fields were populated, this operation will update the stored SID data to comply with the latest SID version (PSID v2NG or RSID). Thus, it changes the SID version to 2, and it will also change the other fields so that they take on their prefered values. Operations done by this member function include (but are not limited to):

setting the version field to 2,
if the magicID is 'RSID', setting the playAddress and speed fields,
setting the dataOffset to 0x007C,
chopping the textual fields of title, author and released to their maximum length of 31 characters,
changing the initAddress to a valid non-zero value,
if the magicID is 'RSID', changing the initAddress to zero if it is pointing to a ROM/IO area ($0000-$07E8, $A000-$BFFF or $D000-$FFFF), or if the C64BASIC flag is set to 1,
changing the loadAddress to 0 if it is non-zero (and also prepending the data with the non-zero loadAddress)
changing the actual load address to $07E8 if it is less than $07E8 and the magicID is RSID,
making sure that loadAddress, initAddress and playAddress are within the $0000-$FFFF range (since the Commodore-64 had only 64KB addressable memory), and setting them to 0 if they aren't,
making sure that startPage and pageLength are within the 0x00-0xFF range, and setting them to 0 if they aren't,
making sure that songs is within the range of [1,256], and changing it to 1 if it less than that or to 256 if it is more than that,
making sure that startSong is within the range of [1,songs], and changing it to 1 if it is not,
setting only the relevant bits in speed, regardless of how many bits were set before, and setting the rest to 0,
setting only the recognized bits in flags, namely 'MUSPlayer', 'psidSpecific', 'clock' and 'sidModel' (bits 0-5), and setting the rest to 0,
setting the pageLength to 0 if startPage is 0 or 0xFF,
setting the startPage to 0xFF and the pageLength to 0 if the relocation range indicated by these two fields overlaps or encompasses the load range of the C64 data,
setting the startPage to 0xFF and the pageLength to 0 if the relocation range indicated by these two fields overlaps or encompasses the ROMs ($A000-$BFFF and $D000-$FFFF) or reserved memory ($0000-$03FF) areas,
removing extra bytes that may have been between the SID header and data in the file (usually happens when dataOffset is larger than the total size of the SID header, i.e. larger than 0x007C),
setting the reserved field to 0,

BUGS

None is known to exist at this time. If you find any bugs in this module, report them to the author (see COPYRIGHT below).

TO DO LIST

More or less in order of perceived priority, from most urgent to least urgent.

Add Stefano's SID player engine recognizer code. Didn't somebody else have something like this, too?
Overload '=' so two objects can be assigned to each other?

COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

(Thanks to Adam Lorentzon for showing me how to extract binary data from SID files! :-)

VERSION

Version v3.10, released to CPAN on Jul 17, 2005.

First version (then called Audio::PSID) created on June 11, 1999.