VBEE SDK for TypeScript/JavaScript

Official TypeScript/JavaScript SDK for VBEE Text-to-Speech and Voice AI Services.

Features

• 🎯 Text-to-Speech: Convert text to natural-sounding speech
• 🎤 Speech Recognition: Transcribe audio to text
• 🗣️ Voice Management: Browse and manage available voices
• 📦 TypeScript Support: Full TypeScript type definitions
• 🔒 Secure: Built-in API key authentication
• ⚡ Easy to Use: Simple and intuitive API
• 🛠️ Customizable: Flexible configuration options

Installation

npm install @vbee/sdk

or with yarn:

yarn add @vbee/sdk

Quick Start

Initialize the SDK

import { VBeeClient } from '@vbee/sdk';

const client = new VBeeClient({
  apiKey: 'YOUR_API_KEY',
});

Text-to-Speech

// Simple text-to-speech
const audioUrl = await client.tts.synthesizeToUrl(
  'Xin chào, đây là VBEE Text-to-Speech',
  'voice-id-123'
);

console.log('Audio URL:', audioUrl);

// Advanced options
const result = await client.tts.synthesize({
  text: 'Hello, this is VBEE TTS',
  voiceId: 'voice-id-123',
  speed: 1.2,
  format: AudioFormat.MP3,
  language: 'vi-VN',
  sampleRate: 24000,
});

console.log('Audio URL:', result.audioUrl);
console.log('Duration:', result.duration);

Voice Management

// Get all available voices
const voices = await client.voice.list();
console.log('Available voices:', voices.voices);

// Filter voices by language
const vietnameseVoices = await client.voice.getByLanguage('vi-VN');
console.log('Vietnamese voices:', vietnameseVoices);

// Get specific voice
const voice = await client.voice.getById('voice-id-123');
console.log('Voice details:', voice);

// Search voices
const searchResults = await client.voice.search('female');
console.log('Search results:', searchResults);

Speech Recognition

// Transcribe audio from URL
const transcription = await client.speechRecognition.transcribeFromUrl(
  'https://example.com/audio.mp3',
  'vi-VN'
);

console.log('Transcription:', transcription.text);
console.log('Confidence:', transcription.confidence);

// Transcribe from buffer
const audioBuffer = fs.readFileSync('audio.mp3');
const result = await client.speechRecognition.transcribeFromBuffer(
  audioBuffer,
  'vi-VN'
);

Configuration

Basic Configuration

const client = new VBeeClient({
  apiKey: 'YOUR_API_KEY',
});

Advanced Configuration

const client = new VBeeClient({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.vbee.vn/v1', // Custom API endpoint
  timeout: 30000, // Request timeout in milliseconds
  retryAttempts: 3, // Number of retry attempts
  debug: true, // Enable debug mode
});

API Reference

VBeeClient

Main client class for interacting with VBEE API.

Methods

• healthCheck(): Test API connection
• getVersion(): Get SDK version

TTSService

Text-to-Speech service.

Methods

• synthesize(request: TTSRequest): Convert text to speech with detailed options
• synthesizeToUrl(text: string, voiceId: string, options?): Get audio URL
• synthesizeToBuffer(text: string, voiceId: string, options?): Get audio data

VoiceService

Voice management service.

Methods

• list(filters?): Get list of available voices
• getById(voiceId: string): Get voice by ID
• search(query: string): Search voices by name
• getByLanguage(language: string): Get voices by language
• getByGender(gender: string): Get voices by gender

SpeechRecognitionService

Speech recognition service.

Methods

• transcribe(request: SpeechRecognitionRequest): Transcribe audio to text
• transcribeFromUrl(audioUrl: string, language?): Transcribe from URL
• transcribeFromBuffer(audioBuffer: Buffer, language?): Transcribe from buffer

Types

VBeeConfig

interface VBeeConfig {
  apiKey: string;
  baseURL?: string;
  timeout?: number;
  retryAttempts?: number;
  debug?: boolean;
}

TTSRequest

interface TTSRequest {
  text: string;
  voiceId: string;
  speed?: number;
  format?: AudioFormat;
  language?: string;
  sampleRate?: number;
}

Voice

interface Voice {
  id: string;
  name: string;
  language: string;
  gender: VoiceGender;
  description?: string;
  category?: string;
  sampleUrl?: string;
  isActive: boolean;
}

Error Handling

The SDK provides comprehensive error handling with specific error types:

import { 
  VBeeError, 
  AuthenticationError, 
  ValidationError, 
  RateLimitError 
} from '@vbee/sdk';

try {
  const result = await client.tts.synthesize({
    text: 'Hello',
    voiceId: 'invalid-voice',
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof ValidationError) {
    console.error('Invalid input:', error.message);
  } else if (error instanceof RateLimitError) {
    console.error('Rate limit exceeded');
  } else if (error instanceof VBeeError) {
    console.error('VBEE Error:', error.code, error.message);
  }
}

Examples

Check out the examples directory for more usage examples:

• Basic TTS
• Voice Management
• Speech Recognition
• Error Handling

Development

Build

npm run build

Test

npm test

Lint

npm run lint
npm run lint:fix

Format

npm run format

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Documentation: https://docs.vbee.vn
• Email: [email protected]
• Issues: GitHub Issues

Changelog

See CHANGELOG.md for a list of changes.