Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
199 changes: 191 additions & 8 deletions sendspin/audio.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@

import collections
import concurrent.futures
import functools
import logging
import queue
import time
Expand All @@ -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
Expand All @@ -30,14 +32,133 @@
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

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.

Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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)

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand All @@ -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
Expand Down
5 changes: 4 additions & 1 deletion sendspin/audio_devices.py
Original file line number Diff line number Diff line change
Expand Up @@ -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]

Expand Down
Loading
Loading