@audio/speaker 2.3.1

package/src/backends/miniaudio.js

@@ -0,0 +1,65 @@
+/**
+ * Miniaudio backend — own N-API addon wrapping miniaudio.h
+ *
+ * Write strategy:
+ * - writeSync: non-blocking memcpy into ring buffer (zero overhead)
+ * - writeAsync: blocks on worker thread when ring buffer is full
+ * - Small writes (real-time rendering) → pure sync, no event loop round-trip
+ * - Large writes → sync partial + async remainder
+ *
+ * Load order:
+ * 1. @audio/speaker-{platform}-{arch} (platform package)
+ * 2. prebuilds/{platform}-{arch}/
+ * 3. build/Release/ or build/Debug/ (local node-gyp)
+ */
+import { createRequire } from 'node:module'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { arch, platform } from 'node:os'
+
+const require = createRequire(import.meta.url)
+const root = join(dirname(fileURLToPath(import.meta.url)), '../..')
+const plat = `${platform()}-${arch()}`
+
+let addon
+const loaders = [
+  () => require(`@audio/speaker-${plat}`),
+  () => require(join(root, 'packages', `speaker-${plat}`, 'speaker.node')),
+  () => require(join(root, 'prebuilds', plat, 'audio-speaker.node')),
+  () => require(join(root, 'prebuilds', plat, 'speaker.node')),
+  () => require(join(root, 'build', 'Release', 'speaker.node')),
+  () => require(join(root, 'build', 'Debug', 'speaker.node')),
+]
+for (const load of loaders) {
+  try { addon = load(); break } catch {}
+}
+
+export function open({ sampleRate = 44100, channels = 2, bitDepth = 16, bufferSize = 50, capture = false } = {}) {
+  if (!addon) throw new Error('miniaudio addon not found — install @audio/speaker-' + plat + ' or run npm run build')
+  const handle = addon.open(sampleRate, channels, bitDepth, bufferSize, capture)
+
+  return {
+    // writeAsync blocks a worker thread until all data is written, then waits
+    // until the ring buffer drains below pull_threshold before firing cb.
+    // This means cb fires when the hardware *needs* more data — true pull pacing.
+    write(buf, cb) {
+      addon.writeAsync(handle, buf, (err, written) => cb?.(err, written))
+    },
+
+    read(buf) {
+      return addon.read(handle, buf)
+    },
+
+    flush(cb) {
+      const poll = () => {
+        if (addon.flush(handle)) cb?.()
+        else setTimeout(poll, 5)
+      }
+      poll()
+    },
+
+    close() {
+      addon.close(handle)
+    }
+  }
+}

package/src/backends/null.js

@@ -0,0 +1,19 @@
+/**
+ * Null backend — silent fallback for headless/CI environments.
+ * Maintains the timing contract: callback fires after the audio duration,
+ * preserving correct pacing for real-time render loops.
+ */
+export function open({ sampleRate = 44100, channels = 2, bitDepth = 16 } = {}) {
+  const bytesPerFrame = channels * (bitDepth / 8)
+  let closed = false
+
+  return {
+    write(buf, cb) {
+      if (closed) return cb?.(new Error('closed'))
+      const frames = (buf.length / bytesPerFrame) | 0
+      setTimeout(() => cb?.(null, frames), frames / sampleRate * 1000)
+    },
+    flush(cb) { cb?.() },
+    close() { closed = true }
+  }
+}

package/src/backends/process.js

@@ -0,0 +1,56 @@
+/**
+ * Process backend — pipe PCM to system audio tools (last resort)
+ */
+import { spawn, execSync } from 'node:child_process'
+import { platform } from 'node:os'
+
+function tryExec(cmd) {
+  try { execSync(cmd, { stdio: 'ignore' }); return true } catch { return false }
+}
+
+function findPlayer(sampleRate, channels, bitDepth) {
+  const os = platform()
+  const fmt = bitDepth === 8 ? 'u8' : bitDepth === 32 ? 'f32le' : `s${bitDepth}le`
+
+  if (tryExec('ffplay -version'))
+    return ['ffplay', ['-nodisp', '-autoexit', '-f', fmt, '-ar', sampleRate, '-ac', channels, '-']]
+
+  if (tryExec('play --version'))
+    return ['play', ['-t', 'raw', '-r', sampleRate, '-c', channels, '-b', bitDepth, '-e', 'signed-integer', '-L', '-']]
+
+  if (os === 'linux' && tryExec('aplay --version'))
+    return ['aplay', ['-f', fmt, '-r', sampleRate, '-c', channels]]
+
+  return null
+}
+
+export function open({ sampleRate = 44100, channels = 2, bitDepth = 16 } = {}) {
+  const player = findPlayer(sampleRate, channels, bitDepth)
+  if (!player) throw new Error('No audio player found (install ffplay or sox)')
+
+  const [cmd, args] = player
+  const proc = spawn(cmd, args.map(String), { stdio: ['pipe', 'ignore', 'ignore'] })
+
+  let closed = false
+
+  proc.on('close', () => { closed = true })
+
+  return {
+    write(buf, cb) {
+      if (closed) return cb?.(new Error('Process exited'))
+      proc.stdin.write(buf, cb)
+    },
+
+    flush(cb) {
+      if (closed) return cb?.()
+      proc.stdin.end(() => cb?.())
+    },
+
+    close() {
+      if (closed) return
+      closed = true
+      proc.stdin.end()
+      proc.kill()
+    }
+  }
+}

package/stream.d.ts

@@ -0,0 +1,4 @@
+import { Writable } from 'node:stream'
+import { SpeakerOptions } from './index.js'
+
+export default function writable(opts?: SpeakerOptions): Writable

package/stream.js

@@ -0,0 +1,19 @@
+/**
+ * @module audio-speaker/stream
+ *
+ * Node.js Writable stream for audio output.
+ */
+import { Writable } from 'node:stream'
+import speaker from './index.js'
+
+export default function writable(opts) {
+  const { sampleRate = 44100, channels = 2, bitDepth = 16, bufferSize = 50 } = opts || {}
+  const write = speaker(opts)
+
+  return new Writable({
+    highWaterMark: Math.round(sampleRate * channels * (bitDepth / 8) * bufferSize / 1000),
+    write(chunk, _, cb) { write(chunk, (err) => cb(err || null)) },
+    final(cb) { write.flush(() => { write.close(); cb() }) },
+    destroy(err, cb) { write.close(); cb(err) }
+  })
+}