Upload 3 files

TMIDIX.py

@@ -51,7 +51,7 @@ r'''############################################################################
 
 ###################################################################################
 
-__version__ = "25.7.8"
+__version__ = "25.12.29"
 
 print('=' * 70)
 print('TMIDIX Python module')
@@ -1485,10 +1485,13 @@ import multiprocessing
 
 from itertools import zip_longest
 from itertools import groupby
+from itertools import cycle
+from itertools import product
 
 from collections import Counter
 from collections import defaultdict
 from collections import OrderedDict
+from collections import deque
 
 from operator import itemgetter
 
@@ -1498,6 +1501,9 @@ from difflib import SequenceMatcher as SM
 
 import statistics
 import math
+from math import gcd
+
+from functools import reduce
 
 import matplotlib.pyplot as plt
 
@@ -3903,7 +3909,8 @@ def chordify_score(score,
 
 def fix_monophonic_score_durations(monophonic_score,
                                    min_notes_gap=1,
-                                   min_notes_dur=1
+                                   min_notes_dur=1,
+                                   extend_durs=False
                                    ):
   
     fixed_score = []
@@ -3918,7 +3925,11 @@ def fix_monophonic_score_durations(monophonic_score,
         if note[1]+note[2] >= nmt:
           note_dur = max(1, nmt-note[1]-min_notes_gap)
         else:
-          note_dur = note[2]
+            if extend_durs:
+                note_dur = max(1, nmt-note[1]-min_notes_gap)
+
+            else:
+                note_dur = note[2]
 
         new_note = [note[0], note[1], note_dur] + note[3:]
         
@@ -3936,9 +3947,13 @@ def fix_monophonic_score_durations(monophonic_score,
         nmt = monophonic_score[i+1][0]
 
         if note[0]+note[1] >= nmt:
-          note_dur = max(1, nmt-note[0]-min_notes_gap)
+            note_dur = max(1, nmt-note[0]-min_notes_gap)
         else:
-          note_dur = note[1]
+            if extend_durs:
+                note_dur = max(1, nmt-note[0]-min_notes_gap)
+
+            else:
+                note_dur = note[1]
           
         new_note = [note[0], note_dur] + note[2:]
         
@@ -3952,8 +3967,6 @@ def fix_monophonic_score_durations(monophonic_score,
 
 ###################################################################################
 
-from itertools import product
-
 ALL_CHORDS = [[0], [7], [5], [9], [2], [4], [11], [10], [8], [6], [3], [1], [0, 9], [2, 5],
               [4, 7], [7, 10], [2, 11], [0, 3], [6, 9], [1, 4], [8, 11], [5, 8], [1, 10],
               [3, 6], [0, 4], [5, 9], [7, 11], [0, 7], [0, 5], [2, 10], [2, 7], [2, 9],
@@ -7128,7 +7141,8 @@ def escore_notes_to_binary_matrix(escore_notes,
                                   channel=0, 
                                   patch=0,
                                   flip_matrix=False,
-                                  reverse_matrix=False
+                                  reverse_matrix=False,
+                                  encode_velocities=False
                                   ):
 
   escore = [e for e in escore_notes if e[3] == channel and e[6] == patch]
@@ -7152,14 +7166,17 @@ def escore_notes_to_binary_matrix(escore_notes,
         duration = max(1, duration)
         chan = max(0, min(15, chan))
         pitch = max(0, min(127, pitch))
-        velocity = max(0, min(127, velocity))
+        velocity = max(1, min(127, velocity))
         pat = max(0, min(128, pat))
 
         if channel == chan and patch == pat:
 
           for t in range(time, min(time + duration, time_range)):
-
-            escore_matrix[t][pitch] = 1
+            if encode_velocities:
+                escore_matrix[t][pitch] = velocity
+                
+            else:
+                escore_matrix[t][pitch] = 1
 
     if flip_matrix:
 
@@ -7183,7 +7200,8 @@ def escore_notes_to_binary_matrix(escore_notes,
 def binary_matrix_to_original_escore_notes(binary_matrix, 
                                            channel=0, 
                                            patch=0, 
-                                           velocity=-1
+                                           velocity=-1,
+                                           decode_velocities=False
                                            ):
 
   result = []
@@ -7222,8 +7240,11 @@ def binary_matrix_to_original_escore_notes(binary_matrix,
 
   for r in result:
     
-    if velocity == -1:
-      vel = max(40, r[2])
+    if velocity == -1 and not decode_velocities:
+        vel = max(40, r[2])
+        
+    if decode_velocities:
+        vel = r[3]
 
     original_escore_notes.append(['note', r[0], r[1], channel, r[2], vel, patch])
 
@@ -8048,7 +8069,7 @@ def solo_piano_escore_notes(escore_notes,
                             keep_drums=False,
                             ):
 
-  cscore = chordify_score([1000, escore_notes])
+  cscore = chordify_score([1000, copy.deepcopy(escore_notes)])
 
   sp_escore_notes = []
 
@@ -9720,7 +9741,14 @@ def escore_notes_to_text_description(escore_notes,
                                      song_name='', 
                                      artist_name='',
                                      timings_divider=16,
+                                     return_feat_dict=False,
+                                     return_feat_dict_vals=False
                                     ):
+    
+    #==============================================================================
+    
+    feat_dict = {}
+    feat_dict_vals = {}
 
     #==============================================================================
 
@@ -9734,6 +9762,9 @@ def escore_notes_to_text_description(escore_notes,
     
     elif song_time_min >= 2.5:
         song_length = 'long'
+        
+    feat_dict['song_len'] = song_length.capitalize()
+    feat_dict_vals['song_len'] = song_time_min
 
     #==============================================================================
 
@@ -9745,18 +9776,25 @@ def escore_notes_to_text_description(escore_notes,
         if len(escore_times) == len(set(escore_times)):
             comp_type = 'monophonic melody'
             ctype = 'melody'
+            ctv = 0
         
         elif len(escore_times) >= len(set(escore_times)) and 1 in Counter(escore_times).values():
             comp_type = 'melody and accompaniment'
             ctype = 'song'
+            ctv = 1
         
         elif len(escore_times) >= len(set(escore_times)) and 1 not in Counter(escore_times).values():
             comp_type = 'accompaniment'
             ctype = 'song'
+            ctv = 2
     
     else:
         comp_type = 'drum track'
         ctype = 'drum track'
+        ctv = 3
+        
+    feat_dict['song_type'] = comp_type.capitalize()
+    feat_dict_vals['song_type'] = ctv
 
     #==============================================================================
 
@@ -9771,6 +9809,13 @@ def escore_notes_to_text_description(escore_notes,
         nd_patches_counts = Counter([p for p in all_patches if p < 128]).most_common()
 
         dominant_instrument = alpha_str(Number2patch[nd_patches_counts[0][0]])
+        
+        feat_dict['most_com_instr'] = instruments
+        feat_dict_vals['most_com_instr'] = [p for p in patches if p < 128]
+        
+    else:
+        feat_dict['most_com_instr'] = None
+        feat_dict_vals['most_com_instr'] = []
 
     if 128 in patches:
         drums_present = True
@@ -9778,9 +9823,16 @@ def escore_notes_to_text_description(escore_notes,
         drums_pitches = [e[4] for e in escore_notes if e[3] == 9]
 
         most_common_drums = [alpha_str(Notenum2percussion[p[0]]) for p in Counter(drums_pitches).most_common(3) if p[0] in Notenum2percussion]
+        
+        feat_dict['most_com_drums'] = most_common_drums
+        feat_dict_vals['most_com_drums'] = [p[0] for p in Counter(drums_pitches).most_common(3)]
 
     else:
         drums_present = False
+        
+        feat_dict['most_com_drums'] = None
+        
+        feat_dict_vals['most_com_drums'] = []
 
     #==============================================================================
 
@@ -9790,60 +9842,111 @@ def escore_notes_to_text_description(escore_notes,
     
     if pitches:
         key = SEMITONES[statistics.mode(pitches) % 12]
+        
+        feat_dict['key'] = key.title()
+        feat_dict_vals['key'] = statistics.mode(pitches) % 12
+        
+    else:
+        feat_dict['key'] = None
+        feat_dict_vals['key'] = -1
 
     #==============================================================================
     
     scale = ''
     mood = ''
     
+    feat_dict['scale'] = None
+    feat_dict['mood'] = None
+    feat_dict_vals['scale'] = -1
+    feat_dict_vals['mood'] = -1
+    
     if pitches:
     
         result = escore_notes_scale(escore_notes)
         
         scale = result[0]
         mood = result[1].split(' ')[0].lower()
+        
+        feat_dict['scale'] = scale.title()
+        feat_dict['mood'] = mood.title()
+        
+        res = escore_notes_scale(escore_notes, return_scale_indexes=True)
+        feat_dict_vals['scale'] = res[0]            
+        feat_dict_vals['mood'] = res[1]
 
     #==============================================================================
-    
+        
+    feat_dict['rythm'] = None
+    feat_dict['tempo'] = None
+    feat_dict['tone'] = None
+    feat_dict['dynamics'] = None
+
+    feat_dict_vals['rythm'] = -1
+    feat_dict_vals['tempo'] = -1
+    feat_dict_vals['tone'] = -1
+    feat_dict_vals['dynamics'] = -1
+
     if pitches:
     
         escore_averages = escore_notes_averages(escore_notes, return_ptcs_and_vels=True)
 
         if escore_averages[0] < (128 / timings_divider):
             rythm = 'fast'
+            ryv = 0
         
         elif (128 / timings_divider) <= escore_averages[0] <= (192 / timings_divider):
             rythm = 'average'
+            ryv = 1
         
         elif escore_averages[0] > (192 / timings_divider):
             rythm = 'slow'
+            ryv = 2
         
         if escore_averages[1] < (256 / timings_divider):
             tempo = 'fast'
+            tev = 0
         
         elif (256 / timings_divider) <= escore_averages[1] <= (384 / timings_divider):
             tempo = 'average'
+            tev = 1
         
         elif escore_averages[1] > (384 / timings_divider):
             tempo = 'slow'
+            tev = 2
         
         if escore_averages[2] < 50:
             tone = 'bass'
+            tov = 0
         
         elif 50 <= escore_averages[2] <= 70:
             tone = 'midrange'
+            tov = 1
         
         elif escore_averages[2] > 70:
             tone = 'treble'
+            tov = 2
         
         if escore_averages[3] < 64:
             dynamics = 'quiet'
+            dyn = 0
         
         elif 64 <= escore_averages[3] <= 96:
             dynamics = 'average'
+            dyn = 1
         
         elif escore_averages[3] > 96:
             dynamics = 'loud'
+            dyn = 2
+            
+        feat_dict['rythm'] = rythm.title()
+        feat_dict['tempo'] = tempo.title()
+        feat_dict['tone'] = tone.title()
+        feat_dict['dynamics'] = dynamics.title()
+        
+        feat_dict_vals['rythm'] = ryv
+        feat_dict_vals['tempo'] = tev
+        feat_dict_vals['tone'] = tov
+        feat_dict_vals['dynamics'] = dyn
 
     #==============================================================================
             
@@ -9851,6 +9954,12 @@ def escore_notes_to_text_description(escore_notes,
  
     lead_melodies = []
     base_melodies = []
+    
+    feat_dict['lead_mono_mels'] = None
+    feat_dict['base_mono_mels'] = None
+    
+    feat_dict_vals['lead_mono_mels'] = []
+    feat_dict_vals['base_mono_mels'] = []
  
     if mono_melodies:
             
@@ -9860,15 +9969,19 @@ def escore_notes_to_text_description(escore_notes,
             
             if mel[0] in LEAD_INSTRUMENTS and escore_avgs[3] > 60:
                 lead_melodies.append([Number2patch[mel[0]], mel[1]])
+                feat_dict_vals['lead_mono_mels'].append(mel[0])
 
             elif mel[0] in BASE_INSTRUMENTS and escore_avgs[3] <= 60:
                 base_melodies.append([Number2patch[mel[0]], mel[1]])
+                feat_dict_vals['base_mono_mels'].append(mel[0])
     
         if lead_melodies:
             lead_melodies.sort(key=lambda x: x[1], reverse=True)
+            feat_dict['lead_mono_mels'] = lead_melodies
             
         if base_melodies:
             base_melodies.sort(key=lambda x: x[1], reverse=True)
+            feat_dict['base_mono_mels'] = base_melodies
 
     #==============================================================================
         
@@ -10055,8 +10168,20 @@ def escore_notes_to_text_description(escore_notes,
         description += '\n'
         
     #==============================================================================
-
-    return description
+        
+    final_feat_dict = []
+        
+    if return_feat_dict:
+        final_feat_dict.append(feat_dict)
+    
+    if return_feat_dict_vals:
+        final_feat_dict.append(feat_dict_vals)
+        
+    if return_feat_dict or return_feat_dict_vals:
+        return final_feat_dict
+    
+    else:
+        return description
 
 ###################################################################################
 
@@ -11282,21 +11407,27 @@ def escore_notes_core(escore_notes, core_len=128):
 
 ###################################################################################
 
-def multiprocessing_wrapper(function, data_list, verbose=True):
+def multiprocessing_wrapper(function, 
+                            data_list, 
+                            num_workers=None, 
+                            verbose=True):
     
-    with multiprocessing.Pool() as pool:
-        
-        results = []
-        
-        for result in tqdm.tqdm(pool.imap_unordered(function, data_list),
-                                total=len(data_list),
-                                disable=not verbose
-                                ):
-            
+    if num_workers is None:
+        num_workers = multiprocessing.cpu_count()
+
+    results = []
+
+    with multiprocessing.Pool(processes=num_workers) as pool:
+        for result in tqdm.tqdm(
+            pool.imap(function, data_list),
+            total=len(data_list),
+            disable=not verbose
+        ):
             results.append(result)
-            
+
     return results
 
+
 ###################################################################################
 
 def rle_encode_ones(matrix, div_mod=-1):
@@ -11479,9 +11610,10 @@ def create_files_list(datasets_paths=['./'],
  
     for dataset_addr in datasets_paths:
         
-        print('=' * 70)
-        print('Processing', dataset_addr)
-        print('=' * 70)
+        if verbose:
+            print('=' * 70)
+            print('Processing', dataset_addr)
+            print('=' * 70)
         
         for dirpath, dirnames, filenames in tqdm.tqdm(os.walk(dataset_addr), disable=not verbose):
                 
@@ -13604,6 +13736,1304 @@ PERCUSSION_GROUPS = {
 
 ###################################################################################
 
+def escore_notes_to_expanded_binary_matrix(escore_notes, 
+                                           channel=0, 
+                                           patch=0,
+                                           flip_matrix=False,
+                                           reverse_matrix=False,
+                                           encode_velocities=True
+                                          ):
+
+  escore = [e for e in escore_notes if e[3] == channel and e[6] == patch]
+
+  if escore:
+    last_time = escore[-1][1]
+    last_notes = [e for e in escore if e[1] == last_time]
+    max_last_dur = max([e[2] for e in last_notes])
+
+    time_range = last_time+max_last_dur
+
+    escore_matrix = []
+
+    escore_matrix = [[(0, 0)] * 128 for _ in range(time_range)]
+
+    for note in escore:
+
+        etype, time, duration, chan, pitch, velocity, pat = note
+
+        time = max(0, time)
+        duration = max(1, duration)
+        chan = max(0, min(15, chan))
+        pitch = max(0, min(127, pitch))
+        velocity = max(1, min(127, velocity))
+        pat = max(0, min(128, pat))
+
+        if channel == chan and patch == pat:
+
+          count = 0
+          
+          for t in range(time, min(time + duration, time_range)):
+            if encode_velocities:
+                escore_matrix[t][pitch] = velocity, count
+
+            else:
+                escore_matrix[t][pitch] = 1, count
+            count += 1
+
+    if flip_matrix:
+
+      temp_matrix = []
+
+      for m in escore_matrix:
+        temp_matrix.append(m[::-1])
+
+      escore_matrix = temp_matrix
+
+    if reverse_matrix:
+      escore_matrix = escore_matrix[::-1]
+
+    return escore_matrix
+
+  else:
+    return None
+
+###################################################################################
+
+def transpose_list(lst):
+    return [list(row) for row in zip(*lst)]
+
+###################################################################################
+
+def chunk_list(lst, size):
+    return [lst[i:i + size] for i in range(0, len(lst), size)]
+
+###################################################################################
+
+def flip_list_rows(lst):
+    return [row[::-1] for row in lst]
+
+###################################################################################
+
+def flip_list_columns(lst):
+    return lst[::-1]
+
+###################################################################################
+
+def exists(sub, lst):
+    sub_len = len(sub)
+    return any(lst[i:i + sub_len] == sub for i in range(len(lst) - sub_len + 1))
+
+###################################################################################
+
+def exists_noncontig(sub, lst):
+    it = iter(lst)
+    return all(x in it for x in sub)
+
+###################################################################################
+
+def exists_ratio(sub, lst, ratio):
+    matches = sum(x in set(lst) for x in sub)
+    return matches / len(sub) >= ratio
+    
+###################################################################################
+
+def top_k_list_value(lst, k, reverse=True):
+    return sorted(lst, reverse=reverse)[k]
+
+###################################################################################
+
+def top_k_list_values(lst, k, reverse=True):
+    return sorted(lst, reverse=reverse)[:k]
+
+###################################################################################
+
+def concat_rows(lst_A, lst_B):
+    return [a + b for a, b in zip(lst_A, lst_B)]
+
+###################################################################################
+
+def concat_cols(lst_A, lst_B):
+    return [[ra + rb for ra, rb in zip(a, b)] for a, b in zip(lst_A, lst_B)]
+
+###################################################################################
+
+def chunk_by_threshold_mode(nums, threshold=0, normalize=False):
+
+    if not nums:
+        return []
+
+    chunks = []
+    chunk = []
+    freq = defaultdict(int)
+    max_freq = 0
+    mode_val = None
+
+    def try_add_and_validate(value):
+
+        nonlocal max_freq, mode_val
+
+        chunk.append(value)
+        freq[value] += 1
+        new_max_freq = max_freq
+        candidate_mode = mode_val
+
+        if freq[value] > new_max_freq:
+            new_max_freq = freq[value]
+            candidate_mode = value
+
+        mode = candidate_mode
+        valid = True
+
+        for v in chunk:
+            if abs(v - mode) > threshold:
+                valid = False
+                break
+
+        if not valid:
+            
+            chunk.pop()
+            freq[value] -= 1
+            if freq[value] == 0:
+                del freq[value]
+                
+            return False
+
+        max_freq = new_max_freq
+        mode_val = mode
+        return True
+
+    for num in nums:
+        if not chunk:
+            chunk.append(num)
+            freq[num] = 1
+            mode_val = num
+            max_freq = 1
+            
+        else:
+            if not try_add_and_validate(num):
+                if normalize:
+                    normalized_chunk = [mode_val] * len(chunk)
+                    chunks.append(normalized_chunk)
+                
+                else:
+                    chunks.append(chunk[:])
+
+                chunk.clear()
+                freq.clear()
+                
+                chunk.append(num)
+                freq[num] = 1
+                mode_val = num
+                max_freq = 1
+
+    if chunk:
+        if normalize:
+            normalized_chunk = [mode_val] * len(chunk)
+            chunks.append(normalized_chunk)
+            
+        else:
+            chunks.append(chunk)
+
+    return chunks
+
+###################################################################################
+
+def proportional_adjust(values, target_sum, threshold):
+
+    n = len(values)
+    if n == 0:
+        return []
+
+    locked_idx = [i for i, v in enumerate(values) if v < threshold]
+    adj_idx    = [i for i in range(n) if i not in locked_idx]
+
+    locked_sum       = sum(values[i] for i in locked_idx)
+    adj_original_sum = sum(values[i] for i in adj_idx)
+    adj_target_sum   = target_sum - locked_sum
+
+    def _proportional_scale(idxs, original, target):
+
+        scaled_vals = {i: original[i] * (target / sum(original[i] for i in idxs))
+                       if sum(original[i] for i in idxs) > 0 else 0
+                       for i in idxs}
+        
+        floored = {i: math.floor(scaled_vals[i]) for i in idxs}
+        rem = target - sum(floored.values())
+
+        fracs = sorted(
+            ((scaled_vals[i] - floored[i], i) for i in idxs),
+            key=lambda x: (x[0], -x[1]),
+            reverse=True
+        )
+        
+        for _, idx in fracs[:rem]:
+            floored[idx] += 1
+            
+        result = original.copy()
+        
+        for i in idxs:
+            result[i] = floored[i]
+            
+        return result
+
+    if not adj_idx:
+        if locked_sum == target_sum:
+            return values.copy()
+
+        return _proportional_scale(locked_idx, values, target_sum)
+
+    if adj_target_sum < 0:
+        return _proportional_scale(range(n), values, target_sum)
+
+    if adj_original_sum == 0:
+        base = adj_target_sum // len(adj_idx)
+        rem  = adj_target_sum - base * len(adj_idx)
+        result = values.copy()
+        
+        for j, idx in enumerate(sorted(adj_idx)):
+            increment = base + (1 if j < rem else 0)
+            result[idx] = values[idx] + increment
+            
+        return result
+
+    result = values.copy()
+    scaled = {i: values[i] * (adj_target_sum / adj_original_sum) for i in adj_idx}
+    floored = {i: math.floor(scaled[i]) for i in adj_idx}
+    floor_sum = sum(floored.values())
+    rem = adj_target_sum - floor_sum
+
+    fracs = sorted(
+        ((scaled[i] - floored[i], i) for i in adj_idx),
+        key=lambda x: (x[0], -x[1]),
+        reverse=True
+    )
+    
+    for _, idx in fracs[:rem]:
+        floored[idx] += 1
+
+    for i in adj_idx:
+        result[i] = floored[i]
+
+    return result
+
+###################################################################################
+
+def advanced_align_escore_notes_to_bars(escore_notes, 
+                                        bar_dtime=200,
+                                        dtimes_adj_thresh=4,
+                                        min_dur_gap=0
+                                       ):
+
+    #========================================================
+
+    escore_notes = recalculate_score_timings(escore_notes)
+
+    cscore = chordify_score([1000, escore_notes])
+
+    #========================================================
+
+    dtimes = [0] + [min(199, b[1]-a[1]) for a, b in zip(escore_notes[:-1], escore_notes[1:]) if b[1]-a[1] != 0]
+
+    score_times = sorted(set([e[1] for e in escore_notes]))
+
+    #========================================================
+
+    dtimes_chunks = []
+    
+    time = 0
+    dtime = []
+    
+    for i, dt in enumerate(dtimes):
+        time += dt
+        dtime.append(dt)
+
+        if time >= bar_dtime:
+            dtimes_chunks.append(dtime)
+            
+            time = 0
+            dtime = []
+    
+    dtimes_chunks.append(dtime)
+
+    #========================================================
+
+    fixed_times = []
+    
+    time = 0
+    
+    for i, dt in enumerate(dtimes_chunks):
+    
+        adj_dt = proportional_adjust(dt, 
+                                     bar_dtime, 
+                                     dtimes_adj_thresh
+                                    )
+    
+        for t in adj_dt:
+    
+            time += t
+    
+            fixed_times.append(time)
+
+    #========================================================
+
+    output_score = []
+    
+    for i, c in enumerate(cscore):
+        
+        cc = copy.deepcopy(c)
+        time = fixed_times[i]
+    
+        for e in cc:
+            e[1] = time
+    
+            output_score.append(e)
+
+    #========================================================
+
+    output_score = fix_escore_notes_durations(output_score, 
+                                              min_notes_gap=min_dur_gap
+                                             )
+
+    #========================================================
+
+    return output_score
+
+###################################################################################
+
+def check_monophonic_melody(escore_notes, 
+                            times_idx=1, 
+                            durs_idx=2
+                           ):
+
+    bcount = 0
+    
+    for i in range(len(escore_notes)-1):
+        if escore_notes[i][times_idx]+escore_notes[i][durs_idx] > escore_notes[i+1][times_idx]:
+            bcount += 1
+
+    return bcount / len(escore_notes)
+
+###################################################################################
+
+def longest_common_chunk(list1, list2):
+    
+    base, mod = 257, 10**9 + 7
+    max_len = min(len(list1), len(list2))
+    
+    def get_hashes(seq, size):
+
+        h, power = 0, 1
+        hashes = set()
+        
+        for i in range(size):
+            h = (h * base + seq[i]) % mod
+            power = (power * base) % mod
+            
+        hashes.add(h)
+        
+        for i in range(size, len(seq)):
+            h = (h * base - seq[i - size] * power + seq[i]) % mod
+            hashes.add(h)
+            
+        return hashes
+
+    def find_match(size):
+
+        hashes2 = get_hashes(list2, size)
+        h, power = 0, 1
+        
+        for i in range(size):
+            h = (h * base + list1[i]) % mod
+            power = (power * base) % mod
+            
+        if h in hashes2:
+            return list1[:size]
+            
+        for i in range(size, len(list1)):
+            h = (h * base - list1[i - size] * power + list1[i]) % mod
+            if h in hashes2:
+                return list1[i - size + 1:i + 1]
+                
+        return []
+
+    left, right = 0, max_len
+    result = []
+    
+    while left <= right:
+        mid = (left + right) // 2
+        chunk = find_match(mid)
+        
+        if chunk:
+            result = chunk
+            left = mid + 1
+        else:
+            
+            right = mid - 1
+            
+    return result
+
+###################################################################################
+
+def detect_plateaus(data, min_len=2, tol=0.0):
+
+    plateaus = []
+    n = len(data)
+    if n < min_len:
+        return plateaus
+
+    min_deque = deque()
+    max_deque = deque()
+
+    start = 0
+    idx = 0
+
+    while idx < n:
+        v = data[idx]
+
+        if not isinstance(v, (int, float)) or math.isnan(v):
+
+            if idx - start >= min_len:
+                plateaus.append(data[start:idx])
+
+            idx += 1
+            start = idx
+            min_deque.clear()
+            max_deque.clear()
+            
+            continue
+
+        while max_deque and data[max_deque[-1]] <= v:
+            max_deque.pop()
+            
+        max_deque.append(idx)
+
+        while min_deque and data[min_deque[-1]] >= v:
+            min_deque.pop()
+            
+        min_deque.append(idx)
+
+        if data[max_deque[0]] - data[min_deque[0]] > tol:
+
+            if idx - start >= min_len:
+                plateaus.append(data[start:idx])
+
+            start = idx
+            
+            min_deque.clear()
+            max_deque.clear()
+
+            max_deque.append(idx)
+            min_deque.append(idx)
+
+        idx += 1
+
+    if n - start >= min_len:
+        plateaus.append(data[start:n])
+
+    return plateaus
+
+###################################################################################
+
+def alpha_str_to_toks(s, shift=0, add_seos=False):
+
+    tokens = []
+
+    if add_seos:
+        tokens = [53+shift]
+    
+    for char in s:
+        if char == ' ':
+            tokens.append(52+shift)
+            
+        elif char.isalpha():
+            base = 0 if char.isupper() else 26
+            offset = ord(char.upper()) - ord('A')
+            token = (base + offset + shift) % 52  # wrap A–Z/a–z
+            tokens.append(token)
+            
+    if add_seos:       
+        tokens.append(53+shift)
+        
+    return tokens
+
+###################################################################################
+
+def toks_to_alpha_str(tokens, shift=0, sep=''):
+
+    chars = []
+    
+    for token in tokens:
+        if token == 53+shift:
+            continue
+            
+        elif token == 52+shift:
+            chars.append(' ')
+            
+        elif 0 <= token <= 25:
+            original = (token - shift) % 52
+            chars.append(chr(ord('A') + original))
+            
+        elif 26 <= token <= 51:
+            original = (token - shift) % 52
+            chars.append(chr(ord('a') + (original - 26)))
+
+    return sep.join(chars)
+
+###################################################################################
+
+def insert_caps_newlines(text):
+
+    if bool(re.search(r'\b[A-Z][a-z]+\b', text)):
+        pattern = re.compile(r'\s+(?=[A-Z])')
+
+        return pattern.sub('\n', text)
+
+###################################################################################
+
+def insert_newlines(text, every=4):
+
+    count = 0
+    result = []
+
+    for char in text:
+        result.append(char)
+        
+        if char == '\n':
+            count += 1
+            
+            if count % every == 0:
+                result.append('\n')
+
+    return ''.join(result)
+
+###################################################################################
+
+def symmetric_match_ratio(list_a, list_b, threshold=0):
+
+    a_sorted = sorted(list_a)
+    b_sorted = sorted(list_b)
+
+    i, j = 0, 0
+    matches = 0
+    
+    used_a = set()
+    used_b = set()
+
+    while i < len(a_sorted) and j < len(b_sorted):
+        diff = abs(a_sorted[i] - b_sorted[j])
+        
+        if diff <= threshold:
+            matches += 1
+            used_a.add(i)
+            used_b.add(j)
+            i += 1
+            j += 1
+            
+        elif a_sorted[i] < b_sorted[j]:
+            i += 1
+            
+        else:
+            j += 1
+
+    avg_len = (len(list_a) + len(list_b)) / 2
+    
+    return matches / avg_len if avg_len > 0 else 0.0
+
+###################################################################################
+
+def escore_notes_to_chords(escore_notes, 
+                           use_full_chords=False,
+                           repair_bad_chords=True,
+                           skip_pitches=False,
+                           convert_pitches=True,
+                           shift_chords=False,
+                           return_tones_chords=False
+                          ):
+
+    if use_full_chords:
+        CHORDS = ALL_CHORDS_FULL
+
+    else:
+        CHORDS = ALL_CHORDS_SORTED
+
+    sp_score = solo_piano_escore_notes(escore_notes)
+
+    cscore = chordify_score([1000, sp_score])
+
+    chords = []
+
+    for c in cscore:
+        pitches = sorted(set([e[4] for e in c]))
+
+        tones_chord = sorted(set([p % 12 for p in pitches]))
+
+        if repair_bad_chords:
+            if tones_chord not in CHORDS:
+                tones_chord = check_and_fix_tones_chord(tones_chord, 
+                                                        use_full_chords=use_full_chords
+                                                       )
+            
+        if return_tones_chords:
+            if convert_pitches:
+                chords.append(tones_chord)
+
+            else:
+                if len(pitches) > 1:
+                    chords.append(tones_chord)
+
+                else:
+                    chords.append([-pitches[0]])
+                    
+        else:
+            if skip_pitches:
+                if tones_chord in CHORDS:
+                    cho_tok = CHORDS.index(tones_chord)
+
+                else:
+                    cho_tok = -1
+
+                if len(pitches) > 1:
+                    chords.append(cho_tok)
+
+            else:
+                if tones_chord in CHORDS:
+                    cho_tok = CHORDS.index(tones_chord)
+
+                else:
+                    cho_tok = -1
+
+                if cho_tok != -1:
+                    if convert_pitches:
+                        if shift_chords:
+                            if len(pitches) > 1:
+                                chords.append(cho_tok+12)
+        
+                            else:
+                                chords.append(pitches[0] % 12)
+                                
+                        else:
+                            chords.append(cho_tok)
+        
+                    else:
+                        if len(pitches) > 1:
+                            chords.append(cho_tok+128)
+        
+                        else:
+                            chords.append(pitches[0])
+
+    return chords
+
+###################################################################################
+
+def replace_chords_in_escore_notes(escore_notes,
+                                   chords_list=[-1],
+                                   use_full_chords=False,
+                                   use_shifted_chords=False
+                                  ):
+
+    if use_full_chords:
+        CHORDS = ALL_CHORDS_FULL
+
+    else:
+        CHORDS = ALL_CHORDS_SORTED
+
+    if use_shifted_chords:
+        shift = 12
+
+    else:
+        shift = 0
+
+    if min(chords_list) >= 0 and max(chords_list) <= len(CHORDS)+shift:
+
+        chords_list_iter = cycle(chords_list)
+
+        nd_score = [e for e in escore_notes if e[3] != 9]
+        d_score = [e for e in escore_notes if e[3] == 9]
+    
+        cscore = chordify_score([1000, nd_score])
+    
+        new_score = []
+    
+        for i, c in enumerate(cscore):
+
+            cur_chord = next(chords_list_iter)
+    
+            cc = copy.deepcopy(c)
+    
+            if use_shifted_chords:
+                if cur_chord < 12:
+                    sub_tones_chord = [cur_chord]
+    
+                else:
+                    sub_tones_chord = CHORDS[cur_chord-12]
+            else:
+                sub_tones_chord = CHORDS[cur_chord]
+                
+            stcho = cycle(sub_tones_chord)
+
+            if len(sub_tones_chord) > len(c):
+                cc = [copy.deepcopy(e) for e in cc for _ in range(len(sub_tones_chord))]
+                
+            pseen = []
+    
+            for e in cc:
+                st = next(stcho)
+                new_pitch = ((e[4] // 12) * 12) + st
+
+                if [new_pitch, e[6]] not in pseen:
+                    e[4] = new_pitch
+                    
+                    new_score.append(e)
+                    pseen.append([new_pitch, e[6]])
+                    
+        final_score = sorted(new_score+d_score, key=lambda x: x[1])
+
+        return final_score
+
+    else:
+        return []
+
+###################################################################################
+
+class Cell:
+    def __init__(self, cost, segments, gaps, prev_dir):
+        self.cost = cost
+        self.segments = segments
+        self.gaps = gaps
+        self.prev_dir = prev_dir
+
+def align_integer_lists(seq1, seq2):
+
+    n, m = len(seq1), len(seq2)
+    
+    if n == 0:
+        return [None]*m, seq2.copy(), sum(abs(x) for x in seq2)
+    if m == 0:
+        return seq1.copy(), [None]*n, sum(abs(x) for x in seq1)
+
+    priority = {'diag': 0, 'up': 1, 'left': 2}
+
+    dp = [
+        [Cell(cost=math.inf, segments=math.inf, gaps=math.inf, prev_dir='') for _ in range(m+1)]
+        for _ in range(n+1)
+    ]
+    dp[0][0] = Cell(cost=0, segments=0, gaps=0, prev_dir='')
+
+    for i in range(1, n+1):
+        prev = dp[i-1][0]
+        new_cost = prev.cost + abs(seq1[i-1])
+        new_seg  = prev.segments + (1 if prev.prev_dir != 'up' else 0)
+        new_gaps = prev.gaps + 1
+        dp[i][0]  = Cell(new_cost, new_seg, new_gaps, 'up')
+
+    for j in range(1, m+1):
+        prev = dp[0][j-1]
+        new_cost = prev.cost + abs(seq2[j-1])
+        new_seg  = prev.segments + (1 if prev.prev_dir != 'left' else 0)
+        new_gaps = prev.gaps + 1
+        dp[0][j] = Cell(new_cost, new_seg, new_gaps, 'left')
+
+    for i in range(1, n+1):
+        for j in range(1, m+1):
+            a, b = seq1[i-1], seq2[j-1]
+
+            c0 = dp[i-1][j-1]
+            cand_diag = Cell(
+                cost     = c0.cost + abs(a - b),
+                segments = c0.segments,
+                gaps     = c0.gaps,
+                prev_dir = 'diag'
+            )
+
+            c1 = dp[i-1][j]
+            seg1 = c1.segments + (1 if c1.prev_dir != 'up' else 0)
+            cand_up = Cell(
+                cost     = c1.cost + abs(a),
+                segments = seg1,
+                gaps     = c1.gaps + 1,
+                prev_dir = 'up'
+            )
+
+            c2 = dp[i][j-1]
+            seg2 = c2.segments + (1 if c2.prev_dir != 'left' else 0)
+            cand_left = Cell(
+                cost     = c2.cost + abs(b),
+                segments = seg2,
+                gaps     = c2.gaps + 1,
+                prev_dir = 'left'
+            )
+
+            best = min(
+                (cand_diag, cand_up, cand_left),
+                key=lambda c: (c.cost, c.segments, c.gaps, priority[c.prev_dir])
+            )
+            dp[i][j] = best
+
+    aligned1 = []
+    aligned2 = []
+    i, j = n, m
+    
+    while i > 0 or j > 0:
+        cell = dp[i][j]
+        
+        if cell.prev_dir == 'diag':
+            aligned1.append(seq1[i-1])
+            aligned2.append(seq2[j-1])
+            i, j = i-1, j-1
+            
+        elif cell.prev_dir == 'up':
+            aligned1.append(seq1[i-1])
+            aligned2.append(None)
+            i -= 1
+            
+        else:
+            aligned1.append(None)
+            aligned2.append(seq2[j-1])
+            j -= 1
+
+    aligned1.reverse()
+    aligned2.reverse()
+    
+    total_cost = int(dp[n][m].cost)
+    
+    return aligned1, aligned2, total_cost
+
+###################################################################################
+
+def most_common_delta_time(escore_notes):
+    
+    dscore = delta_score_notes(escore_notes)
+    
+    dtimes = [t[1] for t in dscore if t[1] != 0]
+    
+    cdtime, count = Counter(dtimes).most_common(1)[0]
+
+    return [cdtime, count / len(dtimes)]
+
+###################################################################################
+
+def delta_tones(escore_notes, 
+                ptcs_idx=4
+               ):
+    
+    pitches = [p[ptcs_idx] for p in escore_notes]
+    tones = [p % 12 for p in pitches]
+
+    return [b-a for a, b in zip(tones[:-1], tones[1:])]
+    
+###################################################################################
+
+def find_divisors(val, 
+                  reverse=False
+                 ):
+  
+    if val == 0:
+        return []
+
+    n = abs(val)
+    divisors = set()
+
+    for i in range(1, int(n**0.5) + 1):
+        if n % i == 0:
+            divisors.add(i)
+            divisors.add(n // i)
+
+    return sorted(divisors, reverse=reverse)
+
+###################################################################################
+
+def find_common_divisors(values, 
+                         reverse=False
+                        ):
+   
+    if not values:
+        return []
+
+    non_zero = [abs(v) for v in values if v != 0]
+    if not non_zero:
+        return []
+
+    overall_gcd = reduce(gcd, non_zero)
+
+    divisors = set()
+    
+    for i in range(1, int(overall_gcd**0.5) + 1):
+        if overall_gcd % i == 0:
+            divisors.add(i)
+            divisors.add(overall_gcd // i)
+
+    return sorted(divisors, reverse=reverse)
+
+###################################################################################
+
+def strings_dict(list_of_strings, 
+                 verbose=False
+                ):
+
+    str_set = set()
+    
+    for st in tqdm.tqdm(list_of_strings, disable=not verbose):
+        for cha in st:
+            str_set.add(cha)
+
+    str_lst = sorted(str_set)
+
+    str_dic = dict(zip(str_lst, range(len(str_lst))))
+    rev_str_dic = {v: k for k, v in str_dic.items()}
+
+    return str_dic, rev_str_dic
+
+###################################################################################
+
+def chords_common_tones_chain(chords, 
+                              use_full_chords=False
+                             ):
+
+    if use_full_chords:
+        CHORDS = ALL_CHORDS_FULL
+
+    else:
+        CHORDS = ALL_CHORDS_SORTED
+
+    tones_chords = [CHORDS[c] for c in chords if 0 <= c < len(CHORDS)]
+
+    n = len(tones_chords)
+    
+    if not tones_chords:
+        return []
+        
+    if n < 2:
+        return tones_chords
+
+    result = []
+
+    for i in range(n):
+        if i == 0:
+            common = set(tones_chords[0]) & set(tones_chords[1])
+            
+        elif i == n - 1:
+            common = set(tones_chords[n - 2]) & set(tones_chords[n - 1])
+            
+        else:
+            common = set(tones_chords[i - 1]) & set(tones_chords[i]) & set(tones_chords[i + 1])
+
+        result.append(min(common) if common else -1)
+
+    return result
+
+###################################################################################
+
+def tones_chord_to_int(tones_chord, 
+                       reverse_bits=True
+                      ):
+
+    cbits = tones_chord_to_bits(tones_chord, 
+                                reverse=reverse_bits
+                               )
+
+    cint = bits_to_int(cbits)
+    
+    return cint
+
+###################################################################################
+
+def int_to_tones_chord(integer, 
+                       reverse_bits=True
+                      ):
+
+    integer = integer % 4096
+
+    cbits = int_to_bits(integer)
+
+    if reverse_bits:
+        cbits.reverse()
+
+    tones_chord = bits_to_tones_chord(cbits)
+
+    return tones_chord
+
+###################################################################################
+
+def fix_bad_chords_in_escore_notes(escore_notes,
+                                   use_full_chords=False,
+                                   return_bad_chords_count=False
+                                  ):
+
+    if use_full_chords:
+        CHORDS = ALL_CHORDS_FULL
+
+    else:
+        CHORDS = ALL_CHORDS_SORTED
+
+    bcount = 0
+
+    if escore_notes:
+
+        chords = chordify_score([1000, escore_notes])
+
+        fixed_chords = []
+    
+        for c in chords:
+            c.sort(key=lambda x: x[3])
+    
+            if len(c) > 1:
+    
+                groups = groupby(c, key=lambda x: x[3])
+        
+                for cha, gr in groups:
+
+                    if cha != 9:
+    
+                        gr = list(gr)
+                        
+                        tones_chord = sorted(set([p[4] % 12 for p in gr]))
+            
+                        if tones_chord not in CHORDS:
+                            tones_chord = check_and_fix_tones_chord(tones_chord, 
+                                                                    use_full_chords=use_full_chords
+                                                                   )
+                    
+                            bcount += 1
+            
+                        ngr = []
+                        
+                        for n in gr:
+                            if n[4] % 12 in tones_chord:
+                                ngr.append(n)
+            
+                        fixed_chords.extend(ngr)
+
+                    else:
+                        fixed_chords.extend(gr)
+                        
+    
+            else:
+                fixed_chords.extend(c)
+                
+        fixed_chords.sort(key=lambda x: (x[1], -x[4]))
+
+        if return_bad_chords_count:
+            return fixed_chords, bcount
+
+        else:
+            return fixed_chords
+            
+    else:
+        if return_bad_chords_count:
+            return escore_notes, bcount
+
+        else:
+            return escore_notes
+        
+###################################################################################
+        
+def remove_events_from_escore_notes(escore_notes,
+                                    ele_idx=2,
+                                    ele_vals=[1],
+                                    chan_idx=3,
+                                    skip_drums=True
+                                    ):
+
+    new_escore_notes = []
+    
+    for e in escore_notes:
+        if skip_drums:
+            if e[ele_idx] not in ele_vals or e[chan_idx] == 9:
+                new_escore_notes.append(e)
+
+        else:
+            if e[ele_idx] not in ele_vals:
+                new_escore_notes.append(e)
+
+    return new_escore_notes
+        
+###################################################################################
+
+def flatten_spikes(arr):
+    
+    if len(arr) < 3:
+        return arr[:]
+
+    result = arr[:]
+    
+    for i in range(1, len(arr) - 1):
+        prev, curr, next_ = arr[i - 1], arr[i], arr[i + 1]
+
+        if (prev <= next_ and (curr > prev and curr > next_)) or \
+           (prev >= next_ and (curr < prev and curr < next_)):
+            result[i] = max(min(prev, next_), min(max(prev, next_), curr))
+            
+    return result
+        
+###################################################################################
+
+def flatten_spikes_advanced(arr, window=1):
+    
+    if len(arr) < 3:
+        return arr[:]
+
+    result = arr[:]
+    n = len(arr)
+
+    def is_spike(i):
+        left = arr[i - window:i]
+        right = arr[i + 1:i + 1 + window]
+        
+        if not left or not right:
+            return False
+
+        avg_left = sum(left) / len(left)
+        avg_right = sum(right) / len(right)
+
+        if arr[i] > avg_left and arr[i] > avg_right:
+            return True
+
+        if arr[i] < avg_left and arr[i] < avg_right:
+            return True
+        
+        return False
+
+    for i in range(window, n - window):
+        if is_spike(i):
+            neighbors = arr[i - window:i] + arr[i + 1:i + 1 + window]
+            result[i] = int(sorted(neighbors)[len(neighbors) // 2])
+
+    return result
+        
+###################################################################################
+
+def add_smooth_melody_to_enhanced_score_notes(escore_notes,
+                                              melody_channel=3,
+                                              melody_patch=40,
+                                              melody_start_chord=0,
+                                              min_notes_gap=0,
+                                              exclude_durs=[1],
+                                              adv_flattening=True,
+                                              extend_durs=True,
+                                              max_mel_vels=127,
+                                              max_acc_vels=80,
+                                              return_melody=False
+                                             ):
+
+    escore_notes1 = remove_duplicate_pitches_from_escore_notes(escore_notes)
+    
+    escore_notes2 = fix_escore_notes_durations(escore_notes1, 
+                                               min_notes_gap=min_notes_gap
+                                              )
+    
+    escore_notes3 = fix_bad_chords_in_escore_notes(escore_notes2)
+    
+    escore_notes4 = remove_events_from_escore_notes(escore_notes3, 
+                                                    ele_vals=exclude_durs
+                                                   )
+    
+    escore_notes5 = add_expressive_melody_to_enhanced_score_notes(escore_notes4,
+                                                                  melody_channel=melody_channel, 
+                                                                  melody_patch=melody_patch, 
+                                                                  melody_start_chord=melody_start_chord,
+                                                                  return_melody=True,
+                                                                 )
+    
+    mel_score = remove_events_from_escore_notes(escore_notes5,
+                                                ele_vals=exclude_durs
+                                               )
+    
+    pitches = [p[4] for p in mel_score]
+    
+    if adv_flattening:
+        res = flatten_spikes_advanced(pitches)
+
+    else:
+        res = flatten_spikes(pitches)
+    
+    mel_score3 = copy.deepcopy(mel_score)
+    
+    for i, e in enumerate(mel_score3):
+        e[4] = res[i]
+    
+    mel_score3 = fix_monophonic_score_durations(merge_melody_notes(mel_score3),
+                                                extend_durs=extend_durs
+                                               )
+
+    adjust_score_velocities(mel_score3, max_mel_vels)
+    adjust_score_velocities(escore_notes4, max_acc_vels)
+
+    if return_melody:
+        return sorted(mel_score3, key=lambda x: (x[1], -x[4]))
+
+    else:
+        return sorted(mel_score3 + escore_notes4, key=lambda x: (x[1], -x[4]))
+    
+###################################################################################
+
+def sorted_chords_to_full_chords(chords):
+
+    cchords = []
+    
+    for c in chords:
+        tones_chord = ALL_CHORDS_SORTED[c]
+
+        if tones_chord not in ALL_CHORDS_FULL:
+            tones_chord = check_and_fix_tones_chord(tones_chord)
+
+        cchords.append(ALL_CHORDS_FULL.index(tones_chord))
+
+    return cchords
+
+###################################################################################
+
+def full_chords_to_sorted_chords(chords):
+
+    cchords = []
+    
+    for c in chords:
+        tones_chord = ALL_CHORDS_FULL[c]
+
+        if tones_chord not in ALL_CHORDS_SORTED:
+            tones_chord = check_and_fix_tones_chord(tones_chord, use_full_chords=False)
+
+        cchords.append(ALL_CHORDS_SORTED.index(tones_chord))
+
+    return cchords
+
+###################################################################################
+
+def chords_to_escore_notes(chords,
+                           use_full_chords=False,
+                           chords_dtime=500,
+                           add_melody=True,
+                           add_texture=True,
+                          ):
+
+    if use_full_chords:
+        CHORDS = ALL_CHORDS_FULL
+
+    else:
+        CHORDS = ALL_CHORDS_SORTED
+
+    score = []
+
+    dtime = 0
+
+    dur = chords_dtime
+
+    for c in chords:
+
+        if add_melody:
+            score.append(['note', dtime, dur, 3, CHORDS[c][0]+72, 115+CHORDS[c][0], 40])
+
+        for cc in CHORDS[c]:
+            score.append(['note', dtime, dur, 0, cc+48, 30+cc+48, 0])
+
+            if random.randint(0, 1) and add_texture:
+                score.append(['note', dtime, dur, 0, cc+60, 20+cc+60, 0])    
+            
+        dtime += chords_dtime
+
+    return score
+
+###################################################################################
+
 print('Module loaded!')
 print('=' * 70)
 print('Enjoy! :)')

midi_to_colab_audio.py

@@ -5,14 +5,14 @@ r'''#===========================================================================
 # Converts any MIDI file to raw audio which is compatible 
 # with Google Colab or HUgging Face Gradio
 #
-# Version 1.0
+# Version 2.0
 #
-# Includes full source code of MIDI, pyfluidsynth, and midi_synthesizer Python modules
+# Includes full source code of MIDI and pyfluidsynth
 # 
-# Original source code for all modules was retrieved on 10/23/2023
+# Original source code for all modules was retrieved on 07/31/2025
 #
 # Project Los Angeles
-# Tegridy Code 2023
+# Tegridy Code 2025
 #
 #===================================================================================================================
 #
@@ -1773,7 +1773,7 @@ def _encode(events_lol, unknown_callback=None, never_add_eot=False,
 
     Python bindings for FluidSynth
 
-    Copyright 2008, Nathan Whitehead <nwhitehe@gmail.com>
+    Copyright 2008--2024, Nathan Whitehead <nwhitehe@gmail.com> and others.
 
 
     Released under the LGPL
@@ -1790,27 +1790,67 @@ def _encode(events_lol, unknown_callback=None, never_add_eot=False,
 ================================================================================
 """
 
-from ctypes import *
-from ctypes.util import find_library
 import os
-
-# A short circuited or expression to find the FluidSynth library
-# (mostly needed for Windows distributions of libfluidsynth supplied with QSynth)
+from ctypes import (
+    CDLL,
+    CFUNCTYPE,
+    POINTER,
+    Structure,
+    byref,
+    c_char,
+    c_char_p,
+    c_double,
+    c_float,
+    c_int,
+    c_short,
+    c_uint,
+    c_void_p,
+    create_string_buffer,
+)
+from ctypes.util import find_library
 
 # DLL search method changed in Python 3.8
 # https://docs.python.org/3/library/os.html#os.add_dll_directory
-if hasattr(os, 'add_dll_directory'):
+if hasattr(os, 'add_dll_directory'):  # Python 3.8+ on Windows only
     os.add_dll_directory(os.getcwd())
+    os.add_dll_directory('C:\\tools\\fluidsynth\\bin')
+    # Workaround bug in find_library, it doesn't recognize add_dll_directory
+    os.environ['PATH'] += ';C:\\tools\\fluidsynth\\bin'
 
-lib = find_library('fluidsynth') or \
-    find_library('libfluidsynth') or \
-    find_library('libfluidsynth-3') or \
-    find_library('libfluidsynth-2') or \
-    find_library('libfluidsynth-1')
+# A function to find the FluidSynth library
+# (mostly needed for Windows distributions of libfluidsynth supplied with QSynth)
+def find_libfluidsynth(debug_print: bool = False) -> str:
+    r"""
+    macOS X64:
+    * 'fluidsynth' was found at /usr/local/opt/fluid-synth/lib/libfluidsynth.dylib.
+    macOS ARM64:
+    * 'fluidsynth' was found at /opt/homebrew/opt/fluid-synth/lib/libfluidsynth.dylib.
+    Ubuntu X86:
+    * 'fluidsynth' was found at libfluidsynth.so.3.
+    Windows X86:
+    * 'libfluidsynth-3' was found at C:\tools\fluidsynth\bin\libfluidsynth-3.dll. --or--
+    * 'fluidsynth-3' was found as C:\tools\fluidsynth\bin\fluidsynth-3.dll. >= v2.4.5
+        * https://github.com/FluidSynth/fluidsynth/issues/1543
+    """
+    libs = "fluidsynth fluidsynth-3 libfluidsynth libfluidsynth-3 libfluidsynth-2 libfluidsynth-1"
+    for lib_name in libs.split():
+        lib = find_library(lib_name)
+        if lib:
+            if debug_print:
+                print(f"'{lib_name}' was found at {lib}.")
+            return lib
+
+    # On macOS on Apple silicon, non-Homebrew Python distributions fail to locate
+    # homebrew-installed instances of FluidSynth. This workaround addresses this.
+    if homebrew_prefix := os.getenv("HOMEBREW_PREFIX"):
+        lib = os.path.join(homebrew_prefix, "lib", "libfluidsynth.dylib")
+        if os.path.exists(lib):
+            return lib
 
-if lib is None:
     raise ImportError("Couldn't find the FluidSynth library.")
 
+lib = find_libfluidsynth()
+
 # Dynamically link the FluidSynth library
 # Architecture (32-/64-bit) must match your Python version
 _fl = CDLL(lib)
@@ -1829,7 +1869,7 @@ def cfunc(name, result, *args):
         return None
 
 # Bump this up when changing the interface for users
-api_version = '1.3.1'
+api_version = '1.3.5'
 
 # Function prototypes for C versions of functions
 
@@ -1843,10 +1883,7 @@ fluid_version = cfunc('fluid_version', c_void_p,
 
 majver = c_int()
 fluid_version(majver, c_int(), c_int())
-if majver.value > 1:
-    FLUIDSETTING_EXISTS = FLUID_OK
-else:
-    FLUIDSETTING_EXISTS = 1
+FLUIDSETTING_EXISTS = FLUID_OK if majver.value > 1 else 1
 
 # fluid settings
 new_fluid_settings = cfunc('new_fluid_settings', c_void_p)
@@ -2086,9 +2123,18 @@ fluid_synth_set_chorus_level = cfunc('fluid_synth_set_chorus_level', c_int,
                                     ('synth', c_void_p, 1),
                                     ('level', c_double, 1))
 
+fluid_synth_set_chorus_speed = cfunc('fluid_synth_set_chorus_speed', c_int,
+                                    ('synth', c_void_p, 1),
+                                    ('speed', c_double, 1))
+
+fluid_synth_set_chorus_depth = cfunc('fluid_synth_set_chorus_depth', c_int,
+                                    ('synth', c_void_p, 1),
+                                    ('depth_ms', c_double, 1))
+
 fluid_synth_set_chorus_type = cfunc('fluid_synth_set_chorus_type', c_int,
                                     ('synth', c_void_p, 1),
                                     ('type', c_int, 1))
+
 fluid_synth_get_reverb_roomsize = cfunc('fluid_synth_get_reverb_roomsize', c_double,
                                     ('synth', c_void_p, 1))
 
@@ -2220,6 +2266,77 @@ fluid_midi_event_get_value = cfunc('fluid_midi_event_get_value', c_int,
 fluid_midi_event_get_velocity = cfunc('fluid_midi_event_get_velocity', c_int,
                                   ('evt', c_void_p, 1))
 
+# fluid modulator
+new_fluid_mod = cfunc("new_fluid_mod", c_void_p)
+
+delete_fluid_mod = cfunc("delete_fluid_mod", c_void_p, ("mod", c_void_p, 1))
+
+fluid_mod_clone = cfunc(
+    "fluid_mod_clone", c_void_p, ("mod", c_void_p, 1), ("src", c_void_p, 1),
+)
+
+fluid_mod_get_amount = cfunc("fluid_mod_get_amount", c_void_p, ("mod", c_void_p, 1))
+
+fluid_mod_get_dest = cfunc("fluid_mod_get_dest", c_void_p, ("mod", c_void_p, 1))
+
+fluid_mod_get_flags1 = cfunc("fluid_mod_get_flags1", c_void_p, ("mod", c_void_p, 1))
+
+fluid_mod_get_flags2 = cfunc("fluid_mod_get_flags2", c_void_p, ("mod", c_void_p, 1))
+
+fluid_mod_get_source1 = cfunc("fluid_mod_get_source1", c_void_p, ("mod", c_void_p, 1))
+
+fluid_mod_get_source2 = cfunc("fluid_mod_get_source2", c_void_p, ("mod", c_void_p, 1))
+
+fluid_mod_get_transform = cfunc(
+    "fluid_mod_get_transform", c_void_p, ("mod", c_void_p, 1),
+)
+
+fluid_mod_has_dest = cfunc(
+    "fluid_mod_has_dest", c_void_p, ("mod", c_void_p, 1), ("gen", c_uint, 1),
+)
+
+fluid_mod_has_source = cfunc(
+    "fluid_mod_has_dest",
+    c_void_p,
+    ("mod", c_void_p, 1),
+    ("cc", c_uint, 1),
+    ("ctrl", c_uint, 1),
+)
+
+fluid_mod_set_amount = cfunc(
+    "fluid_mod_set_amount", c_void_p, ("mod", c_void_p, 1), ("amount", c_double, 1),
+)
+
+fluid_mod_set_dest = cfunc(
+    "fluid_mod_set_dest", c_void_p, ("mod", c_void_p, 1), ("dst", c_int, 1),
+)
+
+fluid_mod_set_source1 = cfunc(
+    "fluid_mod_set_source1",
+    c_void_p,
+    ("mod", c_void_p, 1),
+    ("src", c_int, 1),
+    ("flags", c_int, 1),
+)
+
+fluid_mod_set_source2 = cfunc(
+    "fluid_mod_set_source2",
+    c_void_p,
+    ("mod", c_void_p, 1),
+    ("src", c_int, 1),
+    ("flags", c_int, 1),
+)
+
+fluid_mod_set_transform = cfunc(
+    "fluid_mod_set_transform", c_void_p, ("mod", c_void_p, 1), ("type", c_int, 1),
+)
+
+fluid_mod_sizeof = cfunc("fluid_mod_sizeof", c_void_p)
+
+fluid_mod_test_identity = cfunc(
+    "fluid_mod_test_identity", c_void_p, ("mod1", c_void_p, 1), ("mod2", c_void_p, 1),
+)
+
 # fluid_player_status returned by fluid_player_get_status()
 FLUID_PLAYER_READY = 0
 FLUID_PLAYER_PLAYING = 1
@@ -2281,6 +2398,9 @@ new_fluid_midi_driver = cfunc('new_fluid_midi_driver', c_void_p,
                                ('handler', CFUNCTYPE(c_int, c_void_p, c_void_p), 1),
                                ('event_handler_data', c_void_p, 1))
 
+delete_fluid_midi_driver = cfunc('delete_fluid_midi_driver', None,
+                           ('driver', c_void_p, 1))
+
 
 # fluid midi router rule
 class fluid_midi_router_t(Structure):
@@ -2342,6 +2462,16 @@ fluid_midi_router_add_rule = cfunc('fluid_midi_router_add_rule', c_int,
                                     ('rule', c_void_p, 1),
                                     ('type', c_int, 1))
 
+# fluid file renderer
+new_fluid_file_renderer = cfunc('new_fluid_file_renderer', c_void_p,
+                                ('synth', c_void_p, 1))
+
+delete_fluid_file_renderer = cfunc('delete_fluid_file_renderer', None,
+                                   ('renderer', c_void_p, 1))
+
+fluid_file_renderer_process_block = cfunc('fluid_file_renderer_process_block', c_int,
+                                          ('render', c_void_p, 1))
+
 # fluidsynth 2.x
 new_fluid_cmd_handler=cfunc('new_fluid_cmd_handler', c_void_p,
                                ('synth', c_void_p, 1),
@@ -2416,6 +2546,7 @@ class Synth:
         self.audio_driver = None
         self.midi_driver = None
         self.router = None
+        self.custom_router_callback = None
     def setting(self, opt, val):
         """change an arbitrary synth setting, type-smart"""
         if isinstance(val, (str, bytes)):
@@ -2451,11 +2582,11 @@ class Synth:
         see http://www.fluidsynth.org/api/fluidsettings.xml for allowed values and defaults by platform
         """
         driver = driver or self.get_setting('audio.driver')
-        device = device or self.get_setting('audio.%s.device' % driver)
+        device = device or self.get_setting(f'audio.{driver}.device')
         midi_driver = midi_driver or self.get_setting('midi.driver')
 
         self.setting('audio.driver', driver)
-        self.setting('audio.%s.device' % driver, device)
+        self.setting(f'audio.{driver}.device', device)
         self.audio_driver = new_fluid_audio_driver(self.settings, self.synth)
         self.setting('midi.driver', midi_driver)
         self.router = new_fluid_midi_router(self.settings, fluid_synth_handle_midi_event, self.synth)
@@ -2463,7 +2594,7 @@ class Synth:
             new_fluid_cmd_handler(self.synth, self.router)
         else:
             fluid_synth_set_midi_router(self.synth, self.router)
-        if midi_router == None: ## Use fluidsynth to create a MIDI event handler
+        if midi_router is None: ## Use fluidsynth to create a MIDI event handler
             self.midi_driver = new_fluid_midi_driver(self.settings, fluid_midi_router_handle_midi_event, self.router)
             self.custom_router_callback = None
         else:                   ## Supply an external MIDI event handler
@@ -2474,6 +2605,8 @@ class Synth:
     def delete(self):
         if self.audio_driver:
             delete_fluid_audio_driver(self.audio_driver)
+        if self.midi_driver:
+            delete_fluid_midi_driver(self.midi_driver)
         delete_fluid_synth(self.synth)
         delete_fluid_settings(self.settings)
     def sfload(self, filename, update_midi_preset=0):
@@ -2518,8 +2651,7 @@ class Synth:
                 return None
             return fluid_preset_get_name(preset).decode('ascii')
         else:
-            (sfontid, banknum, presetnum, presetname) = self.channel_info(chan)
-            return presetname
+            return None
     def router_clear(self):
         if self.router is not None:
             fluid_midi_router_clear_rules(self.router)
@@ -2570,16 +2702,16 @@ class Synth:
         if fluid_synth_set_reverb is not None:
             return fluid_synth_set_reverb(self.synth, roomsize, damping, width, level)
         else:
-            set=0
+            flags=0
             if roomsize>=0:
-                set+=0b0001
+                flags+=0b0001
             if damping>=0:
-                set+=0b0010
+                flags+=0b0010
             if width>=0:
-                set+=0b0100
+                flags+=0b0100
             if level>=0:
-                set+=0b1000
-            return fluid_synth_set_reverb_full(self.synth, set, roomsize, damping, width, level)
+                flags+=0b1000
+            return fluid_synth_set_reverb_full(self.synth, flags, roomsize, damping, width, level)
     def set_chorus(self, nr=-1, level=-1.0, speed=-1.0, depth=-1.0, type=-1):
         """
         nr Chorus voice count (0-99, CPU time consumption proportional to this value)
@@ -2632,17 +2764,17 @@ class Synth:
         if fluid_synth_set_chorus_level is not None:
             return fluid_synth_set_chorus_level(self.synth, level)
         else:
-            return self.set_chorus(leve=level)
+            return self.set_chorus(level=level)
     def set_chorus_speed(self, speed):
         if fluid_synth_set_chorus_speed is not None:
             return fluid_synth_set_chorus_speed(self.synth, speed)
         else:
             return self.set_chorus(speed=speed)
-    def set_chorus_depth(self, depth):
+    def set_chorus_depth(self, depth_ms):
         if fluid_synth_set_chorus_depth is not None:
-            return fluid_synth_set_chorus_depth(self.synth, depth)
+            return fluid_synth_set_chorus_depth(self.synth, depth_ms)
         else:
-            return self.set_chorus(depth=depth)
+            return self.set_chorus(depth=depth_ms)
     def set_chorus_type(self, type):
         if fluid_synth_set_chorus_type is not None:
             return fluid_synth_set_chorus_type(self.synth, type)
@@ -2694,10 +2826,10 @@ class Synth:
         A pitch bend value of 0 is no pitch change from default.
         A value of -2048 is 1 semitone down.
         A value of 2048 is 1 semitone up.
-        Maximum values are -8192 to +8192 (transposing by 4 semitones).
+        Maximum values are -8192 to +8191 (transposing by 4 semitones).
 
         """
-        return fluid_synth_pitch_bend(self.synth, chan, val + 8192)
+        return fluid_synth_pitch_bend(self.synth, chan, max(0, min(val + 8192, 16383)))
     def cc(self, chan, ctrl, val):
         """Send control change value
 
@@ -2747,8 +2879,15 @@ class Synth:
 
         """
         return fluid_synth_write_s16_stereo(self.synth, len)
-    def tuning_dump(self, bank, prog, pitch):
-        return fluid_synth_tuning_dump(self.synth, bank, prog, name.encode(), length(name), pitch)
+    def tuning_dump(self, bank, prog):
+        """Get tuning information for given bank and preset
+
+        Return value is an array of length 128 with tuning factors for each MIDI note.
+        Tuning factor of 0.0 in each position is standard tuning. Measured in cents.
+        """
+        pitch = (c_double * 128)()
+        fluid_synth_tuning_dump(self.synth, bank, prog, None, 0, pitch)
+        return pitch[:]
 
     def midi_event_get_type(self, event):
         return fluid_midi_event_get_type(event)
@@ -2767,17 +2906,20 @@ class Synth:
 
     def play_midi_file(self, filename):
         self.player = new_fluid_player(self.synth)
-        if self.player == None: return FLUID_FAILED
-        if self.custom_router_callback != None:
+        if self.player is None:
+            return FLUID_FAILED
+        if self.custom_router_callback is not None:
             fluid_player_set_playback_callback(self.player, self.custom_router_callback, self.synth)
         status = fluid_player_add(self.player, filename.encode())
-        if status == FLUID_FAILED: return status
+        if status == FLUID_FAILED:
+            return status
         status = fluid_player_play(self.player)
         return status
 
     def play_midi_stop(self):
         status = fluid_player_stop(self.player)
-        if status == FLUID_FAILED: return status
+        if status == FLUID_FAILED:
+            return status
         status = fluid_player_seek(self.player, 0)
         delete_fluid_player(self.player)
         return status
@@ -2785,7 +2927,151 @@ class Synth:
     def player_set_tempo(self, tempo_type, tempo):
         return fluid_player_set_tempo(self.player, tempo_type, tempo)
 
+    def midi2audio(self, midifile, audiofile = "output.wav"):
+        """Convert a midi file to an audio file"""
+        self.setting("audio.file.name", audiofile)
+        player = new_fluid_player(self.synth)
+        fluid_player_add(player, midifile.encode())
+        fluid_player_play(player)
+        renderer = new_fluid_file_renderer(self.synth)
+        while fluid_player_get_status(player) == FLUID_PLAYER_PLAYING:
+            if fluid_file_renderer_process_block(renderer) != FLUID_OK:
+                break
+        delete_fluid_file_renderer(renderer)
+        delete_fluid_player(player)
+
+# flag values
+FLUID_MOD_POSITIVE = 0
+FLUID_MOD_NEGATIVE = 1
+FLUID_MOD_UNIPOLAR = 0
+FLUID_MOD_BIPOLAR = 2
+FLUID_MOD_LINEAR = 0
+FLUID_MOD_CONCAVE = 4
+FLUID_MOD_CONVEX = 8
+FLUID_MOD_SWITCH = 12
+FLUID_MOD_GC = 0
+FLUID_MOD_CC = 16
+FLUID_MOD_SIN = 0x80
+
+# src values
+FLUID_MOD_NONE = 0
+FLUID_MOD_VELOCITY = 2
+FLUID_MOD_KEY = 3
+FLUID_MOD_KEYPRESSURE = 10
+FLUID_MOD_CHANNELPRESSURE = 13
+FLUID_MOD_PITCHWHEEL = 14
+FLUID_MOD_PITCHWHEELSENS = 16
+
+# Transforms
+FLUID_MOD_TRANSFORM_LINEAR = 0
+FLUID_MOD_TRANSFORM_ABS = 2
+
+class Modulator:
+    def __init__(self):
+        """Create new modulator object"""
+        self.mod = new_fluid_mod()
+
+    def clone(self, src):
+        response = fluid_mod_clone(self.mod, src)
+        if response == FLUID_FAILED:
+            raise Exception("Modulation clone failed")
+        return response
 
+    def get_amount(self):
+        response = fluid_mod_get_amount(self.mod)
+        if response == FLUID_FAILED:
+            raise Exception("Modulation amount get failed")
+        return response
+
+    def get_dest(self):
+        response = fluid_mod_get_dest(self.mod)
+        if response == FLUID_FAILED:
+            raise Exception("Modulation destination get failed")
+        return response
+
+    def get_flags1(self):
+        response = fluid_mod_get_flags1(self.mod)
+        if response == FLUID_FAILED:
+            raise Exception("Modulation flags1 get failed")
+        return response
+
+    def get_flags2(self):
+        response = fluid_mod_get_flags2(self.mod)
+        if response == FLUID_FAILED:
+            raise Exception("Modulation flags2 get failed")
+        return response
+
+    def get_source1(self):
+        response = fluid_mod_get_source1(self.mod)
+        if response == FLUID_FAILED:
+            raise Exception("Modulation source1 get failed")
+        return response
+
+    def get_source2(self):
+        response = fluid_mod_get_source2(self.mod)
+        if response == FLUID_FAILED:
+            raise Exception("Modulation source2 get failed")
+        return response
+
+    def get_transform(self):
+        response = fluid_mod_get_transform(self.mod)
+        if response == FLUID_FAILED:
+            raise Exception("Modulation transform get failed")
+        return response
+
+    def has_dest(self, gen):
+        response = fluid_mod_has_dest(self.mod, gen)
+        if response == FLUID_FAILED:
+            raise Exception("Modulation has destination check failed")
+        return response
+
+    def has_source(self, cc, ctrl):
+        response = fluid_mod_has_source(self.mod, cc, ctrl)
+        if response == FLUID_FAILED:
+            raise Exception("Modulation has source check failed")
+        return response
+
+    def set_amount(self, amount):
+        response = fluid_mod_set_amount(self.mod, amount)
+        if response == FLUID_FAILED:
+            raise Exception("Modulation set amount failed")
+        return response
+
+    def set_dest(self, dest):
+        response = fluid_mod_set_dest(self.mod, dest)
+        if response == FLUID_FAILED:
+            raise Exception("Modulation set dest failed")
+        return response
+
+    def set_source1(self, src, flags):
+        response = fluid_mod_set_source1(self.mod, src, flags)
+        if response == FLUID_FAILED:
+            raise Exception("Modulation set source 1 failed")
+        return response
+
+    def set_source2(self, src, flags):
+        response = fluid_mod_set_source2(self.mod, src, flags)
+        if response == FLUID_FAILED:
+            raise Exception("Modulation set source 2 failed")
+        return response
+
+    def set_transform(self, type):
+        response = fluid_mod_set_transform(self.mod, type)
+        if response == FLUID_FAILED:
+            raise Exception("Modulation set transform failed")
+        return response
+
+    def sizeof(self):
+        response = fluid_mod_sizeof()
+        if response == FLUID_FAILED:
+            raise Exception("Modulation sizeof failed")
+        return response
+
+    def test_identity(self, mod2):
+        response = fluid_mod_sizeof(self.mod, mod2)
+        if response == FLUID_FAILED:
+            raise Exception("Modulation identity check failed")
+        return response
 
 class Sequencer:
     def __init__(self, time_scale=1000, use_system_timer=True):
@@ -2802,14 +3088,14 @@ class Sequencer:
     def register_fluidsynth(self, synth):
         response = fluid_sequencer_register_fluidsynth(self.sequencer, synth.synth)
         if response == FLUID_FAILED:
-            raise Error("Registering fluid synth failed")
+            raise Exception("Registering fluid synth failed")
         return response
 
     def register_client(self, name, callback, data=None):
         c_callback = CFUNCTYPE(None, c_uint, c_void_p, c_void_p, c_void_p)(callback)
         response = fluid_sequencer_register_client(self.sequencer, name.encode(), c_callback, data)
         if response == FLUID_FAILED:
-            raise Error("Registering client failed")
+            raise Exception("Registering client failed")
 
         # store in a list to prevent garbage collection
         self.client_callbacks.append(c_callback)
@@ -2849,7 +3135,7 @@ class Sequencer:
     def _schedule_event(self, evt, time, absolute=True):
         response = fluid_sequencer_send_at(self.sequencer, evt, time, absolute)
         if response == FLUID_FAILED:
-            raise Error("Scheduling event failed")
+            raise Exception("Scheduling event failed")
 
     def get_tick(self):
         return fluid_sequencer_get_tick(self.sequencer)
@@ -2868,123 +3154,307 @@ def raw_audio_string(data):
 
     """
     import numpy
-    return (data.astype(numpy.int16)).tostring()
+    return (data.astype(numpy.int16)).tobytes()
 
 #===============================================================================
 
 import numpy as np
 import wave
 
-def midi_opus_to_colab_audio(midi_opus, 
-                              soundfont_path='/usr/share/sounds/sf2/FluidR3_GM.sf2', 
-                              sample_rate=16000, # 44100
-                              volume_scale=10,
-                              trim_silence=True,
-                              silence_threshold=0.1,
-                              output_for_gradio=False,
-                              write_audio_to_WAV=''
-                              ):
-
-    def normalize_volume(matrix, factor=10):
-        norm = np.linalg.norm(matrix)
-        matrix = matrix/norm  # normalized matrix
-        mult_matrix = matrix * factor
-        final_matrix = np.clip(mult_matrix, -1.0, 1.0)
-        return final_matrix
+#===============================================================================
 
-    if midi_opus[1]:
+def normalize_audio(audio: np.ndarray,
+                    method: str = 'peak',
+                    target_level_db: float = -1.0,
+                    per_channel: bool = False,
+                    eps: float = 1e-9
+                   ) -> np.ndarray:
+    
+    """
+    Normalize audio to a target dBFS level.
+
+    Parameters
+    ----------
+    audio : np.ndarray
+        Float-valued array in range [-1, 1] with shape (channels, samples)
+        or (samples,) for mono.
+    method : {'peak', 'rms'}
+        - 'peak': scale so that max(|audio|) = target_level_lin  
+        - 'rms' : scale so that RMS(audio) = target_level_lin
+    target_level_db : float
+        Desired output level, in dBFS (0 dBFS = max digital full scale).
+        e.g. -1.0 dBFS means ~0.8913 linear gain.
+    per_channel : bool
+        If True, normalize each channel independently. Otherwise, use a
+        global measure across all channels.
+    eps : float
+        Small constant to avoid division by zero.
+
+    Returns
+    -------
+    normalized : np.ndarray
+        Audio array of same shape, scaled so that levels meet the target.
+    """
+    
+    # Convert target dB to linear gain
+    target_lin = 10 ** (target_level_db / 20.0)
 
-      ticks_per_beat = midi_opus[0]
-      event_list = []
-      for track_idx, track in enumerate(midi_opus[1:]):
-          abs_t = 0
-          for event in track:
-              abs_t += event[1]
-              event_new = [*event]
-              event_new[1] = abs_t
-              event_list.append(event_new)
-      event_list = sorted(event_list, key=lambda e: e[1])
-
-      tempo = int((60 / 120) * 10 ** 6)  # default 120 bpm
-      ss = np.empty((0, 2), dtype=np.int16)
-      fl = Synth(samplerate=float(sample_rate))
-      sfid = fl.sfload(soundfont_path)
-      last_t = 0
-      for c in range(16):
-          fl.program_select(c, sfid, 128 if c == 9 else 0, 0)
-      for event in event_list:
-          name = event[0]
-          sample_len = int(((event[1] / ticks_per_beat) * tempo / (10 ** 6)) * sample_rate)
-          sample_len -= int(((last_t / ticks_per_beat) * tempo / (10 ** 6)) * sample_rate)
-          last_t = event[1]
-          if sample_len > 0:
-              sample = fl.get_samples(sample_len).reshape(sample_len, 2)
-              ss = np.concatenate([ss, sample])
-          if name == "set_tempo":
-              tempo = event[2]
-          elif name == "patch_change":
-              c, p = event[2:4]
-              fl.program_select(c, sfid, 128 if c == 9 else 0, p)
-          elif name == "control_change":
-              c, cc, v = event[2:5]
-              fl.cc(c, cc, v)
-          elif name == "note_on" and event[3] > 0:
-              c, p, v = event[2:5]
-              fl.noteon(c, p, v)
-          elif name == "note_off" or (name == "note_on" and event[3] == 0):
-              c, p = event[2:4]
-              fl.noteoff(c, p)
-
-      fl.delete()
-      if ss.shape[0] > 0:
-          max_val = np.abs(ss).max()
-          if max_val != 0:
-              ss = (ss / max_val) * np.iinfo(np.int16).max
-      ss = ss.astype(np.int16)
-
-      if trim_silence:
-          threshold = np.std(np.abs(ss)) * silence_threshold
-          exceeded_thresh = np.abs(ss) > threshold
-          if np.any(exceeded_thresh): 
-              last_idx = np.where(exceeded_thresh)[0][-1]
-              ss = ss[:last_idx+1]
-
-      if output_for_gradio:
-        return ss
-      
-      ss = ss.swapaxes(1, 0)
+    # Ensure audio is float
+    audio = audio.astype(np.float32)
 
-      raw_audio = normalize_volume(ss, volume_scale)
-      
-      if write_audio_to_WAV != '':
+    # if mono, make it (1, N)
+    if audio.ndim == 1:
+        audio = audio[np.newaxis, :]
 
-        r_audio = raw_audio.T
+    # Choose measurement axis
+    axis = 1 if per_channel else None
 
-        r_audio = np.int16(r_audio / np.max(np.abs(r_audio)) * 32767)
+    if method == 'peak':
+        # Compute peak per channel or global
+        peak = np.max(np.abs(audio), axis=axis, keepdims=True)
+        peak = np.maximum(peak, eps)
+        scales = target_lin / peak
 
-        with wave.open(write_audio_to_WAV, 'w') as wf:
-            wf.setframerate(sample_rate)
-            wf.setsampwidth(2)
-            wf.setnchannels(r_audio.shape[1])
-            wf.writeframes(r_audio)
+    elif method == 'rms':
+        # Compute RMS per channel or global
+        rms = np.sqrt(np.mean(audio ** 2, axis=axis, keepdims=True))
+        rms = np.maximum(rms, eps)
+        scales = target_lin / rms
+
+    else:
+        raise ValueError(f"Unsupported method '{method}'; choose 'peak' or 'rms'.")
 
-      return raw_audio
+    # Broadcast scales back to audio shape
+    normalized = audio * scales
+
+    # Clip just in case of rounding
+    return np.clip(normalized, -1.0, 1.0)
+
+#===============================================================================
+
+def midi_opus_to_colab_audio(midi_opus, 
+                             soundfont_path='/usr/share/sounds/sf2/FluidR3_GM.sf2', 
+                             sample_rate=16000, # 44100
+                             volume_level_db=-1,
+                             trim_silence=True,
+                             silence_threshold=0.1,
+                             enable_reverb=False,
+                             reverb_param_dic={'roomsize': 0,
+                                               'damping': 0,
+                                               'width': 0,
+                                               'level': 0
+                                              },
+                             enable_chorus=False,
+                             chorus_param_dic={'nr': 0,
+                                               'level': 0,
+                                               'speed': 0.1,
+                                               'depth': 0,
+                                               'type': 0},
+                             output_for_gradio=False,
+                             write_audio_to_WAV=False,
+                             output_WAV_name=''
+                            ):
+
+    if midi_opus[1]:
+
+        ticks_per_beat, *tracks = midi_opus
+        if not tracks:
+            return None
+    
+        # Flatten & convert delta-times to absolute-time
+        events = []
+        for track in tracks:
+            abs_t = 0
+            for name, dt, *data in track:
+                abs_t += dt
+                events.append([name, abs_t, *data])
+        events.sort(key=lambda e: e[1])
+    
+        # Setup FluidSynth
+        fl = Synth(samplerate=float(sample_rate))
+        sfid = fl.sfload(soundfont_path)
+        for chan in range(16):
+            # channel 9 = percussion GM bank 128
+            fl.program_select(chan, sfid, 128 if chan == 9 else 0, 0)
+            
+        if enable_reverb:
+            fl.set_reverb(roomsize=reverb_param_dic['roomsize'], 
+                          damping=reverb_param_dic['damping'], 
+                          width=reverb_param_dic['width'],
+                          level=reverb_param_dic['level']
+                         )
+            
+            """
+            roomsize Reverb room size value (0.0-1.0)
+            damping Reverb damping value (0.0-1.0)
+            width Reverb width value (0.0-100.0)
+            level Reverb level value (0.0-1.0)
+            """
+    
+        if enable_chorus:
+            fl.set_chorus(nr=chorus_param_dic['nr'],
+                          level=chorus_param_dic['level'],
+                          speed=chorus_param_dic['speed'],
+                          depth=chorus_param_dic['depth'],
+                          type=chorus_param_dic['type']
+                         )
+        
+        """
+        nr Chorus voice count (0-99, CPU time consumption proportional to this value)
+        level Chorus level (0.0-10.0)
+        speed Chorus speed in Hz (0.29-5.0)
+        depth_ms Chorus depth (max value depends on synth sample rate, 0.0-21.0 is safe for sample rate values up to 96KHz)
+        type Chorus waveform type (0=sine, 1=triangle)
+        """
+        
+        # Playback vars
+        tempo = int((60 / 120) * 1e6)  # default 120bpm
+        last_t = 0
+        ss = np.empty((0, 2), dtype=np.int16)
+    
+        for name, cur_t, *data in events:
+            # compute how many samples have passed since the last event
+            delta_ticks = cur_t - last_t
+            last_t = cur_t
+            dt_seconds = (delta_ticks / ticks_per_beat) * (tempo / 1e6)
+            sample_len = int(dt_seconds * sample_rate)
+            if sample_len > 0:
+                buf = fl.get_samples(sample_len).reshape(-1, 2)
+                ss = np.concatenate([ss, buf], axis=0)
+    
+            # Dispatch every known event
+            if name == "note_on" and data[2] > 0:
+                chan, note, vel = data
+                fl.noteon(chan, note, vel)
+    
+            elif name == "note_off" or (name == "note_on" and data[2] == 0):
+                chan, note = data[:2]
+                fl.noteoff(chan, note)
+    
+            elif name == "patch_change":
+                chan, patch = data[:2]
+                bank = 128 if chan == 9 else 0
+                fl.program_select(chan, sfid, bank, patch)
+    
+            elif name == "control_change":
+                chan, ctrl, val = data[:3]
+                fl.cc(chan, ctrl, val)
+    
+            elif name == "key_after_touch":
+                chan, note, vel = data
+                # fl.key_pressure(chan, note, vel)
+    
+            elif name == "channel_after_touch":
+                chan, vel = data
+                # fl.channel_pressure(chan, vel)
+    
+            elif name == "pitch_wheel_change":
+                chan, wheel = data
+                fl.pitch_bend(chan, wheel)
+    
+            elif name == "song_position":
+                # song_pos = data[0];  # often not needed for playback
+                pass
+    
+            elif name == "song_select":
+                # song_number = data[0]
+                pass
+    
+            elif name == "tune_request":
+                # typically resets tuning; FS handles internally
+                pass
+    
+            elif name in ("sysex_f0", "sysex_f7"):
+                raw_bytes = data[0]
+                # fl.sysex(raw_bytes)
+                pass
+    
+            # Meta events & others—no direct audio effect, so we skip or log
+            elif name in (
+                "set_tempo",       # handled below
+                "end_track",
+                "text_event", "text_event_08", "text_event_09", "text_event_0a",
+                "text_event_0b", "text_event_0c", "text_event_0d", "text_event_0e", "text_event_0f",
+                "copyright_text_event", "track_name", "instrument_name",
+                "lyric", "marker", "cue_point",
+                "smpte_offset", "time_signature", "key_signature",
+                "sequencer_specific", "raw_meta_event"
+            ):
+                if name == "set_tempo":
+                    tempo = data[0]
+                # else: skip all other meta & text; you could hook in logging here
+                continue
+    
+            else:
+                # unknown event type
+                continue
+    
+        # Cleanup synth
+        fl.delete()
+    
+        if ss.size:
+            maxv = np.abs(ss).max()
+            if maxv:
+                ss = (ss / maxv) * np.iinfo(np.int16).max
+        ss = ss.astype(np.int16)
+    
+        # Optional trimming of trailing silence
+        if trim_silence and ss.size:
+            thresh = np.std(np.abs(ss)) * silence_threshold
+            idx = np.where(np.abs(ss) > thresh)[0]
+            if idx.size:
+                ss = ss[: idx[-1] + 1]
+    
+        # For Gradio you might want raw int16 PCM
+        if output_for_gradio:
+            return ss
+    
+        # Swap to (channels, samples) and normalize for playback
+        ss = ss.T
+        raw_audio = normalize_audio(ss, target_level_db=volume_level_db)
+    
+        # Optionally write WAV to disk
+        if write_audio_to_WAV:
+            wav_name = midi_file.rsplit('.', 1)[0] + '.wav'
+            if output_WAV_name != '':
+                wav_name = output_WAV_name
+            pcm = np.int16(raw_audio.T / np.max(np.abs(raw_audio)) * 32767)
+            with wave.open(wav_name, 'wb') as wf:
+                wf.setframerate(sample_rate)
+                wf.setsampwidth(2)
+                wf.setnchannels(pcm.shape[1])
+                wf.writeframes(pcm.tobytes())
+    
+        return raw_audio
   
     else:
       return None
 
-def midi_to_colab_audio(midi_file, 
-                        soundfont_path='/usr/share/sounds/sf2/FluidR3_GM.sf2', 
-                        sample_rate=16000, # 44100
-                        volume_scale=10,
+#===============================================================================
+
+def midi_to_colab_audio(midi_file,
+                        soundfont_path='/usr/share/sounds/sf2/FluidR3_GM.sf2',
+                        sample_rate=16000,
+                        volume_level_db=-1,
                         trim_silence=True,
                         silence_threshold=0.1,
+                        enable_reverb=False,
+                        reverb_param_dic={'roomsize': 0,
+                                          'damping': 0,
+                                          'width': 0,
+                                          'level': 0
+                                         },
+                        enable_chorus=False,
+                        chorus_param_dic={'nr': 0,
+                                          'level': 0,
+                                          'speed': 0.1,
+                                          'depth': 0,
+                                          'type': 0},
                         output_for_gradio=False,
-                        write_audio_to_WAV=False
-                        ):
-
-    '''
-    
+                        write_audio_to_WAV=False,
+                        output_WAV_name=''
+                       ):
+    """
     Returns raw audio to pass to IPython.disaply.Audio func
 
     Example usage:
@@ -2992,99 +3462,176 @@ def midi_to_colab_audio(midi_file,
     from IPython.display import Audio
 
     display(Audio(raw_audio, rate=16000, normalize=False))
-    
-    '''
-
-    def normalize_volume(matrix, factor=10):
-        norm = np.linalg.norm(matrix)
-        matrix = matrix/norm  # normalized matrix
-        mult_matrix = matrix * factor
-        final_matrix = np.clip(mult_matrix, -1.0, 1.0)
-        return final_matrix
-
-    midi_opus = midi2opus(open(midi_file, 'rb').read())
+    """
 
-    if midi_opus[1]:
+    # Read and decode MIDI → opus event list
+    ticks_per_beat, *tracks = midi2opus(open(midi_file, 'rb').read())
+    if not tracks:
+        return None
 
-      ticks_per_beat = midi_opus[0]
-      event_list = []
-      for track_idx, track in enumerate(midi_opus[1:]):
-          abs_t = 0
-          for event in track:
-              abs_t += event[1]
-              event_new = [*event]
-              event_new[1] = abs_t
-              event_list.append(event_new)
-      event_list = sorted(event_list, key=lambda e: e[1])
-
-      tempo = int((60 / 120) * 10 ** 6)  # default 120 bpm
-      ss = np.empty((0, 2), dtype=np.int16)
-      fl = Synth(samplerate=float(sample_rate))
-      sfid = fl.sfload(soundfont_path)
-      last_t = 0
-      for c in range(16):
-          fl.program_select(c, sfid, 128 if c == 9 else 0, 0)
-      for event in event_list:
-          name = event[0]
-          sample_len = int(((event[1] / ticks_per_beat) * tempo / (10 ** 6)) * sample_rate)
-          sample_len -= int(((last_t / ticks_per_beat) * tempo / (10 ** 6)) * sample_rate)
-          last_t = event[1]
-          if sample_len > 0:
-              sample = fl.get_samples(sample_len).reshape(sample_len, 2)
-              ss = np.concatenate([ss, sample])
-          if name == "set_tempo":
-              tempo = event[2]
-          elif name == "patch_change":
-              c, p = event[2:4]
-              fl.program_select(c, sfid, 128 if c == 9 else 0, p)
-          elif name == "control_change":
-              c, cc, v = event[2:5]
-              fl.cc(c, cc, v)
-          elif name == "note_on" and event[3] > 0:
-              c, p, v = event[2:5]
-              fl.noteon(c, p, v)
-          elif name == "note_off" or (name == "note_on" and event[3] == 0):
-              c, p = event[2:4]
-              fl.noteoff(c, p)
-
-      fl.delete()
-      if ss.shape[0] > 0:
-          max_val = np.abs(ss).max()
-          if max_val != 0:
-              ss = (ss / max_val) * np.iinfo(np.int16).max
-      ss = ss.astype(np.int16)
-
-      if trim_silence:
-          threshold = np.std(np.abs(ss)) * silence_threshold
-          exceeded_thresh = np.abs(ss) > threshold
-          if np.any(exceeded_thresh): 
-              last_idx = np.where(exceeded_thresh)[0][-1]
-              ss = ss[:last_idx+1]
-
-      if output_for_gradio:
-        return ss
+    # Flatten & convert delta-times to absolute-time
+    events = []
+    for track in tracks:
+        abs_t = 0
+        for name, dt, *data in track:
+            abs_t += dt
+            events.append([name, abs_t, *data])
+    events.sort(key=lambda e: e[1])
+
+    # Setup FluidSynth
+    fl = Synth(samplerate=float(sample_rate))
+    sfid = fl.sfload(soundfont_path)
+    for chan in range(16):
+        # channel 9 = percussion GM bank 128
+        fl.program_select(chan, sfid, 128 if chan == 9 else 0, 0)
+
+    if enable_reverb:
+        fl.set_reverb(roomsize=reverb_param_dic['roomsize'], 
+                      damping=reverb_param_dic['damping'], 
+                      width=reverb_param_dic['width'],
+                      level=reverb_param_dic['level']
+                     )
+        
+        """
+        roomsize Reverb room size value (0.0-1.0)
+        damping Reverb damping value (0.0-1.0)
+        width Reverb width value (0.0-100.0)
+        level Reverb level value (0.0-1.0)
+        """
 
-      ss = ss.swapaxes(1, 0)
+    if enable_chorus:
+        fl.set_chorus(nr=chorus_param_dic['nr'],
+                      level=chorus_param_dic['level'],
+                      speed=chorus_param_dic['speed'],
+                      depth=chorus_param_dic['depth'],
+                      type=chorus_param_dic['type']
+                     )
+    
+    """
+    nr Chorus voice count (0-99, CPU time consumption proportional to this value)
+    level Chorus level (0.0-10.0)
+    speed Chorus speed in Hz (0.29-5.0)
+    depth_ms Chorus depth (max value depends on synth sample rate, 0.0-21.0 is safe for sample rate values up to 96KHz)
+    type Chorus waveform type (0=sine, 1=triangle)
+    """
+    # Playback vars
+    tempo = int((60 / 120) * 1e6)  # default 120bpm
+    last_t = 0
+    ss = np.empty((0, 2), dtype=np.int16)
+
+    for name, cur_t, *data in events:
+        # compute how many samples have passed since the last event
+        delta_ticks = cur_t - last_t
+        last_t = cur_t
+        dt_seconds = (delta_ticks / ticks_per_beat) * (tempo / 1e6)
+        sample_len = int(dt_seconds * sample_rate)
+        if sample_len > 0:
+            buf = fl.get_samples(sample_len).reshape(-1, 2)
+            ss = np.concatenate([ss, buf], axis=0)
+
+        # Dispatch every known event
+        if name == "note_on" and data[2] > 0:
+            chan, note, vel = data
+            fl.noteon(chan, note, vel)
+
+        elif name == "note_off" or (name == "note_on" and data[2] == 0):
+            chan, note = data[:2]
+            fl.noteoff(chan, note)
+
+        elif name == "patch_change":
+            chan, patch = data[:2]
+            bank = 128 if chan == 9 else 0
+            fl.program_select(chan, sfid, bank, patch)
+
+        elif name == "control_change":
+            chan, ctrl, val = data[:3]
+            fl.cc(chan, ctrl, val)
+
+        elif name == "key_after_touch":
+            chan, note, vel = data
+            # fl.key_pressure(chan, note, vel)
+
+        elif name == "channel_after_touch":
+            chan, vel = data
+            # fl.channel_pressure(chan, vel)
+
+        elif name == "pitch_wheel_change":
+            chan, wheel = data
+            fl.pitch_bend(chan, wheel)
+
+        elif name == "song_position":
+            # song_pos = data[0];  # often not needed for playback
+            pass
+
+        elif name == "song_select":
+            # song_number = data[0]
+            pass
+
+        elif name == "tune_request":
+            # typically resets tuning; FS handles internally
+            pass
+
+        elif name in ("sysex_f0", "sysex_f7"):
+            raw_bytes = data[0]
+            # fl.sysex(raw_bytes)
+            pass
+
+        # Meta events & others—no direct audio effect, so we skip or log
+        elif name in (
+            "set_tempo",       # handled below
+            "end_track",
+            "text_event", "text_event_08", "text_event_09", "text_event_0a",
+            "text_event_0b", "text_event_0c", "text_event_0d", "text_event_0e", "text_event_0f",
+            "copyright_text_event", "track_name", "instrument_name",
+            "lyric", "marker", "cue_point",
+            "smpte_offset", "time_signature", "key_signature",
+            "sequencer_specific", "raw_meta_event"
+        ):
+            if name == "set_tempo":
+                tempo = data[0]
+            # else: skip all other meta & text; you could hook in logging here
+            continue
 
-      raw_audio = normalize_volume(ss, volume_scale)
+        else:
+            # unknown event type
+            continue
 
-      if write_audio_to_WAV:
+    # Cleanup synth
+    fl.delete()
 
-        filename = midi_file.split('.')[-2] + '.wav'
+    if ss.size:
+        maxv = np.abs(ss).max()
+        if maxv:
+            ss = (ss / maxv) * np.iinfo(np.int16).max
+    ss = ss.astype(np.int16)
 
-        r_audio = raw_audio.T
+    # Optional trimming of trailing silence
+    if trim_silence and ss.size:
+        thresh = np.std(np.abs(ss)) * silence_threshold
+        idx = np.where(np.abs(ss) > thresh)[0]
+        if idx.size:
+            ss = ss[: idx[-1] + 1]
 
-        r_audio = np.int16(r_audio / np.max(np.abs(r_audio)) * 32767)
+    # For Gradio you might want raw int16 PCM
+    if output_for_gradio:
+        return ss
 
-        with wave.open(filename, 'w') as wf:
+    # Swap to (channels, samples) and normalize for playback
+    ss = ss.T
+    raw_audio = normalize_audio(ss, target_level_db=volume_level_db)
+
+    # Optionally write WAV to disk
+    if write_audio_to_WAV:
+        wav_name = midi_file.rsplit('.', 1)[0] + '.wav'
+        if output_WAV_name != '':
+            wav_name = output_WAV_name
+        pcm = np.int16(raw_audio.T / np.max(np.abs(raw_audio)) * 32767)
+        with wave.open(wav_name, 'wb') as wf:
             wf.setframerate(sample_rate)
             wf.setsampwidth(2)
-            wf.setnchannels(r_audio.shape[1])
-            wf.writeframes(r_audio)
+            wf.setnchannels(pcm.shape[1])
+            wf.writeframes(pcm.tobytes())
+
+    return raw_audio
 
-      return raw_audio
-  
-    else:
-      return None
-    
 #===================================================================================================================

x_transformer_2_3_1.py

@@ -4,7 +4,7 @@
 #
 # Partial x-transformers code With useful modifications as a stand-alone Python module
 #
-# Version 1.0
+# Version 3.0
 #
 # Original source code courtesy of lucidrains
 # https://github.com/lucidrains/x-transformers
@@ -13,7 +13,7 @@
 # Original version 2.3.1 / Commit 458bc12
 #
 # Project Los Angeles
-# Tegridy Code 2025
+# Tegridy Code 2026
 #
 #===================================================================================================================
 #
@@ -4146,6 +4146,416 @@ class AutoregressiveWrapper(Module):
         out, = unpack(out, ps, '* n')
 
         return out
+
+    @torch.no_grad()
+    @eval_decorator
+    def generate_masked(
+        self,
+        prompts,
+        seq_len,
+        eos_token = None,
+        temperature = 1.,
+        prompt_lens: Tensor | None = None,
+        filter_logits_fn: str | Callable = top_k,
+        restrict_to_max_seq_len = True,
+        amateur_model: Module | Tuple[Module] | None = None,
+        filter_kwargs: dict = dict(),
+        contrastive_decode_kwargs: dict | Tuple[dict] = dict(
+            beta = 0.5,
+            alpha = 0.1
+        ),
+        cache_kv = True,
+        return_prime=False,
+        verbose=True,
+        masked_token_ids: list[int] | Tensor | None = None,
+        **kwargs
+    ):
+        max_seq_len, greedy, device = self.max_seq_len, temperature == 0., prompts.device
+
+        prompts, ps = pack([prompts], '* n')
+
+        b, t = prompts.shape
+
+        # handle filter logits fn given as string
+        if isinstance(filter_logits_fn, str):
+            assert filter_logits_fn in FILTER_LOGITS_FN, f"only {join(FILTER_LOGITS_FN.keys())} are available"
+            filter_logits_fn = FILTER_LOGITS_FN[filter_logits_fn]
+
+        # prepare masked token ids tensor (if any)
+        if masked_token_ids is not None:
+            if not torch.is_tensor(masked_token_ids):
+                masked_token_ids = torch.tensor(masked_token_ids, dtype=torch.long, device=device)
+            else:
+                masked_token_ids = masked_token_ids.to(device=device, dtype=torch.long)
+            # keep unique and non-negative
+            masked_token_ids = torch.unique(masked_token_ids)
+            # remove any ids that are out of range (optional safety)
+            # we can't know vocab size here, so we only remove negative ids
+            masked_token_ids = masked_token_ids[masked_token_ids >= 0]
+        else:
+            masked_token_ids = None
+
+        # handle variable lengthed prompts (prefixes)
+        seq_start_pos = None
+        if exists(prompt_lens):
+            prompts = align_right(prompts, prompt_lens, pad_id = self.pad_value)
+            seq_start_pos = t - prompt_lens
+
+        # output from which sampled tokens appended to
+        out = prompts
+
+        if verbose:
+            print("Generating sequence of max length:", seq_len)
+
+        # kv caches
+        cache = None
+
+        # if doing contrastive decoding, turn off filter automatically
+        if exists(amateur_model):
+            amateur_model = cast_tuple(amateur_model)
+            contrastive_decode_kwargs = cast_tuple(contrastive_decode_kwargs)
+
+            assert len(amateur_model) == len(contrastive_decode_kwargs)
+
+            amateur_caches = [None] * len(amateur_model)
+            filter_logits_fn = identity
+
+            for i, module in enumerate(amateur_model):
+                if isinstance(module, AutoregressiveWrapper):
+                    amateur_model[i] = module.net
+
+                module.eval()
+
+        # sampling up to seq_len
+        for sl in range(seq_len):
+
+            if restrict_to_max_seq_len:
+                max_len_exceeded = out.shape[-1] > max_seq_len
+
+                assert not (cache_kv and max_len_exceeded and not self.net.can_cache_kv_outside_max_seq_len), 'the network cannot use cached key values when decoding outside the max sequence length. most likely because you are using absolute positional embedding. you can switch to rotary embeddings to resolve this issue'
+
+                x = out[:, -max_seq_len:]
+
+                if exists(cache):
+                    for inter in cache.attn_intermediates:
+                        if inter.layer_type == 'a':
+                            inter.cached_kv = [t[..., -(max_seq_len - 1):, :] for t in inter.cached_kv]
+
+            logits, new_cache = self.net(
+                x,
+                return_intermediates = True,
+                cache = cache,
+                seq_start_pos = seq_start_pos,
+                **kwargs
+            )
+
+            if cache_kv and self.net.can_cache_kv:
+                cache = new_cache
+
+            logits = logits[:, -1]
+
+            # handle contrastive decoding, Li et al.
+            # https://arxiv.org/abs/2210.15097
+            if exists(amateur_model):
+                for i, (amateur, amateur_cache, amateur_contrastive_decode_kwargs) in enumerate(zip(amateur_model, amateur_caches, contrastive_decode_kwargs)):
+                    amateur_logits, next_amateur_cache = amateur(
+                        x,
+                        return_intermediates = True,
+                        cache = amateur_cache,
+                        seq_start_pos = seq_start_pos,
+                        **kwargs
+                    )
+
+                    amateur_logits = amateur_logits[:, -1]
+
+                    assert amateur_logits.shape == logits.shape, 'logits dimension are not the same between amateur and expert model'
+                    logits = contrastive_decode_fn(logits, amateur_logits, **amateur_contrastive_decode_kwargs)
+
+                    if cache_kv and amateur.can_cache_kv:
+                        amateur_caches[i] = next_amateur_cache
+
+            # --- apply masked token ids here (after contrastive decoding, before filtering/sampling)
+            if masked_token_ids is not None and masked_token_ids.numel() > 0:
+                # safety: ensure indices are within logits' vocab dimension
+                vocab_size = logits.shape[-1]
+                valid_masked = masked_token_ids[masked_token_ids < vocab_size]
+                if valid_masked.numel() > 0:
+                    # set logits for masked ids to a very large negative value
+                    neg_inf = -1e9
+                    # logits shape: (batch, vocab)
+                    logits[:, valid_masked] = neg_inf
+
+            # filter by top_k, top_p (nucleus), top_a, or custom
+            if greedy:
+                sample = logits.argmax(dim = -1, keepdim = True)
+            else:
+                filtered_logits = filter_logits_fn(logits, **filter_kwargs)
+                probs = F.softmax(filtered_logits / temperature, dim=-1)
+                sample = torch.multinomial(probs, 1)
+
+            # concat sample
+            out = torch.cat((out, sample), dim=-1)
+
+            if verbose:
+              if sl % 32 == 0:
+                print(sl, '/', seq_len)
+
+            if not exists(eos_token):
+                continue
+
+            is_eos_tokens = (out == eos_token)
+
+            if is_eos_tokens.any(dim = -1).all():
+
+                if verbose:
+                    print('Model called the end of sequence at:', sl, '/', seq_len)
+
+                break
+
+        if exists(eos_token):
+            # mask out everything after the eos tokens
+            shifted_is_eos_tokens = F.pad(is_eos_tokens, (1, -1))
+            mask = shifted_is_eos_tokens.float().cumsum(dim = -1) >= 1
+            out = out.masked_fill(mask, self.pad_value)
+
+        if return_prime:
+            out = out[:, :]
+
+        else:
+            out = out[:, t:]
+
+        out, = unpack(out, ps, '* n')
+
+        return out
+
+    @torch.no_grad()
+    @eval_decorator
+    def generate_biased(
+        self,
+        prompts,
+        seq_len,
+        eos_token = None,
+        temperature = 1.,
+        prompt_lens: Tensor | None = None,
+        filter_logits_fn: str | Callable = top_k,
+        restrict_to_max_seq_len = True,
+        amateur_model: Module | Tuple[Module] | None = None,
+        filter_kwargs: dict = dict(),
+        contrastive_decode_kwargs: dict | Tuple[dict] = dict(
+            beta = 0.5,
+            alpha = 0.1
+        ),
+        cache_kv = True,
+        return_prime=False,
+        verbose=True,
+        logit_bias: dict | Tensor | None = None,   # <-- new parameter
+        **kwargs
+    ):
+        """
+        Autoregressive generation with optional additive logit bias.
+    
+        logit_bias:
+            - dict[token_id -> float]  OR
+            - torch.Tensor of shape (vocab,) OR (batch, vocab)
+        """
+    
+        max_seq_len, greedy, device = self.max_seq_len, temperature == 0., prompts.device
+    
+        prompts, ps = pack([prompts], '* n')
+    
+        b, t = prompts.shape
+    
+        # handle filter logits fn given as string
+        if isinstance(filter_logits_fn, str):
+            assert filter_logits_fn in FILTER_LOGITS_FN, f"only {join(FILTER_LOGITS_FN.keys())} are available"
+            filter_logits_fn = FILTER_LOGITS_FN[filter_logits_fn]
+    
+        # handle variable lengthed prompts (prefixes)
+        seq_start_pos = None
+        if exists(prompt_lens):
+            prompts = align_right(prompts, prompt_lens, pad_id = self.pad_value)
+            seq_start_pos = t - prompt_lens
+    
+        # output from which sampled tokens appended to
+        out = prompts
+    
+        if verbose:
+            print("Generating sequence of max length:", seq_len)
+    
+        # kv caches
+        cache = None
+    
+        # if doing contrastive decoding, turn off filter automatically
+        if exists(amateur_model):
+            amateur_model = cast_tuple(amateur_model)
+            contrastive_decode_kwargs = cast_tuple(contrastive_decode_kwargs)
+            assert len(amateur_model) == len(contrastive_decode_kwargs)
+            amateur_caches = [None] * len(amateur_model)
+            filter_logits_fn = identity
+            for i, module in enumerate(amateur_model):
+                if isinstance(module, AutoregressiveWrapper):
+                    amateur_model[i] = module.net
+                module.eval()
+    
+        # -------------------------
+        # Prepare logit_bias (robust vocab-size detection)
+        # -------------------------
+        prepared_bias = None
+        lazy_build_bias_from_dict = None
+    
+        if exists(logit_bias):
+            if isinstance(logit_bias, dict):
+                # try to determine vocab size from model without using logits
+                vocab_size = None
+    
+                # common places to find vocab size
+                try:
+                    if hasattr(self.net, "config") and getattr(self.net.config, "vocab_size", None) is not None:
+                        vocab_size = int(self.net.config.vocab_size)
+                    elif getattr(self.net, "vocab_size", None) is not None:
+                        vocab_size = int(self.net.vocab_size)
+                    else:
+                        # try to infer from embedding / output projection weights
+                        # huggingface style: get_output_embeddings() or embed_tokens or lm_head
+                        get_out = getattr(self.net, "get_output_embeddings", None)
+                        if callable(get_out) and get_out() is not None:
+                            vocab_size = int(get_out().weight.shape[0])
+                        elif hasattr(self.net, "embed_tokens"):
+                            vocab_size = int(self.net.embed_tokens.weight.shape[0])
+                        elif hasattr(self.net, "lm_head"):
+                            vocab_size = int(self.net.lm_head.weight.shape[0])
+                except Exception:
+                    vocab_size = None
+    
+                if vocab_size is not None:
+                    bias_vec = torch.zeros(int(vocab_size), device=device, dtype=torch.float32)
+                    for tok, val in logit_bias.items():
+                        tok_i = int(tok)
+                        if tok_i < 0 or tok_i >= vocab_size:
+                            raise IndexError(f"logit_bias token id {tok_i} out of range for vocab size {vocab_size}")
+                        bias_vec[tok_i] = float(val)
+                    prepared_bias = bias_vec
+                else:
+                    # can't determine vocab size yet — build lazily after first logits are available
+                    lazy_build_bias_from_dict = {int(k): float(v) for k, v in logit_bias.items()}
+    
+            elif isinstance(logit_bias, torch.Tensor):
+                prepared_bias = logit_bias.to(device=device, dtype=torch.float32)
+            else:
+                raise TypeError("logit_bias must be dict or torch.Tensor")
+    
+        # sampling up to seq_len
+        for sl in range(seq_len):
+    
+            if restrict_to_max_seq_len:
+                max_len_exceeded = out.shape[-1] > max_seq_len
+                assert not (cache_kv and max_len_exceeded and not self.net.can_cache_kv_outside_max_seq_len), \
+                    'the network cannot use cached key values when decoding outside the max sequence length. most likely because you are using absolute positional embedding. you can switch to rotary embeddings to resolve this issue'
+                x = out[:, -max_seq_len:]
+                if exists(cache):
+                    for inter in cache.attn_intermediates:
+                        if inter.layer_type == 'a':
+                            inter.cached_kv = [t[..., -(max_seq_len - 1):, :] for t in inter.cached_kv]
+            else:
+                x = out
+    
+            logits, new_cache = self.net(
+                x,
+                return_intermediates = True,
+                cache = cache,
+                seq_start_pos = seq_start_pos,
+                **kwargs
+            )
+    
+            if cache_kv and self.net.can_cache_kv:
+                cache = new_cache
+    
+            logits = logits[:, -1]  # shape (batch, vocab)
+    
+            # If we couldn't build the bias earlier because vocab size was unknown,
+            # build it now from the first logits tensor.
+            if lazy_build_bias_from_dict is not None:
+                vocab_size = logits.shape[-1]
+                bias_vec = torch.zeros(vocab_size, device=device, dtype=torch.float32)
+                for tok, val in lazy_build_bias_from_dict.items():
+                    if tok < 0 or tok >= vocab_size:
+                        raise IndexError(f"logit_bias token id {tok} out of range for vocab size {vocab_size}")
+                    bias_vec[tok] = val
+                prepared_bias = bias_vec
+                lazy_build_bias_from_dict = None  # only build once
+    
+            # handle contrastive decoding, Li et al.
+            # https://arxiv.org/abs/2210.15097
+            if exists(amateur_model):
+                for i, (amateur, amateur_cache, amateur_contrastive_decode_kwargs) in enumerate(zip(amateur_model, amateur_caches, contrastive_decode_kwargs)):
+                    amateur_logits, next_amateur_cache = amateur(
+                        x,
+                        return_intermediates = True,
+                        cache = amateur_cache,
+                        seq_start_pos = seq_start_pos,
+                        **kwargs
+                    )
+                    amateur_logits = amateur_logits[:, -1]
+                    assert amateur_logits.shape == logits.shape, 'logits dimension are not the same between amateur and expert model'
+                    logits = contrastive_decode_fn(logits, amateur_logits, **amateur_contrastive_decode_kwargs)
+                    if cache_kv and amateur.can_cache_kv:
+                        amateur_caches[i] = next_amateur_cache
+    
+            # -------------------------
+            # Apply logit bias if provided
+            # -------------------------
+            if exists(prepared_bias):
+                # prepared_bias can be (vocab,) or (batch, vocab)
+                if prepared_bias.dim() == 1:
+                    # broadcast to batch
+                    logits = logits + prepared_bias.unsqueeze(0)
+                elif prepared_bias.dim() == 2:
+                    # expect shape (batch, vocab)
+                    if prepared_bias.shape[0] != logits.shape[0]:
+                        raise ValueError("logit_bias tensor batch size must match logits batch size")
+                    logits = logits + prepared_bias
+                else:
+                    raise ValueError("logit_bias tensor must be 1D (vocab,) or 2D (batch, vocab)")
+    
+            # filter by top_k, top_p (nucleus), top_a, or custom
+            if greedy:
+                sample = logits.argmax(dim = -1, keepdim = True)
+            else:
+                filtered_logits = filter_logits_fn(logits, **filter_kwargs)
+                probs = F.softmax(filtered_logits / temperature, dim=-1)
+                sample = torch.multinomial(probs, 1)
+    
+            # concat sample
+            out = torch.cat((out, sample), dim=-1)
+    
+            if verbose:
+                if sl % 32 == 0:
+                    print(sl, '/', seq_len)
+    
+            if not exists(eos_token):
+                continue
+    
+            is_eos_tokens = (out == eos_token)
+    
+            if is_eos_tokens.any(dim = -1).all():
+                if verbose:
+                    print('Model called the end of sequence at:', sl, '/', seq_len)
+                break
+    
+        if exists(eos_token):
+            # mask out everything after the eos tokens
+            shifted_is_eos_tokens = F.pad(is_eos_tokens, (1, -1))
+            mask = shifted_is_eos_tokens.float().cumsum(dim = -1) >= 1
+            out = out.masked_fill(mask, self.pad_value)
+    
+        if return_prime:
+            out = out[:, :]
+        else:
+            out = out[:, t:]
+    
+        out, = unpack(out, ps, '* n')
+    
+        return out
     
     def compute_accuracy(self, logits, labels):