Schism:The File Format
From SDWiki
This is unfinished. I wanted to start getting it in WIKI form so others can see it.
Contents |
[edit] Overview and Goals
There are lots of module formats, and the decision to bring another one into this world cannot be taken lightly. On one hand, we need a way to introduce new player features, but on the other hand, whatever we produce, someone will have to play. As soon as someone saves a file in this new format, we cannot as easily change our minds here, and while we will inevitably need to change our minds, we must remember that every place we do will be a corner case that every loader will have to be aware of.
Fortunately, trackers have been around for more than a couple decades now, and while they've come a long way, some of the oldest formats remain completely usable. This means we can take a number of things completely for granted about what kinds of things need to be supported.
Finally, interchange was undervalued for a long time amongst trackers. It was essentially considered that only the tracker which produced the module could truly play it "right" and very little effort was made between players and trackers to remedy this. What Catspaw suggested isn't really as necessary in a world where Open and Free software, but his point underscores the fact that interoperability is something users want, so our format must be considerate of the fact many different programs are going to use it.
[edit] Layered Structure
The Schism module format is a layered structure to simplify conceptual understanding, and to make it easy to "discover" features of the file format interactively.
I recommend at the outermost level a ZIP format container with the simple restriction that only DEFLATE and STORE methods are allowed. Conforming implementations must never use other methods.
The song comment is also the zipfile comment, but no other module-specific elements are lifted to this level of abstraction.
All of the components of the module are implemented as file-entries. Only one file is required to be present in the container and it must be named "MODULE.INF".
[edit] MODULE.INF
The MODULE.INF file is line-oriented. The line-endings must be CR LF and the contents must be in the US-ASCII character set. The high-bit (8th bit) of each octet must be clear.
Each line consists of urls. These urls must presently be http:// but if another protocol becomes as ubiquitous, it may be considered.
The url must point to a plain-text document in US-ASCII character set, in English, and must be freely redistributable. It describes the behavior of any other file or files in the container module. It must provide enough information for an independent developer to be able to produce files such that the original producer (and intended player- especially if different) will accept. It is not permitted for these files (for example) to require some encryption process if the user cannot trivially replace the keys.
There must not be any file (besides MODULE.INF) in the module that isn't documented in at least one of the urls listed in MODULE.INF
Implementors should have a list of understood urls. If it comes across a module with a url that isn't understood it should warn the user that it might not be able to edit/play the module correctly.
One of the urls in MODULE.INF must refer to this document.
If someone comes across a random module in ten or twenty years, there should be enough information in the module in order to play it.
[edit] schismtracker.org
One of the urls will be placed at schismtracker.org someplace in the near future.
[edit] Samples/
Samples are given a name in the zipfile that begins with the byte-string "Samples/" and their filename will be of the form "Samples/NNNN-filename.ext" where "NNNN" refers to the sample number (in hex, uppercase), and "ext" refers to one of the following file formats:
- OGG for OGG/Vorbis
- FLAC
- WAV
Other formats are not permitted by this document. They could be permitted by a suplement listed in MODULE.INF
There will also be a "Samples/NN-filename.txt" which provdes descriptions, information about loops, and sample-effects like vibrato.
[edit] Instruments/
TODO
[edit] Order.lst
The order list can list patterns, one per line.
(Suggestion: More than one pattern per line could enable playing them together? This would be greatly useful for drumloops or repetitive bass tracks with different lead/melody. -delt)
[edit] Message.txt
The song message may have a file name as well. If this exists, it should contain the same thing as the zipfile message.
[edit] Patterns/
Schism Tracker has a plain-text format for representing patterns. It's the same format Modplug uses for copy/pasting patterns.
[edit] Crash Recovery
Implementors are encouraged to unzip the module someplace, and manipulate the files in it directly- perhaps using mmap(). If your tracker crashes, you can look in that folder and offer to reload the module they were working on.
