askrobots / dbbasic-object-server
Public
Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.
danq9
signup: the person chooses the password and name on the confirm page
83c7aa6
2 weeks, 5 days ago
History
object_tts.py · 9.0 KB · 238 lines
| 1 | """Text-to-speech: shell out to whatever engine is on the box, cache the WAV. |
| 2 | |
| 3 | No bundled voice engine ships with the server. At call time we look for |
| 4 | the first of ``espeak-ng``, ``espeak``, or macOS ``say`` on ``PATH`` and |
| 5 | invoke it directly with the text as a real subprocess argument -- never |
| 6 | through a shell string, so there is no injection surface no matter what |
| 7 | the caller sends. Results are cached on disk keyed by engine, voice, and |
| 8 | text, so a repeated phrase (a common shell reply, a stock error message) |
| 9 | costs one synthesis instead of one per request. |
| 10 | |
| 11 | A second, unrelated path lives here too: ``synthesize_cloud``, which calls |
| 12 | OpenAI's dedicated TTS API instead of a local engine. It exists because the |
| 13 | local engines above are a real "not on device" gap -- ``say`` only runs on |
| 14 | macOS (explicitly dev-only, see ``synthesize``'s docstring) and the |
| 15 | production droplet only ever has ``espeak-ng``, which is intelligible but |
| 16 | robotic. Confirmed live before building this: a real ``gpt-4o-mini-tts`` |
| 17 | call, played back and round-tripped through OpenAI's own transcription API, |
| 18 | came back essentially word-for-word. Callers choose between the two paths; |
| 19 | neither silently falls back to the other, matching how this codebase |
| 20 | surfaces provider gaps elsewhere (object_ai.py) rather than hiding them. |
| 21 | """ |
| 22 | |
| 23 | from __future__ import annotations |
| 24 | |
| 25 | import hashlib |
| 26 | import json |
| 27 | import shutil |
| 28 | import subprocess |
| 29 | import tempfile |
| 30 | from pathlib import Path |
| 31 | from typing import Callable, Mapping |
| 32 | |
| 33 | from object_versions import DEFAULT_DATA_DIR |
| 34 | |
| 35 | TTS_CACHE_DIR = "tts-cache" |
| 36 | DEFAULT_TIMEOUT_SECONDS = 10.0 |
| 37 | ENGINE_CANDIDATES = ("espeak-ng", "espeak", "say") |
| 38 | |
| 39 | OPENAI_TTS_URL = "https://api.openai.com/v1/audio/speech" |
| 40 | DEFAULT_CLOUD_MODEL = "gpt-4o-mini-tts" |
| 41 | DEFAULT_CLOUD_VOICE = "alloy" |
| 42 | CLOUD_CONTENT_TYPE = "audio/mpeg" |
| 43 | |
| 44 | # send_http(url, headers, body_bytes) -> (status, response_bytes) -- the same |
| 45 | # shape object_ai.run_chat's caller injects, so the server owns the timeout |
| 46 | # and thread and tests run without a network. |
| 47 | SendHttp = Callable[[str, Mapping[str, str], bytes], tuple[int, bytes]] |
| 48 | |
| 49 | |
| 50 | class TTSEngineNotFoundError(RuntimeError): |
| 51 | """Raised when no supported speech engine is installed.""" |
| 52 | |
| 53 | |
| 54 | class TTSProviderError(RuntimeError): |
| 55 | """Raised when a cloud TTS call fails (bad key, rate limit, bad request).""" |
| 56 | |
| 57 | |
| 58 | class TTSSynthesisError(RuntimeError): |
| 59 | """Raised when the engine ran but failed, hung, or produced no audio.""" |
| 60 | |
| 61 | |
| 62 | class TTSNotSupportedError(RuntimeError): |
| 63 | """Raised when the only available engine can't produce WAV bytes here.""" |
| 64 | |
| 65 | |
| 66 | def discover_engine() -> tuple[str, str] | None: |
| 67 | """Return (name, path) for the first available engine, or None.""" |
| 68 | for name in ENGINE_CANDIDATES: |
| 69 | path = shutil.which(name) |
| 70 | if path: |
| 71 | return name, path |
| 72 | return None |
| 73 | |
| 74 | |
| 75 | def cache_path( |
| 76 | engine: str, |
| 77 | voice: str | None, |
| 78 | text: str, |
| 79 | *, |
| 80 | base_dir: Path | str = DEFAULT_DATA_DIR, |
| 81 | model: str | None = None, |
| 82 | ) -> Path: |
| 83 | """Return the cache file for one (engine, voice, text[, model]) tuple. |
| 84 | |
| 85 | The key hashes the engine name rather than its resolved path, so the |
| 86 | cache stays valid across machines where the binary lives somewhere |
| 87 | else. No eviction in v1 -- the cache only grows; operators wanting a |
| 88 | bound should prune ``data/tts-cache`` on a schedule of their choosing. |
| 89 | |
| 90 | ``model`` only ever comes from the cloud path (different OpenAI TTS |
| 91 | models sound different and cost different amounts) -- omitted, it |
| 92 | leaves local-engine cache keys byte-identical to before this existed. |
| 93 | """ |
| 94 | key = f"{engine}|{voice or ''}|{text}" |
| 95 | if model: |
| 96 | key += f"|{model}" |
| 97 | digest = hashlib.sha256(key.encode("utf-8")).hexdigest() |
| 98 | return Path(base_dir) / TTS_CACHE_DIR / f"{digest}.wav" |
| 99 | |
| 100 | |
| 101 | def synthesize( |
| 102 | text: str, |
| 103 | voice: str | None = None, |
| 104 | *, |
| 105 | base_dir: Path | str = DEFAULT_DATA_DIR, |
| 106 | timeout: float = DEFAULT_TIMEOUT_SECONDS, |
| 107 | ) -> tuple[bytes, bool]: |
| 108 | """Return (wav_bytes, from_cache) for one line of text. |
| 109 | |
| 110 | Raises TTSEngineNotFoundError, TTSNotSupportedError, or |
| 111 | TTSSynthesisError; callers map those to HTTP status codes. |
| 112 | """ |
| 113 | engine = discover_engine() |
| 114 | if engine is None: |
| 115 | raise TTSEngineNotFoundError( |
| 116 | "No speech engine found. Install espeak-ng or espeak " |
| 117 | "(or use macOS 'say' in development)." |
| 118 | ) |
| 119 | name, path = engine |
| 120 | |
| 121 | cached = cache_path(name, voice, text, base_dir=base_dir) |
| 122 | if cached.is_file(): |
| 123 | return cached.read_bytes(), True |
| 124 | |
| 125 | if name in ("espeak-ng", "espeak"): |
| 126 | audio = _synthesize_espeak(path, text, voice, timeout) |
| 127 | elif name == "say": |
| 128 | audio = _synthesize_say(text, voice, timeout) |
| 129 | else: # pragma: no cover - ENGINE_CANDIDATES is exhaustive |
| 130 | raise TTSEngineNotFoundError(f"Unsupported engine: {name}") |
| 131 | |
| 132 | _write_cache(cached, audio) |
| 133 | return audio, False |
| 134 | |
| 135 | |
| 136 | def synthesize_cloud( |
| 137 | text: str, |
| 138 | voice: str | None, |
| 139 | api_key: str, |
| 140 | *, |
| 141 | send_http: SendHttp, |
| 142 | model: str = DEFAULT_CLOUD_MODEL, |
| 143 | base_dir: Path | str = DEFAULT_DATA_DIR, |
| 144 | ) -> tuple[bytes, str, bool]: |
| 145 | """Return (audio_bytes, content_type, from_cache) via OpenAI's TTS API. |
| 146 | |
| 147 | Raises TTSProviderError on any non-2xx response; callers map that to |
| 148 | an HTTP status the same way the local-engine errors already are. |
| 149 | """ |
| 150 | cached = cache_path("openai", voice, text, base_dir=base_dir, model=model) |
| 151 | if cached.is_file(): |
| 152 | return cached.read_bytes(), CLOUD_CONTENT_TYPE, True |
| 153 | |
| 154 | payload = {"model": model, "input": text, "voice": voice or DEFAULT_CLOUD_VOICE} |
| 155 | headers = {"authorization": f"Bearer {api_key}", "content-type": "application/json"} |
| 156 | status, body = send_http(OPENAI_TTS_URL, headers, json.dumps(payload).encode("utf-8")) |
| 157 | if status >= 400: |
| 158 | raise TTSProviderError(_provider_error_detail(status, body)) |
| 159 | |
| 160 | _write_cache(cached, body) |
| 161 | return body, CLOUD_CONTENT_TYPE, False |
| 162 | |
| 163 | |
| 164 | def _provider_error_detail(status: int, body: bytes) -> str: |
| 165 | try: |
| 166 | payload = json.loads(body.decode("utf-8")) |
| 167 | except (UnicodeDecodeError, json.JSONDecodeError): |
| 168 | return f"Provider error (HTTP {status})" |
| 169 | detail = payload.get("error") |
| 170 | if isinstance(detail, dict): |
| 171 | detail = detail.get("message") or json.dumps(detail) |
| 172 | return f"Provider error (HTTP {status}): {str(detail)[:300]}" |
| 173 | |
| 174 | |
| 175 | def _synthesize_espeak( |
| 176 | engine_path: str, text: str, voice: str | None, timeout: float |
| 177 | ) -> bytes: |
| 178 | args = [engine_path, "--stdout"] |
| 179 | if voice: |
| 180 | args.extend(["-v", voice]) |
| 181 | args.append(text) |
| 182 | try: |
| 183 | result = subprocess.run(args, capture_output=True, timeout=timeout, check=False) |
| 184 | except subprocess.TimeoutExpired as exc: |
| 185 | raise TTSSynthesisError(f"{engine_path} timed out after {timeout}s") from exc |
| 186 | except OSError as exc: |
| 187 | raise TTSSynthesisError(f"{engine_path} failed to run: {exc}") from exc |
| 188 | if result.returncode != 0 or not result.stdout: |
| 189 | detail = (result.stderr or b"").decode("utf-8", "replace").strip() |
| 190 | raise TTSSynthesisError(f"{engine_path} exited {result.returncode}: {detail}") |
| 191 | return result.stdout |
| 192 | |
| 193 | |
| 194 | def _synthesize_say(text: str, voice: str | None, timeout: float) -> bytes: |
| 195 | """macOS 'say' writes AIFF; convert with the also-stock 'afconvert'. |
| 196 | |
| 197 | Two straightforward subprocess calls through temp files -- if that |
| 198 | stops being trivial (afconvert missing, say behaving oddly), we say |
| 199 | so with a 501 rather than growing a bespoke audio pipeline here. |
| 200 | """ |
| 201 | afconvert_path = shutil.which("afconvert") |
| 202 | if not afconvert_path: |
| 203 | raise TTSNotSupportedError( |
| 204 | "'say' is available but 'afconvert' is not, so WAV output isn't " |
| 205 | "supported here. Install espeak-ng for full support." |
| 206 | ) |
| 207 | with tempfile.TemporaryDirectory(prefix="dbbasic-tts-") as tmp: |
| 208 | aiff_path = Path(tmp) / "out.aiff" |
| 209 | wav_path = Path(tmp) / "out.wav" |
| 210 | say_args = ["say", "-o", str(aiff_path)] |
| 211 | if voice: |
| 212 | say_args.extend(["-v", voice]) |
| 213 | say_args.append(text) |
| 214 | try: |
| 215 | subprocess.run(say_args, capture_output=True, timeout=timeout, check=True) |
| 216 | subprocess.run( |
| 217 | [afconvert_path, "-f", "WAVE", "-d", "LEI16", str(aiff_path), str(wav_path)], |
| 218 | capture_output=True, |
| 219 | timeout=timeout, |
| 220 | check=True, |
| 221 | ) |
| 222 | except subprocess.TimeoutExpired as exc: |
| 223 | raise TTSSynthesisError(f"say/afconvert timed out after {timeout}s") from exc |
| 224 | except subprocess.CalledProcessError as exc: |
| 225 | detail = (exc.stderr or b"").decode("utf-8", "replace").strip() |
| 226 | raise TTSSynthesisError(f"say/afconvert failed: {detail}") from exc |
| 227 | except OSError as exc: |
| 228 | raise TTSSynthesisError(f"say/afconvert failed to run: {exc}") from exc |
| 229 | if not wav_path.is_file(): |
| 230 | raise TTSSynthesisError("afconvert produced no output") |
| 231 | return wav_path.read_bytes() |
| 232 | |
| 233 | |
| 234 | def _write_cache(path: Path, content: bytes) -> None: |
| 235 | path.parent.mkdir(parents=True, exist_ok=True) |
| 236 | temp_path = path.with_name(f".{path.name}.tmp") |
| 237 | temp_path.write_bytes(content) |
| 238 | temp_path.replace(path) |