@onebud/onebudd-sdk

JavaScript/TypeScript SDK for OneBudd real-time voice AI.

Installation

npm install @onebud/onebudd-sdk
# or
yarn add @onebud/onebudd-sdk
# or
pnpm add @onebud/onebudd-sdk

Quick Start

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

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

Methods

| 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 |

Events

| 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 |

Properties

| Property | Type | Description | |----------|------|-------------| | isConnected | boolean | Connection status | | sessionId | string \| null | Current session ID | | capabilities | SessionCapabilities \| null | Server capabilities |

Browser Usage

<script type="module">
  import { OneBuddClient } from 'https://cdn.jsdelivr.net/npm/@onebud/onebudd-sdk';
  
  const client = new OneBuddClient('pk_xxx');
  // ...
</script>

Capturing Microphone Audio

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

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

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:

import type {
  SessionCapabilities,
  TranscriptPayload,
  ErrorPayload,
  StateChangePayload,
} from '@onebud/onebudd-sdk';

License

MIT