Created by John K. Morris
jmorris@evolutioninteractive.com
Version 2.0.1 – December 2, 2018
The A2R format is the raw flux images as recorded by the Applesauce hardware and software. The A2R has evolved a few times since I originally started work on Applesauce. As of release 1.0.3 of the Applesauce software, I have created a version 2.0 of the A2R file format. This document describes that version. If you need to convert earlier A2R files to the current version, it can be done with the Applesauce software.
What is the thinking behind the A2R format?
Why did I bother with creating the A2R format when everybody just wants to play with WOZ files? There are a few reasons for this decision. First off is that creating WOZ files is an insanely complex process. It isn’t even remotely like just capturing bits and stuffing them into a file. There is a ton of signal processing, analysis and validation that goes on in order to make everything work. This leaves a lot of room for mistakes to happen in the process. The second is that many floppy disks don’t have a lot of life left in them. Bits are rotting away and we may not have many more opportunities to capture this data. So, with these factors in mind, I created an intermediate file format. One that contains purely the lowest level information at the highest resolution that is possible to capture from a disk. No analysis or discarding of potentially useful information. The A2R file stores the data below the bit level. It records the amount of time that exists between flux transitions on the media surface with an accuracy of 125 nanoseconds (that is 125 billionths of a second). This gives us the ability to preserve and work with data that is an exact copy of a floppy disk.
If we have such a precise disk image format, then why bother with the WOZ format? The first reason is that an A2R is huge. On average, a 143 kilobyte floppy disk is represented by a 20 megabyte A2R file. The other difference is that an A2R file is what was read from a disk while a WOZ is what was originally written to the disk. This is where all the signal processing and such that I mentioned earlier comes into play. Due to electrical quirks of floppy drives and the laws of physics, what is read from a disk does not necessarily match what was written to the disk. If you want to delve deeper into that topic, I suggest that you dig into the WOZ Disk Image Reference.
The gist of all of this is that the A2R file is intended to be an archival backup of a disk. One that can be brought out and used for analysis or generation of WOZ files or anything else someone may come up with in the future. And it can be reused over and over again as the WOZ generation process matures, without potentially wearing out or causing further deterioration of the original floppy.
What has changed in the A2R specification for the 2.0.1 release?
This was a pretty minor update with some cleanup for 3.5 disks and Macintosh support.
STRM Chunk Changes
The Location value used for 3.5 disks has changed to have both sides of a track next to each other using the formula ((track << 1) + side), instead of all tracks for side 0 followed by all tracks for side 1.
META Chunk Changes
Added “mac” as a new standard value for the requires_machine metadata key.
A2R File Format Specification
An A2R file uses a chunk-based file binary format that provides future-proof expandability in a way that is safe for older software which may not recognize newer data chunks.
All data is stored little-endian.
A2R files begin with the following 8-byte header in order to identify the file type as well as detect any corruption that may have occurred.
| Byte | Value | Purpose |
|---|---|---|
| 0 | 41 32 52 32 | The ASCII string ‘A2R2’. 0x32523241 |
| 4 | FF | Make sure that high bits are valid (no 7-bit data transmission) |
| 5 | 0A 0D 0A | LF CR LF – File translators will often try to convert these. |
After the header comes a sequence of chunks which each contain information about the disk image. Using chunks allows for the A2R disk format to provide forward compatibility as chunks can be added to the specification and will just be safely ignored by applications that do not care (or know) about the information.
All chunks have the following structure:
| Offset | Size | Name | Usage |
|---|---|---|---|
| +0 | 4 bytes | Chunk ID | 4 ASCII characters that make up the ID of the chunk |
| +4 | uint32 | Chunk Size | The size of the chunk data in bytes. |
| +8 | … | Chunk Data | The chunk data. |
To process the file, you start at the first Chunk ID which will be located at byte 8 of the file, immediately following the header. You read the Chunk ID and the Chunk Size following it. If you want to process this chunk, then your file pointer will be at the start of the data. If you don’t care about this chunk, then skip the number of bytes as Chunk Size indicates and you will now be at the next Chunk ID.
while(data_stream.availableToRead() > 8) {
uint32_t chunk_id = data_stream.readU32();
uint32_t chunk_size = data_stream.readU32();
switch(chunk_id) {
case INFO_CHUNK_ID:
// read the INFO chunk
break;
case STRM_CHUNK_ID:
// read the STRM chunk
break;
case META_CHUNK_ID:
// read the META chunk
break;
default:
// no idea what this chunk is, so skip it
data_stream.skip(chunk_size);
}
}
INFO Chunk
The first chunk in an Applesauce file is always an ‘INFO’ chunk. This contains some fundamental information about the contained image. The data of the ‘INFO’ chunk begins at byte 16 of the file and version 1 is 36 bytes long.
| Offset | Type | Vers | Name | Usage |
|---|---|---|---|---|
| uint32 | ‘INFO’ Chunk ID | 0x4F464E49 | ||
| uint32 | Chunk Size | Version 1 is 36 bytes long. | ||
| +0 | uint8 | 1 | INFO Version | Version number of the INFO chunk. Current version is 1. |
| +1 | UTF-8 32 bytes |
1 | Creator | Name of software that created the A2R file. String in UTF-8. No BOM. Padded to 32 bytes using space character (0x20). ex: “Applesauce v1.0 ” |
| +33 | uint8 | 1 | Disk Type | 1 = 5.25, 2 = 3.5 |
| +34 | uint8 | 1 | Write Protected | 1 = Floppy is write protected |
| +35 | uint8 | 1 | Synchronized | 1 = Cross track sync was used during imaging |
The chunk is versioned to allow for adding additional info in the future. The “Vers” column in the table above indicates at which version the data field became available. When reading data from the chunk, make sure that value you are looking for actually exists within the version of the chunk you are reading.
STRM Chunk
The ‘STRM’ chunk contains all of the raw data streams as captured by the Applesauce hardware. To understand this information, you will need a bit of background as to the different types of data captures that Applesauce performs.
- A timing capture is the standard data capture that Applesauce uses. It starts capturing data when it sees the sync sensor trigger and grabs data for 250 milliseconds. This will grab about 450 degrees of rotation.
- A xtiming (extended timing) capture is basically the same as a timing one except that the capture is 450 milliseconds long (about 810 degrees of rotation). This is currently the primary data capture type used by Applesauce. This was previously only used when Applesauce felt that a regular timing capture was ambiguous when creating a proper loop of the track data.
- A bits capture was originally used to perform the same function as xtiming, but has been deprecated in Applesauce v1.0.3. Instead of capturing flux timing, it captures a bit stream that is 16384 bytes long (averaging about 900 degrees of rotation).
The STRM chunk contains all of the captures that took place during the imaging process. All of these captures are stored end-to-end as packed data. There is no padding or delimiters between the data. The STRM chunk begins like this:
| Offset | Type | Name | Usage |
|---|---|---|---|
| uint32 | ‘STRM’ Chunk ID | 0x4D525453 | |
| uint32 | Chunk Size | Length of the stream data. | |
| +0 | … | Stream Capture Data |
Each capture has the following format:
| Offset | Type | Name | Usage |
|---|---|---|---|
| +0 | uint8 | Location | Track where this capture happened. For 5.25 disks, this value is in halfphases or quarter tracks. For example track 0.00 is halfphase 0 and track 1.00 is halfphase 4. For 3.5 disks, this value indicates track number as well as side. The formula ((track << 1) + side) can be used (0 = Track 0 Side 0, 1 = Track 0 Side 1, 2 = Track 1 Side 0). |
| +1 | uint8 | Capture Type | 1 = timing, 2 = bits, 3 = xtiming |
| +2 | uint32 | Data Length | Length of Data in bytes. |
| +6 | uint32 | Estimated Loop Point | Duration until sync sensor was triggered at loop point. |
| +10 | … | Data |
Since Applesauce does multiple captures of each track, there will be multiple sets of capture data which use the same Location value. After the final capture, the STRM chunk is ended with a single 0xFF byte. If you are walking through the STRM chunk, encountering a Location of 0xFF is your signal that you are done.
For the timing and xtiming Capture Types, the Data is stored as a stream of unsigned bytes. Each byte represents a single flux transition and its value in the number of ticks since the previous flux transition. A single tick is 125 nanoseconds. Therefore the normal 4 microsecond spacing between sequential 1 bits is represented by approximately 32 ticks. This also puts 101 and 1001 bit sequences at approximately 64 and 96 ticks. You are probably thinking to yourself that when it comes to longer runs of no transitions, how is this unsigned byte going to handle representing the time? That is taken care of via the special value of 255. When you encounter a 255, you need to keep adding the values up until you reach a byte that has a non-255 value. You then add this value to all of your accumulated 255s to give you the tick count. For example 255, 255, 10 should be treated as 255 + 255 + 10 = 520 ticks.
For the bits Capture Type, the Data is a 16384 byte bitstream. The bitstream data is the series of bits recorded from the floppy drive and normalized to 4µs intervals. The bits are packed into bytes, but the bytes will not necessarily be representative of nibble values as timing bits are also represented within the bitstream. When processing the bitstream, the order of bits within each byte is high to low, meaning the high bit goes first and the low bit is last.
Estimated Loop Point contains the number of ticks from the start of the capture till the sync sensor is triggered. This is a hint that can be used to determine the track length.
META Chunk
The ‘META’ chunk contains metadata for the disk image. The metadata is stored as a tab-delimited UTF-8 list of keys and values. Columns are by separated by a tab character (‘\t’ 0x09). All rows end with a linefeed character (‘\n’ 0x0A).
| Offset | Type | Name | Usage |
|---|---|---|---|
| uint32 | ‘META’ Chunk ID | 0x4154454D | |
| uint32 | Chunk Size | Length of the metadata string in bytes. | |
| +0 | String | Metadata | Metadata string in UTF-8. No BOM. |
This is the list of standard metadata keys. Multiple values are pipe-separated.
| Key | Purpose | Example Value |
|---|---|---|
| title | Name/Title of the product. | Prince of Persia |
| subtitle | Subtitle of the product. | |
| publisher | Publisher of the software. | Brøderbund Software, Inc. |
| developer | Developer of the software. Pipe-delimited list if needed. | Jordan Mechner |
| copyright | Copyright date. Free form text allowed. | 1989 1987 Muse Software |
| version | Version number of the software. Free form text allowed. | 1.0 19870115P |
| language | Language (see table A) | English |
| requires_ram | RAM requirements (see table B) | 64K |
| requires_machine | Which computers does this run on? Pipe-delimited list. (see table C) | 2+|2e|2c|2gs |
| notes | Additional notes. | |
| side | Physical disk side formatted as: “Disk #, Side [A|B]” |
Disk 1, Side A |
| side_name | Name of the disk side. If the disk side is named on the label like Player, Town, Dungeon, etc then it goes here. | Front |
| contributor | Name of the person who imaged the disk. | Mr. Pirate |
| image_date | ISO8601 date of the imaging. | 2018-01-07T05:00:02.511Z |
If a standard key has no value, then the value will be an empty string. Key names are case-sensitive. Values cannot contain pipe, linefeed or tab characters. It would also be a good idea to keep all values as ASCII-friendly as possible to ensure compatibility with the widest range of devices that will consume these files. No duplicate keys are allowed and key order does not matter. Standard keys that have values laid out in the tables below cannot have values other that those shown below. Implementors are free to add additional keys to the metadata as long as they follow the same rules laid out here.
TABLE A – LANGUAGES
| English | Spanish | French | German |
| Chinese | Japanese | Italian | Dutch |
| Portuguese | Danish | Finnish | Norwegian |
| Swedish | Russian | Polish | Turkish |
| Arabic | Thai | Czech | Hungarian |
| Catalan | Croatian | Greek | Hebrew |
| Romanian | Slovak | Ukrainian | Indonesian |
| Malay | Vietnamese | Other |
TABLE B – REQUIRES_RAM
| 16K | 24K | 32K | 48K |
| 64K | 128K | 256K | 512K |
| 768K | 1M | 1.25M | 1.5M+ |
| Unknown |
TABLE C – REQUIRES_MACHINE
| 2 | 2+ | 2e | 2c |
| 2e+ | 2gs | 2c+ | 3 |
| 3+ | mac |