Your Android phone and your Windows PC, working as one. Local-first, end-to-end encrypted, no account.
// SPDX-License-Identifier: GPL-3.0-or-later
//! Low-latency 16-bit signed little-endian PCM playback on Linux via
//! PulseAudio (`pacat`), PipeWire (`pw-play`), or ALSA (`aplay`), backed by an
//! adaptive jitter buffer with smooth sample interpolation.
use std::collections::VecDeque;
use std::io::{Result, Write};
use std::process::{Child, Command, Stdio};
use std::sync::mpsc::{self, SyncSender, TrySendError};
use std::sync::{
Arc,
atomic::{AtomicBool, Ordering},
};
use std::thread::{self, JoinHandle};
use std::time::{Duration, Instant};
const BYTES_PER_SAMPLE: usize = 2;
const JITTER_START_MS: usize = 40;
const JITTER_LOW_MS: usize = 20;
const JITTER_TARGET_MS: usize = 80;
const JITTER_HIGH_MS: usize = 160;
const JITTER_MAX_MS: usize = 220;
/// Linearly interpolates two interleaved `s16le` frames (`a` and `b`) into `out`.
pub(crate) fn interpolate_frame_s16le(a: &[u8], b: &[u8], out: &mut [u8]) {
let len = a.len().min(b.len()).min(out.len()) & !1;
for i in (0..len).step_by(2) {
let sa = i16::from_le_bytes([a[i], a[i + 1]]);
let sb = i16::from_le_bytes([b[i], b[i + 1]]);
let mid = ((i32::from(sa) + i32::from(sb)) / 2) as i16;
let bytes = mid.to_le_bytes();
out[i] = bytes[0];
out[i + 1] = bytes[1];
}
}
#[derive(Debug)]
struct Jitter {
pcm: VecDeque<u8>,
frame_bytes: usize,
start_bytes: usize,
low_bytes: usize,
target_bytes: usize,
high_bytes: usize,
max_bytes: usize,
primed: bool,
last_frame: Vec<u8>,
}
impl Jitter {
fn new(rate: u32, channels: u16) -> Self {
let frame_bytes = (channels as usize).max(1) * BYTES_PER_SAMPLE;
let bytes_per_ms = ((rate as usize) * frame_bytes / 1000).max(frame_bytes);
let align = |ms: usize| {
let raw = (ms * bytes_per_ms).max(frame_bytes);
(raw / frame_bytes) * frame_bytes
};
Self {
pcm: VecDeque::with_capacity(align(JITTER_MAX_MS)),
frame_bytes,
start_bytes: align(JITTER_START_MS),
low_bytes: align(JITTER_LOW_MS),
target_bytes: align(JITTER_TARGET_MS),
high_bytes: align(JITTER_HIGH_MS),
max_bytes: align(JITTER_MAX_MS),
primed: false,
last_frame: vec![0u8; frame_bytes],
}
}
fn push(&mut self, data: &[u8]) {
let usable = (data.len() / self.frame_bytes) * self.frame_bytes;
if usable == 0 {
return;
}
self.pcm.extend(&data[..usable]);
if self.pcm.len() > self.max_bytes {
let drop = ((self.pcm.len() - self.target_bytes) / self.frame_bytes) * self.frame_bytes;
self.pcm.drain(..drop.min(self.pcm.len()));
}
if self.pcm.len() >= self.start_bytes {
self.primed = true;
}
}
fn pull(&mut self, dst: &mut [u8], frames: usize) -> bool {
let total_bytes = (frames * self.frame_bytes).min(dst.len());
if !self.primed {
dst[..total_bytes].fill(0);
return false;
}
if self.pcm.len() > self.high_bytes && frames >= 8 {
for _ in 0..self.frame_bytes {
let _ = self.pcm.pop_front();
}
}
let available_frames = self.pcm.len() / self.frame_bytes;
if available_frames == 0 {
self.primed = false;
self.last_frame.fill(0);
dst[..total_bytes].fill(0);
return false;
}
let stretch = self.pcm.len() < self.low_bytes && frames >= 16;
let mut written = 0usize;
let mut produced_frames = 0usize;
let mut next_peek = vec![0u8; self.frame_bytes];
while produced_frames < frames && written + self.frame_bytes <= total_bytes {
if self.pcm.len() >= self.frame_bytes {
for b in &mut self.last_frame {
*b = self.pcm.pop_front().unwrap_or(0);
}
dst[written..written + self.frame_bytes].copy_from_slice(&self.last_frame);
written += self.frame_bytes;
produced_frames += 1;
if stretch && produced_frames == frames / 2 && written + self.frame_bytes <= total_bytes {
if self.pcm.len() >= self.frame_bytes {
for (i, b) in next_peek.iter_mut().enumerate() {
*b = self.pcm.get(i).copied().unwrap_or(0);
}
interpolate_frame_s16le(
&self.last_frame,
&next_peek,
&mut dst[written..written + self.frame_bytes],
);
} else {
dst[written..written + self.frame_bytes].copy_from_slice(&self.last_frame);
}
written += self.frame_bytes;
produced_frames += 1;
}
} else {
self.primed = false;
dst[written..total_bytes].fill(0);
break;
}
}
true
}
}
fn spawn_pcm_sink(rate: u32, channels: u16, device_id: Option<&str>) -> Option<Child> {
let rate_s = rate.to_string();
let ch_s = channels.to_string();
let dev = device_id.map(str::trim).filter(|s| {
!s.is_empty() && *s != "default" && !s.starts_with('-') && !s.chars().any(char::is_control)
});
let mut pacat = Command::new("pacat");
pacat.args([
"--playback",
"--raw",
"--format=s16le",
&format!("--rate={rate_s}"),
&format!("--channels={ch_s}"),
"--latency-msec=20",
]);
if let Some(d) = dev {
pacat.arg(format!("--device={d}"));
}
if let Ok(child) = pacat.stdin(Stdio::piped()).stdout(Stdio::null()).stderr(Stdio::null()).spawn() {
return Some(child);
}
let mut pw = Command::new("pw-play");
pw.args(["--raw", "--format=s16", &format!("--rate={rate_s}"), &format!("--channels={ch_s}")]);
if let Some(d) = dev {
pw.arg(format!("--target={d}"));
}
pw.arg("-");
if let Ok(child) = pw.stdin(Stdio::piped()).stdout(Stdio::null()).stderr(Stdio::null()).spawn() {
return Some(child);
}
Command::new("aplay")
.args(["-q", "-t", "raw", "-f", "S16_LE", "-r", &rate_s, "-c", &ch_s, "--buffer-size=1920", "-"])
.stdin(Stdio::piped())
.stdout(Stdio::null())
.stderr(Stdio::null())
.spawn()
.ok()
}
#[derive(Debug)]
pub struct Player {
tx: SyncSender<Vec<u8>>,
stop: Arc<AtomicBool>,
handle: Option<JoinHandle<()>>,
}
impl Player {
pub fn start(rate: u32, channels: u16) -> Result<Player> {
Self::start_for_device(rate, channels, None)
}
pub fn start_on(device: Option<String>, rate: u32, channels: u16) -> Result<Player> {
Self::start_for_device(rate, channels, device.as_deref())
}
pub fn start_for_device(rate: u32, channels: u16, device_id: Option<&str>) -> Result<Player> {
let clean_rate = rate.max(8_000);
let clean_channels = channels.max(1);
let initial_child = spawn_pcm_sink(clean_rate, clean_channels, device_id).ok_or_else(|| {
std::io::Error::new(
std::io::ErrorKind::NotFound,
"no audio playback backend (pacat, pw-play, or aplay) available",
)
})?;
let (tx, rx) = mpsc::sync_channel::<Vec<u8>>(64);
let stop = Arc::new(AtomicBool::new(false));
let thread_stop = Arc::clone(&stop);
let dev_owned = device_id.map(str::to_owned);
let mut child_cell = Some(initial_child);
let handle = thread::Builder::new().name("nectarlink-audio-out".into()).spawn(move || {
let mut jitter = Jitter::new(clean_rate, clean_channels);
let frame_bytes = jitter.frame_bytes;
let frames_per_tick = ((clean_rate as usize) / 100).max(1);
let mut scratch = vec![0u8; frames_per_tick * frame_bytes];
let mut child = child_cell.take();
let tick = Duration::from_millis(10);
let mut next_tick = Instant::now() + tick;
while !thread_stop.load(Ordering::Acquire) {
while let Ok(chunk) = rx.try_recv() {
jitter.push(&chunk);
}
let has_audio = jitter.pull(&mut scratch, frames_per_tick);
if has_audio
&& let Some(proc) = child.as_mut()
&& let Some(stdin) = proc.stdin.as_mut()
&& stdin.write_all(&scratch).is_err()
{
let _ = proc.kill();
let _ = proc.wait();
child = spawn_pcm_sink(clean_rate, clean_channels, dev_owned.as_deref());
}
let now = Instant::now();
if next_tick > now {
thread::sleep(next_tick - now);
} else if now.duration_since(next_tick) > Duration::from_millis(50) {
next_tick = now;
}
next_tick += tick;
}
if let Some(mut proc) = child {
drop(proc.stdin.take());
let _ = proc.kill();
let _ = proc.wait();
}
})?;
Ok(Player { tx, stop, handle: Some(handle) })
}
pub fn push(&self, data: Vec<u8>) {
if data.is_empty() {
return;
}
match self.tx.try_send(data) {
Ok(()) | Err(TrySendError::Full(_)) | Err(TrySendError::Disconnected(_)) => {}
}
}
}
impl Drop for Player {
fn drop(&mut self) {
self.stop.store(true, Ordering::Release);
if let Some(handle) = self.handle.take() {
let _ = handle.join();
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn jitter_waits_for_prime_threshold_before_emitting_audio() {
let mut jitter = Jitter::new(48_000, 2);
let mut out = vec![0xFFu8; 480 * 4];
jitter.push(&vec![0x11u8; 480 * 4]);
assert!(!jitter.pull(&mut out, 480));
assert!(out.iter().all(|&b| b == 0));
jitter.push(&vec![0x22u8; 480 * 4 * 4]);
assert!(jitter.pull(&mut out, 480));
assert!(out.iter().any(|&b| b != 0));
}
#[test]
fn jitter_caps_overflow_to_target_depth() {
let mut jitter = Jitter::new(48_000, 2);
jitter.push(&vec![0x33u8; jitter.max_bytes + 4096]);
assert!(jitter.pcm.len() <= jitter.max_bytes);
assert!(jitter.pcm.len() >= jitter.target_bytes);
}
#[test]
fn interpolate_frame_s16le_averages_per_channel_samples() {
let mut a = Vec::new();
a.extend_from_slice(&1000i16.to_le_bytes());
a.extend_from_slice(&(-2000i16).to_le_bytes());
let mut b = Vec::new();
b.extend_from_slice(&3000i16.to_le_bytes());
b.extend_from_slice(&(-1000i16).to_le_bytes());
let mut out = [0u8; 4];
interpolate_frame_s16le(&a, &b, &mut out);
assert_eq!(i16::from_le_bytes([out[0], out[1]]), 2000);
assert_eq!(i16::from_le_bytes([out[2], out[3]]), -1500);
}
#[test]
fn player_starts_accepts_pushes_and_drops_cleanly() {
match Player::start(48_000, 2) {
Ok(player) => {
player.push(vec![0u8; 1920]);
drop(player);
}
Err(e) => {
assert_eq!(e.kind(), std::io::ErrorKind::NotFound);
}
}
}
}