Audio (TTS/STT)

import { Connector, TextToSpeech, Vendor } from 'oneringai';

// Setup connector
Connector.create({
  name: 'openai',
  vendor: Vendor.OpenAI,
  auth: { type: 'api_key', apiKey: process.env.OPENAI_API_KEY! },
});

// Create TTS instance
const tts = TextToSpeech.create({
  connector: 'openai',
  model: 'tts-1-hd',      // High-quality model
  voice: 'nova',          // Female voice
});

// Synthesize to Buffer
const response = await tts.synthesize('Hello, world!');
console.log(response.audio);   // Buffer
console.log(response.format);  // 'mp3'

// Synthesize to file
await tts.toFile('Hello, world!', './output.mp3');

// Available voices
const voices = await tts.listVoices();
// [
//   { id: 'alloy', name: 'Alloy', gender: 'neutral', isDefault: true },
//   { id: 'echo', name: 'Echo', gender: 'male' },
//   { id: 'fable', name: 'Fable', gender: 'neutral', accent: 'british' },
//   { id: 'onyx', name: 'Onyx', gender: 'male' },
//   { id: 'nova', name: 'Nova', gender: 'female' },
//   { id: 'shimmer', name: 'Shimmer', gender: 'female' },
//   ...
// ]

// Synthesize with specific voice
const audio = await tts.synthesize('Hello', { voice: 'echo' });

import { createReadStream } from 'node:fs';
import { OpenAIVoices, TextToSpeech } from 'oneringai';

const voices = new OpenAIVoices('openai');
const customVoice = await voices.create({
  type: 'audio_sample',
  name: 'Brand narrator',
  audio_sample: createReadStream('./brand-narrator.wav'),
  consent: 'cons_1234abcd',
});

const branded = TextToSpeech.create({
  connector: 'openai',
  model: 'gpt-4o-mini-tts',
  voice: customVoice.id,
});

await branded.toFile('Spoken in your bespoke voice.', './brand.mp3');

// A stored audio-sample voice can also be selected per call.
await branded.synthesize('Different copy.', { voice: 'voice_5678efgh' });

// Supported formats: mp3, opus, aac, flac, wav, pcm
const mp3 = await tts.synthesize('Hello', { format: 'mp3' });
const wav = await tts.synthesize('Hello', { format: 'wav' });
const flac = await tts.synthesize('Hello', { format: 'flac' });

// Speed range: 0.25 (slow) to 4.0 (fast)
const slow = await tts.synthesize('Speaking slowly', { speed: 0.5 });
const normal = await tts.synthesize('Normal speed', { speed: 1.0 });
const fast = await tts.synthesize('Speaking fast', { speed: 2.0 });

const tts = TextToSpeech.create({
  connector: 'openai',
  model: 'gpt-4o-mini-tts',
  voice: 'nova',
});

const audio = await tts.synthesize('I\'m so happy to see you!', {
  vendorOptions: {
    instructions: 'Speak with enthusiasm and joy, like greeting an old friend.',
  },
});

// Get model information
const info = tts.getModelInfo();
console.log(info.capabilities.features.instructionSteering); // true for gpt-4o-mini-tts

// Check feature support
const canSteer = tts.supportsFeature('instructionSteering');
const canStream = tts.supportsFeature('streaming');

// Get supported formats
const formats = tts.getSupportedFormats();  // ['mp3', 'opus', 'aac', ...]

// List available models
const models = tts.listAvailableModels();

import { TextToSpeech } from 'oneringai';

const tts = TextToSpeech.create({
  connector: 'openai',
  model: 'tts-1-hd',
  voice: 'nova',
});

// Check if provider supports streaming
console.log(tts.supportsStreaming('pcm'));  // true for OpenAI

// Stream PCM audio chunks
for await (const chunk of tts.synthesizeStream('Hello, world!', { format: 'pcm' })) {
  if (chunk.audio.length > 0) {
    // Process raw PCM data (24kHz, 16-bit signed LE, mono)
    playPCMChunk(chunk.audio);
  }
  if (chunk.isFinal) break;
}

// Non-streaming providers gracefully fall back to buffered synthesis
// (yields a single chunk with isFinal: true)

import { VoiceStream } from 'oneringai';

const voice = VoiceStream.create({
  ttsConnector: 'openai',
  ttsModel: 'tts-1-hd',
  voice: 'nova',
  format: 'mp3',       // MP3 recommended for broad compatibility
  streaming: false,     // Set true + format 'pcm' for low-latency streaming
});

// Wraps agent stream — text events pass through, audio events interleaved
for await (const event of voice.wrap(agent.stream('Tell me a story'))) {
  if (event.type === 'response.output_text.delta') {
    process.stdout.write(event.delta);
  } else if (event.type === 'response.audio_chunk.ready') {
    playAudio(event.audio_base64, event.format);
  }
}

Connector.create({
  name: 'xai',
  vendor: Vendor.Grok,
  auth: { type: 'api_key', apiKey: process.env.XAI_API_KEY! },
});

const xaiTTS = TextToSpeech.create({
  connector: 'xai', model: 'xai-tts', voice: 'eve',
});

for await (const chunk of xaiTTS.synthesizeStream('[laugh] Hello!', {
  format: 'mulaw',
  vendorOptions: {
    language: 'en',
    sample_rate: 8000,
    optimize_streaming_latency: 2, // xAI accepts levels 0, 1, and 2
  },
})) {
  if (chunk.audio.length) sendToPhone(chunk.audio);
}

import { Connector, SpeechToText, Vendor } from 'oneringai';

// Setup connector
Connector.create({
  name: 'openai',
  vendor: Vendor.OpenAI,
  auth: { type: 'api_key', apiKey: process.env.OPENAI_API_KEY! },
});

// Create STT instance
const stt = SpeechToText.create({
  connector: 'openai',
  model: 'gpt-transcribe',
});

// Transcribe from file path
const result = await stt.transcribeFile('./audio.mp3');
console.log(result.text);

// Transcribe from Buffer
import * as fs from 'fs/promises';
const audioBuffer = await fs.readFile('./audio.mp3');
const result2 = await stt.transcribe(audioBuffer);

const telephoneAudio = await stt.transcribe(pcm16le8kBuffer, {
  encoding: 'pcm',       // 'pcm', 'mulaw', or 'alaw'
  sampleRate: 8000,
});

// Whisper remains available when word/segment timestamp formats are required.
const timestampedStt = SpeechToText.create({
  connector: 'openai',
  model: 'whisper-1',
});

// Word-level timestamps
const withWords = await timestampedStt.transcribeWithTimestamps(audioBuffer, 'word');
console.log(withWords.words);
// [
//   { word: 'Hello', start: 0.0, end: 0.5 },
//   { word: 'world', start: 0.6, end: 1.1 },
// ]

// Segment-level timestamps
const withSegments = await timestampedStt.transcribeWithTimestamps(audioBuffer, 'segment');
console.log(withSegments.segments);
// [
//   { id: 0, text: 'Hello world.', start: 0.0, end: 1.5 },
// ]

const googleResult = await googleStt.transcribe(audio, {
  language: 'en',
  includeTimestamps: true,
  timestampGranularity: 'segment',
  vendorOptions: {
    customVocabulary: ['OneRingAI'],
    diarizationMode: 'speaker',
  },
});

const stt = SpeechToText.create({
  connector: 'openai',
  model: 'whisper-1',
  language: 'fr', // default source-language hint for transcribe and translate
});

// Translate French audio to English
const english = await stt.translate(frenchAudioBuffer);
const germanHint = await stt.translate(germanAudioBuffer, { language: 'de' });
console.log(english.text);  // English translation

// JSON (default)
const json = await stt.transcribe(audio, { outputFormat: 'json' });

// Plain text
const text = await stt.transcribe(audio, { outputFormat: 'text' });

// Subtitles (SRT format)
const srt = await stt.transcribe(audio, { outputFormat: 'srt' });

// WebVTT format
const vtt = await stt.transcribe(audio, { outputFormat: 'vtt' });

// Verbose JSON (includes all metadata)
const verbose = await stt.transcribe(audio, { outputFormat: 'verbose_json' });

// Provide language hint for better accuracy
const result = await stt.transcribe(audio, { language: 'fr' });  // French
const result2 = await stt.transcribe(audio, { language: 'es' }); // Spanish

const liveSTT = SpeechToText.create({ connector: 'xai', model: 'xai-stt' });

for await (const event of liveSTT.transcribeStream(microphoneChunks(), {
  sampleRate: 16000,
  encoding: 'pcm',
  interimResults: true,
  language: 'en',
  vendorOptions: {
    keyterms: ['OneRingAI'],
    smart_turn: 0.7,
    smart_turn_timeout: 3000,
  },
})) {
  if (event.type === 'transcript') {
    renderTranscript(event.text ?? '', { final: event.isFinal });
  }
}

// Get model information
const info = stt.getModelInfo();
console.log(info.capabilities.features.diarization);  // Speaker identification

// Check feature support
const supportsTranslation = stt.supportsFeature('translation');
const supportsDiarization = stt.supportsFeature('diarization');

// Get supported formats
const inputFormats = stt.getSupportedInputFormats();
const outputFormats = stt.getSupportedOutputFormats();

// Get timestamp granularities
const granularities = stt.getTimestampGranularities();  // model-specific

import { Connector, Agent, TextToSpeech, SpeechToText, Vendor } from 'oneringai';

// Setup
Connector.create({
  name: 'openai',
  vendor: Vendor.OpenAI,
  auth: { type: 'api_key', apiKey: process.env.OPENAI_API_KEY! },
});

const stt = SpeechToText.create({ connector: 'openai', model: 'gpt-transcribe' });
const agent = Agent.create({ connector: 'openai', model: 'gpt-5.6-terra' });
const tts = TextToSpeech.create({ connector: 'openai', model: 'tts-1-hd', voice: 'nova' });

// Voice assistant pipeline
async function voiceAssistant(audioInput: Buffer): Promise<Buffer> {
  // 1. Speech → Text
  const transcription = await stt.transcribe(audioInput);
  console.log('User said:', transcription.text);

  // 2. Text → AI Response
  if (!transcription.text) throw new Error('No transcript returned');
  const response = await agent.run(transcription.text);
  console.log('Agent response:', response.output_text);

  // 3. Text → Speech
  const audioResponse = await tts.synthesize(response.output_text ?? '');
  return audioResponse.audio;
}

import { calculateTTSCost, calculateSTTCost } from 'oneringai';

// TTS cost (per 1,000 characters)
const ttsCost = calculateTTSCost('tts-1-hd', 5000);  // 5000 characters
console.log(`TTS cost: $${ttsCost}`);  // $0.15

// STT cost (per minute)
const sttCost = calculateSTTCost('gpt-transcribe', 300);  // 5 minutes
console.log(`STT cost: $${sttCost}`);  // $0.0225

// Groq is much cheaper for STT
const groqCost = calculateSTTCost('whisper-large-v3', 300);  // 5 minutes
console.log(`Groq STT cost: $${groqCost}`);  // $0.0025

const xaiStreaming = calculateSTTCost('xai-stt', 300, { streaming: true });