macos-say-server 0.1.0__py3-none-any.whl

macos_say_server/__init__.py

@@ -0,0 +1,4 @@
+from .cli import main
+from .server import app
+
+__all__ = ["app", "main"]

macos_say_server/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

macos_say_server/cli.py

@@ -0,0 +1,36 @@
+import argparse
+from pathlib import Path
+
+import uvicorn
+
+from .server import app, configure_cache
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Run the macOS say HTTP server.")
+    parser.add_argument("--host", default="127.0.0.1", help="Host interface to bind to")
+    parser.add_argument("--port", type=int, default=2576, help="Port to listen on")
+    parser.add_argument("--cache-dir", type=Path, default=Path(".cache/audio"), help="Directory for cached AIFF files")
+    parser.add_argument("--cache-ttl-seconds", type=int, default=86400, help="Cache TTL in seconds; 0 disables reuse")
+    parser.add_argument(
+        "--cache-cleanup-interval-seconds",
+        type=int,
+        default=300,
+        help="Minimum seconds between lazy cleanup passes",
+    )
+    parser.add_argument("--cache-max-files", type=int, default=0, help="Maximum cached files; 0 means unlimited")
+    parser.add_argument("--cache-max-bytes", type=int, default=0, help="Maximum cached bytes; 0 means unlimited")
+    return parser
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+    configure_cache(
+        cache_dir=args.cache_dir,
+        ttl_seconds=args.cache_ttl_seconds,
+        cleanup_interval_seconds=args.cache_cleanup_interval_seconds,
+        max_files=args.cache_max_files,
+        max_bytes=args.cache_max_bytes,
+    )
+    uvicorn.run(app, host=args.host, port=args.port)
+    return 0

macos_say_server/server.py

@@ -0,0 +1,283 @@
+import os
+import re
+import subprocess
+import tempfile
+import time
+from dataclasses import dataclass
+from hashlib import sha256
+from pathlib import Path
+from typing import Iterator, Optional
+
+from fastapi import FastAPI, HTTPException, Query
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel, Field
+
+
+VOICE_PATTERN = re.compile(r"^(?P<name>.+?)\s{2,}(?P<locale>\S+)\s+#\s(?P<sample>.+)$")
+
+
+@dataclass
+class CacheConfig:
+    cache_dir: Path = Path(".cache/audio")
+    ttl_seconds: int = 86400
+    cleanup_interval_seconds: int = 300
+    max_files: int = 0
+    max_bytes: int = 0
+
+
+CACHE_CONFIG = CacheConfig()
+LAST_CACHE_CLEANUP_AT = 0.0
+
+app = FastAPI(
+    title="macOS Say Server",
+    description="Expose the macOS say command over HTTP and return AIFF audio.",
+    version="0.1.0",
+)
+
+
+class SynthesizeRequest(BaseModel):
+    text: str = Field(..., min_length=1, description="Text that should be spoken")
+    voice: Optional[str] = Field(default=None, description="Optional macOS voice name")
+
+
+def configure_cache(
+    *,
+    cache_dir: Path = Path(".cache/audio"),
+    ttl_seconds: int = 86400,
+    cleanup_interval_seconds: int = 300,
+    max_files: int = 0,
+    max_bytes: int = 0,
+) -> None:
+    global CACHE_CONFIG
+
+    CACHE_CONFIG = CacheConfig(
+        cache_dir=cache_dir,
+        ttl_seconds=max(0, ttl_seconds),
+        cleanup_interval_seconds=max(0, cleanup_interval_seconds),
+        max_files=max(0, max_files),
+        max_bytes=max(0, max_bytes),
+    )
+
+
+def _run_command(command: list[str]) -> subprocess.CompletedProcess[str]:
+    try:
+        return subprocess.run(command, capture_output=True, text=True, check=True)
+    except FileNotFoundError as exc:
+        raise HTTPException(status_code=500, detail="macOS say command is not available") from exc
+    except subprocess.CalledProcessError as exc:
+        detail = exc.stderr.strip() or exc.stdout.strip() or "macOS say command failed"
+        raise HTTPException(status_code=400, detail=detail) from exc
+
+
+def _iter_audio_chunks(output_path: Path) -> Iterator[bytes]:
+    with output_path.open("rb") as audio_file:
+        while True:
+            chunk = audio_file.read(64 * 1024)
+            if not chunk:
+                break
+            yield chunk
+
+
+def _cache_key(text: str, voice: Optional[str]) -> str:
+    digest = sha256()
+    digest.update((voice or "default").encode("utf-8"))
+    digest.update(b"\0")
+    digest.update(text.encode("utf-8"))
+    return digest.hexdigest()
+
+
+def _cache_path(text: str, voice: Optional[str]) -> Path:
+    return CACHE_CONFIG.cache_dir / f"{_cache_key(text, voice)}.aiff"
+
+
+def _is_cache_expired(path: Path, now: float) -> bool:
+    if CACHE_CONFIG.ttl_seconds == 0:
+        return True
+    try:
+        return now - path.stat().st_mtime >= CACHE_CONFIG.ttl_seconds
+    except FileNotFoundError:
+        return True
+
+
+def _touch_cache(path: Path, now: float) -> None:
+    os.utime(path, (now, now))
+
+
+def _cleanup_expired_cache(now: float) -> None:
+    global LAST_CACHE_CLEANUP_AT
+
+    if CACHE_CONFIG.ttl_seconds == 0:
+        return
+    if now - LAST_CACHE_CLEANUP_AT < CACHE_CONFIG.cleanup_interval_seconds:
+        return
+
+    LAST_CACHE_CLEANUP_AT = now
+    if not CACHE_CONFIG.cache_dir.exists():
+        return
+
+    for cached_file in CACHE_CONFIG.cache_dir.glob("*.aiff"):
+        if _is_cache_expired(cached_file, now):
+            cached_file.unlink(missing_ok=True)
+
+
+def _prune_cache_limits(protected_path: Optional[Path] = None) -> None:
+    if CACHE_CONFIG.max_files == 0 and CACHE_CONFIG.max_bytes == 0:
+        return
+    if not CACHE_CONFIG.cache_dir.exists():
+        return
+
+    cache_entries: list[tuple[Path, float, int]] = []
+    total_bytes = 0
+    for cached_file in CACHE_CONFIG.cache_dir.glob("*.aiff"):
+        try:
+            stat_result = cached_file.stat()
+        except FileNotFoundError:
+            continue
+        file_size = stat_result.st_size
+        total_bytes += file_size
+        cache_entries.append((cached_file, stat_result.st_mtime, file_size))
+
+    cache_entries.sort(key=lambda entry: entry[1])
+    current_files = len(cache_entries)
+
+    for cached_file, _mtime, file_size in cache_entries:
+        if protected_path is not None and cached_file == protected_path:
+            continue
+
+        files_over_limit = CACHE_CONFIG.max_files > 0 and current_files > CACHE_CONFIG.max_files
+        bytes_over_limit = CACHE_CONFIG.max_bytes > 0 and total_bytes > CACHE_CONFIG.max_bytes
+        if not files_over_limit and not bytes_over_limit:
+            break
+
+        cached_file.unlink(missing_ok=True)
+        current_files -= 1
+        total_bytes -= file_size
+
+
+def _cache_entries() -> list[tuple[Path, os.stat_result]]:
+    if not CACHE_CONFIG.cache_dir.exists():
+        return []
+
+    entries: list[tuple[Path, os.stat_result]] = []
+    for cached_file in CACHE_CONFIG.cache_dir.glob("*.aiff"):
+        try:
+            entries.append((cached_file, cached_file.stat()))
+        except FileNotFoundError:
+            continue
+    return entries
+
+
+def _cache_stats() -> dict[str, object]:
+    now = time.time()
+    entries = _cache_entries()
+    expired_files = 0
+    total_bytes = 0
+    oldest_mtime: Optional[float] = None
+    newest_mtime: Optional[float] = None
+
+    for cached_file, stat_result in entries:
+        total_bytes += stat_result.st_size
+        file_mtime = stat_result.st_mtime
+        if oldest_mtime is None or file_mtime < oldest_mtime:
+            oldest_mtime = file_mtime
+        if newest_mtime is None or file_mtime > newest_mtime:
+            newest_mtime = file_mtime
+        if _is_cache_expired(cached_file, now):
+            expired_files += 1
+
+    return {
+        "cache_dir": str(CACHE_CONFIG.cache_dir),
+        "cache_dir_exists": CACHE_CONFIG.cache_dir.exists(),
+        "total_files": len(entries),
+        "expired_files": expired_files,
+        "total_bytes": total_bytes,
+        "ttl_seconds": CACHE_CONFIG.ttl_seconds,
+        "cleanup_interval_seconds": CACHE_CONFIG.cleanup_interval_seconds,
+        "max_files": CACHE_CONFIG.max_files,
+        "max_bytes": CACHE_CONFIG.max_bytes,
+        "oldest_mtime": oldest_mtime,
+        "newest_mtime": newest_mtime,
+        "last_cleanup_at": LAST_CACHE_CLEANUP_AT or None,
+    }
+
+
+def _audio_response(output_path: Path, voice: Optional[str], cache_status: str) -> StreamingResponse:
+    filename_voice = (voice or "default").replace(" ", "-")
+    headers = {
+        "Content-Disposition": f'inline; filename="speech-{filename_voice}.aiff"',
+        "X-Cache": cache_status,
+    }
+    return StreamingResponse(
+        _iter_audio_chunks(output_path),
+        media_type="audio/aiff",
+        headers=headers,
+    )
+
+
+def _synthesize_audio(text: str, voice: Optional[str]) -> StreamingResponse:
+    normalized_text = text.strip()
+    if not normalized_text:
+        raise HTTPException(status_code=400, detail="text must not be empty")
+
+    now = time.time()
+    CACHE_CONFIG.cache_dir.mkdir(parents=True, exist_ok=True)
+    _cleanup_expired_cache(now)
+
+    cached_path = _cache_path(normalized_text, voice)
+    if cached_path.exists() and not _is_cache_expired(cached_path, now):
+        _touch_cache(cached_path, now)
+        _prune_cache_limits(protected_path=cached_path)
+        return _audio_response(cached_path, voice, cache_status="HIT")
+
+    cached_path.unlink(missing_ok=True)
+
+    with tempfile.NamedTemporaryFile(dir=CACHE_CONFIG.cache_dir, suffix=".aiff", delete=False) as temporary_file:
+        output_path = Path(temporary_file.name)
+
+    command = ["say", "-o", str(output_path)]
+    if voice:
+        command.extend(["-v", voice])
+    command.append(normalized_text)
+
+    try:
+        _run_command(command)
+    except HTTPException:
+        output_path.unlink(missing_ok=True)
+        raise
+
+    os.replace(output_path, cached_path)
+    _touch_cache(cached_path, now)
+    _prune_cache_limits(protected_path=cached_path)
+    return _audio_response(cached_path, voice, cache_status="MISS")
+
+
+@app.get("/health")
+def healthcheck() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+@app.get("/voices")
+def list_voices() -> list[dict[str, str]]:
+    result = _run_command(["say", "-v", "?"])
+    voices: list[dict[str, str]] = []
+    for line in result.stdout.splitlines():
+        match = VOICE_PATTERN.match(line.rstrip())
+        if not match:
+            continue
+        voices.append(match.groupdict())
+    return voices
+
+
+@app.get("/cache/stats")
+def cache_stats() -> dict[str, object]:
+    return _cache_stats()
+
+
+@app.get("/speak")
+def speak(text: str = Query(..., min_length=1), voice: Optional[str] = None) -> StreamingResponse:
+    return _synthesize_audio(text=text, voice=voice)
+
+
+@app.post("/speak")
+def speak_from_json(request: SynthesizeRequest) -> StreamingResponse:
+    return _synthesize_audio(text=request.text, voice=request.voice)

macos_say_server-0.1.0.dist-info/METADATA

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: macos-say-server
+Version: 0.1.0
+Summary: Expose macOS say as an HTTP server that provides text-to-speech audio generation.
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: fastapi[standard]>=0.116.0
+Requires-Dist: uvicorn>=0.35.0
+Description-Content-Type: text/markdown
+
+# macos-say-server
+
+Expose macOS say as an HTTP server that provides text-to-speech audio generation.
+
+## Features
+
+- `GET /health` for liveness checks.
+- `GET /voices` to list the voices available from `say -v '?'`.
+- `GET /cache/stats` to inspect current cache usage and limits.
+- `GET /speak?text=...&voice=...` to return AIFF audio directly.
+- `POST /speak` with JSON `{ "text": "...", "voice": "..." }` to return AIFF audio.
+- Disk-backed AIFF cache keyed by `text + voice`, with lazy TTL cleanup.
+
+## Run
+
+```bash
+uv sync
+uv run macos-say-server
+```
+
+The server binds to `127.0.0.1:2576` by default.
+
+Use startup arguments to override bind settings:
+
+```bash
+uv run macos-say-server --host 127.0.0.1 --port 2576
+```
+
+You can also run the package module directly:
+
+```bash
+uv run python -m macos_say_server --host 127.0.0.1 --port 2576
+```
+
+## Build
+
+```bash
+uv build
+```
+
+## Cache
+
+The service stores generated audio under `.cache/audio` by default.
+
+- Cache key: hash of `text + voice`
+- Expiration: `CACHE_TTL_SECONDS`, default `86400` seconds
+- Cleanup: lazy cleanup during requests, at most once per `CACHE_CLEANUP_INTERVAL_SECONDS`, default `300` seconds
+- On cache hit, the file timestamp is refreshed, so TTL is sliding rather than fixed from first generation
+- Capacity control: optional LRU-style pruning using file modification time
+- File count limit: `CACHE_MAX_FILES`, default `0` meaning unlimited
+- Total size limit: `CACHE_MAX_BYTES`, default `0` meaning unlimited
+
+When a cache limit is configured, the oldest entries are removed first. Because cache hits refresh the file timestamp, frequently used items stay warm and cold items are evicted first.
+
+`GET /cache/stats` returns:
+
+- `cache_dir` and whether it currently exists
+- `total_files` and `total_bytes`
+- `expired_files` under the current TTL view
+- configured `ttl_seconds`, cleanup interval, and capacity limits
+- oldest and newest cache entry timestamps
+
+Startup arguments:
+
+```bash
+uv run macos-say-server \
+	--cache-dir .cache/audio \
+	--cache-ttl-seconds 86400 \
+	--cache-cleanup-interval-seconds 300 \
+	--cache-max-files 0 \
+	--cache-max-bytes 0
+```
+
+## Examples
+
+```bash
+curl http://127.0.0.1:2576/health
+curl http://127.0.0.1:2576/voices
+curl http://127.0.0.1:2576/cache/stats
+curl -G http://127.0.0.1:2576/speak --data-urlencode "text=hello from macos say server" --output speech.aiff
+curl -i -G http://127.0.0.1:2576/speak --data-urlencode "text=hello from macos say server" --output speech.aiff
+curl -X POST http://127.0.0.1:2576/speak \
+	-H "content-type: application/json" \
+	-d '{"text":"hello from json","voice":"Samantha"}' \
+	--output speech.aiff
+```
+
+If you inspect response headers, `X-Cache: MISS` means the file was newly synthesized, and `X-Cache: HIT` means it was served from cache.

macos_say_server-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+macos_say_server/__init__.py,sha256=gjYy5tc_ad3p3cbTj5Z9OP_2RLgVXKdwYg9kSnafX64,73
+macos_say_server/__main__.py,sha256=PSQ4rpL0dG6f-qH4N7H-gD9igQkdHzH4yVZDcW8lfZo,80
+macos_say_server/cli.py,sha256=zB3JNM03yANPjnJ8l-20lVX-9mZgTWd1LI89Mea5ZtQ,1444
+macos_say_server/server.py,sha256=v2AUYUocR1tAnnpUcxp5_ZEG-el4SwtK029UigjDQ0U,8860
+macos_say_server-0.1.0.dist-info/METADATA,sha256=iKacJnzLKPuf9b3w1laY0ZstSUd6wHAH9oT87SU5_ws,3098
+macos_say_server-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+macos_say_server-0.1.0.dist-info/entry_points.txt,sha256=-pL9OO8-sAB3afH4p84djluCBhx78ngTyy27qScoWck,63
+macos_say_server-0.1.0.dist-info/licenses/LICENSE,sha256=hYRaJ2ed2IMo9RmO96UxUSTt9iwL49leBY5kVtDymRo,1063
+macos_say_server-0.1.0.dist-info/RECORD,,

macos_say_server-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

macos_say_server-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+macos-say-server = macos_say_server.cli:main

macos_say_server-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lanbao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.