Calibrate centered mode for causal-stack delay

README.md

@@ -42,8 +42,8 @@ wavcoch = AutoModel.from_pretrained(
 causal_codes = wavcoch.quantize(waveform_tensor)
 assert torch.equal(causal_codes, wavcoch.quantize(waveform_tensor, mode="causal"))
 
-# Centered mode preserves the number of frames while centering the 1001-sample
-# analysis window on the token endpoint. It uses 421 left and 500 right zeros.
+# Centered mode preserves the number of frames and compensates the measured
+# end-to-end causal-stack delay. It uses 341 left and 580 right zeros.
 centered_codes = wavcoch.quantize(waveform_tensor, mode="centered")
 
 codes = causal_codes
@@ -62,11 +62,12 @@ audio = wavcoch.decode_audio(codes)
 This repo includes a bundled vocoder and supports `decode_audio(...)` for end-to-end waveform synthesis.
 
 `mode="causal"` is the default and uses the original 921 samples of left
-padding. `mode="centered"` redistributes the same total padding as 421 samples
-on the left and 500 samples on the right. This keeps frame counts unchanged
-while moving the analysis-window center forward by 500 samples (31.25 ms at
-16 kHz). Centered encoding uses future waveform context and is therefore not
-streaming-causal.
+padding. `mode="centered"` redistributes the same total padding as 341 samples
+on the left and 580 samples on the right. This keeps frame counts unchanged
+while advancing the front end by 580 samples (36.25 ms at 16 kHz). Of this,
+31.25 ms removes the original analysis-window offset and one additional 5 ms
+frame compensates the measured causal encoder/decoder response delay. Centered
+encoding uses future waveform context and is therefore not streaming-causal.
 
 The mode argument is accepted by `forward(...)`, `quantize(...)`, and
 `wav2coch(...)`. Decoding methods operate on codes and do not take a mode.
@@ -86,16 +87,17 @@ Validation used float32 with TF32 disabled:
   divisible by the 80-sample hop.
 - Six synthetic beep configurations produced the same 200 frames for causal
   and centered modes from one second of audio.
-- Centered decoded-cochleagram power advanced by 6 frames (30 ms, the nearest
-  5 ms token-grid value to 31.25 ms), with shifted-curve Pearson correlations
-  from 0.986 to 0.999.
+- An end-to-end padding sweep found that geometric endpoint centering alone
+  left decoded impulse and abrupt-tone power peaks 5 ms late. Advancing one
+  additional frame aligned the decoded impulse and the median onset/cutoff
+  peaks to 0 ms on the 5 ms output grid.
 - AuriStream7BDeep-40Pred float32 head-1 and head-40 surprisals were bit-exact
   between the base model's codes and this model's causal codes.
 
-Centered mode changes the encoded token sequence and uses 31.25 ms of future
-waveform context. Models trained on causal WavCoch codes should therefore be
-evaluated explicitly before centered codes are used for likelihood estimates
-or generation.
+Centered mode changes the encoded token sequence and uses approximately
+36.25 ms of future waveform context relative to token endpoints. Models trained
+on causal WavCoch codes should therefore be evaluated explicitly before
+centered codes are used for likelihood estimates or generation.
 
 When called with `output_hidden_states=True`, WavCoch exposes a single hidden-state layer:
 the post-FSQ projected embedding sequence used for direct probing.

config.json

@@ -56,8 +56,8 @@
     "causal",
     "centered"
   ],
-  "centered_left_padding": 421,
-  "centered_right_padding": 500,
+  "centered_left_padding": 341,
+  "centered_right_padding": 580,
   "hop_length": 80,
   "causal_convs": true,
   "encoder_layers": 8,

configuration_wavcoch.py

@@ -48,8 +48,13 @@ class WavCochConfig(PretrainedConfig):
         self.window_size = int(window_size)
         self.window_padding = int(window_padding)
         half_window = (self.window_size - 1) // 2
+        # Advance one additional hop beyond geometric endpoint centering to
+        # compensate the measured causal encoder/decoder response delay.
+        default_centered_right_padding = half_window + int(hop_length)
         self.centered_right_padding = int(
-            half_window if centered_right_padding is None else centered_right_padding
+            default_centered_right_padding
+            if centered_right_padding is None
+            else centered_right_padding
         )
         expected_left_padding = self.window_padding - self.centered_right_padding
         self.centered_left_padding = int(

modeling_wavcoch.py

@@ -399,7 +399,7 @@ class WavCoch(PreTrainedModel):
         self.hop_length = int(config.hop_length)
         self.window_padding = int(getattr(config, "window_padding", self.N - self.hop_length))
         self.centered_right_padding = int(
-            getattr(config, "centered_right_padding", (self.N - 1) // 2)
+            getattr(config, "centered_right_padding", (self.N - 1) // 2 + self.hop_length)
         )
         self.centered_left_padding = int(
             getattr(config, "centered_left_padding", self.window_padding - self.centered_right_padding)