.sav structure

This is the structure of the .sav file, produced by emulators and backup devices for storing the LSDJ song data.

For some examples how to parse this, check https://github.com/alexras/lsdj-sav-utils and http://code.google.com/p/lsdj2xml/ as well as https://github.com/stijnfrishert/liblsdj/

Map

This map is valid for v6.7.0:

Bank 0:
4080 0000-0FEF: phrases-> notes
  64 0FF0-102F: bookmarks
  96 1030-108F: empty
 512 1090-128F: grooves
1024 1290-168F: song-> chainno (listed PU1,PU2,WAV,NOI for $00 .. $ff in order)
 512 1690-188F: tables-> envelope
1344 1890-1DCF: instrument->speech->words ($20*42)
 168 1DD0-1E77: instr->speech->wordnames
   2 1E78-1E79: mem initialized flag (set to “rb” on init)
 320 1E7A-1FB9: instr->names
  70 1FBA-1FFF: empty

Bank 1:
  32 2000-201F: empty 
  32 2020-203F: table allocation table (byte per table, 1 if alloced, 0 else)
  64 2040-207F: instr alloc table (byte per instrument, 1 if alloced, 0 else)
2048 2080-287F: chains-> phraseno
2048 2880-307F: chains-> transposes
1024 3080-347F: instr->param
 512 3480-367F: tables-> transpose
 512 3680-387F: tables-> fx
 512 3880-3A7F: tables-> fx val
 512 3A80-3C7F: tables-> fx 2
 512 3C80-3E7F: tables-> fx 2 val
   2 3E80-3E81: mem initialized flag (set to “rb” on init)
  32 3E82-3EA1: phrase allocation table (bit per phrase, 1 if alloced, 0 else)
  16 3EA2-3EB1: chain allocation table (bit per chain, 1 if alloced, 0 else)
 256 3EB2-3FB1: softsynth params (16 parameter blocks of 16 bytes each)
   1 3FB2-3FB2: clock, hours
   1 3FB3-3FB3: clock, minutes
   1 3FB4-3FB4: tempo
   1 3FB5-3FB5: tune setting
   1 3FB6-3FB6: total clock, days
   1 3FB7-3FB7: total clock, hours
   1 3FB8-3FB8: total clock, minutes
   1 3FB9-3FB9: total clock, checksum (days+hours+minutes)
   1 3FBA-3FBA: key delay
   1 3FBB-3FBB: key repeat
   1 3FBC-3FBC: font
   1 3FBD-3FBD: sync setting
   1 3FBE-3FBE: colorset
   1 3FBF-3FBF: empty
   1 3FC0-3FC0: clone (0=deep, 1=slim)
   1 3FC1-3FC1: file changed?
   1 3FC2-3FC2: power save
   1 3FC3-3FC3: prelisten
   2 3FC4-3FC5: wave synth overwrite locks
  58 3FC6-3FFF: empty

Bank 2:
4080 4000-4FEF: phrases->fx
4080 4FF0-5FDF: phrases->fx val
  32 5FE0-5FFF: empty

Bank 3:
4096 6000-6FFF: 256 wave frames (each frame has 32 4-bit samples)
4080 7000-7FEF: phrases->instr
   2 7FF0-7FF1: mem initialized flag (set to “rb” on init)
  13 7FF2-7FFE: empty
   1 7FFF-7FFF: version byte

Instrument Structure

Default Instrument

0, $a8, 0, 0, $ff, 0, 0, 3, 0, 0, $d0, 0, 0, $f3, 0, 0

Pulse Instrument

• Byte 0: 0
• Byte 1: Envelope
• Byte 2: Phase transpose
• Byte 3: Sound length (bit 6-0). If bit 6 is unset, sound length is UNLIM, otherwise length is bitwise not of bits 5-0
• Byte 4: Sweep
• Byte 5:
  • P step (bit 7) (0=normal, 1=step)
  • drummode (bit 6)
  • transpose off (bit 5)
  • PLV speed (bit 4) (0=hi-freq, 1=tick)
  • automate (bit 3)
  • vibrato type (bit 2-1) (0=sin, 1=saw, 2=sqr)
  • vibrato direction (bit 0) (0=down, 1=up)
• Byte 6: Table (bit 5-0: bit 5 = table on/off)
• Byte 7: Wave (bits 7-6); Phase finetune (bit 5-2); Pan (bit 1-0)

Wave Instrument

• Byte 0: 1
• Byte 1: Volume (what will be written to Game Boy register $FF1C)
• Byte 2: Softsynth parameters (bit 7-4, chooses one of the 16 softsynth parameter blocks); Repeat (3-0)
• Byte 3: -
• Byte 4: -
• Byte 5:
  • P step (bit 7) (0=normal, 1=step)
  • drummode (bit 6)
  • transpose off (bit 5)
  • PLV speed (bit 4) (0=hi-freq, 1=tick)
  • automate (bit 3)
  • vibrato type (bit 2-1) (0=sin, 1=saw, 2=sqr)
  • vibrato direction (bit 0) (0=down, 1=up)
• Byte 6: Table (bit 5-0: bit 5 = table on/off)
• Byte 7: Pan (bit 1-0)
• Byte 8: -
• Byte 9: Play type (bits 1-0; 0=once, 1=loop, 2=pingpong, 3=manual)
• Byte 10: Length (bits 3-0)
• Byte 11:  Speed

Kit Instrument

• Byte 0: 2
• Byte 1: Volume
• Byte 2: Keep attack 1 (bit 7); Half-speed (bit 6); Kit (bit 5-0)
• Byte 3: Length 1 (0 = auto)
• Byte 4: -
• Byte 5:
  • P step (bit 7) (0=normal, 1=step)
  • loop 1,2 (bit 6-5)
  • PLV speed (bit 4) (0=hi-freq, 1=tick)
  • automate (bit 3)
  • vibrato type (bit 2-1) (0=sin, 1=saw, 2=sqr)
  • vibrato direction (bit 0) (0=down, 1=up)
• Byte 6: Table (bit 5-0; bit 5 = table on/off)
• Byte 7: Pan (bit 1-0)
• Byte 8: Pitch
• Byte 9: Keep attack 2 (bit 7); Kit 2 (bit 5-0)
• Byte 10: Dist. type ($d0 = CLIP, $d1 = SHAPE, $d2 = SHAP2, $d3 = WRAP)
• Byte 11: Length 2 (0 = auto)
• Byte 12: Offset
• Byte 13: Offset 2

Noise Instrument

• Byte 0: 3
• Byte 1: Envelope
• Byte 2: S CMD (0 = free, 1 = stable)
• Byte 3: Sound length (bit 6-0; if bit 6 is unset, soundlength = UNLIM, otherwise length is bitwise not of bits 5-0)
• Byte 4: Shape
• Byte 5: Automate 1,2 (bit 4-3)
• Byte 6: Table (bit 5-0; bit 5 = table on/off)
• Byte 7: Pan (bit 1-0)

Softsynth Parameters

• Byte 0: Waveform (0 = sawtooth, 1 = square, 2 = triangle)
• Byte 1: Filter Type (0 = lowpass, 1 = highpass, 2 = bandpass, 3 = allpass)
• Byte 2: Filter Resonance
• Byte 3: Distortion (0 = clip, 1 = wrap)
• Byte 4: Phase Type (0 = normal, 1 = resync, 2 = resync2)
• Byte 5: Volume Start
• Byte 6: Filter Cutoff Start
• Byte 7: Phase Amount Start
• Byte 8: Vertical Shift Start
• Byte 9: Volume End
• Byte 10: Filter Cutoff End
• Byte 11: Phase Amount End
• Byte 12: Vertical Shift End

Version Byte (7FFF)

 * 0  0x00: < 3.6.0

 * 1  0x01: 3.6.0

 * 2  0x02: 3.6.1

 * 3  0x03: 4.4.0

 * 4  0x04: 5.7.0

 * 5  0x05: 6.3.0

 * 6  0x06: 6.7.0

 * 7  0x07: 6.8.0

 * 8  0x08: 7.1.0

 * 9  0x09: 7.5.0

 * 10 0x0A: 7.9.8

 * 11 0x0B: 8.1.0

 * 12 0x0C: 8.6.0

 * 13 0x0D: 8.8.0

 * 14 0x0E: 8.8.1

 * 15 0x0F: 8.8.6

 * 16 0x10: 8.8.8

 * 17 0x11: 8.9.3

 * 18 0x12: 9.0.0

 * 19 0x13: 9.1.0

 * 20 0x14: 9.1.5

 * 21 0x15: 9.1.B

 * 22 0x16: 9.2.1