{"_id":"@claude-hooks/voice-vault","name":"@claude-hooks/voice-vault","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@claude-hooks/voice-vault","version":"0.2.0","description":"TTS package with intelligent caching to maximize free tier usage","repository":{"type":"git","url":"git+https://github.com/nathanvale/bun-changesets-template.git","directory":"packages/voice-vault"},"sideEffects":false,"type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./cache":{"types":"./dist/cache/index.d.ts","import":"./dist/cache/index.js"},"./providers":{"types":"./dist/providers/index.d.ts","import":"./dist/providers/index.js"},"./logging":{"types":"./dist/logging/index.d.ts","import":"./dist/logging/index.js"},"./audio":{"types":"./dist/audio/index.d.ts","import":"./dist/audio/index.js"}},"types":"./dist/index.d.ts","dependencies":{"@elevenlabs/elevenlabs-js":"^2.8.0","@orchestr8/logger":"^2.0.0","openai":"^5.12.0"},"devDependencies":{"@types/node":"^22.5.4","dotenv":"^17.2.1","tsx":"^4.20.5","typescript":"^5.8.3","vitest":"^3.2.4"},"publishConfig":{"access":"public","provenance":true},"scripts":{"build":"tsup","clean":"rm -rf dist .tsbuildinfo logs/voice-vault","lint":"eslint . --cache --cache-location ../../.eslintcache/voice-vault","test":"vitest run","test:all":"npm run test:cache && npm run test:fallback && npm run test:errors && npm run test:concurrent","test:cache":"tsx src/test-cache-validation.ts","test:ci":"vitest run --bail 1","test:concurrent":"tsx src/test-concurrent.ts","test:elevenlabs":"tsx src/test-elevenlabs.ts","test:errors":"tsx src/test-error-handling.ts","test:fallback":"tsx src/test-provider-fallback.ts","test:openai":"tsx src/test-openai.ts","test:openai:simple":"tsx src/test-openai-simple.ts","typecheck":"tsc --noEmit"},"_id":"@claude-hooks/voice-vault@0.2.0","bugs":{"url":"https://github.com/nathanvale/bun-changesets-template/issues"},"homepage":"https://github.com/nathanvale/bun-changesets-template#readme","_integrity":"sha512-9ON69LxlNPa60fAr9bpU6mH/wEhcS9FlKMgOuR5i+d9aFJFHspuC1KLYhIshfKEN2pD0I86ibzjV8P/jDdz99A==","_resolved":"/tmp/65c3e13e855ddb3007b055f2e6687c6d/claude-hooks-voice-vault-0.2.0.tgz","_from":"file:claude-hooks-voice-vault-0.2.0.tgz","_nodeVersion":"20.18.1","_npmVersion":"10.8.2","dist":{"integrity":"sha512-9ON69LxlNPa60fAr9bpU6mH/wEhcS9FlKMgOuR5i+d9aFJFHspuC1KLYhIshfKEN2pD0I86ibzjV8P/jDdz99A==","shasum":"08d08a83abd97d22a1d4d523f98717d8340ae657","tarball":"https://registry.npmjs.org/@claude-hooks/voice-vault/-/voice-vault-0.2.0.tgz","fileCount":20,"unpackedSize":115227,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@claude-hooks%2fvoice-vault@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD4ME+/pP24UCbT+wp+ecgfPRNwx6WLaBMqBhurz2mR0gIhAIch0OsR22LnoGgJcmxi+SdGCsz46N0nPl9tFw5gs9VE"}]},"_npmUser":{"name":"nathanvale","email":"hi@nathanvale.com"},"directories":{},"maintainers":[{"name":"nathanvale","email":"hi@nathanvale.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/voice-vault_0.2.0_1758067815291_0.11928650726960988"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-17T00:10:15.218Z","0.2.0":"2025-09-17T00:10:15.539Z","modified":"2025-09-17T00:10:16.045Z"},"maintainers":[{"name":"nathanvale","email":"hi@nathanvale.com"}],"description":"TTS package with intelligent caching to maximize free tier usage","homepage":"https://github.com/nathanvale/bun-changesets-template#readme","repository":{"type":"git","url":"git+https://github.com/nathanvale/bun-changesets-template.git","directory":"packages/voice-vault"},"bugs":{"url":"https://github.com/nathanvale/bun-changesets-template/issues"},"readme":"# Voice Vault 🎙️\n\n> High-performance Text-to-Speech caching library with multi-provider support\n\nVoice Vault is a production-ready Text-to-Speech (TTS) package that reduces API\ncosts through intelligent caching, provides multiple provider support with\nautomatic fallback, and offers complete observability through correlation ID\ntracking.\n\n## Features\n\n- 🎯 **Zero-config usage** - Works immediately with `new VoiceVault()`\n- 💾 **Smart caching** - Reduces API calls by 80%+ for repeated phrases\n- 🔗 **Correlation ID tracking** - Every operation traceable with `vv-` prefixed\n  IDs\n- 📊 **Comprehensive logging** - Structured logs with @orchestr8/logger\n- 🔄 **Provider fallback** - Automatic fallback: OpenAI → ElevenLabs → System\n- 🚀 **ADHD-optimized** - Simple mental model, minimal cognitive load\n- 📈 **Performance metrics** - Cache hit rates, API savings, operation timing\n\n## Installation\n\n```bash\npnpm add @template/voice-vault\n```\n\n## Quick Start\n\n### Zero Configuration\n\n```typescript\nimport VoiceVault from '@template/voice-vault'\n\nconst vault = new VoiceVault()\nawait vault.speak('Hello world!') // Just works!\n```\n\n### With Configuration\n\n```typescript\nconst vault = new VoiceVault({\n  provider: 'openai',\n  cache: {\n    enabled: true,\n    maxSizeMB: 100,\n    maxAgeDays: 30,\n  },\n  logging: {\n    level: 'debug',\n    dir: './logs',\n  },\n})\n\nconst result = await vault.speak('Build successful!')\nconsole.log(`Correlation ID: ${result.correlationId}`)\n```\n\n## API Reference\n\n### Core Methods\n\n#### `speak(text: string, options?: SpeakOptions): Promise<SpeakResult>`\n\nConverts text to speech and plays the audio.\n\n```typescript\nconst result = await vault.speak('Deploy complete', {\n  correlationId: 'deploy-123', // Optional: provide your own\n  voice: 'alloy', // Provider-specific voice\n  speed: 1.0, // Playback speed\n})\n\n// Result includes:\n// - success: boolean\n// - correlationId: string (for tracing)\n// - providerName: string (which provider was used)\n// - fromCache: boolean\n// - durationMs: number\n```\n\n#### `preload(text: string, options?: PreloadOptions): Promise<PreloadResult>`\n\nPre-caches text for faster playback later.\n\n```typescript\nawait vault.preload('Welcome back!') // Warm the cache\n```\n\n#### `getCacheStats(): Promise<CacheStats>`\n\nReturns cache performance metrics.\n\n```typescript\nconst stats = await vault.getCacheStats()\nconsole.log(`Cache hit rate: ${stats.hitRate}%`)\nconsole.log(`API calls saved: ${stats.apiCallsSaved}`)\n```\n\n#### `clearCache(): Promise<void>`\n\nClears all cached audio files.\n\n```typescript\nawait vault.clearCache() // Clean up when needed\n```\n\n## Correlation ID Tracking\n\nEvery operation in Voice Vault is tracked with a correlation ID for complete\nobservability:\n\n### Automatic Generation\n\n```typescript\nconst vault = new VoiceVault()\nconst result = await vault.speak('Test message')\n// Correlation ID automatically generated: vv-abc123-def456\nconsole.log(`Check logs for: ${result.correlationId}`)\n```\n\n### Manual Correlation\n\n```typescript\nconst correlationId = 'vv-custom-trace-id'\nawait vault.speak('Important message', { correlationId })\n// All operations use your provided ID\n```\n\n### Log Tracing\n\nLogs are structured with correlation IDs for easy tracing:\n\n```log\n[2025-01-23T10:30:45.123Z] [INFO] [correlation-id: vv-abc123-def456] [VoiceVault] TTS operation started\n  text_length: 18\n  cache_enabled: true\n  provider: openai\n\n[2025-01-23T10:30:45.245Z] [INFO] [correlation-id: vv-abc123-def456] [VoiceVault.Cache] Cache HIT\n  file_path: ~/.voice-vault-cache/5f4d3e2b1a.mp3\n  age_days: 2\n  api_calls_saved: 47\n\n[2025-01-23T10:30:46.789Z] [INFO] [correlation-id: vv-abc123-def456] [VoiceVault] Operation complete\n  total_duration_ms: 1566\n  from_cache: true\n```\n\n## Provider Configuration\n\n### OpenAI\n\n```typescript\nconst vault = new VoiceVault({\n  provider: 'openai',\n  providerConfig: {\n    apiKey: process.env.OPENAI_API_KEY,\n    model: 'tts-1-hd',\n    voice: 'alloy',\n    speed: 1.0,\n  },\n})\n```\n\n### ElevenLabs\n\n```typescript\nconst vault = new VoiceVault({\n  provider: 'elevenlabs',\n  providerConfig: {\n    apiKey: process.env.ELEVENLABS_API_KEY,\n    voiceId: 'voice_id_here',\n    modelId: 'eleven_turbo_v2_5',\n  },\n})\n```\n\n### System (macOS/Windows/Linux)\n\n```typescript\nconst vault = new VoiceVault({\n  provider: 'system', // Uses platform native TTS\n})\n```\n\n## Environment Variables\n\nVoice Vault automatically detects API keys from environment variables, making it\neasy to use in different environments without hardcoding credentials.\n\n### Supported Environment Variables\n\n```bash\n# OpenAI TTS Provider\nOPENAI_API_KEY=sk-proj-...\n\n# ElevenLabs TTS Provider\nELEVENLABS_API_KEY=sk_...\n```\n\n### Setting Up Environment Variables\n\n#### For Local Development\n\nCreate a `.env` file in your project root:\n\n```bash\n# .env\nOPENAI_API_KEY=your-openai-api-key-here\nELEVENLABS_API_KEY=your-elevenlabs-api-key-here\n```\n\nThen load it in your application:\n\n```typescript\n// Using dotenv (for Node.js)\nimport 'dotenv/config'\nimport { VoiceVault } from '@template/voice-vault'\n\nconst vault = new VoiceVault()\n// API keys are automatically detected from process.env\n```\n\n#### For Production\n\nSet environment variables in your deployment platform:\n\n- **Vercel**: Add in project settings → Environment Variables\n- **Heroku**: Use `heroku config:set OPENAI_API_KEY=...`\n- **Docker**: Pass with `-e OPENAI_API_KEY=...` or use docker-compose\n- **CI/CD**: Add as secrets in GitHub Actions, GitLab CI, etc.\n\n### Configuration Priority\n\nVoice Vault uses the following priority for configuration:\n\n1. **Programmatic configuration** (highest priority)\n2. **Environment variables**\n3. **Default values** (lowest priority)\n\n```typescript\n// This will override the environment variable\nconst vault = new VoiceVault({\n  providerConfig: {\n    apiKey: 'override-api-key', // Takes precedence over OPENAI_API_KEY\n  },\n})\n\n// This will use the environment variable\nconst vault = new VoiceVault()\n// Uses OPENAI_API_KEY from environment\n```\n\n## Logging Configuration\n\nVoice Vault uses @orchestr8/logger for structured logging:\n\n### Log Levels\n\n```typescript\nconst vault = new VoiceVault({\n  logging: {\n    level: 'debug', // trace | debug | info | warn | error\n    dir: './logs', // Output directory\n    pretty: true, // Human-readable format\n  },\n})\n```\n\n### Environment Variables\n\n```bash\nLOG_LEVEL=debug\nLOG_PRETTY=true\nVOICE_VAULT_LOG_DIR=./logs\n```\n\n## Cache Management\n\n### Cache Configuration\n\n```typescript\nconst vault = new VoiceVault({\n  cache: {\n    enabled: true,\n    maxSizeMB: 100, // Maximum cache size\n    maxAgeDays: 30, // Maximum age of entries\n    maxEntries: 1000, // Maximum number of files\n    cacheDir: '~/.voice-vault-cache',\n  },\n})\n```\n\n### Caching Strategy\n\nVoice Vault implements intelligent caching to optimize costs and performance:\n\n- **Paid Providers (OpenAI, ElevenLabs)**: Audio responses are cached to reduce\n  API costs\n- **Free System TTS**: Not cached since there's no API cost\n- **Cache Key Generation**: Based on normalized text + voice + speed + provider\n  settings\n- **LRU Eviction**: Automatically removes least recently used entries when cache\n  is full\n- **TTL Expiration**: Entries expire after configured maxAgeDays\n\n```typescript\n// Example: OpenAI responses are cached\nconst result1 = await vault.speak('Hello', { provider: 'openai' })\n// Makes API call, caches result\n\nconst result2 = await vault.speak('Hello', { provider: 'openai' })\n// Uses cached audio, no API call\n\n// System TTS is never cached\nconst result3 = await vault.speak('Hello', { provider: 'system' })\n// Always generates fresh audio\n```\n\n### Cache Statistics\n\nMonitor cache performance:\n\n```typescript\nconst stats = await vault.getCacheStats()\nconsole.log({\n  hitRate: stats.hitRate,\n  totalRequests: stats.totalRequests,\n  cacheHits: stats.cacheHits,\n  cacheMisses: stats.cacheMisses,\n  apiCallsSaved: stats.apiCallsSaved,\n  diskUsageMB: stats.totalSizeMB,\n})\n```\n\n## Error Handling\n\nVoice Vault provides graceful error handling with provider fallback:\n\n```typescript\ntry {\n  const result = await vault.speak('Test message')\n  if (!result.success) {\n    console.error(`TTS failed: ${result.error}`)\n    // Check correlation ID in logs for details\n    console.log(`Debug with: ${result.correlationId}`)\n  }\n} catch (error) {\n  // Only thrown for critical errors\n  console.error('Critical error:', error)\n}\n```\n\n## Examples\n\n### Basic Usage\n\n```typescript\nimport VoiceVault from '@template/voice-vault'\n\nconst vault = new VoiceVault()\n\n// Simple usage\nawait vault.speak('Hello world!')\n\n// With options\nawait vault.speak('Build complete', {\n  voice: 'nova',\n  speed: 1.2,\n})\n\n// Check cache\nconst stats = await vault.getCacheStats()\nconsole.log(`Saved ${stats.apiCallsSaved} API calls`)\n```\n\n### Advanced Configuration\n\n```typescript\nconst vault = new VoiceVault({\n  provider: 'openai',\n  providerConfig: {\n    apiKey: process.env.OPENAI_API_KEY,\n    model: 'tts-1-hd',\n    voice: 'alloy',\n  },\n  cache: {\n    enabled: true,\n    maxSizeMB: 200,\n    maxAgeDays: 60,\n  },\n  logging: {\n    level: 'info',\n    dir: './logs',\n  },\n})\n\n// Preload common phrases\nawait vault.preload('Welcome back!')\nawait vault.preload('Task completed!')\n\n// Use with correlation tracking\nconst correlationId = `user-${userId}-session-${sessionId}`\nawait vault.speak('Welcome back!', { correlationId })\n```\n\n### Debugging with Logs\n\n```typescript\n// Enable debug logging\nconst vault = new VoiceVault({\n  logging: { level: 'debug' },\n})\n\nconst result = await vault.speak('Debug test')\n\n// Find all logs for this operation\nconsole.log(`grep \"${result.correlationId}\" logs/*.log`)\n```\n\n## Architecture\n\nVoice Vault is built with a modular architecture:\n\n- **Cache Layer**: Intelligent audio caching with LRU eviction\n- **Provider System**: Pluggable TTS providers with fallback\n- **Audio Player**: Cross-platform audio playback\n- **Logging Infrastructure**: Structured logging with correlation IDs\n\n## Performance\n\n- **Cache Hit Rate**: Typically 80%+ for repeated phrases\n- **Operation Overhead**: <5ms for cache hits\n- **API Latency**: 200-500ms for cache misses (provider dependent)\n- **Memory Usage**: ~10MB base + cache size\n\n## Development\n\n```bash\n# Install dependencies\npnpm install\n\n# Build the package\npnpm build\n\n# Run examples\npnpm example:basic\npnpm example:cache\npnpm example:logging\n```\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please ensure all operations include correlation ID\ntracking and comprehensive logging.\n\n---\n\nBuilt with 🧠 ADHD-friendly design principles and complete observability in\nmind.\n","readmeFilename":"README.md","_rev":"1-66a13b805a6681e71ee1345d0e2d00f4"}