@voicexperiences/web

Voice-first interaction SDK for the web. Zero dependencies. Uses the native Web Speech API for speech recognition and synthesis.

Install

npm install @voicexperiences/web

Or via CDN:

<script src="https://cdn.arcsys.one/sdk/0.1.0/vx.min.js"></script>

Quick Start

import { VoiceXperiences, voiceExperience } from '@voicexperiences/web';

// 1. Initialize
VoiceXperiences.init({ apiKey: 'vx-live-...' });

// 2. Define your experience
const experience = voiceExperience({
  greet: 'Welcome! What can I help you with?',
  actions: {
    search: {
      description: 'Find products, articles, or content',
      parameters: [
        { name: 'query', type: 'STRING', description: 'Search query', required: true },
      ],
      handler: async (ctx) => {
        const results = await searchProducts(ctx.params.query);
        ctx.show(results);
        return { speak: `Found ${results.length} results` };
      },
    },
  },
});

// 3. Go
experience.start();

UI Orchestration

Tag your HTML elements with data-voice-tag to let the SDK show/hide content based on voice actions:

<div data-voice-tag="search_results" style="display: none">
  <!-- SDK will show this when search results arrive -->
</div>

Understanding Providers

The SDK ships with a cloud-based LLM provider (default). Bring your own by implementing the UnderstandingProvider interface:

const experience = voiceExperience({
  provider: myCustomProvider,
  // ...
});

Security: API Key Handling

The apiKey passed to VoiceXperiences.init() is sent to the NLU server from the browser. In production, proxy requests through your own backend so the key is never exposed to end users:

// Your Express server
app.post('/api/understand', async (req, res) => {
  const result = await fetch('https://api.arcsys.one/v1/understand', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${process.env.VX_API_KEY}`, // server-side only
    },
    body: JSON.stringify(req.body),
  });
  res.json(await result.json());
});

// Client — point to your proxy
VoiceXperiences.init({ apiKey: 'unused', endpoint: '/api/understand' });

Documentation

• Protocol Specification
• Web Guide
• API Reference

License

MIT