first version of format psuedo-spec

format.md

@@ -0,0 +1,80 @@
+# Varvara tracker format
+
+This is a very early, informal draft of a varvara tracker format, intended to be integrated into demos and games to provide a soundtrack. It is inspired by the .xm format used for PC demos.
+
+## General Layout
+
+A file is overall structured into these parts:
+
+```
+<file header>
+<song table>
+<pattern 0>
+<pattern 1>
+... (for all pattern data)
+
+<instrument 1>
+<instrument 2>
+... (for all instrument data)
+``` 
+
+## File Header
+
+The header is 2 bytes. The high nibble of the first byte is used for flags (detailed below). The low nibble is used for the default speed, measured in how many screen vector cycles it takes to advance 1 line in a pattern. The second byte stores the number of patterns in the file.
+
+```
+first header byte
+| Field | Loop   | [padding] | Speed |
+| Bits  | 1      | 3         | 4     |
+```
+
+The loop flag is 0 if the song should not loop and 1 if it should. The other flags are currently unused.
+
+## Song Table
+
+The Song Table is a table that contains what order patterns will play in in the module. It has the following format:
+
+```
+size [short] - the size, in bytes, of the song table
+<song row>
+<song row>
+... (until the end of the song)
+```
+
+### Song Rows
+
+a song row is 4 bytes. Each byte is a pattern number, with the first byte being the pattern on channel 0, second being channel 1 etc. a byte ff means no pattern.
+
+## Patterns
+
+Patterns contain a short containing the length of the pattern, and 0x10 lines of note data. Patterns are ordered sequentially in the file and there can be up to 255 patterns in a file.
+
+### Pattern lines
+
+A pattern line consists of either 1 or 3 bytes, depending on if the most significant bit of the first byte is high. The 7 remaining bits of the first byte are the note value, with the MSB being set if the line contains an effect and not otherwise. If the line contains an effect, the next two bytes contain an effect and a parameter for that effect.
+
+### Effects
+(what an effect should be drawn as in an editor is in parenthesis)
+
+More soon probably
+
+* 0x01 (V) - set volume to argument
+* 0x02 (I) - set instrument to argument
+* 0x03 (A) - set attack to argument (1-0f) 
+* 0x04 (D) - set decay to argument (1-0f)
+* 0x05 (S) - set sustain to argument (1-0f) 
+* 0x06 (R) - set release to argument (1-0f) 
+* 0x07 (T) - set song speed to argument (1-0f) 
+
+## Instruments
+
+Instruments contain a sample and some default parameters for that sample. Everything is in the same format expected by the audio device.
+
+```
+Sample Length [Short]
+Volume [Byte]
+ADSR [Short]
+Sample
+```
+
+