@hamsa-ai/voice-agents-sdk 0.4.0-beta.1 → 0.4.0-beta.2

package/README.md

@@ -40,7 +40,7 @@ Then, you can initialize the agent like this:
 const agent = new HamsaVoiceAgent("YOUR_API_KEY");
 
 agent.on("callStarted", () => {
-	console.log("Conversation has started!");
+  console.log("Conversation has started!");
 });
 
 // Example: Start a call
@@ -55,11 +55,19 @@ Start a conversation with an existing agent by calling the "start" function. You
 
 ```javascript
 agent.start({
-	agentId: YOUR_AGENT_ID,
-	params: {
-		param1: "NAME",
-		param2: "NAME2",
-	},
+  agentId: YOUR_AGENT_ID,
+  params: {
+    param1: "NAME",
+    param2: "NAME2",
+  },
+  voiceEnablement: true,
+  userId: "user-123", // Optional user tracking
+  preferHeadphonesForIosDevices: true, // iOS audio optimization
+  connectionDelay: {
+    android: 3000, // 3 second delay for Android
+    ios: 0,
+    default: 0,
+  },
 });
 ```
 
@@ -87,6 +95,135 @@ To end a conversation, simply call the "end" function:
 agent.end();
 ```
 
+## Advanced Audio Controls
+
+The SDK provides comprehensive audio control features for professional voice applications:
+
+### Volume Management
+
+```javascript
+// Set agent voice volume (0.0 to 1.0)
+agent.setVolume(0.8);
+
+// Get current output volume
+const currentVolume = agent.getOutputVolume();
+console.log(`Volume: ${Math.round(currentVolume * 100)}%`);
+
+// Get user microphone input level
+const inputLevel = agent.getInputVolume();
+if (inputLevel > 0.1) {
+  showUserSpeakingIndicator();
+}
+```
+
+### Microphone Control
+
+```javascript
+// Mute/unmute microphone
+agent.setMicMuted(true);  // Mute
+agent.setMicMuted(false); // Unmute
+
+// Check mute status
+if (agent.isMicMuted()) {
+  showUnmutePrompt();
+}
+
+// Toggle microphone
+const currentMuted = agent.isMicMuted();
+agent.setMicMuted(!currentMuted);
+
+// Listen for microphone events
+agent.on('micMuted', () => {
+  document.getElementById('micButton').classList.add('muted');
+});
+
+agent.on('micUnmuted', () => {
+  document.getElementById('micButton').classList.remove('muted');
+});
+```
+
+### Audio Visualization
+
+Create real-time audio visualizers using frequency data:
+
+```javascript
+// Input visualizer (user's microphone)
+function createInputVisualizer() {
+  const canvas = document.getElementById('inputVisualizer');
+  const ctx = canvas.getContext('2d');
+  
+  function draw() {
+    const frequencyData = agent.getInputByteFrequencyData();
+    
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
+    const barWidth = canvas.width / frequencyData.length;
+    
+    for (let i = 0; i < frequencyData.length; i++) {
+      const barHeight = (frequencyData[i] / 255) * canvas.height;
+      ctx.fillStyle = `hsl(${i * 2}, 70%, 60%)`;
+      ctx.fillRect(i * barWidth, canvas.height - barHeight, barWidth, barHeight);
+    }
+    
+    requestAnimationFrame(draw);
+  }
+  
+  draw();
+}
+
+// Output visualizer (agent's voice)
+function createOutputVisualizer() {
+  const canvas = document.getElementById('outputVisualizer');
+  const ctx = canvas.getContext('2d');
+  
+  agent.on('speaking', () => {
+    function draw() {
+      const frequencyData = agent.getOutputByteFrequencyData();
+      
+      if (frequencyData.length > 0) {
+        ctx.clearRect(0, 0, canvas.width, canvas.height);
+        
+        // Draw voice characteristics
+        for (let i = 0; i < frequencyData.length; i++) {
+          const barHeight = (frequencyData[i] / 255) * canvas.height;
+          ctx.fillStyle = `hsl(${240 + i}, 70%, 60%)`;
+          ctx.fillRect(i * 2, canvas.height - barHeight, 2, barHeight);
+        }
+        
+        requestAnimationFrame(draw);
+      }
+    }
+    draw();
+  });
+}
+```
+
+
+## Advanced Configuration Options
+
+### Platform-Specific Optimizations
+
+```javascript
+agent.start({
+  agentId: "your-agent-id",
+  
+  // Optimize audio for iOS devices
+  preferHeadphonesForIosDevices: true,
+  
+  // Platform-specific delays to prevent audio cutoff
+  connectionDelay: {
+    android: 3000, // Android needs longer delay for audio mode switching
+    ios: 500,      // Shorter delay for iOS
+    default: 1000  // Default for other platforms
+  },
+  
+  // Disable wake lock for battery optimization
+  disableWakeLock: false,
+  
+  // User tracking
+  userId: "customer-12345"
+});
+```
+
 ## Events
 
 During the conversation, the SDK emits events to update your application about the conversation status.
@@ -95,16 +232,16 @@ During the conversation, the SDK emits events to update your application about t
 
 ```javascript
 agent.on("callStarted", () => {
-	console.log("Conversation has started!");
+  console.log("Conversation has started!");
 });
 agent.on("callEnded", () => {
-	console.log("Conversation has ended!");
+  console.log("Conversation has ended!");
 });
 agent.on("callPaused", () => {
-	console.log("The conversation is paused");
+  console.log("The conversation is paused");
 });
 agent.on("callResumed", () => {
-	console.log("Conversation has resumed");
+  console.log("Conversation has resumed");
 });
 ```
 
@@ -112,10 +249,10 @@ agent.on("callResumed", () => {
 
 ```javascript
 agent.on("speaking", () => {
-	console.log("The agent is speaking");
+  console.log("The agent is speaking");
 });
 agent.on("listening", () => {
-	console.log("The agent is listening");
+  console.log("The agent is listening");
 });
 ```
 
@@ -123,10 +260,10 @@ agent.on("listening", () => {
 
 ```javascript
 agent.on("transcriptionReceived", (text) => {
-	console.log("User speech transcription received", text);
+  console.log("User speech transcription received", text);
 });
 agent.on("answerReceived", (text) => {
-	console.log("Agent answer received", text);
+  console.log("Agent answer received", text);
 });
 ```
 
@@ -134,10 +271,10 @@ agent.on("answerReceived", (text) => {
 
 ```javascript
 agent.on("closed", () => {
-	console.log("Conversation was closed");
+  console.log("Conversation was closed");
 });
 agent.on("error", (e) => {
-	console.log("Error was received", e);
+  console.log("Error was received", e);
 });
 ```
 
@@ -148,46 +285,46 @@ The SDK provides comprehensive analytics for monitoring call quality, performanc
 ```javascript
 // Real-time connection quality updates
 agent.on("connectionQualityChanged", ({ quality, participant, metrics }) => {
-	console.log(`Connection quality: ${quality}`, metrics);
+  console.log(`Connection quality: ${quality}`, metrics);
 });
 
 // Periodic analytics updates (every second during calls)
 agent.on("analyticsUpdated", (analytics) => {
-	console.log("Call analytics:", analytics);
-	// Contains: connectionStats, audioMetrics, performanceMetrics, etc.
+  console.log("Call analytics:", analytics);
+  // Contains: connectionStats, audioMetrics, performanceMetrics, etc.
 });
 
 // Participant events
 agent.on("participantConnected", (participant) => {
-	console.log("Participant joined:", participant.identity);
+  console.log("Participant joined:", participant.identity);
 });
 
 agent.on("participantDisconnected", (participant) => {
-	console.log("Participant left:", participant.identity);
+  console.log("Participant left:", participant.identity);
 });
 
 // Track subscription events (audio/video streams)
 agent.on("trackSubscribed", ({ track, participant, trackStats }) => {
-	console.log("New track:", track.kind, "from", participant);
+  console.log("New track:", track.kind, "from", participant);
 });
 
 agent.on("trackUnsubscribed", ({ track, participant }) => {
-	console.log("Track ended:", track.kind, "from", participant);
+  console.log("Track ended:", track.kind, "from", participant);
 });
 
 // Connection state changes
 agent.on("reconnecting", () => {
-	console.log("Attempting to reconnect...");
+  console.log("Attempting to reconnect...");
 });
 
 agent.on("reconnected", () => {
-	console.log("Successfully reconnected");
+  console.log("Successfully reconnected");
 });
 
 // Custom events from agents
 agent.on("customEvent", (eventType, eventData, metadata) => {
-	console.log(`Custom event: ${eventType}`, eventData);
-	// Examples: flow_navigation, tool_execution, agent_state_change
+  console.log(`Custom event: ${eventType}`, eventData);
+  // Examples: flow_navigation, tool_execution, agent_state_change
 });
 ```
 
@@ -195,6 +332,17 @@ agent.on("customEvent", (eventType, eventData, metadata) => {
 
 The SDK provides comprehensive real-time analytics for monitoring call quality, performance metrics, and custom agent events. Access analytics data through both synchronous methods and event-driven updates.
 
+### Analytics Architecture
+
+The SDK uses a clean modular design with four specialized components:
+
+- **Connection Management**: Handles room connections, participants, and network state
+- **Analytics Engine**: Processes WebRTC statistics and performance metrics
+- **Audio Management**: Manages audio tracks, volume control, and quality monitoring
+- **Tool Registry**: Handles RPC method registration and client-side tool execution
+
+Access analytics data through both synchronous methods and event-driven updates.
+
 ### Synchronous Analytics Methods
 
 Get real-time analytics data instantly for dashboards and monitoring:
@@ -278,16 +426,18 @@ const analytics = agent.getCallAnalytics();
 console.log(analytics);
 /*
 {
-  callDuration: 60000,
-  callStartTime: 1638360000000,
-  isConnected: true,
-  isPaused: false,
-  connectionStats: { ... },
-  audioMetrics: { ... },
-  performanceMetrics: { ... },
-  participants: [ ... ],
-  trackStats: { ... },
-  callStats: { ... }
+  connectionStats: { latency: 45, packetLoss: 0.1, quality: 'good', ... },
+  audioMetrics: { userAudioLevel: 0.8, agentAudioLevel: 0.3, ... },
+  performanceMetrics: { callDuration: 60000, responseTime: 1200, ... },
+  participants: [{ identity: 'agent', sid: 'participant-sid', ... }],
+  trackStats: { totalTracks: 2, activeTracks: 2, ... },
+  callStats: { connectionAttempts: 1, packetsLost: 0, ... },
+  metadata: {
+    callStartTime: 1638360000000,
+    isConnected: true,
+    isPaused: false,
+    volume: 1.0
+  }
 }
 */
 ```
@@ -299,25 +449,31 @@ Build live monitoring dashboards using the analytics data:
 ```javascript
 // Update dashboard every second
 const updateDashboard = () => {
-	const stats = agent.getConnectionStats();
-	const audio = agent.getAudioLevels();
-	const performance = agent.getPerformanceMetrics();
-	
-	// Update UI elements
-	document.getElementById('latency').textContent = `${stats.latency}ms`;
-	document.getElementById('quality').textContent = stats.quality;
-	document.getElementById('duration').textContent = `${Math.floor(performance.callDuration / 1000)}s`;
-	document.getElementById('user-audio').style.width = `${audio.userAudioLevel * 100}%`;
-	document.getElementById('agent-audio').style.width = `${audio.agentAudioLevel * 100}%`;
+  const stats = agent.getConnectionStats();
+  const audio = agent.getAudioLevels();
+  const performance = agent.getPerformanceMetrics();
+
+  // Update UI elements
+  document.getElementById("latency").textContent = `${stats.latency}ms`;
+  document.getElementById("quality").textContent = stats.quality;
+  document.getElementById("duration").textContent = `${Math.floor(
+    performance.callDuration / 1000
+  )}s`;
+  document.getElementById("user-audio").style.width = `${
+    audio.userAudioLevel * 100
+  }%`;
+  document.getElementById("agent-audio").style.width = `${
+    audio.agentAudioLevel * 100
+  }%`;
 };
 
 // Start dashboard updates when call begins
-agent.on('callStarted', () => {
-	const dashboardInterval = setInterval(updateDashboard, 1000);
-	
-	agent.on('callEnded', () => {
-		clearInterval(dashboardInterval);
-	});
+agent.on("callStarted", () => {
+  const dashboardInterval = setInterval(updateDashboard, 1000);
+
+  agent.on("callEnded", () => {
+    clearInterval(dashboardInterval);
+  });
 });
 ```
 
@@ -327,30 +483,40 @@ Track custom events from your voice agents:
 
 ```javascript
 agent.on("customEvent", (eventType, eventData, metadata) => {
-	switch(eventType) {
-		case "flow_navigation":
-			console.log("Agent navigated:", eventData.from, "->", eventData.to);
-			// Track conversation flow
-			break;
-			
-		case "tool_execution":
-			console.log("Tool called:", eventData.toolName, "Result:", eventData.success);
-			// Monitor tool usage
-			break;
-			
-		case "agent_state_change":
-			console.log("Agent state:", eventData.state);
-			// Track agent behavior
-			break;
-			
-		case "user_intent_detected":
-			console.log("User intent:", eventData.intent, "Confidence:", eventData.confidence);
-			// Analyze user intent
-			break;
-			
-		default:
-			console.log("Custom event:", eventType, eventData);
-	}
+  switch (eventType) {
+    case "flow_navigation":
+      console.log("Agent navigated:", eventData.from, "->", eventData.to);
+      // Track conversation flow
+      break;
+
+    case "tool_execution":
+      console.log(
+        "Tool called:",
+        eventData.toolName,
+        "Result:",
+        eventData.success
+      );
+      // Monitor tool usage
+      break;
+
+    case "agent_state_change":
+      console.log("Agent state:", eventData.state);
+      // Track agent behavior
+      break;
+
+    case "user_intent_detected":
+      console.log(
+        "User intent:",
+        eventData.intent,
+        "Confidence:",
+        eventData.confidence
+      );
+      // Analyze user intent
+      break;
+
+    default:
+      console.log("Custom event:", eventType, eventData);
+  }
 });
 ```
 
@@ -360,7 +526,7 @@ The SDK accepts optional configuration parameters:
 
 ```javascript
 const agent = new HamsaVoiceAgent("YOUR_API_KEY", {
-	API_URL: "https://api.tryhamsa.com", // API endpoint (default)
+  API_URL: "https://api.tryhamsa.com", // API endpoint (default)
 });
 ```
 
@@ -370,29 +536,29 @@ You can register client-side tools that the agent can call during conversations:
 
 ```javascript
 const tools = [
-	{
-		function_name: "getUserInfo",
-		description: "Get user information",
-		parameters: [
-			{
-				name: "userId",
-				type: "string",
-				description: "User ID to look up",
-			},
-		],
-		required: ["userId"],
-		fn: async (userId) => {
-			// Your tool implementation
-			const userInfo = await fetchUserInfo(userId);
-			return userInfo;
-		},
-	},
+  {
+    function_name: "getUserInfo",
+    description: "Get user information",
+    parameters: [
+      {
+        name: "userId",
+        type: "string",
+        description: "User ID to look up",
+      },
+    ],
+    required: ["userId"],
+    fn: async (userId) => {
+      // Your tool implementation
+      const userInfo = await fetchUserInfo(userId);
+      return userInfo;
+    },
+  },
 ];
 
 agent.start({
-	agentId: "YOUR_AGENT_ID",
-	tools: tools,
-	voiceEnablement: true,
+  agentId: "YOUR_AGENT_ID",
+  tools: tools,
+  voiceEnablement: true,
 });
 ```
 
@@ -404,69 +570,131 @@ If you're upgrading from a previous version, see the [Migration Guide](./MIGRATI
 
 This SDK supports modern browsers with WebRTC capabilities:
 
--   Chrome 60+
--   Firefox 60+
--   Safari 12+
--   Edge 79+
+- Chrome 60+
+- Firefox 60+
+- Safari 12+
+- Edge 79+
 
 ## TypeScript Support
 
 The SDK includes comprehensive TypeScript definitions with detailed analytics interfaces:
 
 ```typescript
-import { HamsaVoiceAgent } from "@hamsa-ai/voice-agents-sdk";
+import {
+  HamsaVoiceAgent,
+  CallAnalyticsResult,
+  ParticipantData,
+  CustomEventMetadata,
+} from "@hamsa-ai/voice-agents-sdk";
 
 // All analytics methods return strongly typed data
 const agent = new HamsaVoiceAgent("API_KEY");
 
-// TypeScript will provide autocomplete and type checking
-agent.on("analyticsUpdated", (analytics: CallAnalytics) => {
-    console.log(analytics.connectionStats.latency); // number
-    console.log(analytics.audioMetrics.userAudioLevel); // number
-    console.log(analytics.performanceMetrics.callDuration); // number
+// TypeScript will provide full autocomplete and type checking for all methods
+const connectionStats = agent.getConnectionStats(); // ConnectionStatsResult | null
+const audioLevels = agent.getAudioLevels(); // AudioLevelsResult | null
+const performance = agent.getPerformanceMetrics(); // PerformanceMetricsResult | null
+const participants = agent.getParticipants(); // ParticipantData[]
+const trackStats = agent.getTrackStats(); // TrackStatsResult | null
+const analytics = agent.getCallAnalytics(); // CallAnalyticsResult | null
+
+// Advanced audio control methods
+const outputVolume = agent.getOutputVolume(); // number
+const inputVolume = agent.getInputVolume(); // number
+const isMuted = agent.isMicMuted(); // boolean
+const inputFreqData = agent.getInputByteFrequencyData(); // Uint8Array
+const outputFreqData = agent.getOutputByteFrequencyData(); // Uint8Array
+
+// Strongly typed start options with all advanced features
+await agent.start({
+  agentId: "agent-id",
+  voiceEnablement: true,
+  userId: "user-123",
+  params: {
+    userName: "John Doe",
+    sessionId: "session-456"
+  },
+  preferHeadphonesForIosDevices: true,
+  connectionDelay: {
+    android: 3000,
+    ios: 500,
+    default: 1000
+  },
+  disableWakeLock: false
+});
+
+// Strongly typed event handlers
+agent.on("analyticsUpdated", (analytics: CallAnalyticsResult) => {
+  console.log(analytics.connectionStats.latency); // number
+  console.log(analytics.audioMetrics.userAudioLevel); // number
+  console.log(analytics.performanceMetrics.callDuration); // number
+  console.log(analytics.participants.length); // number
+});
+
+// Audio control events
+agent.on("micMuted", () => {
+  console.log("Microphone was muted");
+});
+
+agent.on("micUnmuted", () => {
+  console.log("Microphone was unmuted");
 });
 
 // Strongly typed custom events
-agent.on("customEvent", (eventType: string, eventData: any, metadata: CustomEventMetadata) => {
+agent.on(
+  "customEvent",
+  (eventType: string, eventData: any, metadata: CustomEventMetadata) => {
     console.log(metadata.timestamp); // number
     console.log(metadata.participant); // string
+  }
+);
+
+// Strongly typed participant events
+agent.on("participantConnected", (participant: ParticipantData) => {
+  console.log(participant.identity); // string
+  console.log(participant.connectionTime); // number
 });
 ```
 
 ## Use Cases
 
 ### Real-time Call Quality Monitoring
+
 ```javascript
 agent.on("connectionQualityChanged", ({ quality, metrics }) => {
-    if (quality === 'poor') {
-        showNetworkWarning();
-        logQualityIssue(metrics);
-    }
+  if (quality === "poor") {
+    showNetworkWarning();
+    logQualityIssue(metrics);
+  }
 });
 ```
 
 ### Analytics Dashboard
+
 ```javascript
 const analytics = agent.getCallAnalytics();
 sendToAnalytics({
-    callDuration: analytics.callDuration,
-    audioQuality: analytics.audioMetrics,
-    participantCount: analytics.participants.length,
-    performance: analytics.performanceMetrics
+  callDuration: analytics.callDuration,
+  audioQuality: analytics.audioMetrics,
+  participantCount: analytics.participants.length,
+  performance: analytics.performanceMetrics,
 });
 ```
 
 ### Conversation Flow Analysis
+
 ```javascript
 agent.on("customEvent", (eventType, data) => {
-    if (eventType === "flow_navigation") {
-        trackConversationFlow(data.from, data.to);
-        optimizeAgentResponses(data);
-    }
+  if (eventType === "flow_navigation") {
+    trackConversationFlow(data.from, data.to);
+    optimizeAgentResponses(data);
+  }
 });
 ```
 
 ## Dependencies
 
--   **livekit-client**: Real-time communication infrastructure
--   **events**: EventEmitter for browser compatibility
+- **livekit-client v2.15.4**: Real-time communication infrastructure
+- **events v3.3.0**: EventEmitter for browser compatibility
+
+The SDK uses LiveKit's native WebRTC capabilities for high-quality real-time audio communication and comprehensive analytics.