@kognitivedev/voice-media-bridge 0.2.29

package/dist/routes.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPhoneAudioRoute = createPhoneAudioRoute;
+exports.resolvePhoneAudioRoute = resolvePhoneAudioRoute;
+exports.phoneAudioRouteMetadata = phoneAudioRouteMetadata;
+exports.getStableCarrierProfile = getStableCarrierProfile;
+const profiles_1 = require("./profiles");
+function normalizeAiProvider(value) {
+    return value === "xai-realtime" || value === "gemini-live" ? value : "openai-realtime";
+}
+function pcmLeg(sampleRate) {
+    return {
+        codec: "pcm",
+        format: "audio/pcm",
+        sampleRate,
+        mimeType: `audio/pcm;rate=${sampleRate}`,
+    };
+}
+const PCMU_LEG = {
+    codec: "pcmu",
+    format: "audio/pcmu",
+    sampleRate: 8000,
+    mimeType: "audio/pcmu",
+};
+function resolveAiLegs(aiProvider, carrier) {
+    if (aiProvider === "gemini-live") {
+        return {
+            aiInput: pcmLeg(16000),
+            aiOutput: pcmLeg(24000),
+        };
+    }
+    if (carrier.codec === "pcmu") {
+        return {
+            aiInput: PCMU_LEG,
+            aiOutput: PCMU_LEG,
+        };
+    }
+    if (aiProvider === "xai-realtime") {
+        const leg = pcmLeg(carrier.carrierSampleRate === 16000 ? 16000 : 24000);
+        return {
+            aiInput: leg,
+            aiOutput: leg,
+        };
+    }
+    const leg = pcmLeg(24000);
+    return {
+        aiInput: leg,
+        aiOutput: leg,
+    };
+}
+function createPhoneAudioRoute(carrier, aiProviderInput) {
+    const aiProvider = normalizeAiProvider(aiProviderInput);
+    const { aiInput, aiOutput } = resolveAiLegs(aiProvider, carrier);
+    const inputTranscoding = carrier.codec === "pcmu" && aiInput.codec === "pcmu" && carrier.carrierSampleRate === aiInput.sampleRate
+        ? "none"
+        : "decode-resample";
+    const outputTranscoding = carrier.codec === "pcmu" && aiOutput.codec === "pcmu" && carrier.carrierSampleRate === aiOutput.sampleRate
+        ? "none"
+        : "resample-encode";
+    return {
+        id: `${carrier.id}__${aiProvider}__in-${aiInput.codec}-${aiInput.sampleRate}__out-${aiOutput.codec}-${aiOutput.sampleRate}`,
+        carrierProvider: carrier.provider,
+        aiProvider,
+        carrier,
+        aiInput,
+        aiOutput,
+        inputTranscoding,
+        outputTranscoding,
+        stable: carrier.id !== "telnyx-l16-16k",
+    };
+}
+function resolvePhoneAudioRoute(input) {
+    const carrier = (0, profiles_1.resolvePhoneMediaProfile)({
+        provider: input.carrierProvider,
+        requestedCodec: input.requestedCodec,
+        l16ByteOrder: input.l16ByteOrder,
+        fallbackState: input.fallbackState,
+    });
+    return createPhoneAudioRoute(carrier, input.aiProvider);
+}
+function phoneAudioRouteMetadata(route) {
+    return {
+        id: route.id,
+        carrierProvider: route.carrierProvider,
+        aiProvider: route.aiProvider,
+        carrier: (0, profiles_1.phoneMediaProfileMetadata)(route.carrier),
+        aiInput: route.aiInput,
+        aiOutput: route.aiOutput,
+        inputTranscoding: route.inputTranscoding,
+        outputTranscoding: route.outputTranscoding,
+        stable: route.stable,
+    };
+}
+function getStableCarrierProfile(provider) {
+    if (provider === "telnyx")
+        return Object.assign(Object.assign({}, (0, profiles_1.getPhoneMediaProfile)("telnyx-pcmu-8k")), { source: "auto" });
+    return (0, profiles_1.resolvePhoneMediaProfile)({ provider, requestedCodec: "auto" });
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@kognitivedev/voice-media-bridge",
+  "version": "0.2.29",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc -w --noCheck",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@kognitivedev/telephony": "^0.2.29"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "description": "Reusable realtime telephony media bridge helpers for Kognitive voice agents",
+  "keywords": [
+    "kognitive",
+    "voice",
+    "media",
+    "telnyx",
+    "twilio",
+    "realtime"
+  ],
+  "license": "MIT"
+}

package/src/__tests__/media.test.ts

@@ -0,0 +1,229 @@
+import { describe, expect, it } from "vitest";
+import {
+    base64ToPcm16Le,
+    decodeCarrierPayload,
+    encodeCarrierPayload,
+    frameDurationMs,
+    fromAiOutputAudio,
+    fromOpenAIOutputAudio,
+    getPhoneMediaProfile,
+    isOpenAIRealtimeAudioReady,
+    phoneAudioRouteMetadata,
+    openAIRealtimeAudioFormat,
+    pcm16ToBase64Le,
+    realtimeAudioFormatForRoute,
+    realtimeOutputAudioFormatForRoute,
+    resolvePhoneAudioRoute,
+    resolvePhoneMediaProfile,
+    summarizePcm16Signal,
+    toAiInputAudio,
+    toOpenAIInputAudio,
+} from "../index";
+
+describe("voice media bridge audio profiles", () => {
+    it("round-trips PCMU within lossy telephone tolerance", () => {
+        const profile = getPhoneMediaProfile("twilio-pcmu-8k");
+        const samples = new Int16Array([0, 256, -512, 1024, -2048, 4096, -8192, 12000]);
+
+        const payload = encodeCarrierPayload(profile, samples);
+        const decoded = decodeCarrierPayload(profile, payload);
+
+        expect(decoded.length).toBe(samples.length);
+        for (let index = 0; index < samples.length; index += 1) {
+            expect(Math.abs((decoded[index] ?? 0) - (samples[index] ?? 0))).toBeLessThan(900);
+        }
+    });
+
+    it("preserves L16 little-endian PCM16 values and duration", () => {
+        const profile = getPhoneMediaProfile("telnyx-l16-16k");
+        const samples = new Int16Array([0, 1, -1, 32767, -32768, 1600, -2400]);
+
+        const payload = encodeCarrierPayload(profile, samples);
+        const decoded = decodeCarrierPayload(profile, payload);
+
+        expect(Array.from(decoded)).toEqual(Array.from(samples));
+        expect(frameDurationMs(320, profile.carrierSampleRate)).toBe(20);
+        expect(base64ToPcm16Le(pcm16ToBase64Le(samples))).toEqual(samples);
+    });
+
+    it("can force Telnyx L16 little-endian decoding for live codec experiments", () => {
+        const profile = resolvePhoneMediaProfile({
+            provider: "telnyx",
+            requestedCodec: "l16_16k",
+            l16ByteOrder: "le",
+        });
+        const samples = new Int16Array([0, 1200, -2400, 4800]);
+
+        const payload = encodeCarrierPayload(profile, samples);
+
+        expect(profile).toMatchObject({
+            id: "telnyx-l16-16k",
+            carrierByteOrder: "le",
+            source: "forced",
+        });
+        expect(base64ToPcm16Le(payload)).toEqual(samples);
+        expect(decodeCarrierPayload(profile, payload)).toEqual(samples);
+    });
+
+    it("resamples Telnyx L16 16k to OpenAI PCM16 24k and back without clipping", () => {
+        const profile = getPhoneMediaProfile("telnyx-l16-16k");
+        const carrierSamples = new Int16Array(1600);
+        for (let index = 0; index < carrierSamples.length; index += 1) {
+            carrierSamples[index] = Math.round(Math.sin(index / 8) * 9000);
+        }
+
+        const openAIPayload = toOpenAIInputAudio(profile, encodeCarrierPayload(profile, carrierSamples));
+        const openAISamples = base64ToPcm16Le(openAIPayload);
+        expect(openAISamples.length).toBe(2400);
+
+        const output = fromOpenAIOutputAudio(profile, pcm16ToBase64Le(openAISamples));
+        expect(output.samples.length).toBe(1600);
+        expect(output.durationMs).toBe(100);
+        expect(output.signal.clippedSamples).toBe(0);
+    });
+
+    it("summarizes silence, weak input, likely speech, and clipping", () => {
+        expect(summarizePcm16Signal(new Int16Array(160))).toMatchObject({
+            peakAbs: 0,
+            rms: 0,
+            clippedSamples: 0,
+        });
+
+        const weak = summarizePcm16Signal(new Int16Array([10, -12, 8, -9]));
+        expect(weak.rms).toBeLessThan(400);
+        expect(weak.peakAbs).toBeLessThan(2500);
+
+        const speech = summarizePcm16Signal(new Int16Array([0, 1200, -1800, 2600, -3200]));
+        expect(speech.rms).toBeGreaterThanOrEqual(400);
+        expect(speech.peakAbs).toBeGreaterThanOrEqual(2500);
+
+        const clipped = summarizePcm16Signal(new Int16Array([32767, -32768, 100]));
+        expect(clipped.clippedSamples).toBe(2);
+        expect(clipped.clippingRatio).toBeGreaterThan(0.6);
+    });
+
+    it("selects stable PCMU automatically and keeps Telnyx L16 explicit-only", () => {
+        expect(resolvePhoneMediaProfile({ provider: "telnyx", requestedCodec: "auto" })).toMatchObject({
+            id: "telnyx-pcmu-8k",
+            carrierCodec: "PCMU",
+            carrierSampleRate: 8000,
+            source: "auto",
+        });
+        expect(resolvePhoneMediaProfile({ provider: "telnyx", requestedCodec: "l16_16k" })).toMatchObject({
+            id: "telnyx-l16-16k",
+            carrierCodec: "L16",
+            carrierSampleRate: 16000,
+            source: "forced",
+        });
+        expect(resolvePhoneMediaProfile({ provider: "telnyx", requestedCodec: "pcmu_8k" })).toMatchObject({
+            id: "telnyx-pcmu-8k",
+            source: "forced",
+        });
+        expect(resolvePhoneMediaProfile({ provider: "telnyx", requestedCodec: "auto", fallbackState: { forcePcmu: true } })).toMatchObject({
+            id: "telnyx-pcmu-8k",
+            source: "fallback",
+        });
+        expect(resolvePhoneMediaProfile({ provider: "twilio", requestedCodec: "l16_16k" })).toMatchObject({
+            id: "twilio-pcmu-8k",
+        });
+        expect(resolvePhoneMediaProfile({ provider: "sip", requestedCodec: "auto" })).toMatchObject({
+            id: "sip-pcmu-8k",
+            provider: "sip",
+            carrierCodec: "PCMU",
+            openAIFormat: "audio/pcmu",
+        });
+    });
+
+    it("resolves stable audio routes for every phone provider and AI provider", () => {
+        const phoneProviders = ["twilio", "telnyx", "sip"] as const;
+        const aiProviders = ["openai-realtime", "xai-realtime", "gemini-live"] as const;
+
+        for (const carrierProvider of phoneProviders) {
+            for (const aiProvider of aiProviders) {
+                const route = resolvePhoneAudioRoute({
+                    carrierProvider,
+                    aiProvider,
+                    requestedCodec: "auto",
+                });
+
+                expect(route.carrier.codec).toBe("pcmu");
+                expect(route.carrier.carrierSampleRate).toBe(8000);
+                expect(route.stable).toBe(true);
+                expect(phoneAudioRouteMetadata(route)).toMatchObject({
+                    carrierProvider,
+                    aiProvider,
+                    carrier: {
+                        codec: "PCMU",
+                        sampleRate: 8000,
+                    },
+                });
+
+                if (aiProvider === "gemini-live") {
+                    expect(route.aiInput).toMatchObject({ codec: "pcm", format: "audio/pcm", sampleRate: 16000, mimeType: "audio/pcm;rate=16000" });
+                    expect(route.aiOutput).toMatchObject({ codec: "pcm", format: "audio/pcm", sampleRate: 24000, mimeType: "audio/pcm;rate=24000" });
+                    expect(route.inputTranscoding).toBe("decode-resample");
+                    expect(route.outputTranscoding).toBe("resample-encode");
+                    expect(realtimeAudioFormatForRoute(route)).toEqual({ type: "audio/pcm", rate: 16000 });
+                    expect(realtimeOutputAudioFormatForRoute(route)).toEqual({ type: "audio/pcm", rate: 24000 });
+                } else {
+                    expect(route.aiInput).toMatchObject({ codec: "pcmu", format: "audio/pcmu", sampleRate: 8000, mimeType: "audio/pcmu" });
+                    expect(route.aiOutput).toMatchObject({ codec: "pcmu", format: "audio/pcmu", sampleRate: 8000, mimeType: "audio/pcmu" });
+                    expect(route.inputTranscoding).toBe("none");
+                    expect(route.outputTranscoding).toBe("none");
+                    expect(realtimeAudioFormatForRoute(route)).toEqual({ type: "audio/pcmu" });
+                    expect(realtimeOutputAudioFormatForRoute(route)).toEqual({ type: "audio/pcmu" });
+                }
+            }
+        }
+    });
+
+    it("passes PCMU through for OpenAI/xAI and transcodes Gemini through PCM16 16k", () => {
+        const carrierSamples = new Int16Array(800);
+        for (let index = 0; index < carrierSamples.length; index += 1) {
+            carrierSamples[index] = Math.round(Math.sin(index / 8) * 9000);
+        }
+        const carrierProfile = getPhoneMediaProfile("telnyx-pcmu-8k");
+        const carrierPayload = encodeCarrierPayload(carrierProfile, carrierSamples);
+        const passthroughRoute = resolvePhoneAudioRoute({ carrierProvider: "telnyx", aiProvider: "openai-realtime", requestedCodec: "auto" });
+        const geminiRoute = resolvePhoneAudioRoute({ carrierProvider: "telnyx", aiProvider: "gemini-live", requestedCodec: "auto" });
+
+        expect(toAiInputAudio(passthroughRoute, carrierPayload)).toBe(carrierPayload);
+        expect(fromAiOutputAudio(passthroughRoute, carrierPayload).payload).toBe(carrierPayload);
+
+        const geminiInput = toAiInputAudio(geminiRoute, carrierPayload);
+        expect(geminiInput).not.toBe(carrierPayload);
+        expect(base64ToPcm16Le(geminiInput).length).toBe(1600);
+
+        const geminiOutput = fromAiOutputAudio(geminiRoute, pcm16ToBase64Le(base64ToPcm16Le(geminiInput)), 16000);
+        expect(geminiOutput.samples.length).toBe(800);
+        expect(geminiOutput.durationMs).toBe(100);
+    });
+
+    it("configures OpenAI session audio as PCMU for Twilio and PCM for Telnyx HD", () => {
+        const twilio = getPhoneMediaProfile("twilio-pcmu-8k");
+        const telnyx = getPhoneMediaProfile("telnyx-l16-16k");
+
+        expect(openAIRealtimeAudioFormat(twilio)).toEqual({ type: "audio/pcmu" });
+        expect(openAIRealtimeAudioFormat(telnyx)).toEqual({ type: "audio/pcm", rate: 24000 });
+
+        expect(isOpenAIRealtimeAudioReady({
+            type: "session.updated",
+            session: {
+                audio: {
+                    input: { format: { type: "audio/pcm", rate: 24000 } },
+                    output: { format: { type: "audio/pcm", rate: 24000 } },
+                },
+            },
+        }, telnyx)).toBe(true);
+
+        expect(isOpenAIRealtimeAudioReady({
+            type: "session.updated",
+            session: {
+                audio: {
+                    input: { format: { type: "audio/pcmu" } },
+                    output: { format: { type: "audio/pcmu" } },
+                },
+            },
+        }, twilio)).toBe(true);
+    });
+});

package/src/audio.ts

@@ -0,0 +1,182 @@
+import {
+    decodeTwilioMulawBase64ToPcm16,
+    encodePcm16ToTwilioMulawBase64,
+    resamplePcm16WindowedSinc,
+} from "@kognitivedev/telephony";
+import type { PhoneMediaProfile } from "./profiles";
+import type { PhoneAudioRoute } from "./routes";
+
+export interface PcmSignalSummary {
+    samples: number;
+    peakAbs: number;
+    rms: number;
+    clippedSamples: number;
+    clippingRatio: number;
+    bytes: number;
+}
+
+export interface CarrierAudioOutput {
+    payload: string;
+    durationMs: number;
+    signal: PcmSignalSummary;
+    samples: Int16Array;
+}
+
+export const OPENAI_PCM_SAMPLE_RATE = 24000;
+const CLIP_THRESHOLD = 32760;
+
+export function pcm16ToBase64Le(samples: Int16Array): string {
+    const buffer = Buffer.alloc(samples.length * 2);
+    for (let index = 0; index < samples.length; index += 1) {
+        buffer.writeInt16LE(samples[index] ?? 0, index * 2);
+    }
+    return buffer.toString("base64");
+}
+
+export function base64ToPcm16Le(data: string): Int16Array {
+    const buffer = Buffer.from(data, "base64");
+    const samples = new Int16Array(Math.floor(buffer.length / 2));
+    for (let index = 0; index < samples.length; index += 1) {
+        samples[index] = buffer.readInt16LE(index * 2);
+    }
+    return samples;
+}
+
+export function pcm16ToBase64Be(samples: Int16Array): string {
+    const buffer = Buffer.alloc(samples.length * 2);
+    for (let index = 0; index < samples.length; index += 1) {
+        buffer.writeInt16BE(samples[index] ?? 0, index * 2);
+    }
+    return buffer.toString("base64");
+}
+
+export function base64ToPcm16Be(data: string): Int16Array {
+    const buffer = Buffer.from(data, "base64");
+    const samples = new Int16Array(Math.floor(buffer.length / 2));
+    for (let index = 0; index < samples.length; index += 1) {
+        samples[index] = buffer.readInt16BE(index * 2);
+    }
+    return samples;
+}
+
+export function summarizePcm16Signal(samples: Int16Array, bytes = samples.length * 2): PcmSignalSummary {
+    if (samples.length === 0) {
+        return { samples: 0, peakAbs: 0, rms: 0, clippedSamples: 0, clippingRatio: 0, bytes };
+    }
+
+    let peakAbs = 0;
+    let squareSum = 0;
+    let clippedSamples = 0;
+    for (const sample of samples) {
+        const abs = Math.abs(sample);
+        if (abs > peakAbs) peakAbs = abs;
+        if (abs >= CLIP_THRESHOLD) clippedSamples += 1;
+        squareSum += sample * sample;
+    }
+
+    return {
+        samples: samples.length,
+        peakAbs,
+        rms: Math.round(Math.sqrt(squareSum / samples.length)),
+        clippedSamples,
+        clippingRatio: clippedSamples / samples.length,
+        bytes,
+    };
+}
+
+export function frameDurationMs(sampleCount: number, sampleRate: number): number {
+    if (sampleRate <= 0) return 0;
+    return Math.round((sampleCount / sampleRate) * 1000);
+}
+
+export function decodeCarrierPayload(profile: PhoneMediaProfile, payload: string): Int16Array {
+    if (profile.codec === "pcmu") return decodeTwilioMulawBase64ToPcm16(payload);
+    return profile.carrierByteOrder === "le" ? base64ToPcm16Le(payload) : base64ToPcm16Be(payload);
+}
+
+export function encodeCarrierPayload(profile: PhoneMediaProfile, samples: Int16Array): string {
+    if (profile.codec === "pcmu") return encodePcm16ToTwilioMulawBase64(samples);
+    return profile.carrierByteOrder === "le" ? pcm16ToBase64Le(samples) : pcm16ToBase64Be(samples);
+}
+
+export function summarizeCarrierPayload(profile: PhoneMediaProfile, payload: string): PcmSignalSummary {
+    const bytes = Buffer.byteLength(payload, "base64");
+    return summarizePcm16Signal(decodeCarrierPayload(profile, payload), bytes);
+}
+
+export function toOpenAIInputAudio(profile: PhoneMediaProfile, payload: string): string {
+    if (profile.openAIFormat === "audio/pcmu") return payload;
+    const carrierPcm = decodeCarrierPayload(profile, payload);
+    const openAIPcm = resamplePcm16WindowedSinc(carrierPcm, profile.carrierSampleRate, profile.openAISampleRate);
+    return pcm16ToBase64Le(openAIPcm);
+}
+
+export function fromOpenAIOutputAudio(profile: PhoneMediaProfile, delta: string): CarrierAudioOutput {
+    if (profile.openAIFormat === "audio/pcmu") {
+        const samples = decodeCarrierPayload(profile, delta);
+        return {
+            payload: delta,
+            durationMs: frameDurationMs(samples.length, profile.carrierSampleRate),
+            signal: summarizePcm16Signal(samples, Buffer.byteLength(delta, "base64")),
+            samples,
+        };
+    }
+
+    const openAIPcm = base64ToPcm16Le(delta);
+    const carrierPcm = resamplePcm16WindowedSinc(openAIPcm, profile.openAISampleRate, profile.carrierSampleRate);
+    const payload = encodeCarrierPayload(profile, carrierPcm);
+    return {
+        payload,
+        durationMs: frameDurationMs(carrierPcm.length, profile.carrierSampleRate),
+        signal: summarizePcm16Signal(carrierPcm, Buffer.byteLength(payload, "base64")),
+        samples: carrierPcm,
+    };
+}
+
+export function toAiInputAudio(route: PhoneAudioRoute, payload: string): string {
+    if (
+        route.carrier.codec === "pcmu"
+        && route.aiInput.codec === "pcmu"
+        && route.carrier.carrierSampleRate === route.aiInput.sampleRate
+    ) {
+        return payload;
+    }
+    const carrierPcm = decodeCarrierPayload(route.carrier, payload);
+    const aiPcm = route.carrier.carrierSampleRate === route.aiInput.sampleRate
+        ? carrierPcm
+        : resamplePcm16WindowedSinc(carrierPcm, route.carrier.carrierSampleRate, route.aiInput.sampleRate);
+    return pcm16ToBase64Le(aiPcm);
+}
+
+export function fromAiOutputAudio(route: PhoneAudioRoute, delta: string, sourceRate = route.aiOutput.sampleRate): CarrierAudioOutput {
+    if (
+        route.carrier.codec === "pcmu"
+        && route.aiOutput.codec === "pcmu"
+        && route.carrier.carrierSampleRate === route.aiOutput.sampleRate
+    ) {
+        const samples = decodeCarrierPayload(route.carrier, delta);
+        return {
+            payload: delta,
+            durationMs: frameDurationMs(samples.length, route.carrier.carrierSampleRate),
+            signal: summarizePcm16Signal(samples, Buffer.byteLength(delta, "base64")),
+            samples,
+        };
+    }
+
+    const aiPcm = base64ToPcm16Le(delta);
+    const carrierPcm = sourceRate === route.carrier.carrierSampleRate
+        ? aiPcm
+        : resamplePcm16WindowedSinc(aiPcm, sourceRate, route.carrier.carrierSampleRate);
+    const payload = encodeCarrierPayload(route.carrier, carrierPcm);
+    return {
+        payload,
+        durationMs: frameDurationMs(carrierPcm.length, route.carrier.carrierSampleRate),
+        signal: summarizePcm16Signal(carrierPcm, Buffer.byteLength(payload, "base64")),
+        samples: carrierPcm,
+    };
+}
+
+export function isLikelySpeechPayload(profile: PhoneMediaProfile, payload: string, input: { rms?: number; peakAbs?: number } = {}) {
+    const signal = summarizeCarrierPayload(profile, payload);
+    return signal.rms >= (input.rms ?? 400) || signal.peakAbs >= (input.peakAbs ?? 2500);
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./audio";
+export * from "./openai";
+export * from "./profiles";
+export * from "./routes";

package/src/openai.ts

@@ -0,0 +1,127 @@
+import type { PhoneMediaProfile } from "./profiles";
+import { getPhoneMediaProfile } from "./profiles";
+import type { PhoneAudioRoute } from "./routes";
+
+function getRecord(value: unknown): Record<string, unknown> {
+    return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+function getString(value: unknown, fallback = "") {
+    return typeof value === "string" && value.trim() ? value.trim() : fallback;
+}
+
+function summarizeOpenAIAudioFormat(value: unknown) {
+    if (typeof value === "string") return value;
+    const record = getRecord(value);
+    const type = getString(record.type, "");
+    const rate = typeof record.rate === "number" ? record.rate : undefined;
+    return type ? { type, ...(rate ? { rate } : {}) } : null;
+}
+
+export function openAIRealtimeAudioFormat(profile: PhoneMediaProfile) {
+    return profile.openAIFormat === "audio/pcmu"
+        ? { type: "audio/pcmu" }
+        : { type: "audio/pcm", rate: profile.openAISampleRate };
+}
+
+export function realtimeAudioFormatForRoute(route: PhoneAudioRoute) {
+    return route.aiInput.format === "audio/pcmu"
+        ? { type: "audio/pcmu" }
+        : { type: "audio/pcm", rate: route.aiInput.sampleRate };
+}
+
+export function realtimeOutputAudioFormatForRoute(route: PhoneAudioRoute) {
+    return route.aiOutput.format === "audio/pcmu"
+        ? { type: "audio/pcmu" }
+        : { type: "audio/pcm", rate: route.aiOutput.sampleRate };
+}
+
+export function isOpenAIRealtimeAudioReady(event: unknown, profile: PhoneMediaProfile = getPhoneMediaProfile("twilio-pcmu-8k")) {
+    const record = getRecord(event);
+    if (record.type !== "session.updated") return false;
+
+    const audio = getRecord(getRecord(record.session).audio);
+    const inputFormat = summarizeOpenAIAudioFormat(getRecord(audio.input).format);
+    const outputFormat = summarizeOpenAIAudioFormat(getRecord(audio.output).format);
+    const inputRecord = getRecord(inputFormat);
+    const outputRecord = getRecord(outputFormat);
+    const expected = openAIRealtimeAudioFormat(profile);
+    const expectedType = expected.type;
+    const expectedRate = "rate" in expected ? expected.rate : undefined;
+    const inputType = typeof inputFormat === "string" ? inputFormat : getString(inputRecord.type, "");
+    const outputType = typeof outputFormat === "string" ? outputFormat : getString(outputRecord.type, "");
+    const inputRate = typeof inputRecord.rate === "number" ? inputRecord.rate : undefined;
+    const outputRate = typeof outputRecord.rate === "number" ? outputRecord.rate : undefined;
+
+    if (inputType !== expectedType || outputType !== expectedType) return false;
+    if (expectedRate && inputRate && inputRate !== expectedRate) return false;
+    if (expectedRate && outputRate && outputRate !== expectedRate) return false;
+    return true;
+}
+
+export function isRealtimeAudioReadyForRoute(event: unknown, route: PhoneAudioRoute) {
+    const record = getRecord(event);
+    if (record.type !== "session.updated") return false;
+
+    const audio = getRecord(getRecord(record.session).audio);
+    const inputFormat = summarizeOpenAIAudioFormat(getRecord(audio.input).format);
+    const outputFormat = summarizeOpenAIAudioFormat(getRecord(audio.output).format);
+    const inputRecord = getRecord(inputFormat);
+    const outputRecord = getRecord(outputFormat);
+    const expectedInput = realtimeAudioFormatForRoute(route);
+    const expectedOutput = realtimeOutputAudioFormatForRoute(route);
+    const inputType = typeof inputFormat === "string" ? inputFormat : getString(inputRecord.type, "");
+    const outputType = typeof outputFormat === "string" ? outputFormat : getString(outputRecord.type, "");
+    const inputRate = typeof inputRecord.rate === "number" ? inputRecord.rate : undefined;
+    const outputRate = typeof outputRecord.rate === "number" ? outputRecord.rate : undefined;
+
+    if (inputType !== expectedInput.type || outputType !== expectedOutput.type) return false;
+    if ("rate" in expectedInput && inputRate && inputRate !== expectedInput.rate) return false;
+    if ("rate" in expectedOutput && outputRate && outputRate !== expectedOutput.rate) return false;
+    return true;
+}
+
+export function createCarrierMediaMessage(profile: PhoneMediaProfile, streamSid: string | null, payload: string) {
+    if (profile.provider === "telnyx") {
+        return { event: "media", media: { payload } };
+    }
+    if (profile.provider === "sip") {
+        return { event: "media", streamSid: streamSid ?? "sip", media: { payload } };
+    }
+    if (!streamSid) return null;
+    return {
+        event: "media",
+        streamSid,
+        media: { payload },
+    };
+}
+
+export function createCarrierMarkMessage(profile: PhoneMediaProfile, streamSid: string | null, markName: string) {
+    if (profile.provider === "telnyx") {
+        return { event: "mark", mark: { name: markName } };
+    }
+    if (profile.provider === "sip") {
+        return { event: "mark", streamSid: streamSid ?? "sip", mark: { name: markName } };
+    }
+    if (!streamSid) return null;
+    return {
+        event: "mark",
+        streamSid,
+        mark: { name: markName },
+    };
+}
+
+export function createCarrierClearMessage(profile: PhoneMediaProfile, streamSid: string | null) {
+    if (profile.provider === "telnyx") return { event: "clear" };
+    if (profile.provider === "sip") return { event: "clear", streamSid: streamSid ?? "sip" };
+    if (!streamSid) return null;
+    return { event: "clear", streamSid };
+}
+
+export interface CreateOpenAIPhoneRealtimeBridgeInput {
+    profile: PhoneMediaProfile;
+}
+
+export function createOpenAIPhoneRealtimeBridge(_input: CreateOpenAIPhoneRealtimeBridgeInput): never {
+    throw new Error("createOpenAIPhoneRealtimeBridge is hosted by the backend-cloud phone runtime in this release");
+}