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.