Installation

🚧 CLOSED BETA

Sibilance is currently in closed beta. The @sibilance.is/client package is not yet publicly available on npm. This documentation serves as a reference for how installation will work upon release.

If you're interested in early access, please visit sibilance.is to join the waitlist.

This guide covers different ways to install and use @sibilance.is/client in your project.

Package Manager Installation

npm

npm install @sibilance.is/client

Yarn

yarn add @sibilance.is/client

Bun

bun add @sibilance.is/client

pnpm

pnpm add @sibilance.is/client

CDN Installation

For quick prototyping or static sites, you can use the CDN version:

Standalone JavaScript Bundle

<script src="https://unpkg.com/@sibilance.is/client@latest/dist/index.js"></script>

<script>
  const { SibilanceClient } = window.SibilanceClient;
  
  const client = new SibilanceClient({
    surveyKey: 'sibilance_your_key_here'
  }, {
    onComplete: (yaml) => {
      console.log('Survey completed!', yaml);
    }
  });
  
  client.connect();
</script>

Web Component

<script src="https://unpkg.com/@sibilance.is/client@latest/dist/web-components.js"></script>

<sibilance-survey-widget 
  id="widget"
  survey-key="sibilance_your_key_here">
</sibilance-survey-widget>

<script>
  const widget = document.getElementById('widget');
  
  widget.addEventListener('sibilance-ready', () => {
    console.log('Sibilance is ready!');
  });
</script>

TypeScript Support

@sibilance.is/client is written in TypeScript and includes full type definitions. No additional @types package is needed.

import { SibilanceClient, SibilanceConfig } from '@sibilance.is/client';

const config: SibilanceConfig = {
  surveyKey: 'sibilance_your_key_here'
};

const client = new SibilanceClient(config, {
  onComplete: (yaml) => {
    console.log('Survey completed!', yaml);
  }
});

Framework-Specific Setup

React

// App.tsx
import { useSibilance, FloatingMicButton } from '@sibilance.is/client/react';

function App() {
  const { voiceState, surveyState, toggleSession } = useSibilance({
    surveyKey: process.env.NEXT_PUBLIC_SIBILANCE_SURVEY_KEY!,
  }, {
    onComplete: (yaml) => {
      console.log('Survey completed!', yaml);
    }
  });

  return (
    <div>
      <YourApp />
      <FloatingMicButton
        isConnected={voiceState.isConnected}
        onClick={toggleSession}
      />
    </div>
  );
}

Next.js

// app/components/VoiceSurvey.tsx
'use client';

import { useSibilance, FloatingMicButton } from '@sibilance.is/client/react';

export function VoiceSurvey() {
  const { voiceState, surveyState, toggleSession } = useSibilance({
    surveyKey: process.env.NEXT_PUBLIC_SIBILANCE_SURVEY_KEY!,
  }, {
    onComplete: (yaml) => {
      // Submit to your API
      fetch('/api/survey-results', {
        method: 'POST',
        body: JSON.stringify({ results: yaml })
      });
    }
  });

  return (
    <FloatingMicButton
      isConnected={voiceState.isConnected}
      onClick={toggleSession}
    />
  );
}

Vanilla JavaScript

// survey.ts
import { SibilanceClient } from '@sibilance.is/client';

const client = new SibilanceClient({
  surveyKey: 'sibilance_your_key_here',
}, {
  onComplete: (yaml) => {
    console.log('Survey completed!', yaml);
  }
});

// Start voice session
await client.connect();

Environment Variables

Store your Survey Key in environment variables:

Next.js (.env.local)

NEXT_PUBLIC_SIBILANCE_SURVEY_KEY=sibilance_your_key_here

Vite (.env)

VITE_SIBILANCE_SURVEY_KEY=sibilance_your_key_here

Create React App (.env)

REACT_APP_SIBILANCE_SURVEY_KEY=sibilance_your_key_here

Browser Requirements

Sibilance requires a modern browser with:

• WebRTC support
• Microphone access
• HTTPS (for microphone permissions)

Supported Browsers

• ✅ Chrome/Edge 88+ (Recommended)
• ✅ Firefox 85+
• ✅ Safari 14+
• ⚠️ Mobile browsers (limited support)

Troubleshooting

Microphone Permission Denied

Ensure your site is served over HTTPS. Browsers block microphone access on HTTP (except localhost).

Module Not Found

If you see module resolution errors:

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

TypeScript Errors

Ensure your tsconfig.json includes:

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true
  }
}

Survey Not Loading

1. Verify your Survey Key is correct (starts with sibilance_)
2. Check that the survey is active in the Sibilance platform
3. Verify domain restrictions allow your current domain
4. Check browser console for detailed error messages

Next Steps

• Quick Start - Build your first voice survey
• Sibilance Client - Learn about the core API
• React Integration - React-specific integration guide