CVBS: SMPTE 272M audio profile (48 kHz, genuine 24-bit, synchronous)

The CVBS spec (submodule -> d801241) replaced its per-track audio model
with the SMPTE 272M-1994 profile: audio is now stored as channel pairs,
one stereo WAV each, at 48 kHz / 24-bit, clock-locked to video.

Writer (cvbs.py):
- schema user_version 10: drop the file-level audio_locked column, add
  the audio_channel_pair table (one row per stored pair)
- WAV is 48 kHz, 24-bit signed LE; file named <base>_audio_0.wav
- enforce the normative synchronous sample count at close: 1920/frame
  (PAL) or the 8008-per-5-frame 1602/1601 sequence (NTSC/PAL_M), via a
  small trim/zero-pad of accumulated fractional slack

Audio path: make the output genuinely 24-bit rather than a <<8 promotion
of the 16-bit decode.  dsa_rescale_and_clip takes a full-scale code and
_downscale_audio_to_output emits int32; downscale_audio(bits=...) narrows
to int16 only for the 16-bit path.  bit-depth is threaded through
downscale_audio_out and the worker cfg; CVBS runs it at bits=24.  The
16-bit .pcm output is unchanged (bit-identical: 16-bit uses fullscale
32767 and the values stay in int16 range).

decoder.py forces the CVBS analog-audio rate to 48 kHz regardless of
--analog_audio_frequency/--ntsc_audio_rate.  cvbs_verify.py updated to
check schema v10, the channel-pair row, 48 kHz/24-bit WAV, and the exact
synchronous sample total.

Verified: NTSC+PAL decodes pass cvbs_verify; low audio byte carries real
resolution (all 256 values, not forced-zero); -t parallel audio is
bit-identical to serial; 16-bit .pcm cmp-identical before/after.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: happycube

analysis/cvbs_verify.py

@@ -90,15 +90,15 @@ def main():
     check(os.path.exists(meta), ".meta present")
     con = sqlite3.connect(meta)
     uv = con.execute("PRAGMA user_version").fetchone()[0]
-    check(uv == 8, f"user_version = 8 (got {uv})")
+    check(uv == 10, f"user_version = 10 (got {uv})")
     row = con.execute(
         "SELECT preset, sample_encoding_preset, signal_state_preset, "
-        "signal_type, decoder, number_of_sequential_frames, audio_locked "
+        "signal_type, decoder, number_of_sequential_frames "
         "FROM cvbs_file").fetchone()
     check(row is not None, "cvbs_file row present")
-    preset_name, enc, state, sigtype, decoder, n_frames, audio_locked = row
+    preset_name, enc, state, sigtype, decoder, n_frames = row
     print(f"  preset={preset_name} enc={enc} state={state} type={sigtype} "
-          f"decoder={decoder} frames={n_frames} audio_locked={audio_locked}")
+          f"decoder={decoder} frames={n_frames}")
     check(preset_name in PRESETS, f"known preset {preset_name}")
     p = PRESETS[preset_name]
 
@@ -312,30 +312,38 @@ def main():
     else:
         warn("no EFM extension sidecar")
 
-    # --- audio ---
-    wav = base + "_audio_00.wav"
+    # --- audio (SMPTE 272M: 48 kHz, 24-bit stereo, synchronous) ---
+    pairs = con.execute(
+        "SELECT channel_pair, description FROM audio_channel_pair "
+        "ORDER BY channel_pair").fetchall()
+    wav = base + "_audio_0.wav"
     if os.path.exists(wav):
+        check(any(cp == 0 for cp, _ in pairs),
+              "audio_channel_pair row present for pair 0")
         with open(wav, "rb") as f:
             hdr = f.read(44)
         riff, wave = hdr[0:4], hdr[8:12]
         fmt_tag, channels, rate = struct.unpack("<HHI", hdr[20:28])
         bits = struct.unpack("<H", hdr[34:36])[0]
         data_len = struct.unpack("<I", hdr[40:44])[0]
         check(riff == b"RIFF" and wave == b"WAVE", "WAV RIFF header")
-        check(fmt_tag == 1 and channels == 2 and bits == 16,
-              "WAV stereo s16 PCM")
-        expect_rate = (44056 if (audio_locked and preset_name in
-                                 ("NTSC", "PAL_M")) else 44100)
-        check(rate == expect_rate,
-              f"WAV rate {rate} matches audio_locked={audio_locked}")
+        check(fmt_tag == 1 and channels == 2 and bits == 24,
+              "WAV stereo 24-bit PCM")
+        check(rate == 48000, f"WAV rate 48000 (got {rate})")
         actual = os.path.getsize(wav) - 44
         check(data_len == actual,
               f"WAV data chunk size correct ({data_len} vs {actual})")
-        if audio_locked:
-            per_frame = 1764 if preset_name == "PAL" else 1470
-            check(data_len == file_frames * per_frame * 4,
-                  f"locked audio: {per_frame} samples/frame exactly")
+        # synchronous per-preset total: 1920/frame (PAL) or the 8008-per-
+        # 5-frame 1602/1601 sequence (NTSC/PAL_M)
+        if preset_name == "PAL":
+            target = 1920 * file_frames
+        else:
+            seq = (0, 1602, 3203, 4805, 6406)
+            target = 8008 * (file_frames // 5) + seq[file_frames % 5]
+        check(data_len == target * 6,
+              f"synchronous audio: {target} samples for {file_frames} frames")
     else:
+        check(not pairs, "no audio_channel_pair rows without a WAV file")
         warn("no audio WAV present")
 
     print()

cvbs-file-format-specification

@@ -82,7 +82,8 @@ def _downscale_audio_compute_locs_and_swow(
 
 @njit(cache=True, nogil=True)
 def _downscale_audio_to_output(
-    arange, locs, swow, audio_left, audio_right, audio_lfreq, audio_rfreq
+    arange, locs, swow, audio_left, audio_right, audio_lfreq, audio_rfreq,
+    fullscale
 ):
     """decimate audio to final output samples.
 
@@ -94,11 +95,14 @@ def _downscale_audio_to_output(
         audio_right (np.array(float)): right channel demodulated audio
         audio_lfreq (float): left audio channel frequency
         audio_rfreq (float): right audio channel frequency
+        fullscale (float): positive full-scale code (32767 for 16-bit,
+            8388607 for 24-bit) - sets the output resolution
     Returns: (tuple)
-        output (np.ndarray(int16)): output audio waveform
+        output (np.ndarray(int32)): output audio waveform (24-bit-capable;
+            the caller narrows to int16 when fullscale is 32767)
         failed (bool): whether there were any failed samples that were muted
     """
-    output = np.zeros((2 * (len(arange) - 1)), dtype=np.int16)
+    output = np.zeros((2 * (len(arange) - 1)), dtype=np.int32)
 
     failed = False
 
@@ -114,18 +118,20 @@ def _downscale_audio_to_output(
 
             # Flipping audio here to line up with ralf/he010 digital sample
             # (when comparing, remove the first 265 samples of ralf.pcm as well)
-            output[(i * 2) + 0] = -dsa_rescale_and_clip(output_left)
-            output[(i * 2) + 1] = -dsa_rescale_and_clip(output_right)
+            output[(i * 2) + 0] = -dsa_rescale_and_clip(output_left, fullscale)
+            output[(i * 2) + 1] = -dsa_rescale_and_clip(output_right, fullscale)
         else:
             # TBC failure can cause this (issue #389)
             failed = True
 
     return output, failed
 
 
-# Downscales to 16bit/44.1khz.  It might be nice when analog audio is better to support 24/96,
-# but if we only support one output type, matching CD audio/digital sound is greatly preferable.
-def downscale_audio(audio, lineinfo, rf, linecount, timeoffset=0, freq=44100, rv=None):
+# Downscales to 16- or 24-bit PCM.  16-bit at 44.1 kHz matches CD/digital
+# audio and is the default; 24-bit (bits=24) is used for the CVBS SMPTE 272M
+# audio profile, where the demod's sub-16-bit resolution is actually kept.
+def downscale_audio(audio, lineinfo, rf, linecount, timeoffset=0, freq=44100,
+                    rv=None, bits=16):
     """downscale audio for output.
 
     Parameters:
@@ -135,11 +141,14 @@ def downscale_audio(audio, lineinfo, rf, linecount, timeoffset=0, freq=44100, rv
         linecount (int): # of lines in field
         timeoffset (float): time of first audio sample (ignored w/- frequency)
         freq (int): Output frequency (negative values are multiple of HSYNC frequency)
+        bits (int): Output resolution, 16 (int16) or 24 (int32, 24-bit values)
     Returns: (tuple)
-        output16 (np.array(int)):  Array of 16-bit integers, ready for output
+        output (np.array(int)):  int16 (bits=16) or int32 (bits=24) samples
         next_timeoffset (float): Time to start pulling samples in the next frame (ignore if sync4x)
     """
 
+    fullscale = float((1 << (bits - 1)) - 1)
+
     locs, swow, arange, frametime = _downscale_audio_compute_locs_and_swow(
         lineinfo,
         rf.SysParams["line_period"],
@@ -150,21 +159,27 @@ def downscale_audio(audio, lineinfo, rf, linecount, timeoffset=0, freq=44100, rv
         rf.Filters["audio_fdiv"],
     )
 
-    output16, failed = _downscale_audio_to_output(
+    output, failed = _downscale_audio_to_output(
         arange,
         locs,
         swow,
         audio["audio_left"],
         audio["audio_right"],
         rf.SysParams["audio_lfreq"],
         rf.SysParams["audio_rfreq"],
+        fullscale,
     )
 
+    # int16 for the 16-bit path keeps the .pcm output byte-for-byte as before
+    # (values sit within int16 range, so the narrowing is exact)
+    if bits <= 16:
+        output = output.astype(np.int16)
+
     if failed:
         logs.logger.warning("Analog audio processing error, muting samples")
 
     if rv is not None:
-        rv['dsaudio'] = output16
+        rv['dsaudio'] = output
         rv['audio_next_offset'] = arange[-1] - frametime
 
-    return output16, arange[-1] - frametime
+    return output, arange[-1] - frametime

lddecode/audio.py

@@ -75,7 +75,7 @@ def pal_lattice_positions(n_samples, origin_lines=Fraction(0)):
 
 
 _META_SCHEMA = """
-PRAGMA user_version = 8;
+PRAGMA user_version = 10;
 
 CREATE TABLE cvbs_file (
     cvbs_file_id                INTEGER PRIMARY KEY,
@@ -101,20 +101,32 @@ def pal_lattice_positions(n_samples, origin_lines=Fraction(0)):
         CHECK (number_of_sequential_frames IS NULL OR number_of_sequential_frames >= 1),
     black_level                 INTEGER,
     has_nonstandard_values      BOOLEAN,
-    audio_locked                BOOLEAN,
     capture_notes               TEXT
 );
+
+CREATE TABLE audio_channel_pair (
+    channel_pair                INTEGER PRIMARY KEY
+        CHECK (channel_pair BETWEEN 0 AND 7),
+    description                 TEXT
+);
 """
 
 
 class CVBSWriter:
     """Assembles decoded fields into spec-compliant CVBS output.
 
     Writes <basename>.composite (u16le, CVBS_U16_4FSC), <basename>.meta
-    (SQLite, spec core schema), optional <basename>_audio_00.wav, and the
+    (SQLite, spec core schema), optional <basename>_audio_0.wav, and the
     dropout / EFM extension sidecars (<basename>.dropouts.meta,
     <basename>.efm + .efm.meta).
 
+    Audio follows the SMPTE 272M-1994 profile the spec mandates: one
+    channel pair (stereo) stored as a 48 kHz, 24-bit signed little-endian
+    WAV, synchronous to video.  PAL carries 1920 samples/frame exactly;
+    NTSC/PAL_M carry 8008 samples per 5-frame audio-frame sequence
+    (1602/1601/1602/1601/1602), so the stored stream is trimmed or
+    zero-padded at close to exactly offset(N) samples for N frames.
+
     Frames use the ld-decode line convention (sample 0 at the line start,
     0H ~ +0.8) — the layout decode-orc's cvbs_source reader expects.  One
     field pair produces exactly one frame, so extension frame indices align
@@ -134,9 +146,14 @@ class CVBSWriter:
     NTSC_LOCK_TARGET = 147.25  # line-referenced burst phase target, deg
     LOCK_TOL = 3.0             # residual tolerance for claiming LOCKED
 
+    # SMPTE 272M-1994 audio profile (spec's only permitted format)
+    AUDIO_RATE = 48000         # Hz, synchronous to video
+    AUDIO_BITS = 24            # signed little-endian PCM
+    AUDIO_BYTES_PER_SAMPLE = 2 * (AUDIO_BITS // 8)   # stereo frame, bytes
+
     def __init__(self, fname_out, system, logger=None, version=None,
-                 black_level=None, write_audio=False, audio_rate=44100,
-                 audio_locked=None, capture_notes=None,
+                 black_level=None, write_audio=False,
+                 audio_description="Analogue stereo", capture_notes=None,
                  has_nonstandard_values=None, write_efm=False):
         self.system = system
         self.params = CVBSParams_PAL if system == "PAL" else CVBSParams_NTSC
@@ -176,8 +193,7 @@ def __init__(self, fname_out, system, logger=None, version=None,
 
         # audio
         self.write_audio = write_audio
-        self.audio_rate = audio_rate
-        self.audio_locked = audio_locked
+        self.audio_description = audio_description
         self.f_wav = None
         self._audio_bytes = 0
 
@@ -388,29 +404,72 @@ def _collect_efm(self, frame_id, efm_a, efm_b):
 
     # -- audio ------------------------------------------------------------
 
+    def audio_sample_target(self, n_frames):
+        """Normative total stereo-sample count for n_frames of 48 kHz audio.
+
+        PAL: 1920 samples/frame exactly.  NTSC/PAL_M: an 8008-sample,
+        5-frame audio-frame sequence (1602/1601/1602/1601/1602), so
+        offset(n) = 8008*(n // 5) + cumulative offset for (n % 5).
+        """
+        if self.system == "PAL":
+            return 1920 * n_frames
+        seq_offset = (0, 1602, 3203, 4805, 6406)
+        return 8008 * (n_frames // 5) + seq_offset[n_frames % 5]
+
     def push_audio(self, data):
         if not self.write_audio:
             return
         if self.f_wav is None:
-            self.f_wav = open(self.fname_out + "_audio_00.wav", "wb")
+            self.f_wav = open(self.fname_out + "_audio_0.wav", "wb")
             self.f_wav.write(self._wav_header(0))
-        buf = data.tobytes() if hasattr(data, "tobytes") else bytes(data)
+        buf = self._pack_s24(data)
         self.f_wav.write(buf)
         self._audio_bytes += len(buf)
 
+    def _pack_s24(self, data):
+        """Pack interleaved 24-bit stereo samples as 24-bit signed LE PCM.
+
+        The analog audio decode is run at 24-bit for CVBS (bits=24), so it
+        arrives as int32 holding genuine 24-bit values in [-2^23, 2^23).
+        The little-endian int32 low 3 bytes are exactly that value as
+        24-bit two's-complement LE.
+        """
+        if isinstance(data, (bytes, bytearray)):
+            data = np.frombuffer(data, dtype=np.int32)
+        a = np.ascontiguousarray(np.asarray(data, dtype=np.int32))
+        return np.ascontiguousarray(
+            a.view(np.uint8).reshape(-1, 4)[:, :3]).tobytes()
+
     def _wav_header(self, data_len):
-        # spec: stereo s16le PCM; the integer header rate is 44056 for the
-        # NTSC/PAL_M locked rational rate 44,100,000/1001
-        rate = int(round(self.audio_rate))
-        block_align = 4
+        # spec: stereo 24-bit signed LE PCM at 48 kHz (SMPTE 272M profile)
+        rate = self.AUDIO_RATE
+        bits = self.AUDIO_BITS
+        block_align = self.AUDIO_BYTES_PER_SAMPLE
         byte_rate = rate * block_align
         return b"".join([
             b"RIFF", struct.pack("<I", 36 + data_len), b"WAVE",
             b"fmt ", struct.pack("<IHHIIHH", 16, 1, 2, rate, byte_rate,
-                                 block_align, 16),
+                                 block_align, bits),
             b"data", struct.pack("<I", data_len),
         ])
 
+    def _finalise_audio(self):
+        """Trim or zero-pad the WAV to the normative synchronous count.
+
+        The 48 kHz decode is rate-synchronous, so this only ever adjusts a
+        handful of samples of accumulated fractional slack to land on the
+        exact per-preset offset(N) the spec requires.
+        """
+        bps = self.AUDIO_BYTES_PER_SAMPLE
+        target_bytes = self.audio_sample_target(self.frames_written) * bps
+        if self._audio_bytes > target_bytes:
+            self.f_wav.seek(len(self._wav_header(0)) + target_bytes)
+            self.f_wav.truncate()
+            self._audio_bytes = target_bytes
+        elif self._audio_bytes < target_bytes:
+            self.f_wav.write(b"\x00" * (target_bytes - self._audio_bytes))
+            self._audio_bytes = target_bytes
+
     # -- close ------------------------------------------------------------
 
     def close(self):
@@ -420,6 +479,7 @@ def close(self):
         self.f_video = None
 
         if self.f_wav is not None:
+            self._finalise_audio()
             self.f_wav.seek(0)
             self.f_wav.write(self._wav_header(self._audio_bytes))
             self.f_wav.close()
@@ -463,13 +523,19 @@ def _write_meta(self, signal_state):
                    preset, sample_encoding_preset, signal_state_preset,
                    signal_type, decoder, git_branch, git_commit,
                    number_of_sequential_frames, black_level,
-                   has_nonstandard_values, audio_locked, capture_notes
-               ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+                   has_nonstandard_values, capture_notes
+               ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
             (self.system, "CVBS_U16_4FSC", signal_state,
              "composite", "ld-decode", git_branch, git_commit,
              self.frames_written if self.frames_written else None,
              self.black_level, self.has_nonstandard_values,
-             self.audio_locked, self.capture_notes))
+             self.capture_notes))
+        # one channel pair (stereo), SMPTE 272M channels 1 & 2 -> _audio_0.wav
+        # (every row must correspond to an existing channel-pair file)
+        if self._audio_bytes:
+            con.execute(
+                "INSERT INTO audio_channel_pair (channel_pair, description) "
+                "VALUES (0, ?)", (self.audio_description,))
         con.commit()
         con.close()