Merge pull request #1046 from mpownby/feat/ntsc-locked-audio-rate

feat(audio): add --ntsc_audio_rate for NTSC-locked PCM output

Author: happycube

docs/user-guide/command.md

@@ -320,6 +320,18 @@ Set the analog audio output sampling frequency.
 ld-decode --analog_audio_frequency 48000 input.ldf output
 ```
 
+#### `--ntsc_audio_rate`
+Output analog audio locked to NTSC line timing instead of the default 44100Hz.
+- **Default:** Off (analog audio is output at 44100Hz)
+- **Effect:** Produces exactly 2.8 samples per line (1470 samples/frame, 735 per field), giving a sample rate of ~44055.944Hz that stays perfectly aligned to the NTSC video timing with no drift. The default 44100Hz rate corresponds to a non-integer 1471.47 samples/frame, which slowly drifts against the video.
+- **Metadata:** The `.tbc.json` reports the resolved `sampleRate` as `44055.944055944055`.
+- **Note:** NTSC only. The flag is ignored (with a warning) for PAL, which is already frame-locked at 44100Hz (1764 samples/frame). Overrides `--analog_audio_frequency`.
+
+**Example:**
+```bash
+ld-decode --ntsc_audio_rate input.ldf output
+```
+
 #### `--audio_filterwidth FREQ`
 Set the analog audio filter width.
 - **Type:** FREQ (see Frequency Format section)

lddecode/core.py

@@ -3525,7 +3525,10 @@ def __init__(
             self.lpf.add_function(DemodCache.read)
             #self.lpf.add_function(self.decodefield)
 
-        self.analog_audio = int(analog_audio)
+        # Negative values are a multiple of the HSYNC frequency (line-locked
+        # output, e.g. -2.8 for NTSC-locked ~44055.944hz) and must keep their
+        # fractional part; positive values are a plain integer rate in hz.
+        self.analog_audio = analog_audio if analog_audio < 0 else int(analog_audio)
         self.digital_audio = digital_audio
         self.ac3 = extra_options.get("AC3", False)
         self.write_rf_tbc = extra_options.get("write_RF_TBC", False)
@@ -4649,11 +4652,18 @@ def seek(self, startframe, target):
 
     def build_json(self):
         """ build up the JSON structure for file output. """
+        # A negative analog_audio is a multiple of the HSYNC frequency; report
+        # the resolved nominal rate in hz so downstream tools see the real value.
+        if self.analog_audio < 0:
+            audio_sample_rate = (1000000 / self.rf.SysParams["line_period"]) * -self.analog_audio
+        else:
+            audio_sample_rate = self.analog_audio
+
         pcmAudioParameters = {
             "bits": 16,
             "isLittleEndian": True,
             "isSigned": True,
-            "sampleRate": self.analog_audio,
+            "sampleRate": audio_sample_rate,
         }
 
         jout = {}

lddecode/main.py

@@ -261,6 +261,16 @@ def main(args=None):
         help="RF sampling frequency in source file (default is 44100hz)",
     )
 
+    parser.add_argument(
+        "--ntsc_audio_rate",
+        dest="ntsc_audio_rate",
+        action="store_true",
+        default=False,
+        help="Output analog audio locked to NTSC line timing "
+        "(2.8 samples/line = 1470 samples/frame, ~44055.944hz) instead of 44100hz. "
+        "NTSC only; ignored for PAL (already frame-locked at 44100hz).",
+    )
+
     parser.add_argument(
         "--video_bpf_low",
         dest="vbpf_low",
@@ -328,6 +338,22 @@ def main(args=None):
         print("ERROR: Can only be PAL or NTSC")
         sys.exit(1)
 
+    # Resolve the analog audio output rate.  A negative value is interpreted
+    # downstream as a multiple of the horizontal line frequency (HSYNC-locked
+    # output); -2.8 yields exactly 2.8 samples/line (1470 samples/frame),
+    # locking the audio to NTSC timing at ~44055.944hz.  PAL is already
+    # frame-locked at 44100hz (1764 samples/frame), so the flag is a no-op there.
+    analog_audio_freq = args.analog_audio_freq
+    if args.ntsc_audio_rate:
+        if vid_standard == "NTSC":
+            analog_audio_freq = -2.8
+        else:
+            print(
+                "WARNING: --ntsc_audio_rate ignored for PAL "
+                "(audio is already frame-locked at 44100hz)",
+                file=sys.stderr,
+            )
+
     # Safety check: ensure --write-test-ldf doesn't overwrite the input file
     if args.write_test_ldf is not None:
         import os.path
@@ -407,7 +433,7 @@ def main(args=None):
         loader,
         logger,
         est_frames=req_frames,
-        analog_audio=0 if args.daa else args.analog_audio_freq,
+        analog_audio=0 if args.daa else analog_audio_freq,
         digital_audio=not args.noefm,
         system=vid_standard,
         doDOD=not args.nodod,

tests/test_audio_rate.py

@@ -0,0 +1,59 @@
+"""Tests for NTSC-locked analog audio output (--ntsc_audio_rate).
+
+The flag maps to a negative output frequency, which downscale_audio
+interprets as a multiple of the horizontal line frequency. -2.8 must
+produce exactly 2.8 audio samples per line (1470 per 525-line NTSC
+frame), keeping the audio perfectly aligned to the video with no drift.
+"""
+
+import numpy as np
+
+from lddecode.core import _downscale_audio_compute_locs_and_swow, SysParams_NTSC
+
+NTSC_LINE_PERIOD = SysParams_NTSC["line_period"]  # microseconds
+NTSC_FRAME_LINES = 525
+
+
+def _even_lineinfo(linecount, linelen):
+    """Evenly spaced line locations (no wow), with a few lines of padding."""
+    return np.arange(0, (linecount + 4) * linelen, linelen, dtype=np.double)
+
+
+def _output_sample_count(freq, linecount=NTSC_FRAME_LINES, linelen=910, scale=32):
+    """Run the locs/wow computation and return (n_output_samples, swow)."""
+    lineinfo = _even_lineinfo(linecount, linelen)
+    _, swow, arange, _ = _downscale_audio_compute_locs_and_swow(
+        lineinfo,
+        NTSC_LINE_PERIOD,
+        linelen,
+        linecount,
+        0.0,  # timeoffset (ignored for negative freq)
+        freq,
+        scale,
+    )
+    # arange carries one extra interpolation tick, so samples = len - 1.
+    return len(arange) - 1, swow
+
+
+def test_ntsc_locked_rate_is_exactly_2_8_samples_per_line():
+    """freq=-2.8 yields exactly 1470 samples for a full 525-line frame."""
+    n_samples, swow = _output_sample_count(-2.8)
+
+    assert n_samples == 1470  # == 525 * 2.8, integer => no drift
+    # Evenly spaced lines means unity wow throughout.
+    np.testing.assert_allclose(swow, 1.0, atol=1e-9)
+
+
+def test_negative_freq_resolves_to_ntsc_locked_hz():
+    """-2.8 corresponds to ~44055.944 Hz (2.8 x the NTSC line frequency)."""
+    line_freq = 1_000_000 / NTSC_LINE_PERIOD
+    assert line_freq * 2.8 == 44055.944055944055
+
+
+def test_default_44100_does_not_frame_lock():
+    """The default 44100 Hz rate is a non-integer 1471.47 samples/frame."""
+    n_samples, _ = _output_sample_count(44100)
+
+    # 44100 / (30000/1001) ~= 1471.47, so it cannot equal the locked 1470.
+    assert n_samples != 1470
+    assert n_samples == 1471