@kuralle-syrinx/server-websocket 4.4.1 → 4.5.0

package/dist/inbound-audio.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: MIT
+import { SYRINX_AUDIO_ENVELOPE_NAME, decodeSyrinxAudioEnvelope, hasSyrinxAudioEnvelope, } from "@kuralle-syrinx/core";
+import { pcm16BytesToSamples, pcm16SamplesToBytes, resamplePcm16Streaming, } from "@kuralle-syrinx/core/audio";
+export function socketDataToBytes(data) {
+    if (typeof data === "string")
+        return new TextEncoder().encode(data);
+    return data;
+}
+export function decodeInboundBinaryAudio(data, defaultSampleRateHz, rawBinaryInput, engineInputSampleRateHz, streamingResamplers, decodeOpusIngress) {
+    if (!hasSyrinxAudioEnvelope(data)) {
+        if (!rawBinaryInput) {
+            throw new Error(`Raw binary websocket audio is disabled; use ${SYRINX_AUDIO_ENVELOPE_NAME} or JSON audio frames`);
+        }
+        return { sampleRateHz: defaultSampleRateHz, audio: data };
+    }
+    const { header, audio } = decodeSyrinxAudioEnvelope(data);
+    const sampleRateHz = requirePositiveIntegerFromHeader(header.sampleRateHz) ?? defaultSampleRateHz;
+    const isOpus = header.encoding === "opus";
+    const wireAudio = isOpus
+        ? decodeOpusIngressMessage(audio, sampleRateHz, decodeOpusIngress, engineInputSampleRateHz, streamingResamplers)
+        : audio;
+    // Opus ingress is decoded AND resampled to the engine rate inside
+    // decodeOpusIngressMessage, so the returned PCM is already at engineInputSampleRateHz.
+    // Report that as its rate — reporting the 48 kHz *header* rate made the caller
+    // resample the already-16 kHz audio a second time, delivering ~1/3 the samples
+    // (3× sped-up audio → STT garbage). PCM carries its true header source rate.
+    const effectiveSampleRateHz = isOpus ? engineInputSampleRateHz : sampleRateHz;
+    return {
+        contextId: typeof header.contextId === "string" && header.contextId.length > 0 ? header.contextId : undefined,
+        sampleRateHz: effectiveSampleRateHz,
+        sequence: header.sequence,
+        audio: wireAudio,
+    };
+}
+function decodeOpusIngressMessage(wire, sampleRateHz, decodeOpusIngress, engineInputSampleRateHz, streamingResamplers) {
+    if (!decodeOpusIngress)
+        throw new Error("Browser websocket opus ingress is not initialized");
+    const pcm = decodeOpusIngress(wire, sampleRateHz);
+    if (sampleRateHz === engineInputSampleRateHz)
+        return pcm;
+    const samples = pcm16BytesToSamples(pcm);
+    return pcm16SamplesToBytes(resamplePcm16Streaming(streamingResamplers, samples, sampleRateHz, engineInputSampleRateHz));
+}
+export function rememberContextSampleRate(contextSampleRates, contextId, sampleRateHz) {
+    const existing = contextSampleRates.get(contextId);
+    if (existing !== undefined && existing !== sampleRateHz) {
+        throw new Error(`Websocket audio sampleRateHz changed within context ${contextId}: ${existing} -> ${sampleRateHz}`);
+    }
+    contextSampleRates.set(contextId, sampleRateHz);
+}
+export function resampleAudioBytes(audio, sourceSampleRateHz, targetSampleRateHz, streamingResamplers) {
+    if (audio.byteLength % 2 !== 0) {
+        throw new Error("PCM16 audio payload must contain an even number of bytes");
+    }
+    if (sourceSampleRateHz === targetSampleRateHz)
+        return audio;
+    const samples = pcm16BytesToSamples(audio);
+    const resampled = resamplePcm16Streaming(streamingResamplers, samples, sourceSampleRateHz, targetSampleRateHz);
+    return pcm16SamplesToBytes(resampled);
+}
+function requirePositiveIntegerFromHeader(value) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0)
+        return null;
+    return value;
+}
+//# sourceMappingURL=inbound-audio.js.map

package/dist/inbound-audio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbound-audio.js","sourceRoot":"","sources":["../src/inbound-audio.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAE/B,OAAO,EACL,0BAA0B,EAC1B,yBAAyB,EACzB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,sBAAsB,GAEvB,MAAM,4BAA4B,CAAC;AAWpC,MAAM,UAAU,iBAAiB,CAAC,IAAyB;IACzD,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACpE,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,IAAgB,EAChB,mBAA2B,EAC3B,cAAuB,EACvB,uBAA+B,EAC/B,mBAAyD,EACzD,iBAA4C;IAE5C,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,EAAE,CAAC;QAClC,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CAAC,+CAA+C,0BAA0B,uBAAuB,CAAC,CAAC;QACpH,CAAC;QACD,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAC5D,CAAC;IACD,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,yBAAyB,CAAC,IAAI,CAAC,CAAC;IAC1D,MAAM,YAAY,GAAG,gCAAgC,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,mBAAmB,CAAC;IAClG,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,KAAK,MAAM,CAAC;IAC1C,MAAM,SAAS,GAAG,MAAM;QACtB,CAAC,CAAC,wBAAwB,CAAC,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,mBAAmB,CAAC;QAChH,CAAC,CAAC,KAAK,CAAC;IACV,kEAAkE;IAClE,uFAAuF;IACvF,+EAA+E;IAC/E,+EAA+E;IAC/E,6EAA6E;IAC7E,MAAM,qBAAqB,GAAG,MAAM,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,YAAY,CAAC;IAC9E,OAAO;QACL,SAAS,EAAE,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;QAC7G,YAAY,EAAE,qBAAqB;QACnC,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,KAAK,EAAE,SAAS;KACjB,CAAC;AACJ,CAAC;AAED,SAAS,wBAAwB,CAC/B,IAAgB,EAChB,YAAoB,EACpB,iBAA4C,EAC5C,uBAA+B,EAC/B,mBAAyD;IAEzD,IAAI,CAAC,iBAAiB;QAAE,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IAC7F,MAAM,GAAG,GAAG,iBAAiB,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IAClD,IAAI,YAAY,KAAK,uBAAuB;QAAE,OAAO,GAAG,CAAC;IACzD,MAAM,OAAO,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC;IACzC,OAAO,mBAAmB,CACxB,sBAAsB,CAAC,mBAAmB,EAAE,OAAO,EAAE,YAAY,EAAE,uBAAuB,CAAC,CAC5F,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,kBAAuC,EACvC,SAAiB,EACjB,YAAoB;IAEpB,MAAM,QAAQ,GAAG,kBAAkB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACnD,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,YAAY,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CAAC,uDAAuD,SAAS,KAAK,QAAQ,OAAO,YAAY,EAAE,CAAC,CAAC;IACtH,CAAC;IACD,kBAAkB,CAAC,GAAG,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,KAAiB,EACjB,kBAA0B,EAC1B,kBAA0B,EAC1B,mBAAyD;IAEzD,IAAI,KAAK,CAAC,UAAU,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;IAC9E,CAAC;IACD,IAAI,kBAAkB,KAAK,kBAAkB;QAAE,OAAO,KAAK,CAAC;IAC5D,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAC3C,MAAM,SAAS,GAAG,sBAAsB,CAAC,mBAAmB,EAAE,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,CAAC,CAAC;IAC/G,OAAO,mBAAmB,CAAC,SAAS,CAAC,CAAC;AACxC,CAAC;AAED,SAAS,gCAAgC,CAAC,KAAc;IACtD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACrF,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+import type { IncomingMessage } from "node:http";
+import { type Server as HttpServer } from "node:http";
+import { WebSocketServer } from "ws";
+import { type VoiceAgentSession } from "@kuralle-syrinx/core";
+import { type GracefulCloseOptions } from "./transport-host.js";
+import { type BackgroundAudioConfig } from "./background-audio.js";
+import { type SessionStore } from "./session-store.js";
+export * from "./twilio.js";
+export * from "./telnyx.js";
+export * from "./smartpbx.js";
+export * from "./session-store.js";
+export { validateTwilioSignature } from "./twilio-auth.js";
+export { buildTwilioSendDigits, buildTelnyxSendDtmf, buildTwilioTransfer, buildTelnyxTransfer, dispatchTwilioCommand, dispatchTelnyxCommand, resolveTransferSummary, type TwilioSendDigitsCommand, type TelnyxSendDtmfCommand, type TwilioTransferCommand, type TelnyxTransferCommand, type TwilioRestCredentials, type TelnyxRestCredentials, type WarmTransferSummarizer, type FetchLike, } from "./carrier-commands.js";
+export { wireCarrierControl, type CarrierControlOptions } from "./wire-carrier-control.js";
+export { BackgroundAudioMixer, wireBackgroundThinking, wireBackgroundBackchannel, wireBackgroundAudio, type BackgroundAudioConfig, type BackgroundAudioSource, } from "./background-audio.js";
+export { buildPlaceholderBackchannelCues } from "./backchannel-cue-fixtures.js";
+export { installGracefulShutdown, type GracefulClosable } from "./websocket-lifecycle.js";
+export interface VoiceWebSocketServerOptions {
+    readonly server?: HttpServer;
+    readonly port?: number;
+    readonly host?: string;
+    readonly path?: string;
+    readonly createSession: (request: IncomingMessage) => VoiceAgentSession | Promise<VoiceAgentSession>;
+    /** Explicit resolver for the session identity; when set, it takes precedence over the request query. */
+    readonly sessionId?: (request: IncomingMessage) => string;
+    readonly contextId?: () => string;
+    readonly inputSampleRateHz?: number;
+    readonly outputSampleRateHz?: number;
+    readonly heartbeatIntervalMs?: number;
+    readonly startupTimeoutMs?: number;
+    readonly maxSessionDurationMs?: number;
+    readonly maxBufferedAmountBytes?: number;
+    readonly maxInboundMessageBytes?: number;
+    readonly resumeWindowMs?: number;
+    readonly outboundFrameDurationMs?: number;
+    readonly maxQueuedOutputAudioMs?: number;
+    /**
+     * Raw binary inbound PCM16 lacks turn, sample-rate, sequence, and duration
+     * metadata. Keep disabled for production clients; use JSON audio frames or
+     * the Syrinx binary envelope instead. Set true only for explicitly managed
+     * legacy/embedded clients that send PCM at `inputSampleRateHz`.
+     */
+    readonly rawBinaryInput?: boolean;
+    /**
+     * Assistant audio binary frames are wrapped in the Syrinx binary audio
+     * envelope by default. Set false only for raw-PCM websocket clients.
+     * Inbound binary frames may use the envelope regardless.
+     */
+    readonly binaryAudioEnvelope?: boolean;
+    /**
+     * When true (default), outbound browser assistant audio is Opus inside the Syrinx
+     * envelope. Set false only for tests or legacy clients that require PCM envelopes.
+     */
+    readonly browserOpusDownlink?: boolean;
+    /**
+     * Ambient/thinking bed mixed (ducked) under assistant speech. No idle bed is
+     * sent between turns on the browser path — a web client can loop ambience
+     * locally; the server-side idle bed exists for telephony wires.
+     */
+    readonly backgroundAudio?: BackgroundAudioConfig;
+    readonly sessionStore?: SessionStore;
+    readonly maxConcurrentSessions?: number;
+    readonly maxConcurrentSessionsScope?: "path" | "server";
+    readonly onTransportMetric?: (name: string) => void;
+    /**
+     * Authorize each inbound `/ws` upgrade (shared secret / bearer / signature).
+     * Return false or throw to reject with 4401. Unset = OPEN — voice endpoints are
+     * unauthenticated by default and each connection incurs provider cost and can
+     * attach to a live session; set this before exposing the endpoint publicly.
+     */
+    readonly authorize?: (request: import("node:http").IncomingMessage) => boolean | Promise<boolean>;
+}
+export type { GracefulCloseOptions } from "./transport-host.js";
+export interface VoiceWebSocketServer {
+    readonly httpServer: HttpServer;
+    readonly wsServer: WebSocketServer;
+    address(): ReturnType<HttpServer["address"]>;
+    close(opts?: GracefulCloseOptions): Promise<void>;
+}
+export declare function createVoiceWebSocketServer(options: VoiceWebSocketServerOptions): Promise<VoiceWebSocketServer>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}