OneBudd STS SDK - Real-time voice AI conversations
npm install @onebudd/onebudd-sdkbash
npm install @onebud/onebudd-sdk
or
yarn add @onebud/onebudd-sdk
or
pnpm add @onebud/onebudd-sdk
`
---
Quick Start
`typescript
import { OneBuddClient } from '@onebud/onebudd-sdk';
const client = new OneBuddClient('pk_test_xxx');
// Connect
const session = await client.startSession();
console.log('Connected:', session.id);
// Listen for events
client.on('audio', (bytes) => {
// bytes is Uint8Array - play through Web Audio API
playAudio(bytes);
});
client.on('transcript', ({ role, text, is_final }) => {
console.log(${role}: ${text});
});
// Send text (skips speech recognition)
client.sendMessage('Hello!');
// Or send audio (PCM 16kHz mono 16-bit)
client.sendAudio(audioBytes);
// End session
client.endSession();
`
---
Configuration
`typescript
const client = new OneBuddClient('pk_xxx', {
baseUrl: 'wss://api.onebudd.com', // WebSocket URL
autoReconnect: true, // Auto-reconnect on disconnect
maxReconnectAttempts: 5, // Max reconnection attempts
reconnectDelayMs: 1000, // Base delay (exponential backoff)
});
`
---
API Reference
$3
| Method | Description |
|--------|-------------|
| startSession() | Connect and start a new session |
| endSession() | End the current session |
| sendAudio(chunk) | Send raw PCM audio (Uint8Array) |
| sendAudioWithMeta(chunk, seq?) | Send audio with metadata |
| sendMessage(text) | Send text (bypasses STT) |
| cancel(target?) | Cancel active operations |
$3
| Event | Payload | Description |
|-------|---------|-------------|
| audio | Uint8Array | TTS audio bytes |
| transcript | { role, text, is_final } | Transcription |
| state_change | { from, to, trigger } | Pipeline state |
| error | { code, message, fatal } | Error occurred |
| connected | SessionCapabilities | Session ready |
| disconnected | { reason } | Connection lost |
| response_correction | { original, corrected } | After barge-in |
$3
| Property | Type | Description |
|----------|------|-------------|
| isConnected | boolean | Connection status |
| sessionId | string \| null | Current session ID |
| capabilities | SessionCapabilities \| null | Server capabilities |
---
Browser Usage
`html
`
$3
`typescript
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const audioContext = new AudioContext({ sampleRate: 16000 });
const source = audioContext.createMediaStreamSource(stream);
const processor = audioContext.createScriptProcessor(4096, 1, 1);
processor.onaudioprocess = (e) => {
const float32 = e.inputBuffer.getChannelData(0);
const int16 = new Int16Array(float32.length);
for (let i = 0; i < float32.length; i++) {
int16[i] = Math.max(-32768, Math.min(32767, float32[i] * 32768));
}
client.sendAudio(new Uint8Array(int16.buffer));
};
source.connect(processor);
processor.connect(audioContext.destination);
`
---
Node.js Usage
`typescript
import { OneBuddClient } from '@onebud/onebudd-sdk';
import { createReadStream } from 'fs';
const client = new OneBuddClient('pk_xxx');
await client.startSession();
// Stream audio file
const stream = createReadStream('audio.pcm');
stream.on('data', (chunk) => {
client.sendAudio(new Uint8Array(chunk));
});
`
---
Error Handling
`typescript
client.on('error', ({ code, message, fatal }) => {
console.error(Error [${code}]: ${message});
if (fatal) {
// Connection will be closed
}
});
// Error codes
// AUTH_FAILED, RATE_LIMITED, INVALID_MESSAGE, SESSION_NOT_FOUND, etc.
`
---
TypeScript
Full type definitions included:
`typescript
import type {
SessionCapabilities,
TranscriptPayload,
ErrorPayload,
StateChangePayload,
} from '@onebud/onebudd-sdk';
``