Format of .SAP files

Format of .SAP files is quite simple. SAP file is divided into two parts, text part and binary part. Binary part is just an Atari Binary File. This format is used in all atari binary programs that can be loaded with DOS 2.5 (and with other DOSes compatible with DOS 2.5). In this format, each atari file (and binary part of SAP file) begins with two bytes (in hex) FF,FF. Next bytes are blocks which are loaded into Atari 65kB memory (SAP emulates this 65kB of memory). Each block begins with four byte header. First two bytes tells to loader, when first byte of this block (without header) should be loaded, and next two bytes (in this header) tells to loader, when the last byte (of this block) will be placed. So, for example, block, which looks like this:

00,20,05,20,01,42,A3,04,D5

will load values 01,42,A3,04,D5 into memory, from 2000 to 2005.

Text part of SAP file always begins with a single line "SAP". Next lines can be command lines or comment lines (each line that is not recognized as command line, is threaded as comment line). Currently (version 0.9 of SAP player) only those commands are recognized:

"SONGS" always describes number of songs in this SAP file. "DEFSONG" always describes number of first song, that will be played after SAP file is loaded ("DEFSONG" is ignored if there's only one song). Interpreting of other commands depends on the most important command: "TYPE". "TYPE" can contains full word, but only first character in this word is recognized. Currently there are 4 types:

  1. B (binary). In SAP file with this type, must be also defined commands "INIT" and "PLAYER". "INIT" sets address of initialization procedure. When this procedure is called, register "A" (in 6502) contain number of song that should be played. This procedure must return end with "RTS" opcode. "PLAYER" sets address of procedure that will be called in 1/50s intervals. This procedure should generate sound, that will be emulated via Pokey emulation, and (like in "INIT") must end with "RTS" opcode.
  2. C (cmc). This is special type used only with songs that are composed in quite popular Chaos Music Composer. In SAP with this type, must be also defined commands "PLAYER" and "MUSIC". "PLAYER" sets address of CMC player (that must be included). "MUSIC" sets address of music data for this player. Note! This type is probably temporary, and will be deleted in future release. You should use type "binary" instead.
  3. S (SoftSynth). Like type "C", this type is temporary, and is used only for special type of songs, that where composed using program SoftSynth.
  4. D (digi). In SAP file with this type, must be also defined commands "INIT" and "PLAYER". "PLAYER" (line in type "B") sets address of procedure that will be called in 1/50s intervals and (like in type "B") must end with "RTS" opcode. "INIT" this time is little diferent. "INIT" sets address of procedure that will be called (with number of song in register "A") to initialize program, but it cannot end with "RTS". It should start playing digitalizations in "never ending" loop. In SAP player are emulated two registers $D40B, and $D40A (ANTIC) that can help with playing digitalizations. In Atari, $D40B increases every two screen lines. Single write to $D40A holds CPU to the end of screen line. SAP emulates Atari in PAL with disabled screen. So we have 312 screen lines with 105 CPU cycles per each line, and with 9 cycles of memory refresh (105 cycles of CPU, and 9 cycles of memory refresh gives 114 cycles per line).
  5. R (registers) (will appear in future release) In this type, binary part is not an Atari Binary File! This part contains values that are directly written to Pokey registers ($D200-$D208) in 1/50s intervals.

Last (optional) command "FASTPLAY" can change (in type "B") interval time. As default, procedure "PLAYER" is called in 1/50s intervals. "FASTPLAY" sets number of screen lines for each interval. Default 1/50s sets interval to 312 lines. You can set eg. interval to 1/100s and that will be 156 lines.

Command lines can appear in any order. This is an example of text part:

For more examples You can look into any .SAP files that are already made, or ... just ask an author of SAP ;)

Hint: once You have crated text part of SAP file, You can link this with binary part using eg.command line (in MS-DOS) "copy":

copy /b text_part+binary_part Music.sap

Note that "/b" option is nessesary !!!