Simli WebRTC Client

Common errors

• TypeError: SimliClient is not a constructor

  cause Attempting to import SimliClient using CommonJS 'require' syntax in an ESM-only or hybrid environment where the default export is not correctly handled.
  fix Change your import statement to `import { SimliClient } from 'simli-client';` for ES Module compatibility.

• Error: API key is missing or invalid.

  cause The `apiKey` field in the `SimliClientConfig` object was either not provided or contained an empty/invalid string.
  fix Ensure `SimliClientConfig.apiKey` is set to a valid, non-empty API key provided by Simli. Double-check for typos.

• SimliClient: Connection failed: Signaling error occurred.

  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.
  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.

• ReferenceError: navigator is not defined

  cause Attempting to use browser-specific APIs like `navigator.mediaDevices.getUserMedia` in a Node.js environment without appropriate polyfills or mocking.
  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.

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install simli-client npm
• yarn add simli-client yarn
• pnpm add simli-client pnpm

Imports

• SimliClient
  wrong:

  const SimliClient = require('simli-client');

  correct:

  import { SimliClient } from 'simli-client';

  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.
• SimliClientConfig

  import type { SimliClientConfig } from 'simli-client';

  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.
• Initialize

  await client.Initialize(config);

  The `Initialize` method is asynchronous and must be awaited to ensure the client is properly set up before calling `start()` or other methods.

Quickstart

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.

import { SimliClient } from 'simli-client';
import type { SimliClientConfig } from 'simli-client';

async function setupSimliConnection() {
  // In a real application, ensure these values are loaded securely (e.g., environment variables)
  const SIMLI_API_KEY = process.env.SIMLI_API_KEY ?? 'your-simli-api-key-here';
  const SIMLI_SERVER_URL = process.env.SIMLI_SERVER_URL ?? 'wss://your.simli.server.com/ws';

  if (SIMLI_API_KEY === 'your-simli-api-key-here') {
    console.warn("WARNING: Please replace 'your-simli-api-key-here' with your actual Simli API key.");
  }
  if (SIMLI_SERVER_URL === 'wss://your.simli.server.com/ws') {
    console.warn("WARNING: Please replace 'your.simli.server.com' with your actual Simli server URL.");
  }

  const config: SimliClientConfig = {
    apiKey: SIMLI_API_KEY,
    serverUrl: SIMLI_SERVER_URL,
    // Optional: avatarId: 'default-avatar',
    // Optional: logLevel: 'info' // 'debug', 'warn', 'error'
  };

  const client = new SimliClient();

  // Attach event listeners for connection status
  client.on('connected', () => {
    console.log('SimliClient: Successfully connected to the server.');
    // You can start sending data here
    // For demonstration, let's send dummy audio for 5 seconds
    const dummyAudio = new Uint8Array(1024).fill(0);
    let sendCount = 0;
    const interval = setInterval(() => {
      if (sendCount < 50) { // Send for 50 * 100ms = 5 seconds
        client.sendAudioData(dummyAudio);
        sendCount++;
      } else {
        clearInterval(interval);
        console.log('SimliClient: Finished sending dummy audio data.');
      }
    }, 100);
  });
  client.on('disconnected', () => console.log('SimliClient: Disconnected from the server.'));
  client.on('failed', (error: Error) => console.error('SimliClient: Connection failed:', error));

  try {
    console.log('SimliClient: Initializing with provided configuration...');
    await client.Initialize(config);
    console.log('SimliClient: Initialization complete. Attempting to start connection...');
    await client.start(); // This establishes the WebRTC connection
    console.log('SimliClient: Connection process initiated.');

    // In a real application, you might acquire a MediaStream from getUserMedia
    // and then use client.listenToMediastreamTrack(audioTrack);

  } catch (error) {
    console.error('SimliClient: Fatal error during setup or connection:', error);
    client.close(); // Ensure resources are cleaned up on failure
  }
}

// Execute the setup function
setupSimliConnection();