@xincli/opentui-core 0.4.6

package/src/audio.ts

@@ -0,0 +1,479 @@
+import { EventEmitter } from "events"
+import { readFile } from "node:fs/promises"
+import { resolveRenderLib, type AudioEngineHandle, type RenderLib } from "./zig.js"
+import type { AudioStats } from "./zig-structs.js"
+
+export interface AudioSetupOptions {
+  autoStart?: boolean
+  sampleRate?: number
+  playbackChannels?: number
+  startOptions?: AudioStartOptions
+}
+
+export interface AudioStartOptions {
+  periodSizeInFrames?: number
+  periodSizeInMilliseconds?: number
+  periods?: number
+  performanceProfile?: number
+  shareMode?: number
+  noPreSilencedOutputBuffer?: boolean
+  noClip?: boolean
+  noDisableDenormals?: boolean
+  noFixedSizedCallback?: boolean
+  wasapiNoAutoConvertSrc?: boolean
+  wasapiNoDefaultQualitySrc?: boolean
+  alsaNoMMap?: boolean
+  alsaNoAutoFormat?: boolean
+  alsaNoAutoChannels?: boolean
+  alsaNoAutoResample?: boolean
+}
+
+export interface AudioPlayOptions {
+  volume?: number
+  pan?: number
+  loop?: boolean
+  groupId?: number
+}
+
+export type AudioGroup = number
+export type AudioVoice = number
+export type AudioSound = number
+
+export interface AudioPlaybackDevice {
+  index: number
+  name: string
+  isDefault: boolean
+}
+
+export type AudioAction =
+  | "createAudioEngine"
+  | "start"
+  | "startMixer"
+  | "stop"
+  | "loadSound"
+  | "loadSoundFile"
+  | "unloadSound"
+  | "group"
+  | "play"
+  | "stopVoice"
+  | "setVoiceGroup"
+  | "setGroupVolume"
+  | "setMasterVolume"
+  | "mixFrames"
+  | "enableTap"
+  | "readTapFrames"
+  | "listPlaybackDevices"
+  | "selectPlaybackDevice"
+  | "clearPlaybackDeviceSelection"
+  | "getStats"
+
+export interface AudioErrorContext {
+  action: AudioAction
+  status?: number
+}
+
+export interface AudioEvents {
+  error: [error: Error, context: AudioErrorContext]
+  started: []
+  mixerStarted: []
+  stopped: []
+  disposed: []
+}
+
+function statusToError(action: string, status: number): Error {
+  return new Error(`Audio ${action} failed: ${status}`)
+}
+
+function toBytes(data: Uint8Array | ArrayBuffer): Uint8Array {
+  return data instanceof Uint8Array ? data : new Uint8Array(data)
+}
+
+export class Audio extends EventEmitter<AudioEvents> {
+  static create(options: AudioSetupOptions = {}): Audio {
+    return new Audio(resolveRenderLib(), options)
+  }
+
+  private readonly lib: RenderLib
+  private readonly defaultStartOptions: AudioStartOptions | undefined
+  private engine: AudioEngineHandle | null = null
+  private readonly groups = new Map<string, number>()
+  private playbackStarted = false
+  private mixerStarted = false
+
+  private constructor(lib: RenderLib, options: AudioSetupOptions) {
+    super()
+    this.lib = lib
+    this.defaultStartOptions = options.startOptions
+    const createOptions =
+      options.sampleRate == null && options.playbackChannels == null
+        ? undefined
+        : {
+            sampleRate: options.sampleRate == null ? undefined : Math.max(0, Math.trunc(options.sampleRate)),
+            playbackChannels:
+              options.playbackChannels == null ? undefined : Math.max(0, Math.trunc(options.playbackChannels)),
+          }
+    this.engine = this.lib.createAudioEngine(createOptions)
+    if (!this.engine) {
+      this.emitError("createAudioEngine", undefined, "Audio createAudioEngine returned null")
+      return
+    }
+
+    if (options.autoStart ?? false) {
+      this.start(this.defaultStartOptions)
+    }
+  }
+
+  private emitError(action: AudioAction, status?: number, message?: string, cause?: unknown): void {
+    const error = message ? new Error(message) : statusToError(action, status ?? -1)
+    if (cause) (error as Error & { cause?: unknown }).cause = cause
+    this.emit("error", error, { action, status })
+  }
+
+  start(options?: AudioStartOptions): boolean {
+    if (this.playbackStarted) return true
+    const engine = this.engine
+    if (!engine) {
+      this.emitError("start", undefined, "Audio engine unavailable during start")
+      return false
+    }
+    const startOptions = options ?? this.defaultStartOptions
+    const status = this.lib.audioStart(engine, startOptions)
+    if (status !== 0) {
+      this.emitError("start", status)
+      return false
+    }
+    this.playbackStarted = true
+    this.mixerStarted = true
+    this.emit("started")
+    return true
+  }
+
+  startMixer(): boolean {
+    if (this.mixerStarted) return true
+    const engine = this.engine
+    if (!engine) {
+      this.emitError("startMixer", undefined, "Audio engine unavailable during startMixer")
+      return false
+    }
+    const status = this.lib.audioStartMixer(engine)
+    if (status !== 0) {
+      this.emitError("startMixer", status)
+      return false
+    }
+    this.mixerStarted = true
+    this.emit("mixerStarted")
+    return true
+  }
+
+  stop(): boolean {
+    if (!this.mixerStarted) return true
+    const engine = this.engine
+    if (!engine) {
+      this.emitError("stop", undefined, "Audio engine unavailable during stop")
+      return false
+    }
+    const status = this.lib.audioStop(engine)
+    if (status !== 0) {
+      this.emitError("stop", status)
+      return false
+    }
+    this.playbackStarted = false
+    this.mixerStarted = false
+    this.emit("stopped")
+    return true
+  }
+
+  isStarted(): boolean {
+    return this.playbackStarted
+  }
+
+  isMixerStarted(): boolean {
+    return this.mixerStarted
+  }
+
+  loadSound(data: Uint8Array | ArrayBuffer): AudioSound | null {
+    const engine = this.engine
+    if (!engine) {
+      this.emitError("loadSound", undefined, "Audio engine unavailable during loadSound")
+      return null
+    }
+    const result = this.lib.audioLoad(engine, toBytes(data))
+    if (result.status !== 0 || result.soundId == null) {
+      this.emitError("loadSound", result.status)
+      return null
+    }
+    return result.soundId
+  }
+
+  async loadSoundFile(filePath: string): Promise<AudioSound | null> {
+    const bytes = await readFile(filePath).catch((err) => {
+      this.emitError("loadSoundFile", undefined, `Failed to read file '${filePath}': ${err.message}`, err)
+      return null
+    })
+    if (bytes == null) return null
+    return this.loadSound(bytes)
+  }
+
+  unloadSound(sound: AudioSound): boolean {
+    const engine = this.engine
+    if (!engine) {
+      this.emitError("unloadSound", undefined, "Audio engine unavailable during unloadSound")
+      return false
+    }
+
+    const status = this.lib.audioUnload(engine, sound)
+    if (status !== 0) {
+      this.emitError("unloadSound", status)
+      return false
+    }
+    return true
+  }
+
+  group(name: string): AudioGroup | null {
+    const existing = this.groups.get(name)
+    if (existing != null) {
+      return existing
+    }
+
+    const engine = this.engine
+    if (!engine) {
+      this.emitError("group", undefined, "Audio engine unavailable during group")
+      return null
+    }
+    const result = this.lib.audioCreateGroup(engine, name)
+    if (result.status !== 0 || result.groupId == null) {
+      this.emitError("group", result.status)
+      return null
+    }
+
+    this.groups.set(name, result.groupId)
+    return result.groupId
+  }
+
+  play(sound: AudioSound, options?: AudioPlayOptions): AudioVoice | null {
+    const rawOptions = options
+      ? {
+          volume: options.volume,
+          pan: options.pan,
+          loop: options.loop,
+          groupId: options.groupId ?? 0,
+        }
+      : undefined
+
+    const engine = this.engine
+    if (!engine) {
+      this.emitError("play", undefined, "Audio engine unavailable during play")
+      return null
+    }
+    const result = this.lib.audioPlay(engine, sound, rawOptions)
+    if (result.status !== 0 || result.voiceId == null) {
+      this.emitError("play", result.status)
+      return null
+    }
+
+    return result.voiceId
+  }
+
+  stopVoice(voice: AudioVoice): boolean {
+    const engine = this.engine
+    if (!engine) {
+      this.emitError("stopVoice", undefined, "Audio engine unavailable during stopVoice")
+      return false
+    }
+    const status = this.lib.audioStopVoice(engine, voice)
+    if (status !== 0) {
+      this.emitError("stopVoice", status)
+      return false
+    }
+    return true
+  }
+
+  setVoiceGroup(voice: AudioVoice, group: AudioGroup): boolean {
+    const engine = this.engine
+    if (!engine) {
+      this.emitError("setVoiceGroup", undefined, "Audio engine unavailable during setVoiceGroup")
+      return false
+    }
+    const status = this.lib.audioSetVoiceGroup(engine, voice, group)
+    if (status !== 0) {
+      this.emitError("setVoiceGroup", status)
+      return false
+    }
+    return true
+  }
+
+  setGroupVolume(group: AudioGroup, volume: number): boolean {
+    const engine = this.engine
+    if (!engine) {
+      this.emitError("setGroupVolume", undefined, "Audio engine unavailable during setGroupVolume")
+      return false
+    }
+    const status = this.lib.audioSetGroupVolume(engine, group, volume)
+    if (status !== 0) {
+      this.emitError("setGroupVolume", status)
+      return false
+    }
+    return true
+  }
+
+  setMasterVolume(volume: number): boolean {
+    const engine = this.engine
+    if (!engine) {
+      this.emitError("setMasterVolume", undefined, "Audio engine unavailable during setMasterVolume")
+      return false
+    }
+    const status = this.lib.audioSetMasterVolume(engine, volume)
+    if (status !== 0) {
+      this.emitError("setMasterVolume", status)
+      return false
+    }
+    return true
+  }
+
+  mixFrames(frameCount: number, channels: number = 2): Float32Array | null {
+    const engine = this.engine
+    if (!engine) {
+      this.emitError("mixFrames", undefined, "Audio engine unavailable during mixFrames")
+      return null
+    }
+    const output = new Float32Array(frameCount * channels)
+    const status = this.lib.audioMixToBuffer(engine, output, frameCount, channels)
+    if (status !== 0) {
+      this.emitError("mixFrames", status)
+      return null
+    }
+    return output
+  }
+
+  enableTap(capacityFrames: number = 8192): boolean {
+    const engine = this.engine
+    if (!engine) {
+      this.emitError("enableTap", undefined, "Audio engine unavailable during enableTap")
+      return false
+    }
+    const status = this.lib.audioEnableTap(engine, true, capacityFrames)
+    if (status !== 0) {
+      this.emitError("enableTap", status)
+      return false
+    }
+    return true
+  }
+
+  disableTap(): boolean {
+    const engine = this.engine
+    if (!engine) {
+      this.emitError("enableTap", undefined, "Audio engine unavailable during disableTap")
+      return false
+    }
+    const status = this.lib.audioEnableTap(engine, false, 0)
+    if (status !== 0) {
+      this.emitError("enableTap", status)
+      return false
+    }
+    return true
+  }
+
+  readTapFrames(frameCount: number, channels: number = 2): { frames: Float32Array; framesRead: number } | null {
+    const engine = this.engine
+    if (!engine) {
+      this.emitError("readTapFrames", undefined, "Audio engine unavailable during readTapFrames")
+      return null
+    }
+    const output = new Float32Array(frameCount * channels)
+    const result = this.lib.audioReadTap(engine, output, frameCount, channels)
+    if (result.status !== 0) {
+      this.emitError("readTapFrames", result.status)
+      return null
+    }
+    return { frames: output, framesRead: result.framesRead }
+  }
+
+  listPlaybackDevices(): AudioPlaybackDevice[] | null {
+    const engine = this.engine
+    if (!engine) {
+      this.emitError("listPlaybackDevices", undefined, "Audio engine unavailable during listPlaybackDevices")
+      return null
+    }
+
+    const refreshStatus = this.lib.audioRefreshPlaybackDevices(engine)
+    if (refreshStatus !== 0) {
+      this.emitError("listPlaybackDevices", refreshStatus)
+      return null
+    }
+
+    const count = this.lib.audioGetPlaybackDeviceCount(engine)
+    const devices: AudioPlaybackDevice[] = []
+    for (let index = 0; index < count; index += 1) {
+      devices.push({
+        index,
+        name: this.lib.audioGetPlaybackDeviceName(engine, index),
+        isDefault: this.lib.audioIsPlaybackDeviceDefault(engine, index),
+      })
+    }
+
+    return devices
+  }
+
+  selectPlaybackDevice(index: number): boolean {
+    const engine = this.engine
+    if (!engine) {
+      this.emitError("selectPlaybackDevice", undefined, "Audio engine unavailable during selectPlaybackDevice")
+      return false
+    }
+
+    const refreshStatus = this.lib.audioRefreshPlaybackDevices(engine)
+    if (refreshStatus !== 0) {
+      this.emitError("selectPlaybackDevice", refreshStatus)
+      return false
+    }
+
+    const status = this.lib.audioSelectPlaybackDevice(engine, index)
+    if (status !== 0) {
+      this.emitError("selectPlaybackDevice", status)
+      return false
+    }
+
+    return true
+  }
+
+  clearPlaybackDeviceSelection(): void {
+    const engine = this.engine
+    if (!engine) {
+      this.emitError(
+        "clearPlaybackDeviceSelection",
+        undefined,
+        "Audio engine unavailable during clearPlaybackDeviceSelection",
+      )
+      return
+    }
+    this.lib.audioClearPlaybackDeviceSelection(engine)
+  }
+
+  getStats(): AudioStats | null {
+    const engine = this.engine
+    if (!engine) {
+      this.emitError("getStats", undefined, "Audio engine unavailable during getStats")
+      return null
+    }
+    const stats = this.lib.audioGetStats(engine)
+    if (stats == null) {
+      this.emitError("getStats", undefined, "Failed to retrieve audio stats")
+    }
+    return stats
+  }
+
+  dispose(): void {
+    if (!this.engine) return
+    if (this.mixerStarted) {
+      this.stop()
+    }
+    this.groups.clear()
+    this.lib.destroyAudioEngine(this.engine)
+    this.engine = null
+    this.emit("disposed")
+  }
+}
+
+export function setupAudio(options: AudioSetupOptions = {}): Audio {
+  return Audio.create(options)
+}

package/src/benchmark/attenuation-benchmark.ts

@@ -0,0 +1,81 @@
+#!/usr/bin/env bun
+
+import { performance } from "node:perf_hooks"
+import { OptimizedBuffer } from "../buffer.js"
+import { VignetteEffect } from "../post/effects.js"
+
+type Scenario = { width: number; height: number }
+type ScenarioResult = {
+  size: string
+  cells: number
+  avgMs: number
+  avgNsPerCell: number
+  medianMs: number
+  p95Ms: number
+}
+
+const ITERATIONS = 5000
+const WARMUP_ITERATIONS = 100
+const STRENGTH = 0.7
+const baseScenarios: Array<{ width: number; height: number }> = [
+  { width: 40, height: 20 },
+  { width: 80, height: 24 },
+  { width: 120, height: 40 },
+  { width: 200, height: 60 },
+]
+const scenarios: Scenario[] = baseScenarios
+
+function calculateStats(samples: number[]): { avgMs: number; medianMs: number; p95Ms: number } {
+  const sorted = [...samples].sort((a, b) => a - b)
+  const total = samples.reduce((sum, value) => sum + value, 0)
+  const avgMs = total / samples.length
+  const mid = Math.floor(sorted.length / 2)
+  const medianMs = sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid]
+  const p95Index = Math.floor(0.95 * (sorted.length - 1))
+  const p95Ms = sorted[p95Index]
+
+  return { avgMs, medianMs, p95Ms }
+}
+
+function formatMs(value: number): number {
+  return Number(value.toFixed(4))
+}
+
+function formatNs(value: number): number {
+  return Number(value.toFixed(2))
+}
+
+function runScenario({ width, height }: Scenario): ScenarioResult {
+  const buffer = OptimizedBuffer.create(width, height, "unicode", { id: `vignette-bench-${width}x${height}` })
+  const vignetteEffect = new VignetteEffect(STRENGTH)
+  const { fg, bg } = buffer.buffers
+  fg.fill(1)
+  bg.fill(1)
+
+  for (let i = 0; i < WARMUP_ITERATIONS; i++) {
+    vignetteEffect.apply(buffer)
+  }
+
+  const samples = new Array<number>(ITERATIONS)
+  for (let i = 0; i < ITERATIONS; i++) {
+    const start = performance.now()
+    vignetteEffect.apply(buffer)
+    samples[i] = performance.now() - start
+  }
+
+  buffer.destroy()
+
+  const stats = calculateStats(samples)
+  return {
+    size: `${width}x${height}`,
+    cells: width * height,
+    avgMs: formatMs(stats.avgMs),
+    avgNsPerCell: formatNs((stats.avgMs * 1_000_000) / (width * height)),
+    medianMs: formatMs(stats.medianMs),
+    p95Ms: formatMs(stats.p95Ms),
+  }
+}
+
+console.log(`Vignette Effect Benchmark (${ITERATIONS} iterations per scenario)`)
+const results = scenarios.map(runScenario)
+console.table(results)