{"id":16531,"library":"simli-client","title":"Simli WebRTC Client","description":"SimliClient is a WebRTC frontend client designed for real-time interaction with AI-powered facial recognition and avatar services. It enables developers to integrate live audio and video streaming capabilities into their web applications, specifically for scenarios involving AI-driven avatars or face-based interactions. The current stable version is 3.0.1. While a specific release cadence isn't explicitly stated, the package follows semantic versioning, with major version changes (like the jump to v3) indicating significant updates and potential breaking changes. Its primary differentiator is its focus on streamlining the integration of WebRTC with Simli's AI backend for facial analysis and avatar control, abstracting much of the low-level WebRTC API complexity for these specialized use cases.","status":"active","version":"3.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/simliai/simli-client","tags":["javascript","simli","webrtc","faces","ai","typescript"],"install":[{"cmd":"npm install simli-client","lang":"bash","label":"npm"},{"cmd":"yarn add simli-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add simli-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily uses ES Modules. Direct CommonJS require() is not supported and will result in a 'SimliClient is not a constructor' or similar error.","wrong":"const SimliClient = require('simli-client');","symbol":"SimliClient","correct":"import { SimliClient } from 'simli-client';"},{"note":"Use 'import type' for importing TypeScript interfaces or types to ensure they are stripped from the JavaScript output, preventing runtime errors or unnecessary bundle size increase.","symbol":"SimliClientConfig","correct":"import type { SimliClientConfig } from 'simli-client';"},{"note":"The `Initialize` method is asynchronous and must be awaited to ensure the client is properly set up before calling `start()` or other methods.","symbol":"Initialize","correct":"await client.Initialize(config);"}],"quickstart":{"code":"import { SimliClient } from 'simli-client';\nimport type { SimliClientConfig } from 'simli-client';\n\nasync function setupSimliConnection() {\n  // In a real application, ensure these values are loaded securely (e.g., environment variables)\n  const SIMLI_API_KEY = process.env.SIMLI_API_KEY ?? 'your-simli-api-key-here';\n  const SIMLI_SERVER_URL = process.env.SIMLI_SERVER_URL ?? 'wss://your.simli.server.com/ws';\n\n  if (SIMLI_API_KEY === 'your-simli-api-key-here') {\n    console.warn(\"WARNING: Please replace 'your-simli-api-key-here' with your actual Simli API key.\");\n  }\n  if (SIMLI_SERVER_URL === 'wss://your.simli.server.com/ws') {\n    console.warn(\"WARNING: Please replace 'your.simli.server.com' with your actual Simli server URL.\");\n  }\n\n  const config: SimliClientConfig = {\n    apiKey: SIMLI_API_KEY,\n    serverUrl: SIMLI_SERVER_URL,\n    // Optional: avatarId: 'default-avatar',\n    // Optional: logLevel: 'info' // 'debug', 'warn', 'error'\n  };\n\n  const client = new SimliClient();\n\n  // Attach event listeners for connection status\n  client.on('connected', () => {\n    console.log('SimliClient: Successfully connected to the server.');\n    // You can start sending data here\n    // For demonstration, let's send dummy audio for 5 seconds\n    const dummyAudio = new Uint8Array(1024).fill(0);\n    let sendCount = 0;\n    const interval = setInterval(() => {\n      if (sendCount < 50) { // Send for 50 * 100ms = 5 seconds\n        client.sendAudioData(dummyAudio);\n        sendCount++;\n      } else {\n        clearInterval(interval);\n        console.log('SimliClient: Finished sending dummy audio data.');\n      }\n    }, 100);\n  });\n  client.on('disconnected', () => console.log('SimliClient: Disconnected from the server.'));\n  client.on('failed', (error: Error) => console.error('SimliClient: Connection failed:', error));\n\n  try {\n    console.log('SimliClient: Initializing with provided configuration...');\n    await client.Initialize(config);\n    console.log('SimliClient: Initialization complete. Attempting to start connection...');\n    await client.start(); // This establishes the WebRTC connection\n    console.log('SimliClient: Connection process initiated.');\n\n    // In a real application, you might acquire a MediaStream from getUserMedia\n    // and then use client.listenToMediastreamTrack(audioTrack);\n\n  } catch (error) {\n    console.error('SimliClient: Fatal error during setup or connection:', error);\n    client.close(); // Ensure resources are cleaned up on failure\n  }\n}\n\n// Execute the setup function\nsetupSimliConnection();\n","lang":"typescript","description":"This quickstart demonstrates how to initialize the SimliClient, set up event listeners for connection status, and establish a WebRTC connection. It includes an example of sending dummy audio data after connection and highlights secure API key handling."},"warnings":[{"fix":"Refer to the official SimliClient v3 documentation or migration guides (if available) for updated API usage and configuration. Adjust your code to conform to the new v3 interfaces.","message":"The jump from version 2.x to 3.x likely introduced breaking changes in API signatures, configuration options, or internal mechanisms. Developers upgrading from previous major versions should consult the official documentation for migration guides.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Use environment variables, a backend API endpoint to proxy credentials, or a secure token exchange mechanism (e.g., JWTs) to provide these values to your client-side application at runtime without embedding them directly.","message":"API keys and sensitive server URLs should never be directly hardcoded into client-side bundles for production applications. Exposure can lead to unauthorized access and abuse of your Simli services.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your Simli server infrastructure uses appropriate STUN/TURN servers to facilitate connection establishment across various network topologies. Provide clear error messages to users if connection fails due to network issues.","message":"WebRTC connections can be sensitive to network environments, including firewalls, NAT traversal, and network latency. Users behind restrictive networks may experience connection failures or poor performance.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always `await` the `Initialize` and `start` methods and handle any potential rejections (errors) gracefully. Ensure subsequent API calls are made only after the `connected` event has fired or after these promises resolve.","message":"The `Initialize` and `start` methods are asynchronous. Calling other methods before these operations complete can lead to runtime errors or unexpected behavior as the WebRTC connection might not be ready.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Change your import statement to `import { SimliClient } from 'simli-client';` for ES Module compatibility.","cause":"Attempting to import SimliClient using CommonJS 'require' syntax in an ESM-only or hybrid environment where the default export is not correctly handled.","error":"TypeError: SimliClient is not a constructor"},{"fix":"Ensure `SimliClientConfig.apiKey` is set to a valid, non-empty API key provided by Simli. Double-check for typos.","cause":"The `apiKey` field in the `SimliClientConfig` object was either not provided or contained an empty/invalid string.","error":"Error: API key is missing or invalid."},{"fix":"Verify that `SimliClientConfig.serverUrl` is correct and accessible. Check firewall rules, network connectivity, and the status of your Simli backend server. Inspect console logs for more specific WebSocket or WebRTC errors.","cause":"The WebRTC signaling process failed, often due to an unreachable `serverUrl`, incorrect server configuration, or network issues preventing the client from negotiating a connection with the Simli backend.","error":"SimliClient: Connection failed: Signaling error occurred."},{"fix":"Ensure your code runs in a browser environment or use a tool like JSDOM to mock browser APIs if running unit tests in Node.js. For server-side operations, SimliClient is not typically used directly.","cause":"Attempting to use browser-specific APIs like `navigator.mediaDevices.getUserMedia` in a Node.js environment without appropriate polyfills or mocking.","error":"ReferenceError: navigator is not defined"}],"ecosystem":"npm"}