Sustainability of Digital Formats: Planning for Library of Congress Collections

WOZ is a chunk-based binary disk image format designed for use with Applesauce, the Macintosh floppy drive controller, with the goal "to be able to contain every possible Apple II disk structure and layout." WOZ files are a simple disk image format that accurately stores data as it is encoded in an Apple II 5.25 or 3.5 inch floppy disk. According to FileInfo.com, "WOZ files are typically used for Apple II games, utilities, and educational programs" and "WOZ files can be opened by emulators, such as MAME and OpenEmulator." The .woz Format - Accurate Preservation of Apple II Floppy Disks blog describes "The .woz format is one method to turn the raw data into something an emulator can use. .woz files represent the nibblized bit stream of a floppy disk, in other words the .woz file reflects what was written to the disk."

In the specification (version 1 but this language is consistent in all versions), creator John K. Morris lists several advantages of the WOZ format: "The big benefit is being able to successfully run copy protected software if you follow the emulation guidelines presented in this document. The second benefit is that the WOZ format is actually much simpler to implement than many of the other disk image formats. WOZ files also contain metadata about the disk image - such as disk name, product name, publisher, system requirements and language - that you can use to display additional information in your emulator."  He also states the rationale for developing WOZ: "It basically comes down to the simple fact that none of the currently existing formats accurately represent the way data is encoded on an Apple II floppy disk. There is a place for a format that is an accurate representation of a bitstream that is also the exact length of a track so that it can be looped correctly. And since we are creating a format, it is also a great time to ensure that we organize the data in the image file in a way that allows for easy unpacking with as little memory and processing overhead as possible – this provides more performant usage in hardware and software emulators."

WOZ shares a similar file header structure with MOOF (also developed by John K. Morris). In both, the header is 12 bytes with the first 8 bytes containing the file signature/magic number (WOZ1 or WOZ2 depending on the version). This is followed with an intentionally blank space to ensure there is no data corruption and that the magic numbers values are valid. The last 4 bytes of the header contain a CRC32 checksum of all remaining data in the file.

The header is followed by the INFO chunk, as it is in all Applesauce files. The INFO chunk contains "fundamental information about the contained image. The data of the ‘INFO’ chunk begins at byte 20 of the file and is 60 bytes long (pad "chunk with zeros to full length)." INFO chunk data includes Disk Type (5.25 or 3.5), if the floppy disk is write protected, and the "creator" field documents the name of software that created the WOZ file among other details.

The key component of the WOZ file is the TMAP Chunk which follows the INFO chunk. The TMAP chunk contains a map for all the tracks as well as associated data which are contained in the TRKS chunk. "Each map entry contains an index number for the track data contained within the ‘TRKS’ chunk. If the map entry is 0, then the correct track data to be using is the first entry in the ‘TRKS’ chunk." This unique mapping facilitates cross track synchronization which circumvents copy protection checks that were usually limited to physical disks. Physical disks used a sync sensor which "involved a light source on one side of the disk with a sensor on the other. This sensor would allow the drive to know when it made a full revolution, as the disk media itself had a hole that would let the light pass though as it passed the sensor. When it came to businesses designing copy protection schemes, this was something that they could use to their advantage. The professional disk copiers could easily write out all tracks synchronized with each other, something that your average Apple II floppy drive couldn’t do. Then, the software would read a known sector on a specific track and, when it jumped to a neighboring track, it could make sure that the first sector it encountered there was the one it expected. Later protection schemes even made track widths which were almost 2 standard tracks wide and were accurate to within 1 bit." The mapping protocol in the TMAP circumvented this because it provides the data about the structure and location about the tracks.

The optional ‘META’ chunk contains metadata for the disk image including name/title of the product, publisher, version, copyright date, language and more. There are also options for documenting the disk imaging process with contributor (Name of the person who imaged the disk) and image_date (ISO8601 date of the imaging).

Version 2.0 of the specification adds a new WRIT Chunk Addition. "A new WRIT chunk has been added to the WOZ specification in order to provide detailed instructions for programs wanting to write WOZ files back to a real floppy disk. Inclusion of this chunk in a WOZ file is optional."

Version 2.1 of the specification adds a new "FLUX" chunk to support support flux streams or flux transition timings with an accuracy of 125 nanoseconds.

For many examples of WOZ, see Applesauce's test disk images (downloadable ZIP file), Internet Archives' Software Library: Apple (WOZ Format) and A Woz A Day: A collection of .WOZ disk images for the 8-bit Apple II and 16-bit Apple IIGS.

There are two main versions of the WOZ specification (versions 1 and 2) and several documented beta and minor releases:

• Version 0.9 - January 14, 2018. See https://web.archive.org/web/20180115110331/http://evolutioninteractive.com/applesauce/woz_reference.pdf (link via Internet Archive)
• Version 0.91 - January 15, 2018. See https://wiki.reactivemicro.com/images/2/2e/2018-01-15_-_WOZ_Disk_Image_Reference_v0.91.pdf.
• Version 1.0 - January 17, 2018. See https://ia802207.us.archive.org/15/items/Woz_Reference_Specification_2018_01/Woz_Reference_Specification_2018_01.pdf (link via Internet Archive)
• Version 1.0.1 - May 20, 2018. See https://applesaucefdc.com/woz/reference1/
• Version 2.0 - December 16, 2018. See https://web.archive.org/web/20200924005747/https://applesaucefdc.com/woz/reference2/ (link via Internet Archive)
• Version 2.1 - June 16, 2021. See https://applesaucefdc.com/woz/reference2/.

Comments welcome especially about additional version documentation.

Created and supported by Applesauce.

A number of sample libraries exist as well as many hardware and software emulators.

According to the published specifications, the format utilizes a chunk-based, binary format designed for future-proof expandability. Technical and descriptive metadata are stored in the INFO chunk. The chunk is versioned to allow for adding additional metadata in the future.

Accessibility Support

Support for accessibility features for is unknown and undocumented. However, the structured and consistent chunk based format including some provenance and descriptive embedded data in the META chunk could potentially be helpful.

There are two main versions of the WOZ specification and several documented minor releases. See Documentation and Format Specifications for links.

• Version 0.9 - January 14, 2018.
• Version 0.91 - January 15, 2018.
• Version 1.0 - January 17, 2018.
• Version 1.0.1 - May 20, 2018.
• Version 2.0 - December 16, 2018.
• Version 2.1 - June 16, 2021.

Specification version 2 includes a high level change log from version 1 such as changes in the file identifier (from WOZ1 to WOZ2), new and updated INFO chunk fields related to timing and identifying boot sectors, and updates to the TMAP and TRKS chunks. One interesting thing to note is that version .9 and version .91 state the data is big endian but subsequent versions starting at version 1 state the data is little endian. Comments welcome.