CSNG (File Format) - Revision history

Jackoalan: /* Region Info */

2018-09-04T05:32:27Z

‎Region Info

Jackoalan: /* Continuous Pitch / Modulation Data */

2018-08-16T21:08:13Z

‎Continuous Pitch / Modulation Data

Jackoalan: /* Delta Time RLE */

2018-08-16T20:36:07Z

‎Delta Time RLE

Jackoalan: /* Continuous Pitch / Modulation Data */

2018-08-16T20:31:45Z

‎Continuous Pitch / Modulation Data

Jackoalan: Fix pitch/mod encoding scheme

2018-08-16T20:30:01Z

Fix pitch/mod encoding scheme

Jackoalan: Clarify nature of delta time encoding

2018-08-16T20:04:55Z

Clarify nature of delta time encoding

Jackoalan: /* Region Data */

2016-06-22T03:57:25Z

‎Region Data

Jackoalan: Multi-track SNG clarifications

2016-06-20T20:13:18Z

Multi-track SNG clarifications

Show changes

Jackoalan: /* Continuous Pitch / Modulation Data */

2016-05-20T00:31:12Z

‎Continuous Pitch / Modulation Data

Jackoalan at 00:30, 20 May 2016

2016-05-20T00:30:59Z

@@ Line 104: / Line 104: @@
 | 0x8
 | 2
-| '''Region Data Index'''; used to select region data via the ''region data index''; value is negative on a dummy ''region info'' to terminate track regions
+| '''Region Data Index'''; used to select region data when positive; -1 value terminates track; -2 value loops jumps to ''Loop Region Index'' at this region's tick
 |-
 | 0xA
 | 2
-| {{unknown|'''Unknown'''}}
+| '''Loop Region Index'''; index of region to jump to if ''Region Data Index'' set to -2
 |-
 | 0xC

@@ Line 266: / Line 266: @@
 (0x80). The decoder must track the absolute time and value, summing each consecutive update
 for the current time/values.
 Similar to the command stream, when the delta time exceeds 15 bit range (>32767), extra pairs
@@ Line 296: / Line 298: @@
      ret = [0,0]
      while ret[1] == 0:
          ret[0] += DecodeUnsignedValue(streamIn)
          ret[1] = DecodeSignedValue(streamIn)

@@ Line 147: / Line 147: @@
 in SNG: ''note'', ''control change'', and ''program change''.
-=====Delta Time RLE=====
+=====Delta Time Encoding=====
 Just like MIDI, each command starts with a '''delta time''' value telling the sequencer

@@ Line 268: / Line 268: @@
 Similar to the command stream, when the delta time exceeds 15 bit range (>32767), extra pairs
-with a value delta are inserted.
+with a zeroed value delta are inserted.
 <syntaxhighlight lang="python" line="1">

@@ Line 163: / Line 163: @@
          next = streamIn.PeekU16()
          if next == 0:
              total += 0xffff
              streamIn.seekAhead(2)
@@ Line 169: / Line 170: @@
          return total
 </syntaxhighlight>
 =====Note Command=====
@@ Line 253: / Line 260: @@
 ====Continuous Pitch / Modulation Data====
-If the pitch or mod offsets in a region are non-zero, they point to a buffer of RLE-compressed
+If the pitch or mod offsets in a region are non-zero, they point to a buffer of
-(delta-tick, delta-value) pairs, decoding to signed 16-bit precision. The decoder must track
+(delta-tick, delta-value) pairs. The delta times are encoded as unsigned 7/15 bit values
-the absolute time and value, summing each consecutive update for the current time/values.
+and the delta values are signed 7/15-bit values. The values are promoted to 15-bit if they
-The algorithm for this RLE is different than the delta-time one for commands. It may
+Similar to the command stream, when the delta time exceeds 15 bit range (>32767), extra pairs
-scale down to a single byte if able.
+with a value delta are inserted.
 <syntaxhighlight lang="python" line="1">
-def DecodeRLE(streamIn):
+def SignExtend7(value):
-     # high-bit shift-trigger RLE, limited to 2 bytes
+     return (value & 0x3f) - (value & 0x40)
-    term = streamIn.ReadU8()
-    total = term & 0x7f
-    if term & 0x80:
-        total = total * 256 + streamIn.ReadU8()
-    return total
-def DecodeContinuousRLE(streamIn, isValue):
+def SignExtend15(value):
-     total = 0
+     return (value & 0x3fff) - (value & 0x4000)
-    while True:
-        # 1-2 byte RLE accumulated within continuable RLE
-        term = DecodeRLE(streamIn)
-        if term == 0x8000:
-            total += 0xffff
-            dummy = streamIn.ReadU8()
-            continue
-        total += term
-        # values are signed deltas;
+def DecodeSignedValue(streamIn):
-        # extending into the high-half of 15-bit precision
+    byte0 = streamIn.ReadU8()
-        if isValue:
+    if byte0 & 0x80:
-            if total >= 0x4000:
+        byte1 = streamIn.ReadU8()
-                return total - 0xffff
+        return SignExtend15(byte1 | ((byte0 & 0x7f) << 8))
-            else:
+    else:
-                return total
+        return SignExtend7(byte0)
-         # times are always forward-deltas
+def DecodeUnsignedValue(streamIn):
-         return total
+    byte0 = streamIn.ReadU8()
 </syntaxhighlight>

@@ Line 150: / Line 150: @@
 Just like MIDI, each command starts with a '''delta time''' value telling the sequencer
-how many ticks to wait after the previous command. Unlike MIDI, Factor5 uses a custom
+how many ticks to wait after the previous command. Unlike MIDI, Factor5 uses a fixed 16-bit
-[[wikipedia:Run-length encoding|RLE scheme]] to adaptively scale the value's precision
+value to store the delta times. In case of a delta time greater than 65535, no-op commands
-to reduce the value's size.
+with a 65535 delta time are inserted into the command stream until the target time is attained.
-The RLE operates on 16-bit words, with the value 0xffff triggering a continuation,
+In a theoretical Python streaming API, the delta time can be decoded with no-ops automatically consumed like so:
-then a 'dead' 16-bit word skipped over, then the 0xffff is summed with the following RLE value,
-looping the decode algorithm.
-−
-In Python, decoding works like so:
 <syntaxhighlight lang="python" line="1">
-def DecodeDeltaTimeRLE(streamIn):
+def DecodeDeltaTime(streamIn):
      total = 0
      while True:
          term = streamIn.ReadU16()
-         if term == 0xffff:
+        next = streamIn.PeekU16()
              total += 0xffff
-             dummy = streamIn.ReadU16()
+             streamIn.seekAhead(2)
              continue
          total += term

@@ Line 144: / Line 144: @@
 ====Region Commands====
-After the region data header, the actual playback commands begin. There are only 2 types of commands
+After the region data header, the actual playback commands begin. There are only 3 types of commands
-in SNG: ''note'' and ''control change''.
+in SNG: ''note'', ''control change'', and ''program change''.
 =====Delta Time RLE=====
@@ Line 175: / Line 175: @@
 =====Note Command=====
-When the two bytes following the delta-time != 0xffff, and the high-bit of the first byte is ''unset'',
+When the two bytes following the delta-time != 0xffff, and the high-bits of both bytes are ''unset'',
 this is a '''note command'''.
@@ Line 204: / Line 204: @@
 =====Control Change Command=====
-When the two bytes following the delta-time != 0xffff, and the high-bit of the first byte is ''set'',
+When the two bytes following the delta-time != 0xffff, and the high-bits of both bytes are ''set'',
 this is a '''control change command'''.
@@ Line 224: / Line 224: @@
 | 0x2
 | colspan=2 {{unknown|End of control change}}
 |}