From 2ba61c96bb6aab8b2eecb55c440ce9737e75e9b8 Mon Sep 17 00:00:00 2001 From: Manuel Alcocer J Date: Sat, 7 Nov 2026 10:58:03 +0100 Subject: [PATCH 1/5] Offer the 44.1 kHz family up to 705.6 kHz for DSD over PCM DoP carries DSD64 as 176.4 kHz PCM, DSD128 as 352.8 kHz and DSD256 as 705.6 kHz. Format detection only probed 44.1/48/96/192 kHz, so a server could never send a DoP stream to a DAC that supports it. Each extra rate is still probed against the device before it is offered. --- sendspin/audio_devices.py | 5 ++++- tests/test_audio_devices.py | 16 ++++++++++++++++ 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/sendspin/audio_devices.py b/sendspin/audio_devices.py index eb1bf94..fac63f5 100644 --- a/sendspin/audio_devices.py +++ b/sendspin/audio_devices.py @@ -118,7 +118,10 @@ def detect_supported_audio_formats( Returns: List of supported audio formats, with FLAC formats first (preferred). """ - sample_rates = [48000, 44100, 96000, 192000] + # The 44.1 kHz family above 48 kHz (88.2/176.4/352.8 kHz) is what DSD over PCM + # (DoP) needs: DSD64 travels as 176.4 kHz, DSD128 as 352.8 kHz and DSD256 as + # 705.6 kHz. Each rate is still probed against the device before it is offered. + sample_rates = [48000, 44100, 96000, 88200, 192000, 176400, 384000, 352800, 768000, 705600] bit_depths = [24, 16] channel_counts = [2, 1] diff --git a/tests/test_audio_devices.py b/tests/test_audio_devices.py index 7db483c..df25228 100644 --- a/tests/test_audio_devices.py +++ b/tests/test_audio_devices.py @@ -157,3 +157,19 @@ def test_detect_supported_audio_formats_falls_back_for_alsa_only_device(): formats = detect_supported_audio_formats(_alsa_only_device()) assert formats, "expected safe-default formats for an unprobeable device" + + +def test_detect_supported_audio_formats_offers_dop_rates(): + """The 44.1 kHz family used by DSD over PCM (DoP) is offered when the device takes it.""" + device_rates = {44100, 48000, 88200, 96000, 176400, 192000, 352800, 384000} + + def _fake_check(_device: AudioDevice, rate: int, _channels: int, _dtype: str) -> bool: + return rate in device_rates + + device = _alsa_only_device() + with patch.object(_mod, "_check_format", side_effect=_fake_check): + formats = detect_supported_audio_formats(device) + + pcm_rates = {f.sample_rate for f in formats if f.codec.value == "pcm"} + assert {176400, 352800} <= pcm_rates + assert 705600 not in pcm_rates From 92b90d53452b1a55583bc271e03438329986d499 Mon Sep 17 00:00:00 2001 From: Manuel Alcocer J Date: Sat, 7 Nov 2026 11:23:53 +0100 Subject: [PATCH 2/5] Leave DoP buffers untouched by software volume A DoP (DSD over PCM) stream is only DSD while every sample stays bit-exact: scaling it hides the markers from the DAC, which then plays it as full-scale noise. Skip software volume when a buffer carries the alternating 0x05/0xFA markers; the volume of DSD is set on the amp. --- sendspin/audio.py | 39 +++++++++++++++++++++++++++++++++- tests/test_audio.py | 52 ++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 89 insertions(+), 2 deletions(-) diff --git a/sendspin/audio.py b/sendspin/audio.py index 5bf1a63..376a03e 100644 --- a/sendspin/audio.py +++ b/sendspin/audio.py @@ -38,6 +38,37 @@ logger = logging.getLogger(__name__) +# DoP (DSD over PCM) marks every frame with a marker byte in the top byte of each +# sample, alternating 0x05 / 0xFA from frame to frame and identical on all channels. +_DOP_MARKERS = (0x05, 0xFA) +_DOP_CHECK_FRAMES = 8 + + +def is_dop_buffer(buffer: memoryview | bytes, bytes_per_sample: int, channels: int) -> bool: + """Return True if a PCM buffer carries DoP, which must reach the DAC unaltered. + + Only 24-bit and wider samples can carry DoP. The first frames are checked for the + alternating markers, which plain PCM practically never produces. + """ + if bytes_per_sample < 3 or channels < 1: + return False + frame_size = bytes_per_sample * channels + if len(buffer) < frame_size * _DOP_CHECK_FRAMES: + return False + top = bytes_per_sample - 1 + first = buffer[top] + if first not in _DOP_MARKERS: + return False + other = _DOP_MARKERS[1] if first == _DOP_MARKERS[0] else _DOP_MARKERS[0] + for frame in range(_DOP_CHECK_FRAMES): + expected = first if frame % 2 == 0 else other + base = frame * frame_size + top + for channel in range(channels): + if buffer[base + channel * bytes_per_sample] != expected: + return False + return True + + class AudioTimeInfo(Protocol): """Protocol for audio timing information from sounddevice callback. @@ -928,10 +959,16 @@ def _apply_volume(self, output_buffer: memoryview) -> None: if volume == 100: return + bit_depth = self._format.bit_depth if self._format else 16 + if self._format is not None and is_dop_buffer( + output_buffer, bit_depth // 8, self._format.channels + ): + # Scaling DoP turns DSD into full-scale noise; its volume belongs to the amp. + return + # Power curve for natural volume control (gentler at high volumes) amplitude = (volume / 100.0) ** 1.5 - bit_depth = self._format.bit_depth if self._format else 16 num_bytes = len(output_buffer) if _c_apply_volume is not None: diff --git a/tests/test_audio.py b/tests/test_audio.py index 3290cb5..c336d47 100644 --- a/tests/test_audio.py +++ b/tests/test_audio.py @@ -2,7 +2,7 @@ from types import SimpleNamespace -from sendspin.audio import AudioPlayer, PlaybackState, _QueuedChunk +from sendspin.audio import AudioPlayer, PlaybackState, _QueuedChunk, is_dop_buffer class _NoCallbackStatus: @@ -61,3 +61,53 @@ def now() -> int: assert player._drop_every_n_frames == 0 # noqa: SLF001 assert player._insert_every_n_frames == 0 # noqa: SLF001 + + + +def _dop_buffer(frames: int, *, bytes_per_sample: int = 3, channels: int = 2) -> bytearray: + """Build packed little-endian DoP frames (marker in the top byte of each sample).""" + out = bytearray() + for frame in range(frames): + marker = 0x05 if frame % 2 == 0 else 0xFA + for _ in range(channels): + out += bytes(bytes_per_sample - 3) + bytes([0x69, 0x96, marker]) + return out + + +def _volume_player(volume: int, *, bit_depth: int = 24) -> AudioPlayer: + player = AudioPlayer(lambda ts: ts, lambda ts: ts) + player._format = SimpleNamespace( # noqa: SLF001 + sample_rate=176_400, + channels=2, + bit_depth=bit_depth, + frame_size=2 * bit_depth // 8, + ) + player._volume = volume # noqa: SLF001 + player._muted = False # noqa: SLF001 + return player + + +def test_is_dop_buffer_detects_markers() -> None: + assert is_dop_buffer(bytes(_dop_buffer(16)), 3, 2) + assert is_dop_buffer(bytes(_dop_buffer(16, bytes_per_sample=4)), 4, 2) + assert not is_dop_buffer(bytes(_dop_buffer(16)), 2, 3) + broken = _dop_buffer(16) + broken[3 * 2 * 3 + 2] = 0x05 # fourth frame repeats the marker of the third + assert not is_dop_buffer(bytes(broken), 3, 2) + assert not is_dop_buffer(bytes(6 * 16), 3, 2) + + +def test_volume_leaves_dop_untouched() -> None: + dop = _dop_buffer(64) + player = _volume_player(40) + buffer = bytearray(dop) + player._apply_volume(memoryview(buffer)) # noqa: SLF001 + assert buffer == dop + + +def test_volume_still_scales_plain_pcm() -> None: + pcm = bytearray(b"\x00\x00\x40" * 2 * 64) + player = _volume_player(40) + buffer = bytearray(pcm) + player._apply_volume(memoryview(buffer)) # noqa: SLF001 + assert buffer != pcm From 155e0d18d478987d697f311fa07086233bac6e02 Mon Sep 17 00:00:00 2001 From: Manuel Alcocer J Date: Thu, 12 Nov 2026 09:18:02 +0100 Subject: [PATCH 3/5] Keep short DoP tails and mixed buffers out of software volume The DoP check looked at the first eight frames of each output buffer, so a callback holding a few DoP frames before zero padding, DoP that starts after start-gating silence, or a PCM/DoP transition inside one buffer was scaled as a whole and its markers were corrupted. Classify every frame instead: a run of alternating markers counts as DoP when it is at least eight frames long, continues the DoP run that ended the previous callback, or reaches the end of the buffer. Software volume now scales only the PCM stretches between DoP runs, and clear() forgets the carried-over marker. --- sendspin/audio.py | 107 +++++++++++++++++++++++++++++++------------- tests/test_audio.py | 73 +++++++++++++++++++++++++----- 2 files changed, 139 insertions(+), 41 deletions(-) diff --git a/sendspin/audio.py b/sendspin/audio.py index 376a03e..9725b3a 100644 --- a/sendspin/audio.py +++ b/sendspin/audio.py @@ -17,6 +17,7 @@ from enum import Enum, auto from typing import TYPE_CHECKING, Final, Protocol, cast +import numpy as np import sounddevice from aiosendspin.client.time_sync import SendspinTimeFilter from sounddevice import CallbackFlags @@ -30,7 +31,6 @@ logging.getLogger(__name__).info( "C volume extension unavailable; falling back to numpy (slower)" ) - import numpy as np if TYPE_CHECKING: from aiosendspin.client import AudioFormat, PCMFormat @@ -41,32 +41,52 @@ # DoP (DSD over PCM) marks every frame with a marker byte in the top byte of each # sample, alternating 0x05 / 0xFA from frame to frame and identical on all channels. _DOP_MARKERS = (0x05, 0xFA) -_DOP_CHECK_FRAMES = 8 - - -def is_dop_buffer(buffer: memoryview | bytes, bytes_per_sample: int, channels: int) -> bool: - """Return True if a PCM buffer carries DoP, which must reach the DAC unaltered. - - Only 24-bit and wider samples can carry DoP. The first frames are checked for the - alternating markers, which plain PCM practically never produces. +_DOP_MIN_RUN_FRAMES = 8 + + +def find_dop_frames( + buffer: memoryview | bytes | bytearray, + bytes_per_sample: int, + channels: int, + previous_marker: int | None = None, +) -> tuple[np.ndarray, int | None]: + """Return which frames of a PCM buffer carry DoP, plus the marker to continue from. + + A run of frames whose markers alternate counts as DoP when it has at least + ``_DOP_MIN_RUN_FRAMES`` frames, when it continues the DoP run that ended the + previous buffer (``previous_marker``) or when it reaches the end of the buffer. + That keeps short DoP tails before zero padding, DoP that starts after silence and + PCM/DoP transitions inside one buffer classified correctly. Only 24-bit and wider + samples can carry DoP. """ - if bytes_per_sample < 3 or channels < 1: - return False frame_size = bytes_per_sample * channels - if len(buffer) < frame_size * _DOP_CHECK_FRAMES: - return False - top = bytes_per_sample - 1 - first = buffer[top] - if first not in _DOP_MARKERS: - return False - other = _DOP_MARKERS[1] if first == _DOP_MARKERS[0] else _DOP_MARKERS[0] - for frame in range(_DOP_CHECK_FRAMES): - expected = first if frame % 2 == 0 else other - base = frame * frame_size + top - for channel in range(channels): - if buffer[base + channel * bytes_per_sample] != expected: - return False - return True + n_frames = len(buffer) // frame_size if frame_size > 0 else 0 + if bytes_per_sample < 3 or channels < 1 or n_frames == 0: + return np.zeros(n_frames, dtype=bool), None + + samples = np.frombuffer(buffer, dtype=np.uint8, count=n_frames * frame_size) + tops = samples.reshape(n_frames, channels, bytes_per_sample)[:, :, bytes_per_sample - 1] + marker = tops[:, 0] + is_marker = ((marker == _DOP_MARKERS[0]) | (marker == _DOP_MARKERS[1])) & ( + tops == marker[:, None] + ).all(axis=1) + + # linked[i]: frame i continues the alternating run of the frame before it. + linked = np.zeros(n_frames, dtype=bool) + linked[1:] = is_marker[1:] & is_marker[:-1] & (marker[1:] != marker[:-1]) + linked[0] = bool(is_marker[0] and previous_marker is not None and marker[0] != previous_marker) + + # Number the runs; run 0 is the continuation of the previous buffer's DoP run. + run_ids = np.cumsum(is_marker & ~linked) + lengths = np.bincount(run_ids[is_marker], minlength=int(run_ids[-1]) + 1) + keep = lengths >= _DOP_MIN_RUN_FRAMES + keep[0] = True + if is_marker[-1]: + keep[run_ids[-1]] = True + mask = is_marker & keep[run_ids] + + last_marker = int(marker[-1]) if mask[-1] else None + return mask, last_marker class AudioTimeInfo(Protocol): @@ -262,6 +282,7 @@ def __init__( self._frames_until_next_insert: int = 0 self._frames_until_next_drop: int = 0 self._last_output_frame: bytes = b"" + self._dop_last_marker: int | None = None # Sync error smoothing (Kalman filter) and re-anchor cooldown self._sync_error_filter = SendspinTimeFilter(process_std_dev=0.01, forget_factor=1.001) @@ -430,6 +451,7 @@ def clear(self) -> None: self._frames_until_next_insert = 0 self._frames_until_next_drop = 0 self._last_output_frame = b"" + self._dop_last_marker = None self._sync_error_filter.reset() self._sync_error_filtered_us = 0.0 self._last_reanchor_loop_time_us = 0 @@ -947,6 +969,8 @@ def _apply_volume(self, output_buffer: memoryview) -> None: Apply volume scaling to the output buffer. Scales audio samples by the current volume level, supporting multiple bit depths. + Frames carrying DoP are left untouched: scaling them turns DSD into full-scale + noise, so DSD volume belongs to the DAC or amplifier. """ muted = self._muted volume = self._volume @@ -954,22 +978,43 @@ def _apply_volume(self, output_buffer: memoryview) -> None: if muted or volume == 0: # Fill with silence self._fill_silence(output_buffer, 0, len(output_buffer)) + self._dop_last_marker = None return if volume == 100: + self._dop_last_marker = None return + # Power curve for natural volume control (gentler at high volumes) + amplitude = (volume / 100.0) ** 1.5 bit_depth = self._format.bit_depth if self._format else 16 - if self._format is not None and is_dop_buffer( - output_buffer, bit_depth // 8, self._format.channels - ): - # Scaling DoP turns DSD into full-scale noise; its volume belongs to the amp. + + if self._format is None or bit_depth < 24: + self._scale_samples(output_buffer, amplitude, bit_depth) return - # Power curve for natural volume control (gentler at high volumes) - amplitude = (volume / 100.0) ** 1.5 + frame_size = self._format.frame_size + dop_frames, self._dop_last_marker = find_dop_frames( + output_buffer, bit_depth // 8, self._format.channels, self._dop_last_marker + ) + if not dop_frames.any(): + self._scale_samples(output_buffer, amplitude, bit_depth) + return + # Scale only the PCM stretches between DoP runs. + edges = np.flatnonzero(np.diff(dop_frames.astype(np.int8))) + 1 + bounds = [0, *edges.tolist(), len(dop_frames)] + for start, end in zip(bounds[:-1], bounds[1:], strict=True): + if not dop_frames[start]: + self._scale_samples( + output_buffer[start * frame_size : end * frame_size], amplitude, bit_depth + ) + + def _scale_samples(self, output_buffer: memoryview, amplitude: float, bit_depth: int) -> None: + """Scale the samples in a buffer by a linear amplitude factor.""" num_bytes = len(output_buffer) + if num_bytes == 0: + return if _c_apply_volume is not None: # Fast path: fixed-point volume scaling via C extension diff --git a/tests/test_audio.py b/tests/test_audio.py index c336d47..6ab39b1 100644 --- a/tests/test_audio.py +++ b/tests/test_audio.py @@ -2,7 +2,7 @@ from types import SimpleNamespace -from sendspin.audio import AudioPlayer, PlaybackState, _QueuedChunk, is_dop_buffer +from sendspin.audio import AudioPlayer, PlaybackState, _QueuedChunk, find_dop_frames class _NoCallbackStatus: @@ -63,7 +63,6 @@ def now() -> int: assert player._insert_every_n_frames == 0 # noqa: SLF001 - def _dop_buffer(frames: int, *, bytes_per_sample: int = 3, channels: int = 2) -> bytearray: """Build packed little-endian DoP frames (marker in the top byte of each sample).""" out = bytearray() @@ -87,14 +86,68 @@ def _volume_player(volume: int, *, bit_depth: int = 24) -> AudioPlayer: return player -def test_is_dop_buffer_detects_markers() -> None: - assert is_dop_buffer(bytes(_dop_buffer(16)), 3, 2) - assert is_dop_buffer(bytes(_dop_buffer(16, bytes_per_sample=4)), 4, 2) - assert not is_dop_buffer(bytes(_dop_buffer(16)), 2, 3) - broken = _dop_buffer(16) - broken[3 * 2 * 3 + 2] = 0x05 # fourth frame repeats the marker of the third - assert not is_dop_buffer(bytes(broken), 3, 2) - assert not is_dop_buffer(bytes(6 * 16), 3, 2) +def _pcm_buffer(frames: int) -> bytearray: + """Build packed 24-bit stereo PCM frames at a steady quarter-scale level.""" + return bytearray(b"\x00\x00\x20" * 2 * frames) + + +def test_find_dop_frames_detects_markers() -> None: + mask, last = find_dop_frames(bytes(_dop_buffer(16)), 3, 2) + assert mask.all() + assert last == 0xFA + assert find_dop_frames(bytes(_dop_buffer(16, bytes_per_sample=4)), 4, 2)[0].all() + assert not find_dop_frames(bytes(_dop_buffer(16)), 2, 3)[0].any() + assert not find_dop_frames(bytes(6 * 16), 3, 2)[0].any() + + +def test_find_dop_frames_rejects_short_runs_inside_pcm() -> None: + buffer = _pcm_buffer(8) + _dop_buffer(4) + _pcm_buffer(8) + mask, last = find_dop_frames(bytes(buffer), 3, 2) + assert not mask.any() + assert last is None + + +def test_find_dop_frames_keeps_a_short_tail_that_continues_dop() -> None: + # Three DoP frames left at the end of a stream, followed by zero padding. + buffer = _dop_buffer(3) + bytearray(6 * 61) + mask, last = find_dop_frames(bytes(buffer), 3, 2, previous_marker=0xFA) + assert mask[:3].all() + assert not mask[3:].any() + assert last is None + # The same tail does not count as DoP if the previous buffer was not DoP. + assert not find_dop_frames(bytes(buffer), 3, 2)[0].any() + + +def test_volume_leaves_a_padded_dop_tail_untouched() -> None: + player = _volume_player(40) + first = bytearray(_dop_buffer(64)) + player._apply_volume(memoryview(first)) # noqa: SLF001 + assert first == _dop_buffer(64) + + # The next callback gets two DoP frames, then zero padding after an underrun. + tail = _dop_buffer(2) + bytearray(6 * 62) + buffer = bytearray(tail) + player._apply_volume(memoryview(buffer)) # noqa: SLF001 + assert buffer == tail + + +def test_volume_scales_only_the_pcm_around_dop() -> None: + # Silence while waiting for the start, then DoP, then a transition back to PCM. + dop = _dop_buffer(32) + buffer = bytearray(6 * 8) + dop + _pcm_buffer(24) + player = _volume_player(40) + player._apply_volume(memoryview(buffer)) # noqa: SLF001 + assert buffer[: 6 * 8] == bytearray(6 * 8) + assert buffer[6 * 8 : 6 * 40] == dop + assert buffer[6 * 40 :] != _pcm_buffer(24) + + +def test_clear_forgets_the_dop_state() -> None: + player = _volume_player(40) + player._apply_volume(memoryview(bytearray(_dop_buffer(64)))) # noqa: SLF001 + assert player._dop_last_marker is not None # noqa: SLF001 + player.clear() + assert player._dop_last_marker is None # noqa: SLF001 def test_volume_leaves_dop_untouched() -> None: From 27f8d036d821574ed36883b82efe8ff2f8017cf5 Mon Sep 17 00:00:00 2001 From: Manuel Alcocer J Date: Thu, 12 Nov 2026 09:18:02 +0100 Subject: [PATCH 4/5] Document DoP playback, its volume bypass and its limits --- README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/README.md b/README.md index 2b9d004..0e8b344 100644 --- a/README.md +++ b/README.md @@ -289,6 +289,16 @@ The format string uses the pattern `codec:sample_rate:bit_depth:channels`: The specified format is validated against the audio device on startup. If the device doesn't support it, the player will exit with an error. +### DSD over PCM (DoP) + +A server that sends DSD as DoP (DSD over PCM) packs the DSD bits into 24-bit or 32-bit PCM frames whose top byte carries a marker: DSD64 travels as 176.4 kHz, DSD128 as 352.8 kHz and DSD256 as 705.6 kHz. A DAC with DoP support recognises the markers and plays the DSD directly. The player offers these rates whenever the audio device supports them, so DoP needs no extra option. Keep the automatic format, or pick a 24-bit format with `--audio-format`, because 16-bit output cannot carry DoP. + +DoP only works if the frames reach the DAC bit for bit: + +- **Volume:** software volume would turn DoP into full-scale noise, so the player recognises DoP frames by their markers and leaves them unscaled at any `player_volume` above 0 (0 and mute still output silence). Set the level on the DAC or amplifier instead, for example through `--hook-set-volume` (see [System Volume Control](#system-volume-control)) or a fixed volume on the server. +- **Output path:** the device must pass the samples through unchanged. Point `--audio-device` at the DAC's own ALSA device (`hw:` or a `plughw:` that does not resample) rather than PulseAudio/PipeWire, dmix or another mixing or resampling plugin. +- **Sync correction:** to stay in sync with the server clock, the player now and then repeats or skips a single frame. Each correction breaks the marker sequence, and depending on the DAC that means a short click or a brief loss of DoP lock. How often it happens depends on how far the DAC clock drifts from the server clock. + ### System Volume Control On Linux with PulseAudio/PipeWire, Sendspin can control your system output volume directly. Volume adjustments (keyboard shortcuts, server commands) change the system volume. The current system volume is read on startup — the `player_volume` and `player_muted` settings are only used when hardware volume is disabled. From 8d5352fb010decfb655c34f610dfb6a55545b450 Mon Sep 17 00:00:00 2001 From: Manuel Alcocer J Date: Thu, 12 Nov 2026 09:29:30 +0100 Subject: [PATCH 5/5] Keep the DAC in DSD mode on underruns and mute Underrun padding, a device underflow and mute wrote zero bytes, which end the DoP marker sequence: the DAC drops out of DSD mode and has to lock again, often with a click. While DoP plays, fill those gaps with DoP frames that carry the DSD idle pattern (0x69) and keep the markers alternating, and mute only the payload of DoP frames. DoP is now tracked on every callback, not only below 100% volume. Two fast paths keep that cheap: a PCM buffer that neither continues DoP nor starts or ends with a marker, and a buffer that simply continues the running marker sequence (about 12 us per 2048 frames on an Orange Pi 3B, against 550 us for the full classification). --- README.md | 2 +- sendspin/audio.py | 135 ++++++++++++++++++++++++++++++++++++++------ tests/test_audio.py | 95 ++++++++++++++++++++++++++++--- 3 files changed, 206 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 0e8b344..7dd8645 100644 --- a/README.md +++ b/README.md @@ -295,7 +295,7 @@ A server that sends DSD as DoP (DSD over PCM) packs the DSD bits into 24-bit or DoP only works if the frames reach the DAC bit for bit: -- **Volume:** software volume would turn DoP into full-scale noise, so the player recognises DoP frames by their markers and leaves them unscaled at any `player_volume` above 0 (0 and mute still output silence). Set the level on the DAC or amplifier instead, for example through `--hook-set-volume` (see [System Volume Control](#system-volume-control)) or a fixed volume on the server. +- **Volume:** software volume would turn DoP into full-scale noise, so the player recognises DoP frames by their markers and leaves them unscaled at any `player_volume` above 0. Volume 0 and mute output DSD silence (the `0x69` idle pattern inside DoP frames), and so does an underrun while DoP plays, so the DAC stays in DSD mode instead of dropping back to PCM. Set the level on the DAC or amplifier instead, for example through `--hook-set-volume` (see [System Volume Control](#system-volume-control)) or a fixed volume on the server. - **Output path:** the device must pass the samples through unchanged. Point `--audio-device` at the DAC's own ALSA device (`hw:` or a `plughw:` that does not resample) rather than PulseAudio/PipeWire, dmix or another mixing or resampling plugin. - **Sync correction:** to stay in sync with the server clock, the player now and then repeats or skips a single frame. Each correction breaks the marker sequence, and depending on the DAC that means a short click or a brief loss of DoP lock. How often it happens depends on how far the DAC clock drifts from the server clock. diff --git a/sendspin/audio.py b/sendspin/audio.py index 9725b3a..6d3948f 100644 --- a/sendspin/audio.py +++ b/sendspin/audio.py @@ -9,6 +9,7 @@ import collections import concurrent.futures +import functools import logging import queue import time @@ -42,6 +43,17 @@ # sample, alternating 0x05 / 0xFA from frame to frame and identical on all channels. _DOP_MARKERS = (0x05, 0xFA) _DOP_MIN_RUN_FRAMES = 8 +# DSD idle pattern: as many ones as zeros, so the DAC outputs silence and stays in +# DSD mode. Zero bytes would end DoP and make the DAC switch back to PCM. +_DSD_IDLE_BYTE = 0x69 + + +@functools.lru_cache(maxsize=8) +def _dop_marker_pattern(n_frames: int, channels: int, first: int) -> bytes: + """Return the top bytes of ``n_frames`` DoP frames whose markers start at ``first``.""" + second = _DOP_MARKERS[0] + _DOP_MARKERS[1] - first + pair = bytes([first]) * channels + bytes([second]) * channels + return (pair * ((n_frames + 1) // 2))[: n_frames * channels] def find_dop_frames( @@ -64,8 +76,27 @@ def find_dop_frames( if bytes_per_sample < 3 or channels < 1 or n_frames == 0: return np.zeros(n_frames, dtype=bool), None + top = bytes_per_sample - 1 + if ( + previous_marker is None + and buffer[top] not in _DOP_MARKERS + and buffer[(n_frames - 1) * frame_size + top] not in _DOP_MARKERS + ): + # Fast path for PCM: a buffer that neither continues DoP nor starts or ends + # with a marker holds at most a DoP fragment shorter than itself. + return np.zeros(n_frames, dtype=bool), None + + if previous_marker is not None: + # Fast path for steady DoP: the whole buffer continues the marker sequence. + first = _DOP_MARKERS[1] if previous_marker == _DOP_MARKERS[0] else _DOP_MARKERS[0] + tops_bytes = bytes(memoryview(buffer)[top : n_frames * frame_size : bytes_per_sample]) + if tops_bytes == _dop_marker_pattern(n_frames, channels, first): + last = first if n_frames % 2 == 1 else _DOP_MARKERS[0] + _DOP_MARKERS[1] - first + return np.ones(n_frames, dtype=bool), last + samples = np.frombuffer(buffer, dtype=np.uint8, count=n_frames * frame_size) tops = samples.reshape(n_frames, channels, bytes_per_sample)[:, :, bytes_per_sample - 1] + marker = tops[:, 0] is_marker = ((marker == _DOP_MARKERS[0]) | (marker == _DOP_MARKERS[1])) & ( tops == marker[:, None] @@ -89,6 +120,45 @@ def find_dop_frames( return mask, last_marker +def dop_idle_frames( + n_frames: int, bytes_per_sample: int, channels: int, previous_marker: int | None +) -> tuple[bytes, int | None]: + """Return DoP frames carrying DSD silence, continuing the marker sequence. + + The 16 DSD bits of each sample hold the idle pattern and the markers keep + alternating from ``previous_marker``, so the DAC stays locked in DSD mode. + Returns the frames and the marker of the last one. + """ + if n_frames <= 0 or bytes_per_sample < 3 or channels < 1: + return b"", previous_marker + first = _DOP_MARKERS[1] if previous_marker == _DOP_MARKERS[0] else _DOP_MARKERS[0] + second = _DOP_MARKERS[1] if first == _DOP_MARKERS[0] else _DOP_MARKERS[0] + frames = np.zeros((n_frames, channels, bytes_per_sample), dtype=np.uint8) + frames[:, :, bytes_per_sample - 3 : bytes_per_sample - 1] = _DSD_IDLE_BYTE + frames[0::2, :, bytes_per_sample - 1] = first + frames[1::2, :, bytes_per_sample - 1] = second + last = first if n_frames % 2 == 1 else second + return frames.tobytes(), last + + +def silence_dop_frames( + buffer: memoryview | bytearray, dop_frames: np.ndarray, bytes_per_sample: int, channels: int +) -> None: + """Silence a buffer in place, keeping DoP frames as DoP. + + PCM frames become zeros. DoP frames keep their markers and get the DSD idle + pattern, so a muted DSD stream stays silent DSD instead of dropping out of DoP. + """ + samples = np.frombuffer( + buffer, dtype=np.uint8, count=len(dop_frames) * bytes_per_sample * channels + ) + frames = samples.reshape(len(dop_frames), channels, bytes_per_sample) + frames[~dop_frames] = 0 + if bytes_per_sample > 3: + frames[dop_frames, :, : bytes_per_sample - 3] = 0 + frames[dop_frames, :, bytes_per_sample - 3 : bytes_per_sample - 1] = _DSD_IDLE_BYTE + + class AudioTimeInfo(Protocol): """Protocol for audio timing information from sounddevice callback. @@ -490,7 +560,7 @@ def _audio_callback( # noqa: PLR0915 logger.warning("Audio underflow detected; requesting re-anchor") self._clear_requested = True # Fill buffer with silence and return early to avoid glitches - self._fill_silence(output_buffer, 0, bytes_needed) + self._fill_padding(output_buffer, 0, frames) return logger.debug("Audio callback status: %s", status) @@ -752,9 +822,13 @@ def _read_input_frames_bulk(self, n_frames: int) -> bytes: try: self._initialize_current_chunk() except queue.Empty: - # No more data - pad with silence - silence_bytes = total_bytes_needed - bytes_written - result[bytes_written:] = b"\x00" * silence_bytes + # No more data - pad with silence (DSD silence while DoP plays) + # The DoP state itself is updated later, by _apply_volume. + padding, _ = self._padding_bytes( + (total_bytes_needed - bytes_written) // frame_size, + memoryview(result)[:bytes_written], + ) + result[bytes_written:] = padding break # Calculate how much we can read from current chunk @@ -964,6 +1038,29 @@ def _fill_silence(self, output_buffer: memoryview, offset: int, num_bytes: int) if num_bytes > 0: output_buffer[offset : offset + num_bytes] = b"\x00" * num_bytes + def _padding_bytes(self, n_frames: int, preceding: memoryview) -> tuple[bytes, int | None]: + """Return silence to pad an underrun, continuing DoP if the audio before it was DoP. + + ``preceding`` is the audio already read into the same buffer; when it is empty, + the DoP state left by the previous callback decides. Also returns the DoP marker + of the last padding frame, or None if the padding is plain zeros. + """ + assert self._format is not None + bytes_per_sample = self._format.bit_depth // 8 + channels = self._format.channels + marker = self._dop_last_marker + if bytes_per_sample >= 3 and len(preceding) >= self._format.frame_size: + _, marker = find_dop_frames(preceding, bytes_per_sample, channels, marker) + if bytes_per_sample < 3 or marker is None: + return b"\x00" * (n_frames * self._format.frame_size), None + return dop_idle_frames(n_frames, bytes_per_sample, channels, marker) + + def _fill_padding(self, output_buffer: memoryview, offset: int, n_frames: int) -> None: + """Fill frames with silence that keeps a running DoP stream in DSD mode.""" + assert self._format is not None + padding, self._dop_last_marker = self._padding_bytes(n_frames, output_buffer[:0]) + output_buffer[offset : offset + len(padding)] = padding + def _apply_volume(self, output_buffer: memoryview) -> None: """ Apply volume scaling to the output buffer. @@ -974,29 +1071,33 @@ def _apply_volume(self, output_buffer: memoryview) -> None: """ muted = self._muted volume = self._volume + bit_depth = self._format.bit_depth if self._format else 16 - if muted or volume == 0: - # Fill with silence - self._fill_silence(output_buffer, 0, len(output_buffer)) + if self._format is None or bit_depth < 24: + # Too narrow to carry DoP. self._dop_last_marker = None + if muted or volume == 0: + self._fill_silence(output_buffer, 0, len(output_buffer)) + elif volume != 100: + self._scale_samples(output_buffer, (volume / 100.0) ** 1.5, bit_depth) + return + + # Track DoP at every volume, so padding and mute can keep the DAC in DSD mode. + frame_size = self._format.frame_size + dop_frames, self._dop_last_marker = find_dop_frames( + output_buffer, bit_depth // 8, self._format.channels, self._dop_last_marker + ) + + if muted or volume == 0: + silence_dop_frames(output_buffer, dop_frames, bit_depth // 8, self._format.channels) return if volume == 100: - self._dop_last_marker = None return # Power curve for natural volume control (gentler at high volumes) amplitude = (volume / 100.0) ** 1.5 - bit_depth = self._format.bit_depth if self._format else 16 - - if self._format is None or bit_depth < 24: - self._scale_samples(output_buffer, amplitude, bit_depth) - return - frame_size = self._format.frame_size - dop_frames, self._dop_last_marker = find_dop_frames( - output_buffer, bit_depth // 8, self._format.channels, self._dop_last_marker - ) if not dop_frames.any(): self._scale_samples(output_buffer, amplitude, bit_depth) return diff --git a/tests/test_audio.py b/tests/test_audio.py index 6ab39b1..32d3fe4 100644 --- a/tests/test_audio.py +++ b/tests/test_audio.py @@ -2,7 +2,13 @@ from types import SimpleNamespace -from sendspin.audio import AudioPlayer, PlaybackState, _QueuedChunk, find_dop_frames +from sendspin.audio import ( + AudioPlayer, + PlaybackState, + _QueuedChunk, + dop_idle_frames, + find_dop_frames, +) class _NoCallbackStatus: @@ -131,15 +137,26 @@ def test_volume_leaves_a_padded_dop_tail_untouched() -> None: assert buffer == tail -def test_volume_scales_only_the_pcm_around_dop() -> None: - # Silence while waiting for the start, then DoP, then a transition back to PCM. - dop = _dop_buffer(32) - buffer = bytearray(6 * 8) + dop + _pcm_buffer(24) +def test_volume_keeps_dop_that_starts_after_silence() -> None: + # Silence while waiting for the start, then DoP up to the end of the buffer. + dop = _dop_buffer(56) + buffer = bytearray(6 * 8) + dop + player = _volume_player(40) + player._apply_volume(memoryview(buffer)) # noqa: SLF001 + assert buffer == bytearray(6 * 8) + dop + + +def test_volume_scales_only_the_pcm_after_dop() -> None: player = _volume_player(40) + player._apply_volume(memoryview(bytearray(_dop_buffer(64)))) # noqa: SLF001 + + # DoP continues into this buffer, then the stream turns back to PCM. + dop = _dop_buffer(32) + buffer = dop + _pcm_buffer(32) player._apply_volume(memoryview(buffer)) # noqa: SLF001 - assert buffer[: 6 * 8] == bytearray(6 * 8) - assert buffer[6 * 8 : 6 * 40] == dop - assert buffer[6 * 40 :] != _pcm_buffer(24) + assert buffer[: 6 * 32] == dop + assert buffer[6 * 32 :] != _pcm_buffer(32) + assert player._dop_last_marker is None # noqa: SLF001 def test_clear_forgets_the_dop_state() -> None: @@ -164,3 +181,65 @@ def test_volume_still_scales_plain_pcm() -> None: buffer = bytearray(pcm) player._apply_volume(memoryview(buffer)) # noqa: SLF001 assert buffer != pcm + + +def test_dop_idle_frames_continue_the_markers() -> None: + frames, last = dop_idle_frames(3, 3, 2, previous_marker=0x05) + assert frames == bytes([0x69, 0x69, 0xFA] * 2 + [0x69, 0x69, 0x05] * 2 + [0x69, 0x69, 0xFA] * 2) + assert last == 0xFA + frames, last = dop_idle_frames(2, 4, 1, previous_marker=None) + assert frames == bytes([0x00, 0x69, 0x69, 0x05, 0x00, 0x69, 0x69, 0xFA]) + assert last == 0xFA + + +def _queued_player(audio: bytes, *, volume: int = 100) -> AudioPlayer: + player = _volume_player(volume) + player._queue.put_nowait( # noqa: SLF001 + _QueuedChunk(server_timestamp_us=1, audio_data=audio) + ) + return player + + +def test_underrun_after_dop_pads_with_dsd_silence() -> None: + player = _queued_player(bytes(_dop_buffer(3))) + player._dop_last_marker = 0xFA # noqa: SLF001 + data = player._read_input_frames_bulk(8) # noqa: SLF001 + assert data[: 6 * 3] == _dop_buffer(3) + _, padding_last = dop_idle_frames(5, 3, 2, previous_marker=0x05) + assert data[6 * 3 :] == dop_idle_frames(5, 3, 2, previous_marker=0x05)[0] + mask, last = find_dop_frames(data, 3, 2, previous_marker=0xFA) + assert mask.all() + assert last == padding_last + + +def test_underrun_after_pcm_pads_with_zeros() -> None: + player = _queued_player(bytes(_pcm_buffer(3))) + data = player._read_input_frames_bulk(8) # noqa: SLF001 + assert data[6 * 3 :] == bytes(6 * 5) + + +def test_device_underflow_during_dop_outputs_dsd_silence() -> None: + player = _volume_player(100) + player._dop_last_marker = 0x05 # noqa: SLF001 + buffer = bytearray(6 * 4) + player._fill_padding(memoryview(buffer), 0, 4) # noqa: SLF001 + assert buffer == dop_idle_frames(4, 3, 2, previous_marker=0x05)[0] + assert player._dop_last_marker == 0x05 # noqa: SLF001 + + +def test_mute_keeps_dop_as_dsd_silence() -> None: + player = _volume_player(40) + player._muted = True # noqa: SLF001 + buffer = _dop_buffer(32) + _pcm_buffer(32) + player._dop_last_marker = 0xFA # noqa: SLF001 + player._apply_volume(memoryview(buffer)) # noqa: SLF001 + assert buffer[: 6 * 32] == dop_idle_frames(32, 3, 2, previous_marker=0xFA)[0] + assert buffer[6 * 32 :] == bytes(6 * 32) + + +def test_mute_without_dop_outputs_zeros() -> None: + player = _volume_player(40) + player._muted = True # noqa: SLF001 + buffer = _pcm_buffer(32) + player._apply_volume(memoryview(buffer)) # noqa: SLF001 + assert buffer == bytes(6 * 32)