diff --git a/README.md b/README.md index 2b9d004..7dd8645 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. 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. + ### 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. diff --git a/sendspin/audio.py b/sendspin/audio.py index 5bf1a63..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 @@ -17,6 +18,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 +32,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 @@ -38,6 +39,126 @@ 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_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( + 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. + """ + frame_size = bytes_per_sample * channels + 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 + + 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] + ).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 + + +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. @@ -231,6 +352,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) @@ -399,6 +521,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 @@ -437,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) @@ -699,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 @@ -911,18 +1038,58 @@ 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. 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 + bit_depth = self._format.bit_depth if self._format else 16 + + 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: - # Fill with silence - self._fill_silence(output_buffer, 0, len(output_buffer)) + silence_dop_frames(output_buffer, dop_frames, bit_depth // 8, self._format.channels) return if volume == 100: @@ -931,8 +1098,24 @@ def _apply_volume(self, output_buffer: memoryview) -> None: # 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 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/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.py b/tests/test_audio.py index 3290cb5..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 +from sendspin.audio import ( + AudioPlayer, + PlaybackState, + _QueuedChunk, + dop_idle_frames, + find_dop_frames, +) class _NoCallbackStatus: @@ -61,3 +67,179 @@ 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 _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_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 * 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: + 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: + 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 + + +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) 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