@sibilance.is/client

v0.1.0-alpha.5

Published

2 months ago

Voice survey client for Sibilance - embeddable voice surveys powered by AI [ALPHA - CDN/Standalone Only]

0High
0Medium
0Low

c0d3t3k

cmdpradmin

kykrenek

voice survey ai sibilance vowel conversational-ai

@sibilance.is/client

Voice survey client for Sibilance - embeddable AI-powered voice surveys.

CDN Quick Start

The fastest way to use Sibilance in your website:

<!DOCTYPE html>
<html>
<head>
  <!-- Include the CSS -->
  <link rel="stylesheet" href="https://unpkg.com/@sibilance.is/[email protected]/dist/standalone/sibilance-voice-widget.css">
</head>
<body>
  <!-- Your content here -->
  
  <!-- Add the voice survey widget -->
  <sibilance-voice-widget 
    survey-key="your_survey_key_here"
    position="bottom-right"
    show-tree="true"
    show-settings="true">
  </sibilance-voice-widget>

  <!-- Include the JavaScript -->
  <script src="https://unpkg.com/@sibilance.is/[email protected]/dist/standalone/sibilance-voice-widget.min.js"></script>
</body>
</html>

Get a Survey Key:

Visit Sibilance Platform (coming soon)
Create or select a survey
Click "Generate Survey Key"
Copy the key and paste it in the survey-key attribute above

Features

🎤 Voice-First Surveys - Natural conversation-based data collection
🔑 Survey Key Authentication - Secure, easy-to-use survey access
📝 Markdown-Driven - Survey structure defined in simple markdown
🔄 Structured Flow - Step-by-step progression with branching logic
🎯 Smart Skipping - AI detects volunteered information and skips ahead
⚛️ React Hooks - Easy integration with React applications
🔄 Reactive State - Real-time state updates using Valtio
📊 YAML Output - Structured data output from conversations

NPM Installation (Internal Developers Only)

For Sibilance.is internal developers using this in React projects:

Step 1: Install the package

bun add @sibilance.is/[email protected]

Step 2: Install @vowel.to/client

The React build externalizes @vowel.to/client (not bundled). You must install it separately:

# Option A: Link local development version (current workflow)
cd /path/to/vowel.to/client
bun link

cd /path/to/your/project
bun link @vowel.to/client

# Option B: Install from npm (when published)
bun add @vowel.to/client

Step 3: Use in your React app

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

function App() {
  const { voiceState } = useSibilance({
    surveyKey: "your_survey_key",
  });

  return <SurveyMicButton surveyId="test" position="inline" />;
}

Why is @vowel.to/client separate?

✅ Keeps bundle size small (doesn't duplicate if you use vowel elsewhere)
✅ You control the @vowel.to/client version
✅ Avoids dependency conflicts
⚠️ Standalone CDN build bundles everything, so this only applies to npm usage

React Example (Production Mode)

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

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

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

React Example (Editor/Test Mode)

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

function SurveyTester({ surveyMarkdown, surveySteps }) {
  const { voiceState, toggleSession } = useSibilance({
    survey: { // Direct config for testing
      markdown: surveyMarkdown,
      steps: surveySteps,
      mermaidDiagram: "...",
      surveyName: "Test Survey",
    }
  });

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

Vanilla JavaScript Example

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

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

await client.connect();

Documentation

USAGE.md - Complete usage guide with examples
Sibilance Platform - Create and manage surveys

API Reference

Configuration

interface SibilanceConfig {
  surveyKey?: string;         // Survey key (production mode)
  survey?: SurveyConfig;      // Direct config (editor/test mode)
  backendUrl?: string;        // Optional: Custom backend URL
  appId?: string;             // Optional: Vowel app ID
  voiceConfig?: {
    provider?: 'vowel-prime' | 'gemini' | 'openai';
    model?: string;
    vad?: {
      enabled: boolean;
      mode?: 'simple' | 'advanced';
    };
  };
  customInstructions?: string; // Optional: Additional AI instructions
  autoStart?: boolean;         // Optional: Auto-start voice session
  initialGreetingPrompt?: string; // Optional: Prompt for AI's initial behavior
}

Note: When you provide a surveyKey, the client automatically falls back to import.meta.env.VITE_SIBILANCE_BACKEND_URL (or https://helpful-crab-36.convex.site) for both fetching the survey and submitting results. You only need to set backendUrl if you are pointing at a custom/self-hosted deployment. In editor/test mode (where you pass survey instead of surveyKey) no backend calls are made.

React Hook

const {
  voiceState,      // { isConnected, isUserSpeaking, isAISpeaking, ... }
  surveyState,     // { collectedInfo, conversationLog, isComplete, ... }
  toggleSession,   // Start/stop voice session
  complete,        // Complete survey manually
  pause            // Pause survey
} = useSibilance(config, callbacks);

Callbacks

interface SurveyCallbacks {
  onComplete?: (yaml: any) => void;
  onPause?: () => void;
  onRecordInformation?: (info: CollectedInformation) => void;
  onLogConversation?: (speaker: 'ai' | 'user', message: string) => void;
  onError?: (error: Error) => void;
}

State Management

The client uses Valtio for reactive state management:

// Voice session state
voiceState: {
  isConnected: boolean;
  isConnecting: boolean;
  isUserSpeaking: boolean;
  isAISpeaking: boolean;
  isAIThinking: boolean;
}

// Survey progress state
surveyState: {
  isActive: boolean;
  currentStepId: string | null;
  collectedInfo: CollectedInformation[];
  conversationLog: ConversationLogEntry[];
  yamlData: any[];
  isComplete: boolean;
}

Browser Support

Chrome/Edge 88+
Firefox 85+
Safari 14+

Requires WebRTC and microphone access.

Security

Never commit survey keys - Use environment variables
Keys are rate-limited (1000 requests/minute)
Use separate keys for dev/prod
Rotate keys periodically

Development

Environment Setup

Copy .env.example to .env.local and configure your backend URL:

cp .env.example .env.local

Edit .env.local to point to your Convex deployment:

VITE_SIBILANCE_BACKEND_URL=https://your-deployment.convex.site

This ensures the client connects to your own Convex backend during development.

Build Commands

# Install dependencies
bun install

# Type check
bun run type-check

# Build
bun run build

# Run Storybook (component demos)
bun run storybook

# Build Storybook
bun run build-storybook

# Link for local development
bun link

Storybook

Interactive component documentation and demos are available via Storybook:

bun run storybook

This will start Storybook at http://localhost:6006 with:

Interactive demos of useSibilance hook
Examples of useSurveyState hook
Multiple configuration examples
Live component playground

See STORYBOOK.md for more details.

License

UNLICENSED - Proprietary, internal testing only. See LICENSE.md for full terms.

Can future versions have different licenses? Yes! As the copyright holder, we can release future versions under different licenses (MIT, Apache, etc.). Each version keeps its original license.

Publishing (Internal)

To publish a new alpha version:

# 1. Verify everything is built
bun run build:all

# 2. Check package contents
npm pack --dry-run

# 3. Publish with alpha tag
npm publish --access public --tag alpha

# 4. Verify on CDN (wait 1-2 minutes)
curl -I https://unpkg.com/@sibilance.is/[email protected]/dist/standalone/sibilance-voice-widget.min.js

Using --tag alpha means:

✅ npm install @sibilance.is/client won't install alpha by default
✅ npm install @sibilance.is/client@alpha gets latest alpha
✅ npm install @sibilance.is/[email protected] gets specific version

For subsequent alphas:

npm version prerelease --preid=alpha  # Bumps to 0.1.0-alpha.2
bun run build:all
npm publish --access public --tag alpha

Can unpublish within 72 hours if needed:

npm unpublish @sibilance.is/[email protected]

Support

Documentation: USAGE.md
Platform: sibilance.is
Email: [email protected]

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@sibilance.is/client

CDN Quick Start

Features

NPM Installation (Internal Developers Only)

Step 1: Install the package

Step 2: Install @vowel.to/client

Step 3: Use in your React app

React Example (Production Mode)

React Example (Editor/Test Mode)

Vanilla JavaScript Example

Documentation

API Reference

Configuration

React Hook

Callbacks

State Management

Browser Support

Security

Development

Environment Setup

Build Commands

Storybook

License

Publishing (Internal)

Support