Changeset 62 for trunk/asma/Docs/Sap.txt
- Timestamp:
- Feb 24, 2012, 10:39:34 AM (13 years ago)
- File:
-
- 1 edited
-
trunk/asma/Docs/Sap.txt (modified) (2 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/asma/Docs/Sap.txt
r58 r62 1 SAP file divides into two parts. First part (in text format) describes 2 player/music type and contains credits for the song. Second part (in binary 3 format) contains player and music data formed into Atari Binary File format. 1 SAP File Format 2 Piotr Fusik, Zdenek Eisenhammer 4 3 4 This is the specification of the SAP (Slight Atari Player) file format. SAP files contain chip music of the 8-bit Atari computers. 5 5 6 First part - text info 7 ~~~~~~~~~~~~~~~~~~~~~~ 8 For identification of the format, it always starts with "SAP" string. 9 After that the credits follow. However, this is not fixed order, just a 10 recommendation. Each line should end with EOL string (0D 0A). 6 History 7 ------- 8 The SAP format was created in the 1990s by Adam Bienias and was intended to be a single format for playback of any 8-bit Atari music on a PC. Adam Bienias has also created the first player for Windows and later published its source code so that other players were created. 11 9 12 Credits tags: 13 AUTHOR "" - Name of composer. For ASMA purposes, the name should consist of 14 real name and nickname (scene handle) in parentheses. No scene 15 group allowed. If song was composed by more authors, use "&". 16 Examples: 17 AUTHOR "Dariusz Duma (Dhor)" 18 AUTHOR "Lukasz Sychowicz (X-Ray) & Piotr Swierszcz (Samurai)" 19 NAME "" - Song title. No restrictions, except for it shouldn't contain 20 quotation marks. Use apostrophes instead. 21 Example: 22 NAME "Jocky Wilson's Darts Challenge" 23 DATE "" - Copyright year or year of creation. If exact date is known, it can 24 also be included in DD/MM/YYYY format. 25 Examples: 26 DATE "1986" 27 DATE "1993-1994" 28 DATE "28/08/1997" 29 DATE "12/2001" 10 At the time of writing there are four independent players of the SAP format: 11 Slight Atari Player (SAP) by Adam Bienias 12 Another Slight Atari Player (ASAP) by Piotr Fusik 13 Game_Music_Emu (GME) by Shay Green 14 sapemu by Adrian Matoga 30 15 31 After that the player info follows: 32 TYPE - player type (see below) 33 PLAYER - address of player part which will be executed in 1/50 sec 34 intervals (or as defined with FASTPLAY) 35 MUSIC - address with music data (for C type) 36 INIT - address of player part which will init player (for all types 37 except C) 38 SONGS - number of songs. If SONGS tag not defined, the default value is 39 1. 40 DEFSONG - first song which will be played when .sap is loaded (i.e. the 41 main game theme). This value is counted from zero (if there are 5 42 songs in the file and the last is the default, the value will be 43 DEFSONG 4). The default is 0 if DEFSONG not defined. 44 FASTPLAY - number of lines between each call of playing routine (312 by 45 default, which is one screen - 1/50 of sec.). For example for 46 double-speed song put here the value 156 (312/2). 99% of songs 47 are single-speed which means that you don't have to define the 48 FASTPLAY variable for them. Works for player TYPE "B". 49 Another values recommended: 104 (triple speed), 78 (quadruple 50 speed) 51 STEREO - song uses dual POKEY configuration. 16 There are many players for different platforms based on either SAP, ASAP or GME. sapemu runs on an Atari XL/XE computer with 128 KB RAM. 52 17 53 commands PLAYER, MUSIC, INIT contain addresses in hexadecimal format. Both 54 lower- and uppercase characters are allowed for the number. 18 Concept 19 ------- 20 The SAP format contains the original data and code used to playback the Atari music. SAP players actually run the program contained in the SAP file on an emulated or real (sapemu) 6502 processor. The program controls the POKEY chip, which generates the sound. 21 The same method is used on other platforms, for example the SID format for the C64 music. 22 Important advantages of SAP over, lets say, MP3 are that SAP files are very small (about 5 KB on average) and play more accurately as new players improve their emulation. The downside is that SAP files are generally hard to create. Creating SAP files from Atari software is called ripping and requires some knowledge of the 6502 assembly language. On the other hand, Atari music in popular formats such as CMC or RMT can be easily converted to SAP (and back) using ASAP. 23 One SAP file may contain multiple independent tunes - these are called "subsongs". For example, a game containing many songs may be ripped into one SAP file. Over 90% SAP files contain just one song. Unfortunately many audio players do not support the concept of multiple subsongs per file. 55 24 56 PLAYER A000 57 MUSIC 1234 58 INIT f42e 25 File Naming Conventions 26 ----------------------- 27 The rules introduced in this chapter are not obligatory, however, they are used in the Atari SAP Music Archive. 28 The filenames must not be longer than 26 characters (plus ".sap" extension). 29 For compatibility reasons only uppercase and lowercase characters ('A..Z', 'a..z'), numbers ('0..9') and underscore ('_') can be used in the filenames. 59 30 60 commands SONGS, DEFSONG contain decimal numbers: 31 File Contents 32 ------------- 33 SAP file always consists of two parts: plain-text header, followed by binary data. It is possible to create a SAP file by concatenating a text file with a binary file, for example: 34 On DOS/Windows: 35 copy /b music.txt+music.bin music.sap 61 36 62 SONGS 10 63 DEFSONG 9 37 On Unix/Linux: 38 cat music.txt music.bin >music.sap 64 39 65 command TYPE contains single character which describes player type. The 66 following player types are supported: 67 68 TYPE C - player from CMC (Chaos Music Composer). In this case, also these 69 commands must appear: PLAYER, MUSIC. Additionaly you can define 70 SONGS and DEFSONG. Player will be initialized as follows: 71 72 lda #$70 73 ldx #<MUSIC 74 ldy #>MUSIC 75 jsr PLAYER+3 76 lda #$00 77 ldx #DEFSONG 78 jsr PLAYER+3 79 80 in 1/50 intervals will be executed: 81 82 jsr PLAYER+6 83 84 This is just internal structure already contained in SAP player, you 85 don't have to add this code to the CMC player. 86 87 TYPE B - any player. In this case, also these commands must appear: PLAYER, 88 INIT. Additionaly you can define SONGS and DEFSONG. Player will be 89 initialized as follows: 90 91 lda #DEFSONG 92 jsr INIT 93 94 in 1/50 intervals will be executed: 95 96 jsr PLAYER 97 98 TYPE S - SoftSynth. Like type "C", this type is temporary, and is used only 99 for special type of songs, that were composed using program 100 SoftSynth. 101 TYPE D - Digital. In SAP file with this type, there must be also defined 102 commands "INIT" and "PLAYER". "PLAYER" (like in type B) sets 103 address of procedure that will be called in 1/50s intervals and 104 (like in type B) must end with RTS opcode. INIT this time is a bit 105 different. It sets address of procedure that will be called (with 106 number of song in register A) to initialize program, but it can't 107 end with RTS. It should start playing digis in endless loop. In SAP 108 player two ANTIC registers $D40A and $D40B are emulated. They help 109 playing samples. D40B register increases its contents each two 110 screen lines. D40A holds CPU till the end of actually drawn line. 111 SAP emulates Atari in PAL with disabled screen. It means that we 112 have 312 lines per screen, each taking 105 CPU cycles and 9 cycles 113 of memory refresh (114 cycles per line). 114 115 One more type is recognized by SAP player - TYPE M. Right now it's exactly 116 the same as TYPE B but this differentiation is for future SAP releases. 117 118 Planned features: 119 TYPE R - Registers. In this type, binary part is not an Atari binary file. 120 This part contains values that will be directly written to Pokey 121 registers ($D200-$D208) in 1/50s intervals (or intervals defined 122 with FASTPLAY tag). 123 TIME mm:ss.ttt [LOOP]- Song duration in minutes, seconds and thousandths. In 124 files with subsongs the TIME tag may occur more times 125 (eg. 3 times if there are 3 subsongs total). The 126 optional LOOP string can be added if the song loops in 127 an endless loop. 128 40 Part One - Text Header 41 ---------------------- 42 This part consists of tags, one tag per line. Lines must be terminated by a CR/LF (0x0d, 0x0a) pair (required by ASAP, other SAP players may be more forgiving). A line consists of an uppercase tag name and an optional argument which may be a string, a decimal integer, a hexadecimal integer or a single letter. The argument should be separated from tag name with a single space. Extra whitespace is not allowed. 129 43 Example of the header: 130 44 SAP … … 140 54 TIME 00:15.40 LOOP 141 55 142 Second part - binary data 143 ~~~~~~~~~~~~~~~~~~~~~~~~~ 144 This part contains player and music data represented in Atari binary file 145 format. This format has two bytes header FF,FF. The following two bytes tell 146 the loader where to load data, and next two bytes tell where the data end. 147 Init data block ($02E2,$02E3) is not supported. 56 The first line must consist of the word "SAP" immediately followed by CR/LF, for format identification. 57 It is recommended, but not required, that tags are specified in the order described here. Note that format identification in GStreamer requires the AUTHOR tag be placed right after the "SAP" line. 58 The arguments to AUTHOR, NAME and DATE must be wrapped in doublequotes. Allowed characters are those identical in ASCII and ATASCII (ATari ASCII), which are: characters with ASCII codes from space to underscore plus all lowercase letters plus the pipe (|). There are no backquote, tilde nor curly brackets in ATASCII. It is recommended to avoid doublequotes inside the arguments, as not all SAP players handle them. The arguments should be limited to 120 characters (plus the outer quotes). 59 It is strongly recommended that all SAP files contain the AUTHOR, NAME and DATE tags. Use "<?>" for unknown values. 148 60 149 A little example: 61 AUTHOR 62 Name of the composer. The name should consist of a real name and optionally nickname (scene handle, no scene group) in parentheses. If song has been composed by many authors, separate them with " & ". Examples: 150 63 151 FF FF 00 20 04 20 01 42 A3 04 D5 152 \___/ \_________/ \____________/ 153 A B C 64 AUTHOR "Dariusz Duma (Dhor)" 65 AUTHOR "Lukasz Sychowicz (X-Ray) & Piotr Swierszcz (Samurai)" 66 AUTHOR "<?> (Trzcinowy Zakapior)" 67 AUTHOR "Bill Williams <?>" 154 68 155 A - Binary file header identification (always FF FF) 156 B - Load addres (StartAddr, EndAddr in LO,HI order - $2000 to $2004) 157 C - Data (that will be loaded from StartAddr) 69 The last two examples are respecively: known nickname with unknown real name and an uncertain author. 158 70 159 This example will load values 01,42,A3,04,D5 into memory from $2000 to $2004. 71 NAME 72 Song title. Examples: 160 73 74 NAME "Jocky Wilson's Darts Challenge" 75 NAME "<?>" 161 76 162 How to create .SAP file 163 ~~~~~~~~~~~~~~~~~~~~~~~ 164 First of all we need to rip music from a game or a demo and save it in Atari 165 binary file. Next we can create a text file with description (as described 166 above), then we can make .sap file by linking these two files. We can do that 167 using DOS command "copy", e.g.: 77 DATE 78 Copyright year or year of creation. If exact date is known, it can be included in the DD/MM/YYYY format. Examples: 168 79 169 copy /b music.txt+music.bin music.sap 80 DATE "1986" 81 DATE "1993-1994" 82 DATE "28/08/1997" 83 DATE "12/2001" 170 84 171 The file is made now! 172 If you didn't find that song in ASMA, feel free to send it to pg@dspaudio.com 173 with all needed information (see ASMA.TXT for details). The song should be 174 then included in the nearest ASMA update. 85 SONG 86 Number of subsongs in the file. If there is just one song in the file, it is recommended to omit this tag. ASAP currently limits the number of songs to 32. The biggest known number of songs in a SAP file is 20. 87 88 DEFSONG 89 Zero-based index of the song that should be played when the file is opened. Defaults to zero. 90 91 STEREO 92 Specifies that the file uses dual POKEY configuration. Takes no argument. 93 94 NTSC 95 Specifies that the file should be played on an NTSC machine instead of the default PAL. Takes no argument. This tag is only supported on ASAP 2.1.1 and above. 96 97 TYPE 98 Player type. The argument should be one uppercase letter: B, C, D or S. See below for an explanation. 99 100 FASTPLAY 101 Number of scanlines between calls of the player routine. A scanline is defined to be 114 clock cycles. FASTPLAY defaults to one frame: 312 scanlines for PAL (about 50 Hz), 262 for NTSC (about 60 Hz). Most songs dont include this tag. Common values are 156 (twice per frame), 104 (three times per frame) and 78 (four times per frame). ASAP 3.0.0 and above supports FASTPLAY up to 32767. Other SAP players may limit the value to 312. 102 103 INIT 104 Hexadecimal address of a 6502 routine that initializes the player. Required for player types B, D and S. Invalid for type C. The address should be specified as four uppercase hexadecimal digits, although players usually forgive lowercase and less digits. 105 106 MUSIC 107 Hexadecimal address of the music data. Required for type C. Invalid for other types. 108 109 PLAYER 110 Hexadecimal address of the player routine. 111 112 COVOX 113 Specifies that the file uses the COVOX hardware expansion at the specified hexadecimal address. COVOX offers better quality of digitalized sounds than the POKEY, in stereo. Currently only ASAP supports this and the only possible address is D600. 114 115 TIME 116 Song duration in minutes, seconds and milliseconds. In files with subsongs the TIME tag may occur many times (for example 3 times if there are 3 subsongs). The optional LOOP modifier specifies that the song starts looping endlessly at the specified moment. The exact format of the argument is: 117 118 - one or two digits specifying minutes 119 - colon 120 - two digits specifying seconds 121 - optionally: decimal point (dot) followed by one to three digits (fraction of a second) 122 - optionally: one space followed by four uppercase letters "LOOP" 123 124 Part Two - Binary Data 125 ---------------------- 126 This part contains the player routine and music data in the format of Atari executables. This format has a two-byte header 0xFF, 0xFF. The following two bytes are the starting memory address (little endian), the next two bytes are the ending address. Then data bytes follow. Usually there are multiple blocks (the 0xFF/0xFF header is only required for the first block). 127 The difference from Atari executables is that INIT (0x2e2) and RUN (0x2e0) blocks are not supported. 128 129 Example: 130 131 FF FF - executable header (always 0xFF, 0xFF) 132 00 06 - start address of the first block (0x0600) 133 01 06 - end address of the first block (0x0601) 134 AB CD - first block data - loaded to 0x0600-0x0601 135 25 20 - start address of the second block (0x2025) 136 27 20 - end address of the second block (0x2027) 137 01 42 A3 - second block data - loaded to 0x2025-0x2027 138 139 Some players allow files that end in the middle of start/end address or block data, but this practice is strongly discouraged. 140 141 Execution Model 142 --------------- 143 The program from the SAP file is run inside an emulated machine that resembles a limited Atari computer with the 6502 processor, POKEY chip (at least the audio part) and 64 KB RAM. Some players include emulation of parts of the ANTIC and GTIA chips, as well as the COVOX expansion. Since SAP files may be played on a real Atari, they should be prepared for the possibility that all the original hardware is present (for example PIA doing the bankswitching). 144 145 Memory map: 146 0000-CFFF - RAM. 147 D000-D0FF - GTIA chip mirrored 8 times. ASAP maps just the PAL register at D014 for NTSC/PAL detection and the CONSOL register at D01F for 1-bit sounds, the rest is RAM. 148 D100-D1FF - reserved for parallel devices connected to the Atari, do not use. 149 D200-D2FF - POKEY chip mirrored 16 times or two POKEY chips (stereo) mirrored 8 times. At least the AUDF1-4, AUDC1-4 and AUDCTL registers must be implemented in a SAP player. Emulation of timer interrupts via IRQEN and IRQST is strongly recommended. SAP by Adam Bienias emulates only timer 1 interrupts. 150 D300-D3FF - reserved for the PIA chip, do not use. 151 D400-D4FF - ANTIC chip mirrored 16 times. SAP files may rely on WSYNC (D40A) and VCOUNT (D40B) registers. ASAP also implements NMIST/NMIRES (D40F), but not NMIEN (D40E). The playback routine should be driven by the PLAYER/FASTPLAY mechanism instead of directly programming ANTIC interrupts. 152 D500-D5FF - reserved for cartridge, do not use. 153 D600-D6FF - COVOX chip if enabled via the COVOX tag (ASAP only). The COVOX consists of four unsigned 8-bit DACs: 0 and 3 for the left channel, 1 and 2 for the right channel. 154 D700-D7FF - reserved for expansions, do not use. 155 D800-FFFF - RAM. FFFE/FFFF is 6502s interrupt vector for POKEY timer interrupts. 156 157 Timing: The main clock is 1773447 Hz (PAL) or 1789772.5 Hz (NTSC). There are 114 cycles per scanline, including 9 cycles memory refresh not available for the 6502 - same as in the Atari with ANTIC DMA disabled completely. WSYNC and VCOUNT registers may be used for delays. Note that some SAP players reset VCOUNT at the FASTPLAY rate instead of every frame. 158 159 Player Types 160 ------------ 161 The value of the TYPE tag determines how the player routine gets called by the SAP player: 162 163 TYPE B 164 The player is initialized by loading the zero-based subsong number into the accumulator and calling the routine specified in the INIT tag. The routine must return with an RTS. Then, every FASTPLAY scanlines (312 being the default) the PLAYER routine is called. It must return with an RTS as well. 165 166 TYPE C 167 This type is for convenience of handling CMC (Chaos Music Composer) music. The player is initialized using the values of MUSIC, PLAYER and DEFSONG as follows: 168 169 lda #$70 170 ldx #<MUSIC 171 ldy #>MUSIC 172 jsr PLAYER+3 173 lda #$00 174 ldx #DEFSONG 175 jsr PLAYER+3 176 177 Then, in FASTPLAY intervals, PLAYER+6 is called. When switching subsongs, the above procedure is repeated with the subsong number instead of DEFSONG. 178 179 TYPE D 180 This is similar to TYPE B, but used for digitalized music. The difference is that the INIT routine must not return. It should play the digitalized music. It can use WSYNC and VCOUNT registers and/or POKEY timer interrupts for timing. The POKEY interrupts can be programmed via IRQEN/IRQST/AUDF1-4/AUDCTL registers, the FFFE/FFFF interrupt vector and the I 6502 flag. All 6502 registers (including flags) are saved when calling the PLAYER routine and restored when it returns to the running INIT routine. In ASAP 2.1.0 and above the PLAYER tag is optional for TYPE D. 181 182 TYPE S 183 This is a convenience type for SoftSynth music. The PLAYER tag is not used here, yet some SAP players require it. Instead of the PLAYER routine, at FASTPLAY intervals the memory location 0x45 is decreased and if reaches zero, the memory location 0xb07b is increased. The default FASTPLAY for this type is 78. 184 185 TYPE R 186 The data part is a raw dump of the POKEY registers (D200-D208) in FASTPLAY intervals, instead of an Atari executable. No mainstream SAP player supports this type at the time of writing. 187 188 Game_Music_Emu supports only types B and C.
Note: See TracChangeset
for help on using the changeset viewer.
