formats index
*** SID/PSID (Various SIDPlay / PlaySID Emulator Formats)
** Document revision 1.0
The data files used by SIDPLAY contain binary C64 data and music player
machine code. Both, the programmer on the C64 and this emulator need
information on how to access the code inside the binary file. That means,
information like the memory location to load the file to, the number of
tunes, the starting address of the executable code and its subroutines.
This specific information has to be delivered in either a separate file -
which is often called info file - or in form of a header in the single
binary data file. A standalone C64 data file without a header or without a
corresponding info file is considered invalid.
It is recommended that you get accustomed to one-file sidtunes with the
*.sid extension. For raw C64 binary files the extension .c64 or .prg is
preferred in order to be able to assign a .sid extension to the additional
info file.
Supported and merely used file formats are:
PlaySID single-file-format (widely known as PSID)
PlaySID info-file-format (Raw C64 binary file plus Amiga Workbench icon
tooltype file .INFO)
SIDPLAY info-file-format (Raw C64 binary file plus SIDPLAY ASCII text
info file, previously .SID)
C64 Sidplayer format (.MUS)
Raw data or PSID files have appeared as *.data, *.psid or psid.*.
DAT files
The .DAT file name extension has been introduced by the early versions of
SIDPLAY/DOS. It has never been used to specify a file format. Its main use
has been in assigning a unique file name extension to any sidtune file, but
especially raw C64 data files, and allowing to use .SID for additional info
files.
INFO files
These are Amiga Workbench tooltype icons containing binary graphics data
and ASCII text information strings. They have been used by PlaySID and are
supported by SIDPLAY. Their file name extension normally is .info or .INF.
This is a two-file format. A separate C64 binary data file is required. On
Amiga the corresponding C64 data files usually haven't had filename
extensions. However, they might have been renamed on other systems.
SIDPLAY info files
These are plain ASCII text files which have been introduced by the
earlier versions of SIDPLAY/DOS. They are used to be able to alter the
information inside with a normal ASCII text editor. They can be converted
to a single file that contains a binary header. This is a two-file format.
A separate C64 binary data file is required. Notice that each pair of files
usually has the old DOS-naming of .SID for the info file and .DAT for the
C64 data file.
The SIDPLAY info file is derived from the information inside the PlaySID
one-file format. It is structured like this:
SIDPLAY INFOFILE
ADDRESS=,,
SONGS=[,]
SPEED=
NAME=
AUTHOR=
COPYRIGHT=
SIDSONG=
The first line of the text containing ``SIDPLAY INFOFILE'' is only used
to identify the type of file.
ADDRESS=,,
Each specified address is a 16-bit effective C64 memory location in case
insensitive hexa-decimal notation without a prefix, e.g. C000 or E012, but
neither $FCE2 nor 0xFCE2. Preceding zeroes are ignored.
is the C64 memory location where to put the C64 data. 0
means, the data is in original C64 format, i.e. the first two bytes contain
the little-endian load address (low byte, high byte). Please don't
explicitly specify the load address unless required for sure. If the load
address is explicitly specified, some sidtune converters and utilities
conjecture that the C64 data lacks its load address. Hence they move it in
front of the C64 data. This would create two redundant bytes if the C64
data already had a load address in the first two bytes. Additionally, those
extra bytes in the beginning can confuse disassemblers.
is the start address of the machine code subroutine that
initializes a song by accepting the contents of the 8-bit 6510 Accumulator
as the song number parameter. 0 means, the address is equal to the
effective load address.
is the start address of the machine code subroutine that can
be called frequently to produce a continuous sound. 0 means, the
initialization subroutine is expected to install an interrupt handler,
which then calls the music player. If so, the value in the bank-select
register $01 determines whether the IRQ vector $0314/$0315 (Kernal-ROM on)
or the IRQ vector $FFFE/$FFFF (Kernal-ROM off) is to be used.
SONGS=,[]
is the decimal number of songs (or sound effects) that can be
initialized by calling the init address. The minimum is 1.
is the decimal number of the song to be played by default. This
value is meant as a proposal and is optional. It has a default of 1. It
often specifies the first song you would hear upon starting the program is
has been taken from.
SPEED=
is a value in case insensitive hexa-decimal notation without a
prefix. Preceding zeroes are ignored. The value contains information about
the speed of each song. For each song a bit is reserved, bit 0 for song 1,
bit 1 for song 2, and so on. A bit set to 0 means, the music player
subroutine is called at 50 Hz. A bit set to 1 means, the real speed is
indicated by the CIA 1 Timer A $DC04/05, which defaults to 60 Hz. To not
break compatibility to the PlaySID formats, use a maximum of 32 bits, which
is equal to 32 songs. Due to a bug in PlaySID, the PSID format can only
handle up to 8 songs correctly. On the contrary, the SIDPLAY info format is
extended to 256 bits, which is equal to 256 songs. Examples: SPEED=0
replays every song at 50 Hz speed. SPEED=1F replays songs 1-5 at 60 Hz
speed, all other songs at 50 Hz speed.
NAME=
AUTHOR=
COPYRIGHT=
These three fields are all plain ASCII text strings. There are limited to
a maximum of 80 characters each. To not break compatibility to the PlaySID
formats, use a maximum of 31 characters.
SIDSONG=
is used to indicate that the corresponding C64 data file is in (Enhanced)
Sidplayer file format. This field is optional and defaults to NO.
An example file ``EXAMPLE.SID'' may look like this:
SIDPLAY INFOFILE
ADDRESS=2AF0,3002,300C
SONGS=3,2
SPEED=0
NAME=Example
AUTHOR=Example
COPYRIGHT=199? (c) Example
SIDSONG=NO
PSID file header
You can display any file with a normal ASCII/HEX editor. If the first
four characters (bytes) contain the word PSID, and if close to the
beginning there are ASCII text strings containing readable author and
copyright information, you can almost be sure that it is in PlaySID v2.2+
(Amiga) one-file format.
The detailed structure of the PSID header looks like the following.
Header offsets are in hexa-decimal notation. Other integer values are
decimal unless explicitly marked otherwise. Because of the Amiga hardware,
any stored integer values are in big-endian format:
+00 ``PSID''
This is a four byte long ASCII character string containing the value
0x50534944.
+04 WORD version
Available version number can either be 0001 or 0002. Headers of version 2
provide additional fields.
+06 WORD dataOffset
This is the offset from the start of the file to the C64 binary data area.
Because of the fixed size of the header, this is either 0x0076 for version
1 and 0x007C for version 2. Whether the value in this field might also be
the address of the used Amiga timer interrupt handler is unconfirmed.
Although interrupt level 7 really is at address 0x0000007C, the other value
would be invalid. The playsid.library doesn't recognize PSID files with
other data offets.
+08 WORD loadAddr
The C64 memory location where to put the C64 data. 0 means, the data is in
original C64 format, i.e. the first two bytes contain the little-endian
load address (low byte, high byte). Please don't explicitly specify the
load address unless required for sure. If the load address is explicitly
specified, some sidtune converters and utilities conjecture that the C64
data lacks its load address. Hence they move it in front of the C64 data.
This would create two redundant bytes if the C64 data already had a load
address in the first two bytes. Additionally, those extra bytes in the
beginning can confuse disassemblers.
+0A WORD initAddr
The start address of the machine code subroutine that initializes a song,
accepting the contents of the 8-bit 6510 Accumulator as the song number
parameter. 0 means, the address is equal to the effective load address.
+0C WORD playAddr
The start address of the machine code subroutine that can be called
frequently to produce a continuous sound. 0 means, the initialization
subroutine is supposed to install an interrupt handler, which then calls
the music player at some place.
+0E WORD songs
The number of songs (or sound effects) that can be initialized by calling
the init address. The minimum is 1. The maximum is 256.
+10 WORD startSong
The song number to be played by default. This value is meant as a proposal
and is optional. It often specifies the first song you would hear upon
starting the program is has been taken from. It has a default of 1.
+12 LONGWORD speed
This field does not work like it was intended. The PlaySID authors wrote:
speeddata contains info about playspeed. For each tune a bit is reserved,
bit 0 for tune nr 1 and so on. A 0 bit means vertical sync (50Hz PAL Amiga
or 60Hz NTSC Amiga) and a 1 bit means 60 Hz or the time set in $DC04/05.
Default value is 0 for all bits. Unfortunately, PlaySID's behaviour upon
evaluating this field is different. Only the least significant byte does
work. When starting to count from 0, all songs above or equal to number 8
are always set to speed 0, i.e. 50 Hz PAL. Since 32-bits are used, the
technique would work only for a maximum of 32 songs anyway.
+16 ``''
+36 ``''
+56 ``''
These are 32 byte long zero terminated ASCII character strings. Upon
evaluating the header, a zero byte will always be put into the last byte of
each string. So the maximum number of available free characters is 31.
+76
Version 1 of the PSID header is complete at this point. The binary C64 data
starts here.
The PSID file header v2
Version 2 of the header provides additional fields. These are undocumented,
but most likely rarely used.
+76 WORD flags
If bit 0 of this field is set, the appended binary data is in Compute!'s
Sidplayer MUS format, and does not contain a built-in music player. An
external player machine code must be merged to replay such a sidtune. This
field almost ever contains a zero.
+78 LONGWORD reserved
This is undocumented.
+7C
Version 2 of the PSID header ends here. This offset is the start of the
binary C64 data.
ÿ