Replace postMessage with SharedArrayBuffer for lock-free audio transfer

[kixelated]

Summary

Replaces the message-passing audio transfer mechanism with a lock-free shared ring buffer implementation using SharedArrayBuffer, eliminating sample drops and reducing latency overhead in audio worklet communication.

Key Changes

• New SharedRingBuffer implementation (shared-ring-buffer.ts):

  • Lock-free ring buffer using atomic operations for thread-safe coordination between main thread and AudioWorklet
  • Handles out-of-order writes, gap filling with zeros, and automatic overflow management
  • Supports dynamic latency adjustment via setLatency()
  • Provides modular i32 arithmetic for correct wrapping behavior with large sample indices

• Comprehensive test suite (shared-ring-buffer.test.ts):

  • 527 lines of tests covering initialization, insertion, reading, stall behavior, ring wrapping, multi-channel audio, overflow handling, and edge cases
  • Tests verify gap filling, out-of-order writes, latency skipping, and timestamp tracking

• Decoder refactoring (decoder.ts):

  • Allocates SharedRingBuffer on worklet initialization with 1-second capacity
  • Writes decoded audio directly to shared memory via insert() instead of postMessage()
  • Polls shared buffer state (timestamp, stalled flag) every 50ms instead of receiving postMessage updates
  • Dynamically re-allocates buffer if capacity becomes insufficient for target latency

• AudioWorklet simplification (render-worklet.ts):

  • Removes AudioRingBuffer dependency and complex state tracking
  • Simplified process() to directly read from SharedRingBuffer
  • Eliminates underflow tracking and periodic state messages

• Message protocol cleanup (render.ts):

  • Removes Data and Latency message types
  • Init message now carries SharedRingBufferInit data (samples and control SharedArrayBuffers)
  • Eliminates ToMain state messages in favor of atomic polling

Notable Implementation Details

• Uses atomic operations (Atomics.load, Atomics.store) for lock-free coordination
• Implements modular i32 arithmetic (i32Max, slot()) to handle wrapping with signed 32-bit integers
• Automatically advances READ pointer on overflow to prevent buffer exhaustion
• Implements latency skipping to maintain target latency distance between READ and WRITE pointers
• Handles fractional timestamps by rounding to nearest sample index

https://claude.ai/code/session_01DyHBcF8vEs1wtbJubRVExp