SpeakEasy

A unified speech library for all your projects with support for multiple TTS providers and clean configuration structure.

Requirements

• Node.js >= 22.5 or Bun >= 1.0 (built-in SQLite cache)
• macOS for system voice and audio playback

Key Features

Intelligent Caching System

• 16x faster repeated playback with built-in SQLite (node:sqlite / bun:sqlite)
• Automatic cache management with TTL and size limits
• Content-aware deduplication prevents redundant API calls
• Comprehensive analytics and cache inspection tools

Centralized Configuration

• Single config file at ~/.config/speakeasy/settings.json
• No more scattered API keys - configure once, use everywhere
• Global defaults with per-call overrides
• Environment variable integration

Core Capabilities

• Multiple TTS Providers: System (macOS), OpenAI, ElevenLabs, Groq
• Smart Fallbacks: Automatic provider switching on failure
• Volume Control: Precise control without affecting system volume
• Queue Management: Priority-based speech queue with interruption
• TypeScript: Full type safety and IntelliSense support

Installation

npm install @arach/speakeasy

Quick Start

import { say } from '@arach/speakeasy';

await say('Hello world!');                    // system voice
await say('Hello!', 'openai');                // OpenAI TTS
await say('Hello!', 'elevenlabs');            // ElevenLabs TTS
await say('Hello!', 'groq');                  // Groq TTS

Performance Impact

Caching makes a dramatic difference:

Documentation Index

Quick Start

• CLI Reference - Complete command-line documentation
• SDK Guide - TypeScript SDK usage and examples

Configuration

• Configuration Guide - Complete configuration options
• Providers Guide - Provider-specific setup and features
• Cache System - Cache management and optimization

Support

• Troubleshooting - Common issues and solutions

Quick Navigation

For Developers

1. Start here: SDK Guide - Learn the TypeScript API
2. Configuration: Configuration Guide - Set up API keys and defaults
3. Providers: Providers Guide - Choose and configure TTS providers

For CLI Users

1. Start here: CLI Reference - Learn command-line usage
2. Setup: Configuration Guide - Configure global settings
3. Troubleshooting: Troubleshooting - Fix common issues

For System Administrators

1. Configuration: Configuration Guide - Global deployment settings
2. Cache Management: Cache System - Optimize performance and storage
3. Provider Setup: Providers Guide - API key management

Feature Documentation

Core Features

• Multi-Provider Support - System, OpenAI, ElevenLabs, Groq
• Smart Caching - SQLite cache with metadata (no extra deps)
• Queue Management - Priority-based speech queue
• Rate Control - Customizable speech rate (WPM)
• Volume Control - Precise volume without affecting system
• Auto Fallbacks - Intelligent provider fallback on failure

CLI Features

• Global Configuration - ~/.config/speakeasy/settings.json
• Cache Management - List, search, play, and clear cached audio
• Health Diagnostics - --doctor and --diagnose commands
• Debug Mode - Detailed logging with --debug

SDK Features

• TypeScript Support - Full type safety and IntelliSense
• Convenience Functions - say() and speak() for quick usage
• Class-based API - SpeakEasy class for advanced control
• Event Handling - Promise-based async operations
• Error Recovery - Graceful fallback patterns

API Reference

CLI Commands Quick Reference

SDK Quick Reference

// Quick functions
await say('Hello world');                    // System voice
await say('Hello world', 'openai');          // Specific provider

// Class usage
const speaker = new SpeakEasy({
  provider: 'openai',
  openaiVoice: 'nova',
  rate: 180,
  cache: { enabled: true }
});

await speaker.speak('Hello world');

Configuration Quick Reference

Global Configuration File

Location: ~/.config/speakeasy/settings.json

{
  "providers": {
    "openai": { "enabled": true, "voice": "nova", "apiKey": "sk-..." },
    "elevenlabs": { "enabled": true, "voiceId": "...", "apiKey": "..." },
    "system": { "enabled": true, "voice": "Samantha" },
    "groq": { "enabled": true, "voice": "tara", "apiKey": "gsk_..." }
  },
  "defaults": {
    "provider": "system",
    "fallbackOrder": ["system", "openai", "elevenlabs"],
    "rate": 180,
    "volume": 0.7
  },
  "cache": {
    "enabled": true,
    "ttl": "7d",
    "maxSize": "100mb"
  }
}

Environment Variables

export OPENAI_API_KEY="sk-..."
export ELEVENLABS_API_KEY="..."
export GROQ_API_KEY="gsk_..."

Use Case Examples

Development Notifications

# Build completion
speakeasy "Build completed successfully" --provider system

# Error alerts
speakeasy "Build failed with errors" --provider openai --voice nova

Claude Code Integration

import { say } from '@arach/speakeasy';

export async function speakNotification(message: string, project: string) {
  await say(`In ${project}, ${message}`, 'openai');
}

Accessibility

const speaker = new SpeakEasy({
  provider: 'elevenlabs',
  volume: 0.8,
  cache: { enabled: true }
});

await speaker.speak('Screen reader text', { priority: 'high' });

Troubleshooting Quick Fixes

Common Issues

# API key missing
export OPENAI_API_KEY="your-key-here"

# Cache not working
speakeasy "test" --cache --provider openai

# System voice not working (non-macOS)
speakeasy "test" --provider openai

# Network issues
speakeasy "fallback" --provider system

# Configuration errors
speakeasy --doctor

Performance Guide

Cache Performance

• OpenAI TTS: ~800ms to ~50ms (16x faster with cache)
• ElevenLabs: ~1200ms to ~50ms (24x faster with cache)
• System Voice: ~100ms (no cache needed)

Best Practices

• Enable caching for API providers
• Use consistent text for better cache hits
• Choose appropriate TTL for your use case
• Monitor cache size with --stats

Contributing

See the main README for contribution guidelines.

License

MIT License - see LICENSE for details.

Need help? Start with the Troubleshooting Guide or run speakeasy --doctor for diagnostics.