API reference

Every public class, method, and event in @codexo/exojs. Generated from source.

classInputVoice

@codexo/exojs / audio / stable

Live control handle for an AudioInput (microphone / WebRTC stream), created via AudioSystem.open. Unlike a Playable voice it is **analysis-only by default** - its output is not routed to a bus, so it never causes feedback. Tap it for visualisation/beat-detection (`new AudioAnalyser({ source: inputVoice })`), opt into monitoring with InputVoice.routeTo, or capture it with InputVoice.record. A live stream cannot be seeked, paused, looped, or rate-shifted, so it only mixes in Spatializable (via BaseVoice) on top of the base Voice surface (volume / fade / stop / effects / output tap / bus).

props

methods

events

Import

import { InputVoice } from '@codexo/exojs'

A live stream cannot be seeked, paused, looped, or rate-shifted, so it only mixes in Spatializable (via BaseVoice) on top of the base Voice surface (volume / fade / stop / effects / output tap / bus).

Constructors1

new(init: InputVoiceInit): InputVoice

Methods17

_applyDopplerRate(_ratio: number): void

Apply a Doppler pitch-shift multiplier on top of whatever playback rate the voice already has (never overwrite the user's own explicit rate - multiply it). Default no-op: voice types with no meaningful, live rate parameter (AudioGeneratorVoice's rate is documented as inert; InputVoice/NoopVoice have no source to modulate) simply don't override this. Overridden by SoundVoice and AudioStreamVoice.

_clearStopTimer(): void

_connectOutput(): void

_finish(): void

Called once on natural end or explicit BaseVoice.stop. Idempotent - subsequent calls are no-ops once _ended is set.

_routeDirect(): void

Restore the direct source-to-output route.

_routeThroughPanner(panner: PannerNode): void

Insert panner between the voice's source and its output gain. The source is currently connected directly to BaseVoice._output; rewire it as source → panner → output.

_tail(): AudioNode

The last node in the voice chain before the bus - the output gain, the occlusion stage, or the last effect.

_teardownSource(): void

Stop and disconnect the voice's source node(s). Called once from _finish.

addEffect(effect: AudioEffectAbstract base for all insertable audio effects in ExoJS. Each effect exposes stable inputNode and outputNode AudioNodes that an AudioBus or Voice connects into…): this

Append an effect to this voice's chain. Attaching the same effect twice is a caller error: the rebuilt chain would wire the effect's output back into its own input, producing a feedback loop. The dev build asserts; production ignores the second attach.

addSend(bus: AudioBusHierarchical mixer node in the engine's audio routing graph. Each bus owns three Web Audio nodes (input gain, optional effect chain, stereo pan, output gain) a…, level: number): AudioSendA parallel tap from one voice's output into an AudioBus, at its own level. A send is what an insert effect cannot express: the voice keeps playing into its own…

Open a parallel send from this voice's output into bus at level (default 1). The dry path is untouched: the voice keeps playing into its own Voice.bus, and a copy of the same signal additionally reaches bus. Use it for shared ambience processing - one reverb serving many voices - which an insert effect cannot express, because an insert replaces the signal rather than duplicating it. The returned AudioSend is owned by this voice and torn down with it; remove one early with Voice.removeSend only to change the routing.

fade(to: number, duration: SecondsA length of time in seconds. The unit every duration in the public API is expressed in - frame deltas, the fixed step, elapsed totals, timer limits. It is a `n…): void

Ramp the volume to to (clamped to [0, 1]) over duration without stopping. Use Voice.stop with a fade argument to fade out and stop.

follow(node: SceneNodeTransform-bearing leaf in the scene-graph hierarchy. Carries position, rotation, scale, skew and origin. Implements Collidable so any node can participate dire… | null): void

Track node's position each frame and pan this voice from it (or stop tracking with null). Reads SceneNode.getWorldTransform - the TRUE world position, composed through RetainedContainer transform-group boundaries - so an emitter inside a camera-panned world group sounds where it is drawn.

record(duration: SecondsA length of time in seconds. The unit every duration in the public API is expressed in - frame deltas, the fixed step, elapsed totals, timer limits. It is a `n…): Promise<SoundPre-decoded short audio clip backed by an `AudioBuffer`. Sound is a **data descriptor** - it holds the decoded audio buffer, sprite definitions, and default pl…>

Record duration of the live input and resolve with a playable Sound. Uses MediaRecorder under the hood, then decodes the captured blob into an AudioBuffer.

removeEffect(effect: AudioEffectAbstract base for all insertable audio effects in ExoJS. Each effect exposes stable inputNode and outputNode AudioNodes that an AudioBus or Voice connects into…): this

Remove a previously added per-voice effect. The caller still owns it and must destroy() it.

removeSend(send: AudioSendA parallel tap from one voice's output into an AudioBus, at its own level. A send is what an insert effect cannot express: the voice keeps playing into its own…): this

Tear down a send opened on this voice. Idempotent; a send from another voice is ignored.

routeTo(bus: AudioBusHierarchical mixer node in the engine's audio routing graph. Each bus owns three Web Audio nodes (input gain, optional effect chain, stereo pan, output gain) a…): this

Make the live input audible by routing it to a bus (monitoring). Use sparingly - routing a microphone to the speakers risks feedback.

stop(fade?: SecondsA length of time in seconds. The unit every duration in the public API is expressed in - frame deltas, the fixed step, elapsed totals, timer limits. It is a `n…): void

Stop playback and release this voice's resources. Pass fade to ramp the volume to zero over that duration before stopping; omit (or pass 0) to stop immediately. Idempotent - calling again is a no-op.

Properties19

bus: AudioBusHierarchical mixer node in the engine's audio routing graph. Each bus owns three Web Audio nodes (input gain, optional effect chain, stereo pan, output gain) a…

The AudioBus this voice routes into. Reassign to reroute live.

coneInnerAngle: number

Full-gain cone half-angle in degrees. Default 360 (omnidirectional - no cone).

coneOuterAngle: number

Falloff-to-coneOuterGain cone half-angle in degrees. Default 360.

coneOuterGain: number

Gain applied outside coneOuterAngle. Default 0.

distanceModel: DistanceModelDistance-attenuation model used by spatial sounds. Mirrors Web Audio's `PannerNode.distanceModel`: - `'linear'` - `v = 1 - rolloffFactor * (d - refDistance) /…

Distance-attenuation model. Default 'linear'.

elevation: number

Height of the source above (positive) or below (negative) the world plane, in world units. Default 0. Independent of Spatializable.position, and preserved across a position change that does not carry a z. It contributes to distance attenuation, to the panner's own directionality, and to Doppler - a source rising straight up recedes.

elevationVelocity: number

Vertical component of Spatializable.velocity, in world units per second. Default 0. Only Doppler reads it.

ended: boolean

true once playback has ended naturally or been stopped.

maxDistance: number

For the 'linear' model: distance at which volume reaches zero. Default 1000.

occlusion: number

How obstructed the path from this source to the listener is, in [0, 1]. 0 (default) is a clear path; 1 is fully obstructed. Caller-supplied: the engine does not trace geometry, because what counts as an obstruction is a game's decision (a wall, a closed door, a crowd). Write an estimate as often as you like - it is ramped, not stepped, so a per-frame value does not click. Realized as a lowpass plus an attenuation, tuned by app.audio.spatial.occlusionCutoff / .occlusionAttenuation. A voice whose occlusion stays 0 builds neither node.

orientation: number

Facing direction for cone attenuation, in degrees - same convention as SceneNode.rotation (0° = local +X / "east", clockwise-positive on a Y-down screen). Has no audible effect unless coneInnerAngle/ coneOuterAngle are narrowed below 360°. Default 0.

output: AudioNode

The voice's output node - the last node before the AudioBus. Use it as a parallel tap for an analyser, or (later) as the insertion point for per-voice effects.

panningModel: PanningModelType | null

Per-voice panning model override. null (default) inherits the app-wide default from app.audio.spatial.panningModel.

position: VectorConcrete mutable 2D vector with full AbstractVector arithmetic and Collidable collision support (treated as a point collider). `Vector.temp` provides a shared… | null

World-plane position of the source, or null when not spatialized. Two-dimensional, because the world plane is: the third axis lives on Spatializable.elevation, which Spatializable.follow cannot fill in and which most 2D games never touch.

refDistance: number

Distance below which volume is at full strength. Default 50.

rolloffFactor: number

Falloff rate. Higher = steeper attenuation. Default 1.

sends: readonly AudioSendA parallel tap from one voice's output into an AudioBus, at its own level. A send is what an insert effect cannot express: the voice keeps playing into its own…[]

Live view of this voice's open sends, in the order they were opened.

velocity: VectorConcrete mutable 2D vector with full AbstractVector arithmetic and Collidable collision support (treated as a point collider). `Vector.temp` provides a shared… | null

World-space velocity of the source (world units/second), or null. Feeds the Doppler calculation (app.audio.spatial.dopplerFactor) - has no other effect. Explicit; when null and follow(node) is active, velocity is auto-derived each frame from the tracked node's position delta instead.

volume: number

Playback volume in the range [0, 1]. Bus volume (0..2) can amplify beyond this.

Events1

onEnd: SignalLightweight typed event emitter. Each `Signal` represents one named notification channel (e.g. `onResize`, `onFrame`). Listeners are added with Signal.add or S…<[]>

Fires once when this voice ends (natural end or Voice.stop).

Source

src/audio/InputVoice.ts