@ariaflowagents/livekit-plugin-transport-twilio 0.9.0

package/dist/transport_adapter.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Twilio Media Streams Transport Adapter.
+ *
+ * Connects AriaFlow agents to Twilio Media Streams for telephony
+ * voice AI applications. Works in Cloudflare Workers, Node.js, and
+ * any runtime with WebSocket support.
+ *
+ * Twilio sends G.711 μ-law audio at 8kHz. This transport handles
+ * decoding, resampling to 24kHz, and integration with AriaFlow sessions.
+ */
+import type { TransportAdapterConfig } from '@ariaflow/livekit-plugin';
+import { TransportAdapter } from '@ariaflow/livekit-plugin';
+import { TwilioAudioInput } from './audio_input.js';
+import { TwilioAudioOutput } from './audio_output.js';
+import { TwilioTextOutput } from './text_output.js';
+/**
+ * Options for creating a Twilio transport adapter.
+ */
+export interface TwilioTransportOptions {
+    id?: string;
+    /**
+     * Callback to send messages to the WebSocket.
+     * The transport will format messages as Twilio Media Streams events.
+     */
+    send: (message: string) => void;
+}
+/**
+ * Transport adapter for Twilio Media Streams.
+ *
+ * This adapter bridges Twilio's Media Streams WebSocket protocol
+ * with AriaFlow's voice agent pipeline.
+ *
+ * Audio flow:
+ * - Inbound: Twilio → μ-law 8kHz → decode → resample to 24kHz → AriaFlow STT
+ * - Outbound: AriaFlow TTS → 24kHz → resample to 8kHz → μ-law encode → Twilio
+ *
+ * Usage in Cloudflare Workers:
+ * ```typescript
+ * export default {
+ *   async fetch(request, env) {
+ *     if (request.headers.get('Upgrade') === 'websocket') {
+ *       const pair = new WebSocketPair();
+ *       const [client, server] = Object.values(pair);
+ *
+ *       const transport = new TwilioTransportAdapter({
+ *         send: (msg) => server.send(msg),
+ *       });
+ *
+ *       server.accept();
+ *
+ *       // Handle incoming messages
+ *       server.addEventListener('message', (event) => {
+ *         const data = JSON.parse(event.data);
+ *         if (data.event === 'media') {
+ *           transport.audioInput.handleMediaEvent(data);
+ *         }
+ *       });
+ *
+ *       const { agent, sessionOptions } = createAriaFlowSession({...});
+ *       await sessionManager.startSession(transport, agent, sessionOptions);
+ *
+ *       return new Response(null, { status: 101, webSocket: client });
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare class TwilioTransportAdapter extends TransportAdapter {
+    readonly id: string;
+    readonly audioInput: TwilioAudioInput;
+    readonly audioOutput: TwilioAudioOutput;
+    readonly textOutput: TwilioTextOutput;
+    readonly config: TransportAdapterConfig;
+    private _isOpen;
+    private _streamSid;
+    constructor(options: TwilioTransportOptions);
+    /**
+     * Get the current Twilio stream SID.
+     */
+    get streamSid(): string;
+    get isOpen(): boolean;
+    close(): Promise<void>;
+    /**
+     * Handle an incoming message from Twilio.
+     * Call this for each WebSocket message received from Twilio.
+     *
+     * @param message - JSON string from Twilio Media Streams
+     */
+    handleMessage(message: string): void;
+    /**
+     * Send a clear event to Twilio (clears audio buffer).
+     */
+    clearAudio(): void;
+}
+//# sourceMappingURL=transport_adapter.d.ts.map

package/dist/transport_adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport_adapter.d.ts","sourceRoot":"","sources":["../src/transport_adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAEV,sBAAsB,EACvB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qBAAa,sBAAuB,SAAQ,gBAAgB;IAC1D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IACtC,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAC;IACxC,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;IAExC,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,UAAU,CAAc;gBAEpB,OAAO,EAAE,sBAAsB;IAkC3C;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,IAAI,MAAM,IAAI,OAAO,CAEpB;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B;;;;;OAKG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAyDpC;;OAEG;IACH,UAAU,IAAI,IAAI;CAGnB"}

package/dist/transport_adapter.js

@@ -0,0 +1,174 @@
+/**
+ * Twilio Media Streams Transport Adapter.
+ *
+ * Connects AriaFlow agents to Twilio Media Streams for telephony
+ * voice AI applications. Works in Cloudflare Workers, Node.js, and
+ * any runtime with WebSocket support.
+ *
+ * Twilio sends G.711 μ-law audio at 8kHz. This transport handles
+ * decoding, resampling to 24kHz, and integration with AriaFlow sessions.
+ */
+import { TransportAdapter } from '@ariaflow/livekit-plugin';
+import { TwilioAudioInput } from './audio_input.js';
+import { TwilioAudioOutput } from './audio_output.js';
+import { TwilioTextOutput } from './text_output.js';
+/**
+ * Transport adapter for Twilio Media Streams.
+ *
+ * This adapter bridges Twilio's Media Streams WebSocket protocol
+ * with AriaFlow's voice agent pipeline.
+ *
+ * Audio flow:
+ * - Inbound: Twilio → μ-law 8kHz → decode → resample to 24kHz → AriaFlow STT
+ * - Outbound: AriaFlow TTS → 24kHz → resample to 8kHz → μ-law encode → Twilio
+ *
+ * Usage in Cloudflare Workers:
+ * ```typescript
+ * export default {
+ *   async fetch(request, env) {
+ *     if (request.headers.get('Upgrade') === 'websocket') {
+ *       const pair = new WebSocketPair();
+ *       const [client, server] = Object.values(pair);
+ *
+ *       const transport = new TwilioTransportAdapter({
+ *         send: (msg) => server.send(msg),
+ *       });
+ *
+ *       server.accept();
+ *
+ *       // Handle incoming messages
+ *       server.addEventListener('message', (event) => {
+ *         const data = JSON.parse(event.data);
+ *         if (data.event === 'media') {
+ *           transport.audioInput.handleMediaEvent(data);
+ *         }
+ *       });
+ *
+ *       const { agent, sessionOptions } = createAriaFlowSession({...});
+ *       await sessionManager.startSession(transport, agent, sessionOptions);
+ *
+ *       return new Response(null, { status: 101, webSocket: client });
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export class TwilioTransportAdapter extends TransportAdapter {
+    id;
+    audioInput;
+    audioOutput;
+    textOutput;
+    config;
+    _isOpen = true;
+    _streamSid = '';
+    constructor(options) {
+        super();
+        this.id = options.id || `twilio-${crypto.randomUUID()}`;
+        // Twilio uses G.711 μ-law at 8kHz, but we resample to 24kHz internally
+        this.config = {
+            sampleRate: 24000, // Internal sample rate after resampling
+            numChannels: 1,
+            encoding: 'pcm_s16le',
+            samplesPerChannel: 2400, // 100ms at 24kHz
+        };
+        // Create I/O implementations
+        this.audioInput = new TwilioAudioInput();
+        this.audioOutput = new TwilioAudioOutput();
+        this.textOutput = new TwilioTextOutput();
+        // Wire up send callbacks with streamSid tracking
+        this.audioOutput.setSendCallback((message) => {
+            // Inject current streamSid into media events
+            const event = JSON.parse(message);
+            event.streamSid = this._streamSid;
+            options.send(JSON.stringify(event));
+        });
+        this.textOutput.setSendCallback((markName) => {
+            options.send(JSON.stringify({
+                event: 'mark',
+                streamSid: this._streamSid,
+                sequenceNumber: `${Date.now()}`,
+                mark: { name: markName },
+            }));
+        });
+    }
+    /**
+     * Get the current Twilio stream SID.
+     */
+    get streamSid() {
+        return this._streamSid;
+    }
+    get isOpen() {
+        return this._isOpen;
+    }
+    async close() {
+        if (!this._isOpen)
+            return;
+        this._isOpen = false;
+        await this.audioInput.close();
+        await this.audioOutput.close();
+        await this.textOutput.close();
+    }
+    /**
+     * Handle an incoming message from Twilio.
+     * Call this for each WebSocket message received from Twilio.
+     *
+     * @param message - JSON string from Twilio Media Streams
+     */
+    handleMessage(message) {
+        try {
+            const event = JSON.parse(message);
+            switch (event.event) {
+                case 'media':
+                    // Audio data
+                    this.audioInput.handleMediaEvent(event);
+                    break;
+                case 'connected':
+                    // Connection established
+                    console.log('[TwilioTransport] Connected to Twilio Media Streams');
+                    break;
+                case 'start':
+                    // Stream established - capture streamSid and ready to send audio
+                    this._streamSid = event.start?.streamSid || event.streamSid || '';
+                    console.log('[TwilioTransport] Stream started:', {
+                        streamSid: this._streamSid,
+                        callSid: event.start?.callSid,
+                        tracks: event.start?.tracks,
+                    });
+                    break;
+                case 'stop':
+                case 'disconnected':
+                    // Stream ended - flush remaining audio
+                    console.log('[TwilioTransport] Stream ended:', this._streamSid);
+                    this.audioInput.endCurrentStream();
+                    this._isOpen = false;
+                    this._streamSid = '';
+                    break;
+                case 'clear':
+                    // Clear audio buffer
+                    console.log('[TwilioTransport] Clear audio buffer requested');
+                    this.audioOutput.clearBuffer();
+                    break;
+                case 'mark':
+                    // Metadata mark from Twilio
+                    console.log('[TwilioTransport] Received mark:', event.mark?.name);
+                    break;
+                default:
+                    console.log('[TwilioTransport] Unknown event:', event.event);
+            }
+        }
+        catch (error) {
+            console.error('[TwilioTransport] Error handling message:', {
+                error: error instanceof Error ? error.message : String(error),
+                transportId: this.id,
+                timestamp: new Date().toISOString(),
+            });
+        }
+    }
+    /**
+     * Send a clear event to Twilio (clears audio buffer).
+     */
+    clearAudio() {
+        this.audioOutput.clearBuffer();
+    }
+}
+//# sourceMappingURL=transport_adapter.js.map

package/dist/transport_adapter.js.map

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

package/dist/twilio_protocol.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Twilio Media Streams protocol message types and handlers.
+ *
+ * Twilio's Media Streams API sends JSON events over WebSocket:
+ * - Media events: Audio data with base64 payload
+ * - Control events: connected, disconnected, started, stopped
+ * - Metadata: marks/custom events
+ *
+ * Reference: https://www.twilio.com/docs/voice/media-streams
+ */
+/**
+ * Twilio Media Streams event types.
+ */
+export type TwilioEventType = 'connected' | 'start' | 'media' | 'stop' | 'mark' | 'clear';
+/**
+ * Base interface for all Twilio events.
+ */
+export interface TwilioEvent {
+    event: TwilioEventType;
+    sequenceNumber?: string;
+    media?: {
+        track: string;
+        chunk: string;
+        timestamp: string;
+        payload: string;
+    };
+    start?: {
+        streamSid: string;
+        callSid: string;
+        tracks?: string[];
+        mediaFormat?: {
+            encoding: 'audio/x-mulaw' | 'mulaw';
+            sampleRate: 8000;
+            channels: 1;
+        };
+    };
+    mark?: {
+        name: string;
+    };
+    streamSid?: string;
+}
+/**
+ * Media event with audio data.
+ */
+export interface TwilioMediaEvent extends TwilioEvent {
+    event: 'media';
+    media: {
+        track: string;
+        chunk: string;
+        timestamp: string;
+        payload: string;
+    };
+}
+/**
+ * Connected event - stream established.
+ */
+export interface TwilioConnectedEvent extends TwilioEvent {
+    event: 'connected';
+    streamSid: string;
+    callSid: string;
+}
+/**
+ * Started event - media transmission began.
+ */
+export interface TwilioStartEvent extends TwilioEvent {
+    event: 'start';
+    start: {
+        streamSid: string;
+        callSid: string;
+        tracks?: string[];
+        mediaFormat?: {
+            encoding: 'audio/x-mulaw' | 'mulaw';
+            sampleRate: 8000;
+            channels: 1;
+        };
+    };
+    streamSid?: string;
+}
+/**
+ * Stopped event - media transmission ended.
+ */
+export interface TwilioStopEvent extends TwilioEvent {
+    event: 'stop';
+    streamSid: string;
+    callSid: string;
+}
+/**
+ * Mark event - custom metadata from TwiML.
+ */
+export interface TwilioMarkEvent extends TwilioEvent {
+    event: 'mark';
+    streamSid: string;
+    mark: {
+        name: string;
+    };
+}
+/**
+ * Clear event - clears buffered audio.
+ */
+export interface TwilioClearEvent extends TwilioEvent {
+    event: 'clear';
+    streamSid: string;
+}
+/**
+ * Parse a JSON message from Twilio Media Streams.
+ *
+ * @param message - Raw JSON string from WebSocket
+ * @returns Parsed Twilio event or null if invalid
+ */
+export declare function parseTwilioMessage(message: string): TwilioEvent | null;
+/**
+ * Check if an event is a media event with audio data.
+ */
+export declare function isMediaEvent(event: TwilioEvent): event is TwilioMediaEvent;
+/**
+ * Extract μ-law audio payload from a media event.
+ *
+ * @param event - Twilio media event
+ * @returns Base64-encoded μ-law audio data or null
+ */
+export declare function extractMediaPayload(event: TwilioMediaEvent): string | null;
+/**
+ * Create a clear message to send to Twilio (clears audio buffer).
+ */
+export declare function createClearMessage(): string;
+/**
+ * Create a mark message (adds metadata to the stream).
+ */
+export declare function createMarkMessage(name: string): string;
+//# sourceMappingURL=twilio_protocol.d.ts.map

package/dist/twilio_protocol.d.ts.map

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

package/dist/twilio_protocol.js

@@ -0,0 +1,74 @@
+/**
+ * Twilio Media Streams protocol message types and handlers.
+ *
+ * Twilio's Media Streams API sends JSON events over WebSocket:
+ * - Media events: Audio data with base64 payload
+ * - Control events: connected, disconnected, started, stopped
+ * - Metadata: marks/custom events
+ *
+ * Reference: https://www.twilio.com/docs/voice/media-streams
+ */
+/**
+ * Parse a JSON message from Twilio Media Streams.
+ *
+ * @param message - Raw JSON string from WebSocket
+ * @returns Parsed Twilio event or null if invalid
+ */
+export function parseTwilioMessage(message) {
+    try {
+        const event = JSON.parse(message);
+        // Validate event has required fields
+        if (!event.event) {
+            return null;
+        }
+        // Validate event type
+        const validEvents = ['connected', 'start', 'media', 'stop', 'mark', 'clear'];
+        if (!validEvents.includes(event.event)) {
+            return null;
+        }
+        return event;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if an event is a media event with audio data.
+ */
+export function isMediaEvent(event) {
+    return event.event === 'media' && event.media !== undefined && typeof event.media.payload === 'string';
+}
+/**
+ * Extract μ-law audio payload from a media event.
+ *
+ * @param event - Twilio media event
+ * @returns Base64-encoded μ-law audio data or null
+ */
+export function extractMediaPayload(event) {
+    if (event.media && event.media.payload) {
+        return event.media.payload;
+    }
+    return null;
+}
+/**
+ * Create a clear message to send to Twilio (clears audio buffer).
+ */
+export function createClearMessage() {
+    return JSON.stringify({
+        event: 'clear',
+        streamSid: '', // Will be filled by sender
+        sequenceNumber: `${Date.now()}`,
+    });
+}
+/**
+ * Create a mark message (adds metadata to the stream).
+ */
+export function createMarkMessage(name) {
+    return JSON.stringify({
+        event: 'mark',
+        streamSid: '', // Will be filled by sender
+        sequenceNumber: `${Date.now()}`,
+        mark: { name },
+    });
+}
+//# sourceMappingURL=twilio_protocol.js.map

package/dist/twilio_protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"twilio_protocol.js","sourceRoot":"","sources":["../src/twilio_protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA6GH;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAgB,CAAC;QAEjD,qCAAqC;QACrC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YACjB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,sBAAsB;QACtB,MAAM,WAAW,GAAsB,CAAC,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;QAChG,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;YACvC,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,KAAkB;IAC7C,OAAO,KAAK,CAAC,KAAK,KAAK,OAAO,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,KAAK,CAAC,OAAO,KAAK,QAAQ,CAAC;AACzG,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAuB;IACzD,IAAI,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QACvC,OAAO,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC;IAC7B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,KAAK,EAAE,OAAO;QACd,SAAS,EAAE,EAAE,EAAE,2BAA2B;QAC1C,cAAc,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,EAAE;KAChC,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,KAAK,EAAE,MAAM;QACb,SAAS,EAAE,EAAE,EAAE,2BAA2B;QAC1C,cAAc,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,EAAE;QAC/B,IAAI,EAAE,EAAE,IAAI,EAAE;KACf,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@ariaflowagents/livekit-plugin-transport-twilio",
+  "version": "0.9.0",
+  "description": "Twilio Media Streams transport adapter for AriaFlow agents. Works with Node.js, Bun, Deno, and any WebSocket-compatible runtime.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "example:echo": "tsx examples/echo_bot.ts",
+    "example:server": "tsx examples/standalone_server.ts",
+    "example:hono": "tsx examples/hono_server.ts"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@ariaflowagents/livekit-plugin": "workspace:*",
+    "@livekit/agents": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20241218.0",
+    "hono": "^4.6.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0",
+    "ws": "^8.18.0"
+  },
+  "keywords": [
+    "ariaflow",
+    "livekit",
+    "twilio",
+    "voice",
+    "transport"
+  ],
+  "license": "Apache-2.0"
+}