@daxov/client
Call in the browser (microphone, voice, face, mute, end, state) and the server helpers for live events, webhooks and tool calls.
@daxov/client runs a live call in the browser from the CallStart your server got from POST /v1/calls. @daxov/client/server is for your server: the call's live events, and checking webhooks and tool calls.
The package is private until the product has its name; @daxov/client is a placeholder name. The code below shows how it will be used.
Call, in the browser
import { Call } from "@daxov/client";
const call = new Call();
call.on("state", (state) => render(state));
call.on("ended", (reason) => console.log("Ended:", reason));
// Straight from the person's click: browsers allow sound and the microphone only then.
button.onclick = () =>
call.start(() => fetch("/api/calls", { method: "POST" }).then((r) => r.json()));start does the whole start in the right order: the microphone first, then your server's CallStart, then the connection. It takes the CallStart itself, or a function that asks your server for it (called only once the microphone is open).
Options
new Call(options):
Prop
Type
Methods
| Method | What it does |
|---|---|
start(source) | The whole start, from the click: open(), then the CallStart (source is one, or a function that returns one), then connect() |
open() | The sound system and the microphone. Call it straight from a click |
connect(start) | Connects to the call your server started and starts talking (after open()). Rejects with a CallError if the call refuses the connection |
setMuted(muted) | Mutes or unmutes the microphone |
end(reason?) | Hangs up. Safe at any time, more than once. reason goes to the logs, so a call always says why it ended |
on(name, fn), once(name, fn) | Listens to an event (below); returns a function that stops listening |
getState(), subscribe(fn) | The state, and a change listener, for your own UI framework |
events | The live events socket when the events option opened it (the same ControlSocket your server would use), else null |
State
call.getState() and the state event give one object:
| Field | What it is |
|---|---|
phase | idle, opening, connecting, live, ended or failed |
callId | The call's id (call_…), once connecting |
maxSeconds, liveSince | The most it can last, and when it went live (for a timer) |
status | The call's status as we report it (starting, running…) |
micLevel, aiLevel | Loudness from 0 to 1, for meters |
aiSpeaking | The AI's voice is playing (with a face: the face is speaking) |
muted | Whether the microphone is muted |
error | A CallError, with a message written for the person on the call |
endedReason | Why the call ended, in plain words ("The call reached its time limit.") |
playback | How the voice is played: direct, element, loopback or face |
face | { status, video, startupMs, problem }: status is off, joining, waiting, live, failed or ended; video is a MediaStream for a <video> element |
transcript | Lines as they come, with the events option only |
Events
| Event | When |
|---|---|
state | Anything in the state changed |
phase | The phase changed |
speaking | The AI started or stopped speaking |
transcript | A transcript line (with the events option) |
ended | The call is over, with the reason when there is one |
error | A CallError |
log | What the call is doing, for your logs (no secrets) |
Errors
A CallError has a kind and a message you can show as it is:
kind | What happened |
|---|---|
mic_blocked | The browser or the person blocked the microphone |
mic_missing | There's no microphone |
mic_busy | Another app holds the microphone |
unsupported | The browser can't run a call |
start_failed | Your server couldn't start the call (the function given to start threw) |
refused | The call refused the connection: an expired or used ticket, or the call open elsewhere |
lost | The connection dropped mid-call |
Echo
The AI must not hear itself through the microphone. echo: "auto" (the default) plays the voice the way each browser's echo cancellation catches it:
echo | How the voice plays |
|---|---|
direct | Through Web Audio. Chrome and Firefox cancel this |
element | Through an <audio> element |
loopback | Through a call inside the page, which every browser treats as a call: the fix for Safari and iOS. Adds a few tens of milliseconds |
auto | direct on Chrome and Firefox, loopback on Safari and iOS |
With a face, the voice comes from the face's own call track, which every browser cancels by itself. Headphones avoid echo whichever way.
Content-Security-Policy
A page with a Content-Security-Policy needs:
script-src blob:: the sound processors load from ablob:URL;connect-src wss://api.daxov.com: the call's connection;- the face's room, when the call has a face: the
livekit_urlthe call'sws.facenames, a server of ours. The SDK joins it with the open-source LiveKit client library, which loads only when a call has a face.
@daxov/client/server, on your server
Nothing here touches a microphone or the page, so it runs in Node 22+, Deno, Bun and workers (and in browsers too).
ControlSocket: the call's live events
import { ControlSocket } from "@daxov/client/server";
const events = new ControlSocket(start.events_url);
events.on("transcript", (line) => console.log(line.who, line.text));
events.on("ended", (e) => console.log(e.reason, e.message));
const snapshot = await events.connect();
if (snapshot.controls.includes("say")) await events.say("Your order has shipped.");It speaks the live events socket for you: the snapshot, each transcript line once (also across reconnects), and your controls answered by their ack.
| Member | What it does |
|---|---|
connect() | Connects and resolves with the first snapshot. Fails if that first connection is refused; later drops are reconnected with the same token |
say(text) | The character says this next, word for word (at most 1,000 characters). Resolves when the call takes it |
context(text) | A note the mind reads at the head of its next turn and keeps (at most 4,000 characters; 20,000 a call) |
end() | Ends the call, as POST /v1/calls/{id}/end does |
close() | Stops listening. The call goes on |
snapshot, status, transcript, controls, ended | What it last heard |
Events: snapshot, status, transcript, speaking, tool, lagged, ended, error, close (with final when it won't reconnect), reconnecting, and message for every frame.
Options: WebSocket (a WebSocket class, where there's no global one, for example the ws package's), reconnect (default true), retryDelaysMs, and ackTimeoutMs (default 10,000). A refused control rejects with a ControlError whose code is the socket's (not_supported, queue_full, too_long…).
Webhooks and tool calls
import { readWebhook, WebhookVerificationError } from "@daxov/client/server";
try {
const event = await readWebhook(process.env.WEBHOOK_SECRET, req.headers, rawBody);
// dedupe on event.id: deliveries are at least once, in no guaranteed order
} catch (e) {
if (e instanceof WebhookVerificationError) return reply(400);
throw e;
}| Function | What it does |
|---|---|
readWebhook(secret, headers, rawBody) | Checks a webhook delivery and returns its event, typed. Throws WebhookVerificationError when it isn't ours |
readToolCall(secret, headers, rawBody) | The same for a tool call, with the tool's secret: returns what the character asked for |
verifyWebhook(secret, headers, rawBody) | true when a signature matches and the timestamp is recent |
signWebhook(secret, id, timestamp, rawBody) | Signs a body as we do, for your tests |
headers may be a Headers or Node's headers object; rawBody is the body exactly as it arrived (a string or bytes). The timestamp may be at most 300 seconds off (toleranceSeconds changes it). They use WebCrypto. See Verify signatures.
forBrowser(start)
Takes events_url out of a CallStart before it goes to the person's browser. Whoever holds that token can make the character say anything and end the call, so it stays on your server.
Types
The API's shapes, for TypeScript: CallStart, BrowserCallStart, ApiCall, CallDetail, CallAnalysis, WebhookEvent, ToolCallRequest, TranscriptTurn, ApiErrorBody and more.