🔊 @trap_stevo/voxen

Universal Sound Intelligence Layer.
Every sound. Every space. One voice.

Unifies interface audio, spatial environments, and intelligent sound behavior inside one modular, extensible system.
From reactive UI cues to full 3D soundfields—audio flows with precision, elegance, and control.

---

✨ Features

- 🧭 Universal Spatial Audio — 3D/2D positional playback (HRTF/equal-power) with distance rolloffs & cones
- 🧩 Plugin Architecture — Built-ins: Occlusion, Proximity, Limiter, Reverb + custom DSP extensions
- 🎚️ Layered Mixing — Arbitrary buses ("layer:") with smooth volume automation
- 📦 Direct Sources & Streaming — load() for direct refs; auto-decoding + streaming cache
- 🧠 AI Hearing Propagation — propagate() / cancelPropagation() waves; occlusion-aware intensity; heard event
- 🚦 Audience Targeting — Include/exclude/byTag/custom predicates per play/propagation
- 🚀 Optimized Core — Node pooling (Gain/Panner), audibility culling, guarded listener updates
- 🗂️ Soundboards — Declarative registries with hierarchical extends and versioning
- 🧾 Rich Events — Play/fade/updates, plugin diagnostics, preload + propagation lifecycle

---

⚙️ Constructor

``js
import { Voxen } from "@trap_stevo/voxen";

const voxen = new Voxen({
cullHz: 60
});
`

Options

| Option | Type | Default | Description |
|---------|---------|---------|-------------|
| cullHz | number | 30 | Tick rate for listener and plugin updates |

---

🧠 Core Concepts

- Listener – Defines hearing point. Multiple listeners allowed; one active at a time.
- Soundboard – Groups related sounds; supports overrides and inheritance.
- Layer – Controls volume and mix per domain (UI, world, music).
- Plugin – Extends system with DSP or behavioral logic.
- Propagation – Expanding hearing waves for AI detection and stealth simulation.

---

⚙️ Core Methods

| Method | Description | Params (summary) | Returns | Async |
|---|---|---|---|:---:|
| resume() | Unlocks and resumes the AudioContext. | — | Promise | ✅ |
| destroy() | Stops all sounds, clears timers/caches, closes context. | — | void | ❌ |
| on(type, handler) | Subscribes to an event. | type, handler(payload) | () => void | ❌ |
| off(type, handler) | Unsubscribes an event handler. | type, handler | void | ❌ |
| registerPlugin(plugin) | Registers a custom plugin. | { name, ... } | void | ❌ |
| enableReverb(options?) | Enables built-in reverb bus. | { mix?, ir? } | Promise | ✅ |
| disableReverb() | Disables built-in reverb. | — | void | ❌ |
| enableLimiter(options?) | Enables built-in limiter. | { threshold?, knee?, ratio?, attack?, release? } | void | ❌ |
| disableLimiter() | Disables built-in limiter. | — | void | ❌ |
| enableOcclusion(options?) | Enables occlusion (raycast-aware). | { raycast?, getListenerPosition?, maxAttenuation?, smoothing? } | void | ❌ |
| disableOcclusion() | Disables occlusion. | — | void | ❌ |
| setProximityTriggers(options) | Starts/updates proximity trigger loop. | { getListenerPosition, getInstancePosition?, triggers[], tickHz?, distance? } | void | ❌ |
| registerSoundboard(board) | Registers a soundboard. | { name, items, extends? } | void | ❌ |
| useSoundboards(names) | Activates soundboards (topmost wins). | string[] | void | ❌ |
| contains(id) | Checks if an active soundboard has id. | string | boolean | ❌ |
| preload(ids) | Prepares/decodes assets by ids. | string[] | Promise | ✅ |
| addListener(listener) | Adds a listener. | { id, position, orientation?, tags? } | void | ❌ |
| updateListener(id, patch) | Patches listener fields. | string, { position?, orientation?, tags? } | void | ❌ |
| removeListener(id) | Removes a listener. | string | void | ❌ |
| setActiveListener(id) | Sets active listener and applies to context. | string | void | ❌ |
| load(soundId, sourceRef, defaults?) | Registers & prepares a direct sound. | string, SourceRef, { loop?, volume?, pitch?, distance? } | Promise | ✅ |
| play(idOrDirect, opts?) | Plays by soundboard id or direct source. | string | DirectRef, PlayOptions | Promise (instanceId) | ✅ |
| stop(instanceId, opts?) | Stops an instance (optional fade). | string, { fadeOut? } | void | ❌ |
| updateInstance(instanceId, patch) | Updates volume/pitch/spatial origin. | string, { volume?, pitch?, spatial? } | void | ❌ |
| getActiveInstances() | Lists active instance ids. | — | string[] | ❌ |
| setVolume(target, value) | Sets "master" or "layer:" volume. | string, 0..1 | void | ❌ |
| ensureLayer(name, node?) | Ensures a named layer exists (Gain by default). | string, AudioNode? | void | ❌ |
| propagate(options) | Starts an expanding hearing wave. | PropagateOptions | string (token) | ❌ |
| cancelPropagation(token, extra?) | Cancels an in-flight wave. | string, { natural? } | void | ❌ |

---

🔔 Events

| Event | Description |
|-------|--------------|
| play | Fires when playback starts. |
| ended | Fires when playback stops. |
| audibility | Signals sound visibility to listener. |
| layerVolumeChange | Occurs when layer volume changes. |
| pluginError | Reports plugin failure. |
| fadeStart | Marks fade-in or fade-out begin. |
| fadeEnd | Marks fade completion. |
| instanceUpdate | Reflects runtime parameter change. |
| layerMute | Toggles layer mute state. |
| preloadComplete | Confirms preload success. |
| contextStateChange | Indicates context resume or suspend. |
| propagateStart | Emitted when a sound wave begins. |
| heard | Emitted when a listener perceives a propagated sound. |
| propagateEnd | Fired when propagation completes or is canceled. |

---

📘 Parameter Reference

This section defines the shapes and defaults of Voxen’s primary configuration objects. All objects are plain JSON-like structures; functions are allowed where noted (e.g., for live positions).

$3

| Type | Meaning |
|------|--------|
| Seconds | Number in seconds (e.g., 0.25) |
| Hertz | Number in Hz (e.g., 60) |
| Decibels | Number in dBFS for WebAudio nodes (e.g., -3) |
| Linear01 | Number clamped to 0..1 |
| Vec3 | { x:number, y:number, z:number } |
| Vec3Fn | () => Vec3 (evaluated per frame/tick) |
| TimeFn | T | (() => T) — static value or function return |

---

$3

#### SourceRef
A reference to media to be decoded or streamed.

| Field | Type | Required | Notes |
|------|------|----------|------|
| kind | "url" \| "element" \| "buffer" | ✅ | How audio is provided |
| href | string | ⬅ when kind:"url" | Absolute/relative URL |
| element | HTMLMediaElement | ⬅ when kind:"element" |