← Back to Home

API Reference

TypeScript interfaces and types

v0.2.12

Documentation

GitHubNPM Package

API Reference

Interfaces

SpeakEasyConfig

Main configuration for SpeakEasy instances.

PropertyTypeRequiredDefaultDescription
provider'system' | 'openai' | 'elevenlabs' | 'groq' | 'gemini'No'system'TTS provider
systemVoicestringNo'Samantha'macOS voice name
openaiVoice'alloy' | 'echo' | 'fable' | 'onyx' | 'nova' | 'shimmer'No'nova'OpenAI voice
elevenlabsVoiceIdstringNo'EXAVITQu4vr4xnSDxMaL'ElevenLabs voice ID
groqVoicestringNo'tara'Groq Orpheus voice
geminiModelstringNo'gemini-2.5-flash-preview-tts'Gemini model
ratenumberNo180Speech rate (WPM)
volumenumberNo0.7Volume (0.0-1.0)
instructionsstringNo-OpenAI-only steering instructions
apiKeysApiKeysNo-API keys object
tempDirstringNo'/tmp'Temp file directory
debugbooleanNofalseEnable debug logging
cacheCacheConfigNo-Cache configuration

ApiKeys

typescript
interface ApiKeys {
  openai?: string;
  elevenlabs?: string;
  groq?: string;
  gemini?: string;
}

CacheConfig

typescript
interface CacheConfig {
  enabled?: boolean;      // Auto-enabled for API providers
  ttl?: string | number;  // '7d', '1h', 86400000
  maxSize?: string | number; // '100mb', '1gb', 104857600
  dir?: string;           // Cache directory path
}

SpeakEasyOptions

Options for individual speak calls.

PropertyTypeRequiredDefaultDescription
priority'high' | 'normal' | 'low'No'normal'Queue priority
interruptbooleanNofalseStop current speech
cleanupbooleanNotrueDelete temp files
silentbooleanNofalseGenerate without playing

Provider

Interface all TTS providers must implement.

typescript
interface Provider {
  speak(config: ProviderConfig): Promise<void>;
  validateConfig(): boolean;
  getErrorMessage(error: any): string;
}

ProviderConfig

typescript
interface ProviderConfig {
  text: string;
  rate: number;
  tempDir: string;
  voice?: string;
  apiKey?: string;
  volume?: number;
  instructions?: string;
}

GlobalConfig

Structure of ~/.config/speakeasy/settings.json.

typescript
interface GlobalConfig {
  providers?: {
    openai?: { enabled?: boolean; voice?: string; model?: string; apiKey?: string; instructions?: string };
    elevenlabs?: { enabled?: boolean; voiceId?: string; modelId?: string; apiKey?: string };
    system?: { enabled?: boolean; voice?: string };
    groq?: { enabled?: boolean; voice?: string; apiKey?: string };
    gemini?: { enabled?: boolean; model?: string; apiKey?: string };
  };
  defaults?: {
    provider?: string;
    fallbackOrder?: string[];
    rate?: number;
    volume?: number;
  };
  global?: {
    tempDir?: string;
    cleanup?: boolean;
  };
  cache?: CacheConfig;
}

Classes

SpeakEasy

Main class for text-to-speech.

Constructor

typescript
new SpeakEasy(config?: SpeakEasyConfig)

Methods

MethodSignatureDescription
speak(text: string, options?: SpeakEasyOptions) => Promise<void>Speak text with options
stopSpeaking() => voidStop current playback
getCacheStats() => Promise<CacheStats>Get cache statistics
getCacheMetadata() => Promise<CacheEntry[]>Get all cache entries
findByText(text: string) => Promise<CacheEntry[]>Search cache by text
findByProvider(provider: string) => Promise<CacheEntry[]>Filter cache by provider
clearCache() => Promise<void>Clear all cached audio

TTSCache

SQLite audio cache using Node.js built-in node:sqlite.

Constructor

typescript
new TTSCache(dir: string, ttl?: string | number, maxSize?: string | number)

Methods

MethodSignatureDescription
get(key: string) => Promise<CacheEntry | null>Get cached entry
set(key: string, filePath: string, metadata: object) => Promise<void>Store entry
delete(key: string) => Promise<void>Delete entry
clear() => Promise<void>Clear all entries
getStats() => Promise<CacheStats>Get statistics
cleanup() => Promise<void>Remove expired entries

Convenience Functions

say

Quick one-liner for speech.

typescript
async function say(
  text: string,
  provider?: 'system' | 'openai' | 'elevenlabs' | 'groq' | 'gemini',
  options?: { volume?: number; cache?: boolean }
): Promise<void>

Examples:

typescript
await say('Hello world');                     // System voice
await say('Hello', 'openai');                 // OpenAI
await say('Hello', 'groq', { volume: 0.5 });  // Groq at 50% volume

speak

Full-featured speech with options.

typescript
async function speak(
  text: string,
  options?: SpeakEasyOptions & { provider?: string; volume?: number }
): Promise<void>

Examples:

typescript
await speak('Hello', { priority: 'high' });
await speak('Hello', { provider: 'openai', interrupt: true });

Provider-Specific Notes

OpenAI

  • Voices: alloy, echo, fable, onyx, nova, shimmer
  • Models: tts-1 (fast), tts-1-hd (quality)
  • Supports instructions for voice steering

ElevenLabs

Groq

  • Model: canopylabs/orpheus-v1-english
  • Voices: tara, leah, jess, mia, zoe, leo, dan, zac
  • Requires terms acceptance at Groq console

Gemini

  • Model: gemini-2.5-flash-preview-tts
  • Uses Google Generative AI SDK

System (macOS)

  • Uses say command
  • List voices: say -v ?
  • Common: Samantha, Alex, Victoria, Daniel