@kognitivedev/voice-media-bridge 0.2.29

package/src/profiles.ts

@@ -0,0 +1,135 @@
+export type PhoneMediaProvider = "twilio" | "telnyx" | "sip";
+export type PhoneMediaProfileId = "twilio-pcmu-8k" | "telnyx-pcmu-8k" | "telnyx-l16-16k" | "sip-pcmu-8k";
+export type PhoneMediaCodecPreference = "auto" | "l16_16k" | "pcmu_8k";
+export type PhoneMediaL16ByteOrder = "be" | "le";
+
+export interface PhoneMediaProfile {
+    id: PhoneMediaProfileId;
+    provider: PhoneMediaProvider;
+    codec: "pcmu" | "l16";
+    carrierCodec: "PCMU" | "L16";
+    carrierSampleRate: 8000 | 16000;
+    carrierByteOrder?: PhoneMediaL16ByteOrder;
+    openAIFormat: "audio/pcmu" | "audio/pcm";
+    openAISampleRate: 8000 | 24000;
+    source: "auto" | "forced" | "fallback";
+}
+
+export interface PhoneMediaFallbackState {
+    forcePcmu?: boolean;
+}
+
+export interface ResolvePhoneMediaProfileInput {
+    provider: PhoneMediaProvider;
+    requestedCodec?: PhoneMediaCodecPreference | string | null;
+    l16ByteOrder?: PhoneMediaL16ByteOrder | string | null;
+    fallbackState?: PhoneMediaFallbackState | null;
+}
+
+const TWILIO_PCMU_8K: PhoneMediaProfile = {
+    id: "twilio-pcmu-8k",
+    provider: "twilio",
+    codec: "pcmu",
+    carrierCodec: "PCMU",
+    carrierSampleRate: 8000,
+    openAIFormat: "audio/pcmu",
+    openAISampleRate: 8000,
+    source: "forced",
+};
+
+const TELNYX_PCMU_8K: PhoneMediaProfile = {
+    id: "telnyx-pcmu-8k",
+    provider: "telnyx",
+    codec: "pcmu",
+    carrierCodec: "PCMU",
+    carrierSampleRate: 8000,
+    openAIFormat: "audio/pcmu",
+    openAISampleRate: 8000,
+    source: "forced",
+};
+
+const TELNYX_L16_16K: PhoneMediaProfile = {
+    id: "telnyx-l16-16k",
+    provider: "telnyx",
+    codec: "l16",
+    carrierCodec: "L16",
+    carrierSampleRate: 16000,
+    carrierByteOrder: "le",
+    openAIFormat: "audio/pcm",
+    openAISampleRate: 24000,
+    source: "auto",
+};
+
+const SIP_PCMU_8K: PhoneMediaProfile = {
+    id: "sip-pcmu-8k",
+    provider: "sip",
+    codec: "pcmu",
+    carrierCodec: "PCMU",
+    carrierSampleRate: 8000,
+    openAIFormat: "audio/pcmu",
+    openAISampleRate: 8000,
+    source: "forced",
+};
+
+export function getPhoneMediaProfile(id: PhoneMediaProfileId): PhoneMediaProfile {
+    switch (id) {
+        case "twilio-pcmu-8k":
+            return { ...TWILIO_PCMU_8K };
+        case "telnyx-pcmu-8k":
+            return { ...TELNYX_PCMU_8K };
+        case "telnyx-l16-16k":
+            return { ...TELNYX_L16_16K };
+        case "sip-pcmu-8k":
+            return { ...SIP_PCMU_8K };
+    }
+}
+
+export function normalizePhoneMediaCodecPreference(value: unknown): PhoneMediaCodecPreference {
+    if (value === "l16_16k" || value === "pcmu_8k" || value === "auto") return value;
+    if (value === "L16" || value === "l16" || value === "telnyx-l16-16k") return "l16_16k";
+    if (value === "PCMU" || value === "pcmu" || value === "telnyx-pcmu-8k" || value === "twilio-pcmu-8k") return "pcmu_8k";
+    return "auto";
+}
+
+export function normalizePhoneMediaL16ByteOrder(value: unknown): PhoneMediaL16ByteOrder {
+    return value === "le" || value === "little" || value === "little-endian" ? "le" : "be";
+}
+
+function resolveL16ByteOrder(value: unknown, fallback: PhoneMediaL16ByteOrder): PhoneMediaL16ByteOrder {
+    return value === undefined || value === null || value === "" ? fallback : normalizePhoneMediaL16ByteOrder(value);
+}
+
+export function resolvePhoneMediaProfile(input: ResolvePhoneMediaProfileInput): PhoneMediaProfile {
+    if (input.provider === "twilio") return getPhoneMediaProfile("twilio-pcmu-8k");
+    if (input.provider === "sip") return getPhoneMediaProfile("sip-pcmu-8k");
+
+    const requested = normalizePhoneMediaCodecPreference(input.requestedCodec);
+    if (input.fallbackState?.forcePcmu) {
+        return { ...getPhoneMediaProfile("telnyx-pcmu-8k"), source: "fallback" };
+    }
+    if (requested === "pcmu_8k") {
+        return { ...getPhoneMediaProfile("telnyx-pcmu-8k"), source: "forced" };
+    }
+    if (requested === "l16_16k") {
+        const profile = getPhoneMediaProfile("telnyx-l16-16k");
+        return {
+            ...profile,
+            carrierByteOrder: resolveL16ByteOrder(input.l16ByteOrder, profile.carrierByteOrder ?? "le"),
+            source: "forced",
+        };
+    }
+    return { ...getPhoneMediaProfile("telnyx-pcmu-8k"), source: "auto" };
+}
+
+export function phoneMediaProfileMetadata(profile: PhoneMediaProfile) {
+    return {
+        id: profile.id,
+        provider: profile.provider,
+        codec: profile.carrierCodec,
+        sampleRate: profile.carrierSampleRate,
+        ...(profile.carrierByteOrder ? { byteOrder: profile.carrierByteOrder } : {}),
+        openAIFormat: profile.openAIFormat,
+        openAISampleRate: profile.openAISampleRate,
+        source: profile.source,
+    };
+}

package/src/routes.ts

@@ -0,0 +1,139 @@
+import {
+    getPhoneMediaProfile,
+    phoneMediaProfileMetadata,
+    resolvePhoneMediaProfile,
+    type PhoneMediaFallbackState,
+    type PhoneMediaL16ByteOrder,
+    type PhoneMediaProfile,
+    type PhoneMediaProvider,
+} from "./profiles";
+
+export type PhoneAiProvider = "openai-realtime" | "xai-realtime" | "gemini-live";
+export type PhoneAudioCodec = "pcmu" | "pcm";
+export type PhoneAudioFormat = "audio/pcmu" | "audio/pcm";
+
+export interface PhoneAiAudioLeg {
+    codec: PhoneAudioCodec;
+    format: PhoneAudioFormat;
+    sampleRate: 8000 | 16000 | 24000;
+    mimeType: string;
+}
+
+export interface PhoneAudioRoute {
+    id: string;
+    carrierProvider: PhoneMediaProvider;
+    aiProvider: PhoneAiProvider;
+    carrier: PhoneMediaProfile;
+    aiInput: PhoneAiAudioLeg;
+    aiOutput: PhoneAiAudioLeg;
+    inputTranscoding: "none" | "decode-resample";
+    outputTranscoding: "none" | "resample-encode";
+    stable: boolean;
+}
+
+export interface ResolvePhoneAudioRouteInput {
+    carrierProvider: PhoneMediaProvider;
+    aiProvider: PhoneAiProvider | string | null | undefined;
+    requestedCodec?: string | null;
+    l16ByteOrder?: PhoneMediaL16ByteOrder | string | null;
+    fallbackState?: PhoneMediaFallbackState | null;
+}
+
+function normalizeAiProvider(value: unknown): PhoneAiProvider {
+    return value === "xai-realtime" || value === "gemini-live" ? value : "openai-realtime";
+}
+
+function pcmLeg(sampleRate: 16000 | 24000): PhoneAiAudioLeg {
+    return {
+        codec: "pcm",
+        format: "audio/pcm",
+        sampleRate,
+        mimeType: `audio/pcm;rate=${sampleRate}`,
+    };
+}
+
+const PCMU_LEG: PhoneAiAudioLeg = {
+    codec: "pcmu",
+    format: "audio/pcmu",
+    sampleRate: 8000,
+    mimeType: "audio/pcmu",
+};
+
+function resolveAiLegs(aiProvider: PhoneAiProvider, carrier: PhoneMediaProfile) {
+    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,
+    };
+}
+
+export function createPhoneAudioRoute(carrier: PhoneMediaProfile, aiProviderInput: PhoneAiProvider | string | null | undefined): PhoneAudioRoute {
+    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",
+    };
+}
+
+export function resolvePhoneAudioRoute(input: ResolvePhoneAudioRouteInput): PhoneAudioRoute {
+    const carrier = resolvePhoneMediaProfile({
+        provider: input.carrierProvider,
+        requestedCodec: input.requestedCodec,
+        l16ByteOrder: input.l16ByteOrder,
+        fallbackState: input.fallbackState,
+    });
+    return createPhoneAudioRoute(carrier, input.aiProvider);
+}
+
+export function phoneAudioRouteMetadata(route: PhoneAudioRoute) {
+    return {
+        id: route.id,
+        carrierProvider: route.carrierProvider,
+        aiProvider: route.aiProvider,
+        carrier: phoneMediaProfileMetadata(route.carrier),
+        aiInput: route.aiInput,
+        aiOutput: route.aiOutput,
+        inputTranscoding: route.inputTranscoding,
+        outputTranscoding: route.outputTranscoding,
+        stable: route.stable,
+    };
+}
+
+export function getStableCarrierProfile(provider: PhoneMediaProvider): PhoneMediaProfile {
+    if (provider === "telnyx") return { ...getPhoneMediaProfile("telnyx-pcmu-8k"), source: "auto" };
+    return resolvePhoneMediaProfile({ provider, requestedCodec: "auto" });
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "module": "commonjs",
+    "rootDir": "src",
+    "outDir": "dist",
+    "declaration": true,
+    "noEmit": false,
+    "incremental": false
+  },
+  "include": ["src"],
+  "exclude": ["src/__tests__"]
+}