Fix the ADPCM-B note playback

ADPCM-B can vary sample playback, and the frequency to be used for
sample playback depends on the sample's configured frequency.
Expose that frequency in intruments and use it to generate the proper
frequency for the requested note in the Furnace module.

Author: dciabrin

tools/furtool.py

@@ -207,12 +207,14 @@ class adpcm_a_sample:
 class adpcm_b_sample:
     name: str = ""
     data: bytearray = field(default=b"", repr=False)
+    frequency: int = 0
 
 
 @dataclass
 class pcm_sample:
     name: str = ""
     data: bytearray = field(default=b"", repr=False)
+    frequency: int = 0
     loop: bool = False
 
 
@@ -245,6 +247,7 @@ class adpcm_a_instrument:
 class adpcm_b_instrument:
     name: str = ""
     sample: adpcm_b_sample = None
+    tuned: int = 0
     loop: bool = False
 
 
@@ -276,54 +279,70 @@ def read_fm_instrument(bs):
     return ifm
 
 
-@dataclass
-class ssg_prop:
-    name: str = ""
-    offset: int = 0
-
-    
-def read_ssg_macro(length, bs):
-    # TODO -1 are unsupported in nullsound
-    code_map = {0: ssg_prop("volume", 3),      # volume
-                3: ssg_prop("waveform", 4),    # noise_tune
-                6: ssg_prop("env", 0),         # envelope shape
-                7: ssg_prop("env_vol_num", 1), # volume envelope numerator
-                8: ssg_prop("env_vol_den", 2)  # volume envelope denominator
-                }
-
-    blocks={}
-    autoenv=False
-    init=bs.pos
+def read_macro_data(length, bs):
+    macros={}
     max_pos = bs.pos + length
     header_len = bs.u2()
-    # pass: read all macro blocks
     while bs.pos < max_pos:
         header_start = bs.pos
+        # macro code (vol, arp, pitch...)
         code = bs.u1()
         if code == 255:
             break
         length = bs.u1()
         # TODO unsupported. no loop
         loop = bs.u1()
-        # TODO unsupported. last macro stays
+        # TODO unsupported. last macro value stays
         release = bs.u1()
         # TODO meaning?
         mode = bs.u1()
         msize, mtype = ubits(bs.u1(), [7, 6], [2, 1])
         assert msize == 0, "macro value should be of type '8-bit unsigned'"
-        assert mtype == 0, "macro should be of type 'sequence'"
+        assert mtype == 0, "macro should be of type 'sequence'. ADSR or LFO unsupported"
         # TODO unsupported. no delay
         delay = bs.u1()
         # TODO unsupported. same speed as the module tick
         speed = bs.u1()
         header_end = bs.pos
         assert header_end - header_start == header_len
         data = [bs.u1() for i in range(length)]
+        macros[code]=data
+    assert bs.pos == max_pos
+    return macros
+
+
+def configure_b_macros(ins, macros):
+    # temporary workaround for instrument manually tuned with arpeggio macro
+    if 1 in macros and len(macros[1])==1:
+        ins.tuned = macros[1][0]
+    else:
+        error("unsupported use of macros in ADPCM-B instrument %s"%ins.name)
+
+
+@dataclass
+class ssg_prop:
+    name: str = ""
+    offset: int = 0
+
+
+def read_ssg_macro(length, bs):
+    # TODO -1 are unsupported in nullsound
+    code_map = {0: ssg_prop("volume", 3),      # volume
+                3: ssg_prop("waveform", 4),    # noise_tune
+                6: ssg_prop("env", 0),         # envelope shape
+                7: ssg_prop("env_vol_num", 1), # volume envelope numerator
+                8: ssg_prop("env_vol_den", 2)  # volume envelope denominator
+                }
+
+    autoenv=False
+    blocks = {}
+    macros = read_macro_data(length, bs)
+    for code in macros:
         if code not in code_map:
             warning("macro element not supported yet: %02x"%code)
         else:
-            blocks[code_map[code].offset]=data
-    assert bs.pos == max_pos
+            blocks[code_map[code].offset] = macros[code]
+
     # pass: create a "empty" waveform property if it's not there
     # we need it to tell nullsound to not update the envelope SSG register
     if 0 not in blocks:
@@ -416,7 +435,11 @@ def asm_ident(x):
             sample = bs.u2()
             bs.u2()  # unused flags and waveform
         elif feat == b"MA" and itype == 6:
+            # SSG macro is essentially the full SSG instrument
             mac = read_ssg_macro(length, bs)
+        elif feat == b"MA" and itype == 38:
+            # other macro types are currently not supported
+            mac = read_macro_data(length, bs)
         elif feat == b"NE":            
             # NES DPCM tag is present when the instrument
             # uses a PCM sample instead of ADPCM. Skip it
@@ -447,6 +470,8 @@ def asm_ident(x):
         return mac
     else:
         ins.name = asm_ident("instr_%02x_%s"%(nth, name))
+        if itype == 38 and mac:
+            configure_b_macros(ins, mac)
         return ins
 
 
@@ -482,7 +507,6 @@ def read_sample(bs, sample_idx):
         data_padding = 0  # adpcmtool codecs automatically adds padding
     else:
         error("sample '%s' is of unsupported type: %d"%(str(name), stype))
-    # assert c4_freq == {5: 18500, 6: 44100}[stype]
     bs.u1()  # unused loop direction
     bs.u2()  # unused flags
     loop_start, loop_end = bs.s4(), bs.s4()
@@ -494,6 +518,7 @@ def read_sample(bs, sample_idx):
            6: adpcm_b_sample,
            16: pcm_sample}[stype](insname, data)
     ins.loop = loop_start != -1 and loop_end != -1
+    ins.frequency = c4_freq
     return ins
 
 

tools/nsstool.py

@@ -75,7 +75,7 @@ def to_nss_note(furnace_note):
     return nss_note
 
 def to_nss_b_note(furnace_note):
-    octave = (furnace_note // 12) - 6
+    octave = (furnace_note // 12) - 5
     note = furnace_note % 12
     nss_note = (octave << 4) + note
     return nss_note
@@ -682,6 +682,82 @@ def compact_instr_pass(op, out):
     return out
 
 
+def tune_adpcm_b_notes(nss, ins):
+    # idea: all b-notes in the b channels are seen as an offset from C-4
+    # the playback freq is also a an offset, but from the current instrument's sample freq
+    # for convenience, each playback freq of the B-channel is given a note notation
+    # we have to find the note `i_note` corresponding the the current intrument's sample freq
+    # and from there, each note played will be an offset from `i_note`.
+    # this is the note that must be effectively stored in the NSS bytecode for correct playback
+
+    semitones = [ "C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B" ]
+    # lowest frequency playback for 12 semitones (can be seen as octave 0)
+    base_delta = [3255, 3448, 3653, 3871, 4101, 4345, 4603, 4877, 5167, 5474, 5800, 6144]
+    # all the frequencies for each supported octaves (up to 55Khz)
+    freqs = [[int(55555*x/65536)*(2**o) for x in base_delta] for o in range(5)]
+    # each octave's frequency bounds (with a 2.9% uncertainty/tolerance)
+    octaves_freqs = [(int(f[0]/1.029), int(f[-1]*1.029)) for f in freqs]
+
+    # all notes in the ADPCM-B channel are relative to C-4
+    c4 = (4*12)+0
+    # current instrument for ADPCM-B
+    current_inst = -1
+    # nullsound note from current sample's frequency
+    sample_note = c4
+
+    def to_direct_note(note):
+        semitone = note & 0xf
+        octave = (note>>4) & 0xf
+        return (octave*12)+semitone
+
+    def to_b_note(direct):
+        octave, semitone = direct // 12, direct % 12
+        return (octave<<4) | semitone
+
+    def note_str(note):
+        octave, semitone = note // 12, note % 12
+        return semitones[semitone].ljust(2, '-')+str(octave)
+
+    def tune_adpcm_b_pass(op, out):
+        nonlocal current_inst
+        nonlocal sample_note
+        nonlocal c4
+
+        if type(op) == nss_label:
+            current_inst = -1
+            out.append(op)
+        elif type(op) == b_instr:
+            if current_inst != op.inst:
+                current_inst = op.inst
+                sample_freq = ins[current_inst].sample.frequency
+                # determine nullsound note based on sample frequency
+                i_octave = next((i for i, f in enumerate(octaves_freqs) if f[0] < sample_freq < f[-1]), -1)
+                assert i_octave != -1
+                i_semitone = next((i for i, f in enumerate(freqs[i_octave]) if f/1.029 < sample_freq < f *1.029))
+                sample_note = (i_octave * 12) + i_semitone
+                # temporary workaround to support arpeggio tweak from macro
+                sample_note += ins[current_inst].tuned
+                out.append(op)
+        elif type(op) == b_note:
+            # get the semitone offset from c4
+            dnote = to_direct_note(op.note)
+            semitone_offset = dnote - c4
+            # the "tuned" note is the note to use in nullsound to configure the
+            # right frequency in the YM2610 (i.e. the semitone offset from the
+            # sample's base frequency)
+            tuned = to_b_note(sample_note + semitone_offset)
+            # fmt_off = "%s %2d"%("+" if semitone_offset>=0 else "-", abs(semitone_offset))
+            # print("B NOTE: %s (= C-4 %s)"%(note_str(dnote), fmt_off),
+            #       "-> TUNED: %s %s = %s"%(note_str(sample_note),
+            #       fmt_off, note_str(to_direct_note(tuned))))
+            out.append(b_note(tuned))
+        else:
+            out.append(op)
+
+    out = run_control_flow_pass(tune_adpcm_b_pass, nss)
+    return out
+
+
 def remove_ctx(nss):
     ctxs = [fm_ctx_1, fm_ctx_2, fm_ctx_3, fm_ctx_4,
             s_ctx_1, s_ctx_2, s_ctx_3,
@@ -971,6 +1047,9 @@ def generate_nss_stream(m, p, bs, ins, channels, stream_idx):
     dbg(" - remove successive INSTR opcodes if they keep intrument unchanged")
     nss = compact_instr(nss)
 
+    dbg(" - tune ADPCM-B notes based on instrument's sample speed")
+    nss = tune_adpcm_b_notes(nss, ins)
+
     if compact:
         dbg(" - remove CTX opcodes for compact stream")
         nss = remove_ctx(nss)