aillom-vox-client 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, Aillom Technologies
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,272 @@
+# 🎙️ AillomVox Public Client
+
+[![npm version](https://img.shields.io/npm/v/aillom-vox-client.svg)](https://www.npmjs.com/package/aillom-vox-client)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)](https://nodejs.org/)
+
+**The Enterprise-Grade Voice AI SDK.** 
+
+Build **Speech-to-Speech**, **Audio-to-Audio**, and **Realtime Multimodal** applications with a single, unified protocol. 
+Connect effortlessly to **OpenAI Realtime**, **Gemini Multimodal**, **AWS Nova**, **Qwen**, **Grok**, **UltraVox**, and **AillomVox** native models.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install aillom-vox-client
+```
+
+## 📚 Documentation
+- [**Quick Start (SDK)**](#-quick-start-sdk) - The modern way
+- [**Quick Start (WebSocket)**](#-quick-start-websocket) - The low-level way
+- [**Examples**](#-examples) - Ready-to-use client implementations
+- [**N8N Integration**](#-n8n-node) - Official AillomVox node for n8n
+- [**Client Tools**](#-client-tools) - Add custom UI controls to your AI
+- [**Voice Catalog**](docs/VOICES.md) - All voices across all providers
+- [**Asterisk Integration**](docs/ASTERISK.md) - Complete guide for Asterisk 23/SIP
+- [**Protocol Specification**](docs/PROTOCOL.md) - WebSocket messages and binary formats
+- [**Supported Providers**](docs/PROVIDERS.md) - AI models and configuration options
+- [**Troubleshooting**](docs/TROUBLESHOOTING.md) - Common errors and solutions
+
+---
+
+## 🚀 Key Features
+- **Unified API**: Switch between OpenAI, Gemini, and others by changing one string
+- **Real-Time Streaming**: Full-duplex WebSocket for sub-500ms latency
+- **65 Voices**: Full Inworld TTS 1.5 catalog across 15 languages
+- **Robust Audio**: Native PCM 16-bit at **8kHz**, **16kHz**, or **24kHz**
+- **Client Tools**: Add custom UI controls (hangup, alerts, navigation) to your AI
+- **15 Languages**: en, pt, es, fr, de, it, ja, zh, ko, hi, ar, ru, pl, nl, he
+- **Event Driven**: Simple event emitter (`audio`, `transcript`, `interrupt`)
+- **Enterprise Security**: Automatic key redaction and sanitized error messages
+
+---
+
+## 💰 Pricing & Performance
+
+Choose the tier that fits your budget. **AillomVox** is optimized for telephony and high-volume use cases.
+
+| Provider | Cost/Min | Tier | Recommended For |
+| :--- | :--- | :--- | :--- |
+| **AillomVox** | **$0.03** | 🚀 **Best Value** | High volume, Telephony, Support |
+| **Gemini** | $0.06 | Standard | Google Gemini 2.5 Flash. Multimodal |
+| **AWS** | $0.06 | Standard | AWS Nova Sonic 2. Enterprise |
+| **Qwen** | $0.06 | Standard | Alibaba Qwen Omni 3. Cost-effective |
+| **OpenAI** | $0.10 | Premium | GPT Realtime Mini. Logic-heavy |
+| **Grok** | $0.10 | Premium | Grok Beta. Witty personality |
+| **UltraVox** | $0.10 | Premium | High emotional intelligence |
+
+> **Why AillomVox?**  
+> Native optimized pipeline delivers **sub-500ms latency** and **8kHz support** at less than half the cost. Choose from **65 voices** with dynamic mid-conversation switching.
+
+---
+
+## 📱 Examples
+
+This repository contains multiple examples ranging from a minimal connection script to full-featured dashboards and creative use cases.
+
+| Folder | Level | Description |
+| :--- | :--- | :--- |
+| [`examples/01-basic`](./examples/01-basic) | ⭐ Beginner | Minimal HTML/JS implementation. Connects, sends defaults, streams audio. Perfect for understanding the core protocol. |
+| [`examples/02-advanced-dashboard`](./examples/02-advanced-dashboard) | ⭐⭐⭐ Expert | Full-featured UI with Dark Mode. Configures Voice, LLM Provider, Tools, and Visualizations. |
+| [`examples/03-smart-home`](./examples/03-smart-home) | ⭐⭐ Creative | A Smart Home Controller simulation. Use voice to "turn on lights" or "adjust temperature" via Tool Calling. |
+| [`examples/04-customer-support`](./examples/04-customer-support) | ⭐⭐ Industry | A CRM / Support Agent interface. Demonstrates integration with business data. |
+
+---
+
+## ⚡ Quick Start (SDK)
+
+The easiest way to connect to AillomVox.
+
+```typescript
+import { AillomVox } from 'aillom-vox-client';
+
+const client = new AillomVox({
+  apiKey: 'av_YOUR_KEY',
+  voice: 'Edward',
+  debug: true
+});
+
+client.on('transcript', (msg) => {
+  console.log(`[${msg.role}] ${msg.text}`);
+});
+
+client.on('audio', (chunk) => {
+  // Play chunk (ArrayBuffer)
+});
+
+await client.connect();
+```
+
+---
+
+## 🔌 Quick Start (WebSocket)
+
+If you prefer raw WebSockets (e.g. for Python, Go, or minimal JS):
+
+```javascript
+const ws = new WebSocket("wss://vox.aillom.com/ws");
+
+ws.onopen = () => {
+  ws.send(JSON.stringify({
+    type: "config",
+    apikey: "YOUR_API_KEY",
+    provider: "aillomvox",
+    voice: "Edward"
+  }));
+};
+
+ws.onmessage = (event) => {
+  if (event.data instanceof ArrayBuffer) {
+    playAudio(event.data);
+  }
+};
+```
+
+---
+
+## 🎤 Voices
+
+AillomVox uses **Inworld TTS 1.5** with 65 voices across 15 languages. See the full [Voice Catalog](docs/VOICES.md).
+
+### Top Picks
+
+| Voice | Gender | Style | Best For |
+| :--- | :--- | :--- | :--- |
+| **Edward** | Male | Fast-talking, emphatic | General purpose (default EN) |
+| **Julia** | Female | Quirky, playful | Customer support |
+| **Heitor** | Male | Composed, neutral | Portuguese (default PT) |
+| **Maitê** | Female | Professional | Portuguese |
+| **Ashley** | Female | Warm, natural | Sales, onboarding |
+| **Craig** | Male | Refined, articulate | Enterprise, authority |
+| **Diego** | Male | Soothing, gentle | Spanish (default ES) |
+| **Luna** | Female | Calm, relaxing | Wellness, concierge |
+
+---
+
+## 🛠️ Client Tools
+
+**Client Tools** allow the AI to control your application's UI directly. When the AI decides to execute a tool, your app receives a callback and can respond.
+
+### Registering Tools
+
+```javascript
+{
+    "provider": "aillomvox",
+    "voice": "Edward",
+    "tools": [
+        {
+            "name": "hangup",
+            "description": "End the call when user says goodbye.",
+            "parameters": { "type": "object", "properties": {} }
+        },
+        {
+            "name": "show_alert",
+            "description": "Show alert to user",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "message": { "type": "string", "description": "Alert message" }
+                },
+                "required": ["message"]
+            }
+        }
+    ]
+}
+```
+
+### Handling Tool Calls (Client-Side)
+
+```javascript
+socket.onmessage = (event) => {
+    if (typeof event.data !== 'string') return;
+    const msg = JSON.parse(event.data);
+    
+    if (msg.type === 'tool_call') {
+        console.log(`Tool requested: ${msg.name}`, msg.args);
+        
+        let result = 'OK';
+        if (msg.name === 'hangup') {
+            disconnect();
+            result = 'Call ended';
+        } else if (msg.name === 'show_alert') {
+            alert(msg.args.message);
+            result = 'Alert displayed';
+        }
+
+        // Always respond — AI waits for this (15s timeout)
+        socket.send(JSON.stringify({
+            type: 'tool_result',
+            call_id: msg.call_id,
+            result: result
+        }));
+    }
+};
+```
+
+---
+
+## 🔧 Advanced Configuration
+
+### Audio Formats
+
+```javascript
+{
+    sample_rate: 16000,  // 8000 (telephony), 16000 (standard), 24000 (high-quality)
+    // Audio is PCM 16-bit little-endian Mono
+}
+```
+
+### Session Limits
+
+```javascript
+{
+    max_duration: 300,  // 1-3600 seconds (default: 300 = 5 minutes)
+}
+```
+
+At 15 seconds remaining, the AI will say the `farewell_message`. At 0 seconds, the connection closes.
+
+### Multi-Language Support
+
+```javascript
+{
+    language: 'pt-BR',
+    voice: 'Heitor',  // or 'Maitê' for female
+    system_prompt: 'Você é um assistente da Aillom. Seja conciso.',
+    first_message: 'Olá! Como posso ajudar?',
+    farewell_message: 'Obrigado por ligar. Até logo!'
+}
+```
+
+Supported: `en-US`, `pt-BR`, `es-ES`, `fr-FR`, `de-DE`, `it-IT`, `ja-JP`, `ko-KR`, `zh-CN`, `hi-IN`, `ar-SA`, `ru-RU`, `pl-PL`, `nl-NL`, `he-IL`
+
+---
+
+## 🛡️ Security & Limits
+
+### Automatic Sanitization
+- All error messages are stripped of sensitive data
+- API keys are never exposed in logs
+- Client cannot access server-side resources
+
+### Rate Limits
+- **Concurrent**: 3 connections per user, 2 per API key
+- **Max Duration**: 1-60 minutes per call
+- **Default**: 5 minutes per session
+- **Behavior**: Warning at 15s remaining, force disconnect at 0s
+
+---
+
+## 🤝 Support
+
+- **Documentation**: [https://vox.aillom.com/docs](https://vox.aillom.com/docs)
+- **Issues**: [GitHub Issues](https://github.com/aillom/aillom-vox-client/issues)
+- **Email**: contato@aillom.com.br
+
+---
+
+## 📄 License
+
+ISC © Aillom Technologies

package/dist/AillomVox.d.ts

@@ -0,0 +1,36 @@
+import { AillomVoxConfig, TranscriptEvent, ToolCallEvent } from './types';
+export declare class AillomVox {
+    private ws;
+    private config;
+    private eventListeners;
+    private isConnected;
+    private url;
+    constructor(config: AillomVoxConfig);
+    /**
+     * Connects to the AillomVox Gateway
+     */
+    connect(): Promise<void>;
+    /**
+     * Sends audio chunk (PCM 16-bit) to the AI
+     */
+    sendAudio(chunk: ArrayBuffer | Int16Array | Buffer): void;
+    /**
+     * Sends a tool result back to the AI
+     */
+    sendToolResult(callId: string, result: any): void;
+    /**
+     * Disconnects the session
+     */
+    disconnect(): void;
+    /**
+     * Subscribes to an event
+     */
+    on(event: 'audio', handler: (data: ArrayBuffer) => void): void;
+    on(event: 'transcript', handler: (data: TranscriptEvent) => void): void;
+    on(event: 'tool_call', handler: (data: ToolCallEvent) => void): void;
+    on(event: 'error', handler: (error: any) => void): void;
+    on(event: 'connected' | 'disconnected' | 'interruption', handler: (data: any) => void): void;
+    private sendConfig;
+    private handleMessage;
+    private emit;
+}

package/dist/AillomVox.js

@@ -0,0 +1,152 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AillomVox = void 0;
+const isomorphic_ws_1 = __importDefault(require("isomorphic-ws"));
+class AillomVox {
+    constructor(config) {
+        this.ws = null;
+        this.eventListeners = new Map();
+        this.isConnected = false;
+        this.url = 'wss://vox.aillom.com/ws';
+        this.config = config;
+        if (!this.config.apiKey) {
+            throw new Error('AillomVox: apiKey is required');
+        }
+    }
+    /**
+     * Connects to the AillomVox Gateway
+     */
+    connect() {
+        return new Promise((resolve, reject) => {
+            try {
+                this.ws = new isomorphic_ws_1.default(this.url);
+                this.ws.binaryType = 'arraybuffer';
+                this.ws.onopen = () => {
+                    this.isConnected = true;
+                    this.sendConfig();
+                    this.emit('connected', {});
+                    resolve();
+                };
+                this.ws.onmessage = (event) => {
+                    this.handleMessage(event);
+                };
+                this.ws.onerror = (error) => {
+                    this.emit('error', error);
+                    if (!this.isConnected)
+                        reject(error);
+                };
+                this.ws.onclose = (event) => {
+                    this.isConnected = false;
+                    this.emit('disconnected', { code: event.code, reason: event.reason });
+                };
+            }
+            catch (err) {
+                reject(err);
+            }
+        });
+    }
+    /**
+     * Sends audio chunk (PCM 16-bit) to the AI
+     */
+    sendAudio(chunk) {
+        if (!this.ws || this.ws.readyState !== isomorphic_ws_1.default.OPEN)
+            return;
+        this.ws.send(chunk);
+    }
+    /**
+     * Sends a tool result back to the AI
+     */
+    sendToolResult(callId, result) {
+        if (!this.ws || this.ws.readyState !== isomorphic_ws_1.default.OPEN)
+            return;
+        this.ws.send(JSON.stringify({
+            type: 'tool_result',
+            call_id: callId,
+            result: result
+        }));
+    }
+    /**
+     * Disconnects the session
+     */
+    disconnect() {
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+            this.isConnected = false;
+        }
+    }
+    on(event, handler) {
+        if (!this.eventListeners.has(event)) {
+            this.eventListeners.set(event, []);
+        }
+        this.eventListeners.get(event)?.push(handler);
+    }
+    sendConfig() {
+        if (!this.ws)
+            return;
+        const payload = {
+            type: 'config',
+            apikey: this.config.apiKey,
+            provider: this.config.provider || 'aillomvox',
+            voice: this.config.voice || 'Edward',
+            language: this.config.language || 'en-US',
+            sample_rate: this.config.sampleRate || 16000,
+            system_prompt: this.config.systemPrompt,
+            tools: this.config.tools,
+            webhook_url: this.config.webhookUrl,
+            max_duration: this.config.maxDuration
+        };
+        if (this.config.debug) {
+            console.log('[AillomVox] Sending config:', JSON.stringify(payload, null, 2));
+        }
+        this.ws.send(JSON.stringify(payload));
+    }
+    handleMessage(event) {
+        const data = event.data;
+        // Handle Binary Audio
+        if (data instanceof ArrayBuffer || (typeof Buffer !== 'undefined' && Buffer.isBuffer(data))) {
+            this.emit('audio', data);
+            return;
+        }
+        // Handle JSON Control Messages
+        if (typeof data === 'string') {
+            try {
+                const msg = JSON.parse(data);
+                switch (msg.type) {
+                    case 'transcript':
+                        this.emit('transcript', msg);
+                        break;
+                    case 'tool_call':
+                        this.emit('tool_call', msg);
+                        break;
+                    case 'error':
+                        this.emit('error', msg);
+                        break;
+                    case 'interruption':
+                        this.emit('interruption', {});
+                        break;
+                    case 'hangup':
+                        this.disconnect();
+                        this.emit('disconnected', { reason: 'agent_hangup' });
+                        break;
+                    default:
+                        if (this.config.debug)
+                            console.log('[AillomVox] Data:', msg);
+                }
+            }
+            catch (e) {
+                console.error('[AillomVox] Failed to parse message:', e);
+            }
+        }
+    }
+    emit(event, data) {
+        const listeners = this.eventListeners.get(event);
+        if (listeners) {
+            listeners.forEach(handler => handler(data));
+        }
+    }
+}
+exports.AillomVox = AillomVox;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './AillomVox';

package/dist/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./AillomVox"), exports);

package/dist/types.d.ts

@@ -0,0 +1,36 @@
+export type ProviderType = 'aillomvox' | 'gemini' | 'openai' | 'aws' | 'qwen' | 'grok' | 'ultravox';
+export interface MicrophoneConfig {
+    sampleRate?: 8000 | 16000 | 24000;
+    inputSampleRate?: number;
+}
+export interface ClientTool {
+    name: string;
+    description: string;
+    parameters: Record<string, any>;
+}
+export interface AillomVoxConfig {
+    apiKey: string;
+    provider?: ProviderType;
+    voice?: string;
+    language?: string;
+    systemPrompt?: string;
+    sampleRate?: 8000 | 16000 | 24000;
+    debug?: boolean;
+    tools?: ClientTool[];
+    webhookUrl?: string;
+    maxDuration?: number;
+}
+export interface TranscriptEvent {
+    role: 'user' | 'assistant';
+    text: string;
+    final: boolean;
+}
+export interface ToolCallEvent {
+    call_id: string;
+    name: string;
+    args: any;
+}
+export interface AudioEvent {
+    buffer: ArrayBuffer;
+}
+export type EventHandler<T = any> = (data: T) => void;

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });