Runtime

Runtime configuration, session lifecycle, adapter contracts, media handling, reconnect, turn detection, and call-control hooks.

#Runtime Plugin

import { Elysia } from "elysia";
import { createVoiceMemoryStore, voice } from "@absolutejs/voice";
import { deepgram } from "@absolutejs/voice-deepgram";
import { elevenlabs } from "@absolutejs/voice-elevenlabs";

const sessions = createVoiceMemoryStore();
const stt = deepgram({ apiKey: process.env.DEEPGRAM_API_KEY! });
const tts = elevenlabs({
	apiKey: process.env.ELEVENLABS_API_KEY!,
	voiceId: process.env.ELEVENLABS_VOICE_ID!
});

new Elysia()
	.use(voice({
		path: "/voice/realtime",
		session: sessions,
		stt,
		tts,
		greeting: "Hi, how can I help?",
		context: async ({ session }) => ({ sessionId: session.id }),
		onTurn: async (_session, turn, api) => {
			await api.say(`You said: ${turn.text}`);
		}
	}))
	.listen(3000);

console.log("voice websocket: ws://localhost:3000/voice/realtime");

#VoicePluginConfig Options

Option	Meaning
`amd`	Answering-machine detection driver for phone routes.
`assistantMode`	Resolved mode for realtime or split STT/TTS operation.
`audioConditioning`	Input normalization, resampling, gating, and conditioning before STT.
`bargeInMinPartialWords`	Minimum partial transcript word count before cancelling assistant audio.
`context`	Route/context resolver that builds app-specific session context.
`costTelemetry`	Cost attribution hooks for provider usage, call runtime, and turn-level accounting.
`defaultSilentTurnAck`	Spoken acknowledgement for tool-only or otherwise silent assistant turns.
`fillerDelayMs`	Delay before static latency filler is allowed to play.
`fillerFor`	Content-aware filler callback for short acknowledgements.
`fillerForTimeoutMs`	Timeout for the content-aware filler callback.
`fillerPhrases`	Static latency filler phrases spoken while the assistant response is pending.
`greeting`	Static or per-session first assistant message.
`handoff`	Transfer, escalation, voicemail, no-answer, and completion hooks.
`htmx`	Enables HTMX-oriented runtime attributes and responses.
`languageStrategy`	Fixed, auto-detect, or allow-switching language plan passed to providers.
`lexicon`	Static or context-resolved pronunciation/domain lexicon.
`liveOps`	Runtime control-state resolver for live operator actions.
`logger`	Structured runtime logger hook.
`modalities`	Audio/text modality list passed to realtime providers.
`monitor`	Live monitor registry binding for listen/control sockets.
`noiseSuppressor`	Optional @absolutejs/media-compatible noise suppressor.
`noiseSuppressorFormat`	AudioFormat expected by the noise suppressor.
`onTurn`	Required handler or assistant invocation for committed user turns.
`ops`	Operations task, review, sink, webhook, and event integration.
`path`	Required WebSocket path for the main voice runtime.
`phraseHints`	Static or context-resolved STT phrase hints.
`preset`	Runtime preset that fills common defaults for profile, language, turn detection, and carrier behavior.
`profileSwitchGuard`	Runtime guard that audits, blocks, or auto-applies profile-switch recommendations.
`prosody`	TTS speed, pitch, emphasis, and style hints.
`realtime`	Full-duplex realtime adapter for unified input and output.
`realtimeInputFormat`	AudioFormat for realtime input when it differs from the route default.
`reconnect`	Client reconnect/resume behavior and continuity policy.
`recording`	Recording store and channel capture policy.
`redact`	Transcript redactor applied before storage, traces, and sinks.
`routeOnTurnTimeoutMs`	Hard timeout for one onTurn call.
`scenarioId`	Scenario identifier used by simulation, proof, and profiles.
`semanticTurnDetector`	Model or heuristic semantic turn detector for natural turn completion.
`session`	Required session store used to create, read, update, and persist VoiceSessionRecord values.
`sessionMetadata`	Additional metadata attached to the runtime session.
`stt`	Streaming speech-to-text adapter used in split STT/TTS mode.
`sttFallback`	Fallback STT policy for empty or low-confidence turns.
`sttLifecycle`	Provider lifecycle hooks for STT session open, events, errors, and close.
`trace`	Trace event store used by diagnostics, timelines, proofs, and ops.
`tts`	Streaming text-to-speech adapter used for assistant audio output.
`turnDetection`	Silence, vendor, manual, semantic, or hybrid end-of-turn policy.

#Adapter Contracts

STTAdapter.open() creates sessions that receive audio chunks and emit partial, final, endOfTurn, error, and close events.

TTSAdapter.open() creates sessions that receive text and emit audio, error, and close events; optional cancel() supports barge-in.

RealtimeAdapter.open() accepts audio or text and emits both transcript and audio events.

AudioFormat covers raw alaw, mulaw, and pcm_s16le with sample rate and mono/stereo channel count.

Language strategy supports fixed language, auto-detect with allow-list, or allow-switching.

The example exposes two runtime paths: /voice/intake for cascaded STT+TTS and /voice/realtime for OpenAI Realtime. The frontend chooses the route with an engine query parameter and passes stable sessionId values so every audio frame belongs to one server-side session.

export const getVoiceRoutePath = (
	scenarioId: "guided" | "general",
	provider?: "openai" | "anthropic" | "gemini" | "deterministic",
	routing?: "balanced" | "fastest" | "cheapest" | "quality",
	engine: "cascaded" | "openai-realtime" = "cascaded",
	profileId?: string,
	sessionId?: string
) => {
	const params = new URLSearchParams({ scenarioId });
	if (provider) params.set("provider", provider);
	if (routing) params.set("routing", routing);
	if (profileId) params.set("voiceProfile", profileId);
	if (sessionId) params.set("sessionId", sessionId);
	const path = engine === "openai-realtime" ? "/voice/realtime" : "/voice/intake";
	return `${path}?${params.toString()}`;
};

#Turns And Media

Turn detection can use vendor events, silence windows, manual end_turn messages, semantic VAD, or hybrids.

STT fallback can replay audio to secondary providers on empty or low-confidence turns.

Audio conditioning and noise suppression run before STT.

Barge-in cancels active assistant audio based on partial transcript thresholds.

Latency filler can be static phrases or content-aware fillerFor() acknowledgements with timeout fallback.

Recording captures assistant and/or user channels into a configured recording store.

#Follow one call through the runtime

Browser, phone, realtime, and synthetic callers converge on the same observable session contract.

Connect
Accept a WebSocket, telephony media stream, provider realtime session, or tester connection.
Resolve
Resolve tenant context, assistant, language, provider route, policy, and live-ops state.
Understand
Condition audio, detect turns, transcribe or stream realtime input, and invoke the assistant.
Respond
Execute tools, synthesize audio, support barge-in, or transfer through typed handoff policy.
Prove
Persist trace, cost, audit, recording, delivery, SLO, and proof evidence for the same session.

Continue toward an outcome

These playbooks show where this package fits, how to verify the combined system, and what changes before production.

Build a voice agentConnect one caller, resolve a provider stack, complete a turn, and retain the trace needed to operate the call.

PreviousComparison NextAdapters