juicewrld-desktopsrc-taurisrcpluginsring.rs
1.4.2Released Nov 21, 2026
ring.rs
566 lines23.6 KBRust//! The audio ring: one WebView2 shared buffer per stream, mapped by three parties at once. The app lays it out//! ([`init`]), the page's AudioWorklet (src/plugins/worklet.js, the same offsets) writes input and reads output, and the//! plugin host (host/audio.rs) reads input and writes output. No locks: each counter has one writer, and they're 32-bit//! words read and written atomically on both sides (Atomics in the worklet).//!//! ```text//! words 0..15 the layout, written once by the app: magic, version, channels, capacity, latency, mode, rate, block//! words 16..31 the page's: in_write, out_read, underruns, quanta, closed, tempo, playing, position//! words 32..47 the host's: in_read, out_write, beat, state, slowest and last block (µs), plugin latency, late, skips,//! and the hole a skip left (start, end)//! byte 256.. input ring (one plane of `capacity` f32 per channel), then the output ring the same way//! ```//!//! Positions are frame counts that wrap at 2^32; the output for input frame p lands at output position p. The page//! writes each render quantum at `in_write` and plays the output from `latency` frames earlier, so every frame comes//! back exactly `latency` frames later, or the page plays silence there and counts an underrun: the delay never drifts.//! In offline mode (an OfflineAudioContext, an export) the page waits for each block instead, with no latency of its own.use std::sync::atomic::{AtomicU32, Ordering};pub const MAGIC: u32 = 0x3152_574A; // "JWR1"pub const VERSION: u32 = 1;pub const HEADER_BYTES: usize = 256;pub const CHANNELS: u32 = 2;pub const MODE_REALTIME: u32 = 0;pub const MODE_OFFLINE: u32 = 1;pub const STATE_WAITING: u32 = 0;pub const STATE_RUNNING: u32 = 1;pub const STATE_STOPPED: u32 = 2;/// The host died with this stream attached (written by the app, which outlives it).pub const STATE_LOST: u32 = 3;/// Word offsets (the byte offset / 4: the worklet indexes an Int32Array with them).pub mod at { pub const MAGIC: usize = 0; pub const VERSION: usize = 1; pub const CHANNELS: usize = 2; pub const CAPACITY: usize = 3; pub const LATENCY: usize = 4; pub const MODE: usize = 5; pub const RATE: usize = 6; pub const MAX_BLOCK: usize = 7; pub const DATA: usize = 8; pub const IN_WRITE: usize = 16; pub const OUT_READ: usize = 17; pub const UNDERRUNS: usize = 18; pub const QUANTA: usize = 19; pub const CLOSED: usize = 20; pub const TEMPO: usize = 21; pub const PLAYING: usize = 22; pub const POSITION_LO: usize = 23; pub const POSITION_HI: usize = 24; pub const IN_READ: usize = 32; pub const OUT_WRITE: usize = 33; pub const HOST_BEAT: usize = 34; pub const STATE: usize = 35; pub const MAX_US: usize = 36; pub const LAST_US: usize = 37; pub const PLUGIN_LATENCY: usize = 38; pub const LATE: usize = 39; pub const SKIPS: usize = 40; /// Output positions [HOLE_START, HOLE_END) were never processed (the host skipped them, see skip_to_newest): the /// page plays silence there and counts underruns, as for any block that isn't ready. pub const HOLE_START: usize = 41; pub const HOLE_END: usize = 42;}/// Bytes for a ring of `capacity` frames.pub fn bytes_for(capacity: u32) -> usize { HEADER_BYTES + 2 * CHANNELS as usize * capacity as usize * 4}/// The ring's size in frames for a latency: room for the latency, a few of the largest blocks and slack, a power of/// two so positions map with a mask.pub fn capacity_for(latency: u32, max_block: u32) -> u32 { (latency + 4 * max_block.max(128) + 4096).next_power_of_two().max(8192)}/// One stream's ring over memory someone else owns (a mapped view, or a test's buffer).pub struct Ring { base: *mut u8, len: usize,}// SAFETY: the memory is shared on purpose; every field has a single writer and is accessed atomically, and the planes// are read and written only in ranges the counters hand over.unsafe impl Send for Ring {}unsafe impl Sync for Ring {}pub struct Layout { pub channels: u32, pub capacity: u32, pub latency: u32, pub mode: u32, pub rate: u32, pub max_block: u32,}impl Ring { /// # Safety /// `base` points at `len` bytes that stay mapped, 4-byte aligned, for as long as the ring is used. pub unsafe fn new(base: *mut u8, len: usize) -> Ring { Ring { base, len } } pub fn word(&self, i: usize) -> &AtomicU32 { assert!(i < HEADER_BYTES / 4); // SAFETY: inside the header, aligned (base is), and only ever accessed as atomics. unsafe { &*(self.base.add(i * 4) as *const AtomicU32) } } pub fn get(&self, i: usize) -> u32 { self.word(i).load(Ordering::Acquire) } pub fn set(&self, i: usize, v: u32) { self.word(i).store(v, Ordering::Release) } /// The app, before anyone else sees the memory. pub fn init(&self, l: Layout) -> Result<(), String> { if !l.capacity.is_power_of_two() || bytes_for(l.capacity) > self.len || l.channels != CHANNELS { return Err("the ring doesn't fit its buffer".into()); } if l.latency + l.max_block > l.capacity / 2 { return Err("latency too long for the ring".into()); } for i in 0..HEADER_BYTES / 4 { self.set(i, 0); } self.set(at::VERSION, VERSION); self.set(at::CHANNELS, l.channels); self.set(at::CAPACITY, l.capacity); self.set(at::LATENCY, l.latency); self.set(at::MODE, l.mode); self.set(at::RATE, l.rate); self.set(at::MAX_BLOCK, l.max_block); self.set(at::DATA, HEADER_BYTES as u32); self.set(at::TEMPO, 0f32.to_bits()); // Last: whoever checks the magic sees the rest. self.set(at::MAGIC, MAGIC); Ok(()) } /// The host, before it trusts anything in it: the layout must be one it knows and must fit the mapping. pub fn layout(&self) -> Result<Layout, String> { if self.len < HEADER_BYTES || self.get(at::MAGIC) != MAGIC || self.get(at::VERSION) != VERSION { return Err("not an audio ring".into()); } let l = Layout { channels: self.get(at::CHANNELS), capacity: self.get(at::CAPACITY), latency: self.get(at::LATENCY), mode: self.get(at::MODE), rate: self.get(at::RATE), max_block: self.get(at::MAX_BLOCK), }; let fits = l.channels == CHANNELS && l.capacity.is_power_of_two() && l.capacity >= 256 && bytes_for(l.capacity) <= self.len && self.get(at::DATA) as usize == HEADER_BYTES && l.latency + l.max_block <= l.capacity / 2 && l.mode <= MODE_OFFLINE; if fits { Ok(l) } else { Err("the audio ring's layout doesn't fit".into()) } } fn plane(&self, output: bool, channel: u32, capacity: u32) -> *mut f32 { let index = if output { CHANNELS + channel } else { channel } as usize; // SAFETY: layout() checked the planes fit inside len. unsafe { self.base.add(HEADER_BYTES + index * capacity as usize * 4) as *mut f32 } } fn copy_out(&self, output: bool, capacity: u32, pos: u32, dst: [&mut [f32]; 2]) { let mask = capacity - 1; let start = (pos & mask) as usize; let n = dst[0].len(); let first = n.min(capacity as usize - start); for (c, d) in dst.into_iter().enumerate() { let p = self.plane(output, c as u32, capacity); // SAFETY: start + first <= capacity and n - first <= capacity: both ranges lie in the plane. unsafe { std::ptr::copy_nonoverlapping(p.add(start), d.as_mut_ptr(), first); std::ptr::copy_nonoverlapping(p, d.as_mut_ptr().add(first), n - first); } } } fn copy_in(&self, output: bool, capacity: u32, pos: u32, src: [&[f32]; 2]) { let mask = capacity - 1; let start = (pos & mask) as usize; let n = src[0].len(); let first = n.min(capacity as usize - start); for (c, s) in src.into_iter().enumerate() { let p = self.plane(output, c as u32, capacity); // SAFETY: as in copy_out. unsafe { std::ptr::copy_nonoverlapping(s.as_ptr(), p.add(start), first); std::ptr::copy_nonoverlapping(s.as_ptr().add(first), p, n - first); } } } // ---- the host's side ---- /// Input frames written and not yet taken. pub fn available(&self) -> u32 { self.get(at::IN_WRITE).wrapping_sub(self.get(at::IN_READ)) } pub fn read_input(&self, l: &Layout, pos: u32, left: &mut [f32], right: &mut [f32]) { self.copy_out(false, l.capacity, pos, [left, right]); } /// Writes the output for input position `pos` and hands both counters over. pub fn write_output(&self, l: &Layout, pos: u32, left: &[f32], right: &[f32]) { self.copy_in(true, l.capacity, pos, [left, right]); let end = pos.wrapping_add(left.len() as u32); self.set(at::OUT_WRITE, end); self.set(at::IN_READ, end); // Late: the page has already gone past (some of) these frames and played silence for them. if (self.get(at::OUT_READ).wrapping_sub(pos) as i32) > 0 { self.word(at::LATE).fetch_add(1, Ordering::Relaxed); } } /// The host fell so far behind that unread input was overwritten: drop it and carry on from the newest. The output /// the page has still to play before that point (up to `latency` frames, and a block to spare) was never processed: /// it's cleared and marked as a hole, so the page plays silence there and counts underruns, never a block left in /// the ring from a lap before. pub fn skip_to_newest(&self, l: &Layout) { let w = self.get(at::IN_WRITE); let span = (l.latency + l.max_block).min(l.capacity / 2); let start = w.wrapping_sub(span); self.zero_output(l.capacity, start, span); self.set(at::HOLE_START, start); self.set(at::HOLE_END, w); self.set(at::OUT_WRITE, w); self.set(at::IN_READ, w); self.word(at::SKIPS).fetch_add(1, Ordering::Relaxed); } fn zero_output(&self, capacity: u32, pos: u32, n: u32) { let mask = capacity - 1; let start = (pos & mask) as usize; let n = n.min(capacity) as usize; let first = n.min(capacity as usize - start); for c in 0..CHANNELS { let p = self.plane(true, c, capacity); // SAFETY: as in copy_out: both ranges lie in the plane. unsafe { std::ptr::write_bytes(p.add(start), 0, first); std::ptr::write_bytes(p, 0, n - first); } } } /// Whether any of the `n` frames from `pos` fall in the hole the last skip left (wrap-safe: the hole is shorter /// than the ring). pub fn in_hole(&self, pos: u32, n: u32) -> bool { let start = self.get(at::HOLE_START); let len = self.get(at::HOLE_END).wrapping_sub(start); pos.wrapping_sub(start) < len || pos.wrapping_add(n.max(1) - 1).wrapping_sub(start) < len } /// The page's transport for the block starting now: tempo (0 unknown), playing, position in samples. pub fn transport(&self) -> (f64, bool, i64) { let tempo = f32::from_bits(self.get(at::TEMPO)) as f64; let pos = (self.get(at::POSITION_LO) as u64 | ((self.get(at::POSITION_HI) as u64) << 32)) as i64; (tempo, self.get(at::PLAYING) != 0, pos) } // ---- the page's side (the worklet does this in JS; tests do it here) ---- /// One render quantum: writes `input`, returns the output due now in `output`, and whether it was ready. pub fn page_quantum(&self, l: &Layout, input: [&[f32]; 2], output: [&mut [f32]; 2]) -> bool { let n = input[0].len() as u32; let w = self.get(at::IN_WRITE); self.copy_in(false, l.capacity, w, input); self.set(at::IN_WRITE, w.wrapping_add(n)); // Until `latency` frames have gone in there is nothing due yet: silence, and not an underrun. let quanta = self.word(at::QUANTA).fetch_add(1, Ordering::Relaxed); let due = if l.mode == MODE_OFFLINE { w } else { w.wrapping_sub(l.latency) }; let started = l.mode == MODE_OFFLINE || quanta as u64 * n as u64 >= l.latency as u64; let ready = (self.get(at::OUT_WRITE).wrapping_sub(due) as i32) >= n as i32 && !(l.mode == MODE_REALTIME && self.in_hole(due, n)); let [ol, or] = output; if started && ready { self.copy_out(true, l.capacity, due, [ol, or]); } else { ol.fill(0.0); or.fill(0.0); if started { self.word(at::UNDERRUNS).fetch_add(1, Ordering::Relaxed); } } if started { self.set(at::OUT_READ, due.wrapping_add(n)); } started && ready }}mod tests { use super::*; use std::sync::Arc; use std::time::{Duration, Instant}; /// A heap buffer standing in for the shared mapping. struct Mem(Vec<u64>); fn mem(capacity: u32) -> (Mem, Ring) { let mut m = Mem(vec![0u64; bytes_for(capacity).div_ceil(8)]); let ring = unsafe { Ring::new(m.0.as_mut_ptr() as *mut u8, bytes_for(capacity)) }; (m, ring) } fn layout(capacity: u32, latency: u32, mode: u32) -> Layout { Layout { channels: 2, capacity, latency, mode, rate: 48000, max_block: 512 } } /// What the host does, all of it at once. fn host_step(ring: &Ring, l: &Layout, plugin: impl Fn(f32) -> f32) { let mut left = vec![0f32; l.max_block as usize]; let mut right = vec![0f32; l.max_block as usize]; loop { let avail = ring.available(); if avail == 0 { return; } let n = avail.min(l.max_block) as usize; let pos = ring.get(at::IN_READ); ring.read_input(l, pos, &mut left[..n], &mut right[..n]); for x in left[..n].iter_mut().chain(right[..n].iter_mut()) { *x = plugin(*x); } ring.write_output(l, pos, &left[..n], &right[..n]); } } fn layout_checks_refuse_what_doesnt_fit() { let (_m, ring) = mem(8192); assert!(ring.layout().is_err(), "no magic yet"); ring.init(layout(8192, 1024, MODE_REALTIME)).unwrap(); assert_eq!(ring.layout().unwrap(), layout(8192, 1024, MODE_REALTIME)); // A latency the ring can't hold, a capacity that isn't a power of two, more than fits the buffer. assert!(ring.init(layout(8192, 6000, MODE_REALTIME)).is_err()); assert!(ring.init(layout(6000, 128, MODE_REALTIME)).is_err()); assert!(ring.init(layout(16384, 128, MODE_REALTIME)).is_err()); // A header someone scribbled on is refused by the host. ring.init(layout(8192, 1024, MODE_REALTIME)).unwrap(); ring.set(at::CAPACITY, 1 << 20); assert!(ring.layout().is_err()); assert_eq!(capacity_for(1024, 128), 8192); assert!(capacity_for(8000, 2048) >= 8000 + 2048 * 2); } fn every_frame_comes_back_exactly_latency_frames_later() { let (_m, ring) = mem(8192); let l = layout(8192, 640, MODE_REALTIME); ring.init(l).unwrap(); // A ramp through a plugin that halves it, the host keeping up block by block, across many wraps of the ring. let mut t = 0u32; let mut heard = Vec::new(); for _ in 0..2000 { let input: Vec<f32> = (0..128).map(|i| (t + i) as f32).collect(); t += 128; let (mut ol, mut or) = (vec![0f32; 128], vec![0f32; 128]); ring.page_quantum(&l, [&input, &input], [&mut ol, &mut or]); heard.extend_from_slice(&ol); host_step(&ring, &l, |x| x * 0.5); } for (i, &v) in heard.iter().enumerate() { let expected = if i < 640 { 0.0 } else { (i - 640) as f32 * 0.5 }; assert_eq!(v, expected, "frame {i}"); } assert_eq!(ring.get(at::UNDERRUNS), 0); assert_eq!(ring.get(at::LATE), 0); } fn a_late_block_is_silence_and_the_delay_stays_put() { let (_m, ring) = mem(8192); let l = layout(8192, 256, MODE_REALTIME); ring.init(l).unwrap(); let mut heard = Vec::new(); let mut t = 0u32; for q in 0..40 { let input: Vec<f32> = (0..128).map(|i| (t + i + 1) as f32).collect(); t += 128; let (mut ol, mut or) = (vec![0f32; 128], vec![0f32; 128]); ring.page_quantum(&l, [&input, &input], [&mut ol, &mut or]); heard.push(ol); // The host stalls through quanta 10..14, then catches up all at once. if !(10..15).contains(&q) { host_step(&ring, &l, |x| x); } } let underruns = ring.get(at::UNDERRUNS); assert!(underruns >= 3 && underruns <= 5, "{underruns} underruns"); assert!(ring.get(at::LATE) >= 1); // Afterwards every frame is where it was before the stall: input frame p plays at p + 256. for (q, block) in heard.iter().enumerate().skip(20) { for (i, &v) in block.iter().enumerate() { let frame = q * 128 + i; assert_eq!(v, (frame - 256 + 1) as f32, "quantum {q} frame {i}"); } } } fn a_host_that_fell_a_whole_ring_behind_leaves_silence_counted_as_underruns() { let (_m, ring) = mem(8192); let l = layout(8192, 896, MODE_REALTIME); ring.init(l).unwrap(); let host = |ring: &Ring| { let mut a = vec![0f32; 512]; let mut b = vec![0f32; 512]; loop { let avail = ring.available(); if avail == 0 { return; } if avail > l.capacity - l.max_block { ring.skip_to_newest(&l); return; } let n = avail.min(l.max_block) as usize; let pos = ring.get(at::IN_READ); ring.read_input(&l, pos, &mut a[..n], &mut b[..n]); ring.write_output(&l, pos, &a[..n], &b[..n]); } }; let mut frame = 0usize; let (mut wrong, mut silent_ready) = (0, 0); for q in 0..400 { let input: Vec<f32> = (0..128).map(|i| (frame + i + 1) as f32).collect(); let (mut ol, mut or) = (vec![0f32; 128], vec![0f32; 128]); if ring.page_quantum(&l, [&input, &input], [&mut ol, &mut or]) { for (i, &v) in ol.iter().enumerate() { if v != (frame + i) as f32 - 896.0 + 1.0 { wrong += 1; if v == 0.0 { silent_ready += 1; } } } } frame += 128; // The host stalls for 70 quanta (187 ms): more than the ring holds. if !(100..170).contains(&q) { host(&ring); } } assert_eq!(ring.get(at::SKIPS), 1); assert_eq!((wrong, silent_ready), (0, 0), "every quantum played as ready is the input, delayed exactly"); // The quanta lost in the stall and the skip were all counted: the 70 the host missed, and the hole after it. let underruns = ring.get(at::UNDERRUNS); assert!((70..=70 + 896 / 128 + 1).contains(&underruns), "{underruns}"); // The hole's start and end compare across the counter's wrap. ring.set(at::HOLE_START, u32::MAX - 100); ring.set(at::HOLE_END, 200); assert!(ring.in_hole(u32::MAX - 50, 128) && ring.in_hole(150, 128) && ring.in_hole(u32::MAX - 200, 128)); assert!(!ring.in_hole(200, 128) && !ring.in_hole(u32::MAX - 300, 128)); } fn positions_wrap_at_two_to_the_thirty_two() { let (_m, ring) = mem(8192); let l = layout(8192, 384, MODE_REALTIME); ring.init(l).unwrap(); // Start near the end of the counter's range, as after a day of audio. let start = u32::MAX - 128 * 20 + 1; for i in [at::IN_WRITE, at::IN_READ, at::OUT_WRITE, at::OUT_READ] { ring.set(i, start); } let mut ok = 0; for q in 0..60u32 { let v = q as f32; let input = vec![v; 128]; let (mut ol, mut or) = (vec![0f32; 128], vec![0f32; 128]); if ring.page_quantum(&l, [&input, &input], [&mut ol, &mut or]) && q >= 3 { assert_eq!(ol[0], (q - 3) as f32); ok += 1; } host_step(&ring, &l, |x| x); } assert!(ok > 50); assert_eq!(ring.get(at::UNDERRUNS), 0); } fn offline_mode_waits_for_each_block_with_no_latency() { let (_m, ring) = mem(8192); let l = layout(8192, 0, MODE_OFFLINE); ring.init(l).unwrap(); let input: Vec<f32> = (0..128).map(|i| i as f32).collect(); let (mut ol, mut or) = (vec![0f32; 128], vec![0f32; 128]); // Not processed yet: not ready (the worklet would wait here). assert!(!ring.page_quantum(&l, [&input, &input], [&mut ol, &mut or])); // The real worklet spins until the host is done; here the host goes first for the next block. let input2: Vec<f32> = (128..256).map(|i| i as f32).collect(); let w = ring.get(at::IN_WRITE); ring.copy_in(false, l.capacity, w, [&input2, &input2]); ring.set(at::IN_WRITE, w + 128); host_step(&ring, &l, |x| x + 1.0); let mut out = [vec![0f32; 128], vec![0f32; 128]]; let [a, b] = &mut out; ring.copy_out(true, l.capacity, 128, [a, b]); assert_eq!(out[0][0], 129.0); assert_eq!(out[1][127], 256.0); } fn page_and_host_on_their_own_threads() { // The real arrangement: the page renders quanta on one thread, the host polls on another, and neither waits // for the other. A sine through a gain must come back intact after the declared latency. let (m, ring) = mem(16384); let ring = Arc::new(ring); let l = layout(16384, 2048, MODE_REALTIME); ring.init(l).unwrap(); let stop = Arc::new(std::sync::atomic::AtomicBool::new(false)); let host = { let (ring, stop) = (ring.clone(), stop.clone()); std::thread::spawn(move || { while !stop.load(Ordering::Relaxed) { host_step(&ring, &l, |x| x * 2.0); std::thread::sleep(Duration::from_micros(300)); } }) }; let sine = |n: u32| ((n as f64) * 0.01).sin() as f32; let mut n = 0u32; let mut heard = Vec::new(); let t0 = Instant::now(); // About a second of 48 kHz audio, in bursts of 4 quanta every 10.7 ms as Chromium's audio thread renders them. for _ in 0..94 { for _ in 0..4 { let input: Vec<f32> = (0..128).map(|i| sine(n + i)).collect(); n += 128; let (mut ol, mut or) = (vec![0f32; 128], vec![0f32; 128]); ring.page_quantum(&l, [&input, &input], [&mut ol, &mut or]); heard.extend_from_slice(&ol); } std::thread::sleep(Duration::from_micros(10_667)); } stop.store(true, Ordering::Relaxed); host.join().unwrap(); assert!(t0.elapsed() >= Duration::from_millis(900)); assert_eq!(ring.get(at::UNDERRUNS), 0, "the host kept up"); for (i, &v) in heard.iter().enumerate().skip(2048) { assert!((v - 2.0 * sine(i as u32 - 2048)).abs() < 1e-6, "frame {i}"); } drop(m); }}