Consolidate escape hatch API

Author: dy

.github/workflows/test.yml

@@ -14,6 +14,8 @@ jobs:
         node-version: [18, 20, 22]
     steps:
       - uses: actions/checkout@v4
+        with:
+          submodules: true
       - uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
@@ -25,6 +27,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          submodules: true
       - uses: denoland/setup-deno@v2
       - uses: actions/setup-node@v4
         with:
@@ -37,6 +41,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          submodules: true
       - uses: oven-sh/setup-bun@v2
       - run: bun install
       - run: bun test/index.js

README.md

@@ -40,10 +40,10 @@ const buffer = await ctx.startRendering()
 
 ### Custom output stream
 
-For piping to external tools or custom sinks, set `outStream` to any writable:
+Pass any writable stream as `sinkId` to pipe PCM to external tools:
 
 ```js
-ctx.outStream = myWritableStream
+const ctx = new AudioContext({ sinkId: process.stdout })
 ```
 
 ```sh
@@ -167,6 +167,16 @@ Supports WAV, MP3, FLAC, OGG, AAC, and [more](https://github.com/audiojs/audio-d
 
 </dl>
 
+## Node extensions
+
+These APIs extend the Web Audio spec for Node.js use cases. Code using them is not directly portable to browsers.
+
+| API | What it does | Browser equivalent |
+|---|---|---|
+| `addModule(fn)` | Register processor via callback | `addModule(url)` &mdash; URL string only |
+| `sinkId: writableStream` | Pipe PCM to any writable stream | N/A (hardware output) |
+| `numberOfChannels`, `bitDepth` | Constructor options for output format | N/A (hardware-determined) |
+
 ## Architecture
 
 Pull-based audio graph. `AudioDestinationNode` pulls upstream via `_tick()`, 128-sample render quanta per the spec. AudioWorklet runs synchronously (no thread isolation). DSP kernels separated from graph plumbing for future WASM swap.

examples/pipe-stdout.js

@@ -5,7 +5,7 @@
 import { AudioContext } from 'web-audio-api'
 
 const duration = 2
-const ctx = new AudioContext()
+const ctx = new AudioContext({ sinkId: process.stdout })
 await ctx.resume()
 
 const osc = ctx.createOscillator()

index.d.ts

@@ -87,19 +87,17 @@ export class BaseAudioContext extends EventTarget {
 }
 
 export class AudioContext extends BaseAudioContext {
-  constructor(options?: { sampleRate?: number; numberOfChannels?: number; bitDepth?: number; latencyHint?: 'interactive' | 'balanced' | 'playback' | number; sinkId?: string | { type: 'none' } });
+  constructor(options?: { sampleRate?: number; numberOfChannels?: number; bitDepth?: number; bufferSize?: number; numBuffers?: number; latencyHint?: 'interactive' | 'balanced' | 'playback' | number; sinkId?: string | { type: 'none' } | { write(chunk: Uint8Array): boolean; once?(event: string, fn: () => void): void; end?(): void; close?(): void } });
   readonly numberOfChannels: number;
   readonly baseLatency: number;
   readonly outputLatency: number;
   readonly renderQuantumSize: number;
   readonly sinkId: string | { type: string };
   readonly playbackStats: { totalDuration: number; underrunDuration: number; underrunEvents: number; minimumLatency: number; maximumLatency: number; averageLatency: number };
   readonly playoutStats: { totalFramesDuration: number; fallbackFramesDuration: number; fallbackFramesEvents: number; minimumLatency: number; maximumLatency: number; averageLatency: number };
-  outStream: any;
-  format: { numberOfChannels: number; bitDepth: number; sampleRate: number };
   onsinkchange: ((event: Event) => void) | null;
   getOutputTimestamp(): { contextTime: number; performanceTime: number };
-  setSinkId(sinkId: string | { type: 'none' }): Promise<void>;
+  setSinkId(sinkId: string | { type: 'none' } | { write(chunk: Uint8Array): boolean }): Promise<void>;
   suspend(): Promise<void>;
   resume(): Promise<void>;
   close(): Promise<void>;

src/AudioContext.js

@@ -25,6 +25,7 @@ class AudioContext extends BaseAudioContext {
   #bitDepth
   #encoder
   #speaker = null  // audio-speaker write function (default output)
+  #stream = null   // writable stream sink (when sinkId is a stream)
   #loopDeferred = false
   #sinkId = ''
   #playbackStats = new PlaybackStats()
@@ -70,9 +71,10 @@ class AudioContext extends BaseAudioContext {
     }
 
     // Validate sinkId option
-    if (opts.sinkId !== undefined) {
-      if (typeof opts.sinkId === 'object' && opts.sinkId !== null) {
-        if (opts.sinkId.type !== 'none')
+    let sinkId = opts.sinkId
+    if (sinkId !== undefined) {
+      if (typeof sinkId === 'object' && sinkId !== null && typeof sinkId.write !== 'function') {
+        if (sinkId.type !== 'none')
           throw new TypeError("Failed to construct 'AudioContext': Invalid AudioSinkOptions.type value.")
       }
     }
@@ -86,38 +88,39 @@ class AudioContext extends BaseAudioContext {
     this.#bitDepth = opts.bitDepth || 16
 
     // Handle sinkId from constructor options
-    if (opts.sinkId !== undefined) {
-      if (typeof opts.sinkId === 'object' && opts.sinkId !== null) {
-        this.#sinkId = { type: opts.sinkId.type }
-      } else if (typeof opts.sinkId === 'string') {
-        // Validate against known devices if a registry exists
+    if (sinkId !== undefined) {
+      if (typeof sinkId === 'object' && sinkId !== null) {
+        if (typeof sinkId.write === 'function') {
+          this.#stream = sinkId
+        } else {
+          this.#sinkId = { type: sinkId.type }
+        }
+      } else if (typeof sinkId === 'string') {
         let known = this.constructor._knownDeviceIds || AudioContext._knownDeviceIds
-        if (opts.sinkId !== '' && known && !known.has(opts.sinkId)) {
-          // Invalid device ID: dispatch onerror asynchronously per spec
+        if (sinkId !== '' && known && !known.has(sinkId)) {
           setTimeout(() => this.dispatchEvent(new Event('error')), 0)
         } else {
-          this.#sinkId = opts.sinkId
+          this.#sinkId = sinkId
         }
       }
     }
 
-    this.format = {
+    let format = {
       numberOfChannels: this.#numberOfChannels,
       bitDepth: this.#bitDepth,
       sampleRate: this.sampleRate
     }
-    if (opts.bufferSize) this.format.bufferSize = opts.bufferSize
-    if (opts.numBuffers) this.format.numBuffers = opts.numBuffers
+    if (opts.bufferSize) format.bufferSize = opts.bufferSize
+    if (opts.numBuffers) format.numBuffers = opts.numBuffers
 
-    this.#encoder = BufferEncoder(this.format)
-    this.outStream = null
+    this.#encoder = BufferEncoder(format)
 
     // Start render loop when a connection is established.
     // Deferred via queueMicrotask so user can finish setting up the graph
     // (connect + start) before rendering begins.
     this._destination._inputs[0].on('connection', () => {
       if (this.#loopRunning || this.#loopDeferred || this._state !== 'running') return
-      if (!this.outStream && !this.#speaker) return
+      if (!this.#stream && !this.#speaker) return
       this.#loopDeferred = true
       queueMicrotask(() => {
         this.#loopDeferred = false
@@ -156,6 +159,14 @@ class AudioContext extends BaseAudioContext {
     if (this._state === 'closed')
       return Promise.reject(DOMErr('Cannot setSinkId on a closed AudioContext', 'InvalidStateError'))
     if (typeof sinkId === 'object' && sinkId !== null) {
+      if (typeof sinkId.write === 'function') {
+        // Writable stream as sink
+        if (this.#speaker) { this.#speaker.close(); this.#speaker = null }
+        let prev = this.#stream
+        this.#stream = sinkId
+        if (prev !== sinkId) this.dispatchEvent(new Event('sinkchange'))
+        return Promise.resolve()
+      }
       if (sinkId.type !== 'none')
         return Promise.reject(new TypeError('Invalid AudioSinkOptions.type value.'))
       let prev = this.#sinkId
@@ -195,15 +206,16 @@ class AudioContext extends BaseAudioContext {
     if (this._state === 'closed') return Promise.reject(DOMErr('Cannot resume a closed AudioContext', 'InvalidStateError'))
     // Create speaker eagerly on resume — starts device with silence so there's
     // no hardware pop when audio actually begins (same as browsers).
-    if (!this.outStream && !this.#speaker) {
+    let isNone = typeof this.#sinkId === 'object' && this.#sinkId?.type === 'none'
+    if (!this.#stream && !this.#speaker && !isNone) {
       this.#speaker = await Speaker({
         sampleRate: this.sampleRate,
         channels: this.#numberOfChannels,
         bitDepth: this.#bitDepth
       })
     }
     this._setState('running')
-    if (!this.#loopRunning && (this.#speaker || this.outStream) && this._destination._inputs[0].sources.length) {
+    if (!this.#loopRunning && (this.#speaker || this.#stream) && this._destination._inputs[0].sources.length) {
       this.#loopRunning = true
       this._renderLoop()
     }
@@ -219,7 +231,7 @@ class AudioContext extends BaseAudioContext {
 
   _closeOutput() {
     if (this.#speaker) { this.#speaker.close(); this.#speaker = null }
-    if (this.outStream) (this.outStream.close ?? this.outStream.end)?.call(this.outStream)
+    if (this.#stream) { (this.#stream.close ?? this.#stream.end)?.call(this.#stream); this.#stream = null }
   }
 
   _renderLoop() {
@@ -230,20 +242,17 @@ class AudioContext extends BaseAudioContext {
     try {
       let buf = this._renderQuantum()
 
+      let nch = buf.numberOfChannels
+      let channels = []
+      for (let c = 0; c < nch; c++) channels.push(buf.getChannelData(c))
+      let encoded = this.#encoder(channels)
+
       if (this.#speaker) {
-        let nch = buf.numberOfChannels
-        let channels = []
-        for (let c = 0; c < nch; c++) channels.push(buf.getChannelData(c))
-        let encoded = this.#encoder(channels)
         this.#speaker(encoded, () => this._renderLoop())
-      } else if (this.outStream) {
-        let nch = buf.numberOfChannels
-        let channels = []
-        for (let c = 0; c < nch; c++) channels.push(buf.getChannelData(c))
-        let encoded = this.#encoder(channels)
-        let ok = this.outStream.write(encoded)
-        if (ok || !this.outStream.once) setTimeout(() => this._renderLoop(), 0)
-        else this.outStream.once('drain', () => this._renderLoop())
+      } else if (this.#stream) {
+        let ok = this.#stream.write(encoded)
+        if (ok || !this.#stream.once) setTimeout(() => this._renderLoop(), 0)
+        else this.#stream.once('drain', () => this._renderLoop())
       }
     } catch (e) {
       console.error('AudioContext render error:', e)

test/AudioContext.test.js

@@ -4,15 +4,10 @@ import AudioContext from '../src/AudioContext.js'
 import AudioNode from '../src/AudioNode.js'
 import { BLOCK_SIZE } from '../src/constants.js'
 
-let mkCtx = () => {
-  let ctx = new AudioContext()
-  ctx.outStream = { end() {} }
-  return ctx
-}
+let mkCtx = () => new AudioContext({ sinkId: { type: 'none' } })
 
 test('AudioContext > graph traversal collects all connected nodes', () => {
-  let ctx = new AudioContext()
-  ctx.outStream = { write() { return true }, once() {} }
+  let ctx = new AudioContext({ sinkId: { write() { return true }, once() {} } })
 
   let n1a = new AudioNode(ctx, 2, 1)
   let n1b = new AudioNode(ctx, 0, 1)
@@ -65,8 +60,8 @@ test('AudioContext > sampleRate is read-only', () => {
 })
 
 test('AudioContext > sampleRate from constructor option', () => {
-  let ctx = new AudioContext({ sampleRate: 48000 })
-  ctx.outStream = { end() {} }; ctx[Symbol.dispose]()
+  let ctx = new AudioContext({ sampleRate: 48000, sinkId: { type: 'none' } })
+  ctx[Symbol.dispose]()
   is(ctx.sampleRate, 48000)
 })
 

test/OfflineAudioContext.test.js

@@ -11,8 +11,8 @@ import { BLOCK_SIZE } from '../src/constants.js'
 // --- BaseAudioContext ---
 
 test('BaseAudioContext > AudioContext extends it', () => {
-  let ctx = new AudioContext()
-  ctx.outStream = { end() {} }; ctx[Symbol.dispose]()
+  let ctx = new AudioContext({ sinkId: { type: 'none' } })
+  ctx[Symbol.dispose]()
   ok(ctx instanceof BaseAudioContext, 'AudioContext is BaseAudioContext')
 })
 

test/audit-fixes.test.js

@@ -223,8 +223,7 @@ test('enum setters > silently ignore invalid values per spec', () => {
 })
 
 test('AudioContext > onstatechange as event handler property', async () => {
-  let ctx = new AudioContext()
-  ctx.outStream = { end() {} }
+  let ctx = new AudioContext({ sinkId: { type: 'none' } })
   let states = []
 
   // set via property

test/manual-testing/AudioContext-sound-output.js

@@ -1,21 +1,9 @@
-// if (require.main === module) { // Just to avoid mocha running this
-
 import fs from 'fs'
 import AudioContext from '../../src/AudioContext.js'
 import Speaker from 'speaker'
 
-const context = new AudioContext
-
-console.log('encoding format : '
-  + context.format.numberOfChannels + ' channels ; '
-  + context.format.bitDepth + ' bits ; '
-  + context.sampleRate + ' Hz'
-)
-context.outStream = new Speaker({
-  channels: context.format.numberOfChannels,
-  bitDepth: context.format.bitDepth,
-  sampleRate: context.sampleRate
-})
+const speaker = new Speaker({ channels: 2, bitDepth: 16, sampleRate: 44100 })
+const context = new AudioContext({ sinkId: speaker })
 
 fs.readFile(new URL('./sounds/powerpad.wav', import.meta.url), function(err, buffer) {
   if (err) throw err

test/manual-testing/AudioContext-stdout.js

@@ -1,12 +1,9 @@
-// if (require.main === module) { // Just to avoid mocha running this
-
 import fs from 'fs'
-import AudioContext from '../../src/AudioContext'
-import context = new AudioContext
+import AudioContext from '../../src/AudioContext.js'
 
-context.outStream = process.stdout
+const context = new AudioContext({ sinkId: process.stdout })
 
-fs.readFile(__dirname + '/sounds/powerpad.wav', function(err, buffer) {
+fs.readFile(new URL('./sounds/powerpad.wav', import.meta.url), function(err, buffer) {
   if (err) throw err
   context.decodeAudioData(buffer, function(audioBuffer) {
     var bufferNode = context.createBufferSource()