Skip to content

XP event5x XPListening, games, ratings, comments and chat earn five times the XP

leftLeaderboard

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 {}#[derive(Debug, Clone, Copy, PartialEq)]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    }}#[cfg(test)]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]);        }    }    #[test]    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);    }    #[test]    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);    }    #[test]    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}");            }        }    }    #[test]    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));    }    #[test]    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);    }    #[test]    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);    }    #[test]    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);    }}