Appearance

API Reference ​

🚧 CLOSED BETA

Sibilance is currently in closed beta. This API reference documentation is provided as a reference to showcase the implementation that will be available upon release.

The @sibilance.is/client package is not yet publicly available. If you're interested in early access, please visit sibilance.is to join the waitlist.

Package Overview ​

The Sibilance client library provides two entry points for different use cases:

Core Library (@sibilance.is/client) ​

The core library provides framework-agnostic functionality for voice surveys:

  • SibilanceClient - Main client class for voice survey integration
  • Survey State Management - Track survey progress and collect data
  • YAML Generation - Convert survey results to YAML format
  • Voice Integration - Built on top of vowel.to voice AI platform

React Library (@sibilance.is/client/react) ​

The React library provides React-specific components and hooks:

  • <SibilanceProvider> - Context provider for Sibilance client
  • <SurveyMicButton> - Pre-built microphone button component
  • <SurveyTreeView> - Survey state visualization component
  • useSibilance() - Hook for voice and survey state
  • useSurveyState() - Hook for survey state only
  • useSurveyTreeView() - Hook for tree view state

Quick Start ​

Installation ​

bash
npm install @sibilance.is/client
# or
bun add @sibilance.is/client

Basic Usage (React) ​

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

function VoiceSurvey() {
  const { voiceState, surveyState, toggleSession } = useSibilance({
    surveyKey: "sibilance_your_key_here",
  }, {
    onComplete: (yaml) => {
      console.log('Survey completed!', yaml);
      // Submit to your backend
    }
  });

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

Basic Usage (Vanilla JS) ​

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

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

// Connect to voice AI
await client.connect();

// Start the session
await client.start();

Core Classes ​

SibilanceClient ​

The main client class for integrating Sibilance voice surveys.

Constructor:

typescript
new SibilanceClient(config: SibilanceConfig, callbacks?: SurveyCallbacks)

Key Methods:

  • connect() - Initialize voice connection
  • start() - Start voice session
  • disconnect() - End voice session
  • getSurveyState() - Get current survey state
  • getYAML() - Get survey results as YAML

Example:

typescript
const client = new SibilanceClient({
  surveyKey: 'your_key_here',
  // Or for testing:
  survey: {
    markdown: '# Survey\n## Start\nHello!',
    steps: [...],
    mermaidDiagram: '...'
  }
});

React Hooks ​

useSibilance() ​

Main hook for accessing voice and survey state in React.

typescript
const { 
  voiceState,      // Voice connection state
  surveyState,     // Survey progress state
  toggleSession,   // Toggle voice session
  client          // SibilanceClient instance
} = useSibilance(config, callbacks);

useSurveyState() ​

Hook for accessing survey state without voice functionality.

typescript
const surveyState = useSurveyState(client);

useSurveyTreeView() ​

Hook for survey state visualization (tree view).

typescript
const { 
  treeData,       // Tree structure
  expandedKeys,   // Expanded nodes
  toggleNode      // Toggle node expansion
} = useSurveyTreeView(surveyState);

React Components ​

<SibilanceProvider> ​

Context provider for Sibilance client.

tsx
<SibilanceProvider client={client}>
  <YourComponents />
</SibilanceProvider>

<SurveyMicButton> ​

Pre-built microphone button with status indicators.

tsx
<SurveyMicButton
  surveyId="your_survey_id"
  onComplete={(yaml) => console.log(yaml)}
/>

<SurveyTreeView> ​

Visual tree representation of survey state.

tsx
<SurveyTreeView 
  treeData={treeData}
  expandedKeys={expandedKeys}
  onToggle={toggleNode}
/>

TypeScript Types ​

The library is fully typed with TypeScript. Key interfaces:

  • SibilanceConfig - Client configuration
  • SurveyConfig - Survey definition
  • SurveyState - Survey progress state
  • VoiceSessionState - Voice connection state
  • SurveyCallbacks - Lifecycle callbacks
  • CollectedInformation - Survey data

Configuration ​

SibilanceConfig ​

typescript
interface SibilanceConfig {
  // Production mode: Fetch survey from backend
  surveyKey?: string;
  
  // Test/editor mode: Use provided survey
  survey?: SurveyConfig;
  
  // Optional: Backend URL override
  backendUrl?: string;
  
  // Optional: Vowel configuration
  vowelConfig?: VowelConfig;
}

SurveyCallbacks ​

typescript
interface SurveyCallbacks {
  onComplete?: (yaml: string) => void;
  onStepChange?: (step: SurveyStep) => void;
  onError?: (error: Error) => void;
  onConnect?: () => void;
  onDisconnect?: () => void;
}

Survey State ​

The survey state tracks progress through the conversation:

typescript
interface SurveyState {
  currentStep: SurveyStep | null;
  visitedSteps: string[];
  collectedInformation: CollectedInformation;
  conversationLog: ConversationLogEntry[];
  isComplete: boolean;
}

Error Handling ​

The library provides typed errors for common scenarios:

typescript
try {
  await client.connect();
} catch (error) {
  if (error instanceof SurveyNotFoundError) {
    // Handle survey not found
  } else if (error instanceof SurveyAuthError) {
    // Handle authentication error
  } else {
    // Handle other errors
  }
}

Advanced Usage ​

Custom Voice Configuration ​

typescript
const client = new SibilanceClient({
  surveyKey: 'your_key',
  vowelConfig: {
    voice: 'Kore',
    model: 'gemini-2.0-flash-exp',
    voiceProvider: 'google'
  }
});

Handling Previous Steps ​

typescript
const client = new SibilanceClient({
  surveyKey: 'your_key'
}, {
  onStepChange: (step) => {
    if (step.previousSteps) {
      // Handle multi-step context
      console.log('Building on:', step.previousSteps);
    }
  }
});

Test Mode (Editor) ​

typescript
const client = new SibilanceClient({
  survey: {
    markdown: surveyMarkdown,
    steps: parsedSteps,
    mermaidDiagram: diagram,
    surveyName: 'Test Survey'
  }
});

Browser Compatibility ​

The library requires:

  • Modern browser with Web Audio API
  • Microphone permissions
  • Secure context (HTTPS or localhost)

Tested on:

  • Chrome 90+
  • Firefox 88+
  • Safari 14+
  • Edge 90+

Examples ​

See the Guide for detailed examples and tutorials.

Support ​

License ​

Proprietary - see package for details

Copyright © 2025 sibilance.is