Skip to content

feat: add macOS say as alternative TTS engine#989

Open
hydrohelix wants to merge 4 commits intodanielmiessler:mainfrom
hydrohelix:feature/voice-server-macos-say
Open

feat: add macOS say as alternative TTS engine#989
hydrohelix wants to merge 4 commits intodanielmiessler:mainfrom
hydrohelix:feature/voice-server-macos-say

Conversation

@hydrohelix
Copy link
Copy Markdown

Summary

  • Adds macOS built-in say command as an alternative TTS engine alongside ElevenLabs
  • Configurable via settings.json (voice.tts_engine: "macos-say") or TTS_ENGINE env var
  • Auto-falls back to macOS say when no ElevenLabs API key is present
  • Adds voice CLI script for easy engine switching and server management
  • install.sh symlinks the CLI to /usr/local/bin/voice for universal access

Changes

  • VoiceServer/server.ts — TTS engine abstraction: speakWithSay() function, engine branching in sendNotification(), updated /health endpoint and startup logs
  • VoiceServer/voice — New CLI: voice say [name] [rate], voice 11labs, voice status, voice test, voice restart, voice log, voice voices
  • VoiceServer/install.sh — Symlinks voice CLI to /usr/local/bin with permission fallback
  • VoiceServer/uninstall.sh — Removes the symlink on uninstall
  • .gitignore — Adds .local-backup/ for user customizations

Configuration

{
  "voice": {
    "tts_engine": "macos-say",
    "macos_say": {
      "voice": "Samantha",
      "rate": 200
    }
  }
}

Or via env var: TTS_ENGINE=macos-say

Test plan

  • voice say switches engine and restarts server
  • voice 11labs switches back to ElevenLabs
  • voice status shows correct engine and server health
  • voice test produces audible speech with both engines
  • Server auto-falls back to macOS say when ELEVENLABS_API_KEY is missing
  • curl localhost:8888/health reflects active engine in response
  • Pronunciation rules apply to both engines
  • Volume control works with macOS say (renders AIFF, plays via afplay)
  • install.sh creates /usr/local/bin/voice symlink
  • uninstall.sh removes the symlink

🤖 Generated with Claude Code

hydrohelix and others added 4 commits March 23, 2026 21:49
Adds support for switching between ElevenLabs and macOS built-in `say`
command, so users without an ElevenLabs API key (or who prefer local TTS)
can still use voice notifications.

Config via settings.json (`voice.tts_engine`) or `TTS_ENGINE` env var.
Auto-falls back to macOS say when ElevenLabs key is missing.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Adds `voice` script for easy switching between ElevenLabs and macOS say,
plus server management (restart, status, test, log tailing).

Usage: voice say [name] [rate] | voice 11labs | voice status | voice test

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
install.sh now symlinks the voice script to /usr/local/bin/voice for
universal PATH access. Falls back gracefully if permissions are denied.
uninstall.sh removes the symlink.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Adds /mute and /unmute API endpoints (in-memory toggle, no restart needed)
and corresponding `voice mute` / `voice unmute` CLI commands.
Status and /health endpoint reflect muted state.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant