🔊 @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:<name>") with smooth volume automation
• 📦 Direct Sources & Streaming — load() for direct refs; auto-decoding + <audio> 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

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

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

Options

🧠 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

🔔 Events

📘 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).

🔤 Common Scalar & Utility Types

🗂️ Sound Sources

SourceRef

A reference to media to be decoded or streamed.

DirectRef

Play without a soundboard entry.

🧭 Spatial & Distance

DistanceModel

"inverse" | "linear" | "exponential"

DistanceOptions

SpatialOptions

🎚️ Playback

FadeOptions

PlayDefaults

PlayOptions

updateInstance(instanceId, patch)

🧑‍🦻 Audience Targeting

Use to filter who can hear a sound or who participates in a propagation wave.

Audience

A discriminated union:

type Audience =
  | { kind:"all" }
  | { kind:"include"; ids:string[] }
  | { kind:"exclude"; ids:string[] }
  | { kind:"byTag"; tags:string[] }
  | { kind:"predicate"; test:(meta:{ id:string; tags?:string[]; extra?:any }) => boolean }

• When used for playback, audience is applied at instance connect time.
• When used for propagate(), audience is sampled per wavefront step.

🛰️ Propagation (AI Hearing)

PropagateOptions

Events (Propagation)

• propagateStart — { token, origin, power, maxRadius }
• heard — { token, listenerId, distance, intensity, tags }
• propagateEnd — { token, reason:"completed"|"canceled" }

🧲 Proximity Triggers

setProximityTriggers(options)

ProximityTrigger

Events:

• proximityEnter — { id, position }
• proximityExit — { id, position }

🧱 Occlusion Plugin

enableOcclusion(options)

🧰 Limiter Plugin

enableLimiter(options)

Recommended: bypass UI, keep world/music under control.

engine.enableLimiter({
  threshold : -3, ratio : 12, attack : 0.003, release : 0.120,
  bypassLayers : ["ui"]
});

🌫️ Reverb Bus

enableReverb(options)

🎛️ Mixing & Layers

• setVolume("master", value) — Set master gain.
• setVolume("layer:<name>", value) — Set per-bus gain.
• ensureLayer(name, node?) — Create a custom bus (default GainNode); you can pass a pre-wired AudioNode for advanced routing (e.g., side-chains).

👂 Listeners

addListener(listener)

setActiveListener(id) switches the engine to drive WebAudio’s AudioListener from this definition.

🧩 Plugin Hook Context (ctx)

Hook argument available to beforeConnect, afterConnect, frame, onStop.

type PluginCtx = {
  engine : Voxen;
  audioCtx : AudioContext;
  nodes : {
    source : AudioNode;
    gain : GainNode;
    layer : GainNode;      // or custom node if provided
    master : GainNode;
  };
  layer : string;          // "master" or "layer:<name>"
  contextTime : number;    // audioCtx.currentTime
  instanceId : string;     // current play instance
  meta? : any;             // item meta / tags
};

📡 Events (Payload Shapes)

• play — { instanceId, id, layer, tags? }
• ended — { instanceId, id, reason:"natural"|"stop"|"error" }
• audibility — { instanceId, audible:boolean }
• layerVolumeChange — { layer, value }
• pluginError — { plugin, error }
• fadeStart — { instanceId, kind:"in"|"out", duration }
• fadeEnd — { instanceId, kind:"in"|"out" }
• instanceUpdate — { instanceId, patch }
• preloadComplete — { ids:string[] }
• contextStateChange — { state:"running"|"suspended"|"closed" }
• proximityEnter / proximityExit — { id, position }
• propagateStart / heard / propagateEnd — see Propagation above

📦 Installation

npm install @trap_stevo/voxen

# or

yarn add @trap_stevo/voxen

⚡ Quick Start & Examples

Example 1 — UI Click

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

const voxen = new Voxen();

voxen.registerSoundboard({
  name: "ui",
  items: [
    {
      id: "ui/click",
      sources: [{ kind: "url", href: "https://upload.wikimedia.org/wikipedia/commons/2/26/Computer_mouse_single_click.ogg" }],
      meta: { volume: 0.85 }
    }
  ]
});

voxen.useSoundboards(["ui"]);
await voxen.preload(["ui/click"]);
await voxen.resume();

document.addEventListener("click", () => voxen.play("ui/click", { layer: "ui" }));

Example 2 — 3D Fountain Ambience

voxen.addListener({
  id: "listener",
  position: () => ({ x: camera.x, y: camera.y, z: camera.z }),
  orientation: {
    forward: () => camera.forward(),
    up: () => ({ x: 0, y: 1, z: 0 })
  }
});
voxen.setActiveListener("listener");

voxen.registerSoundboard({
  name: "scene",
  items: [
    {
      id: "env/fountain",
      sources: [{ kind: "url", href: "https://upload.wikimedia.org/wikipedia/commons/5/54/Fountainnoise.ogg" }],
      meta: { loop: true, volume: 0.85, distance: { refDistance: 1, maxDistance: 45 } }
    }
  ]
});

voxen.useSoundboards(["scene"]);
await voxen.preload(["env/fountain"]);
await voxen.play("env/fountain", {
  spatial: {
    origin: () => ({ x: 6, y: 0.5, z: -10 }),
    distance: { refDistance: 1, maxDistance: 45 },
    hrtf: true
  },
  layer: "ambient",
  fade: { in: 1.0 }
});

Example 3 — Proximity + Occlusion + AI Propagation

voxen.enableOcclusion({
  raycast: (from, to) => performRaycast(from, to),
  getListenerPosition: () => player.position,
  maxAttenuation: 0.55,
  smoothing: 0.08
});

voxen.setProximityTriggers({
  getListenerPosition: () => player.position,
  triggers: [
    {
      id: "pickup-zone",
      position: { x: 5, y: 0, z: -8 },
      radius: 1.5,
      enterPlay: { soundId: "ui/click", options: { layer: "ui" } }
    }
  ],
  tickHz: 45
});

// AI Hearing Example
voxen.on("heard", e => console.log("AI heard:", e.listenerId, e.tags));

voxen.propagate({
  origin: () => player.position,
  power: 1,
  maxRadius: 40,
  velocity: 343,
  sampleHz: 30,
  audience: { kind: "byTag", tags: ["ai"] },
  occlusionAware: true,
  occlusionPenalty: 0.6
});

Example 4 — Layer Mixing & Live Updates

voxen.setVolume("layer:ambient", 0.3);
voxen.updateInstance(fountainId, { pitch: 1.15 });
voxen.stop(fountainId, { fadeOut: 0.5 });

🧩 Custom Plugin API

Custom DSP, analyzers, or automation logic can slot directly into the playback chain.

Configuration Hooks

Usage Example

const EchoPlugin = {
  name: "custom:echo",

  onRegister({ audioCtx }) {
    this.delay = audioCtx.createDelay();
    this.delay.delayTime.value = 0.3;
    this.feedback = audioCtx.createGain();
    this.feedback.gain.value = 0.4;
    this.delay.connect(this.feedback);
    this.feedback.connect(this.delay);
  },

  beforeConnect(ctx, node) {
    node.connect(this.delay);
    return this.delay;
  },

  frame(ctx, dt) {
    const g = ctx.nodes.gain.gain.value;
    this.feedback.gain.setTargetAtTime(g * 0.4, ctx.nodes.master.contextTime, 0.05);
  },

  onStop() {
    this.delay.disconnect();
    this.feedback.disconnect();
  }
};

voxen.registerPlugin(EchoPlugin);

⚡ Performance & Integration Notes

🎛️ Plugin Chain Order

Source → [Plugin.beforeConnect nodes] → preGain → gain → layer → master → destination

Use beforeConnect for filters or delays.
Use custom layers for post-processing or global DSP.

🧮 Frame Efficiency

Set cullHz to match simulation tick:

• 90 Hz for rhythmic or rapid feedback loops
• 30–45 Hz for dense spatial environments

🧠 Memory & Pooling

Gain and Panner nodes reuse pooled memory.
Inactive nodes disconnect automatically.
Streamed sources skip redundant decoding.

⚡ Latency Control

Chromium engines reach sub-5 ms latency with preloaded buffers.
Call .preload() before playback to prevent decode delays.
Trigger .resume() once after user gesture to unlock playback.

🕹️ Integration Guidelines

Three.js

• Update listener in render loop via updateListener().
• Pass camera.getWorldPosition() and camera.getWorldDirection().

Babylon.js

• Hook into camera.onViewMatrixChangedObservable.

React / DOM

• Resume audio after click:

  useEffect(() => {
    const click = () => voxen.play("ui/click");
    document.addEventListener("click", click);
    return () => document.removeEventListener("click", click);
  }, []);

Physics Engines

• Provide world coordinates in spatial.origin.
• Interpolation handled internally.

🧭 Debugging

Monitor pluginError for DSP exceptions.
Audit getActiveInstances() for pool usage.
Trace audibility for live diagnostics:

voxen.on("audibility", e => console.log("Audible:", e.audible));

🚀 Best Practice Summary

📜 License

See License in LICENSE.md

🔊 Orchestrate Sound. One Voice.

Unify UI clicks, spatial worlds, and cinematic layers into one deterministic audio fabric. From web apps to 3D games, Voxen delivers low-latency playback, precise spatialization, and event-driven control—so sound design scales with your vision, not your constraints. Every sound. Every space. One voice.