vocalize-cli 0.1.1__py3-none-any.whl

vocalize/__init__.py

@@ -0,0 +1,10 @@
+"""vocalize: a text-to-speech CLI built on the ElevenLabs API.
+
+Converts plain text, markdown, or piped stdin into natural-sounding
+speech, with a preprocessing pass that flattens markdown tables and
+formatting into something that actually sounds good spoken aloud
+(most TTS tools just read a table's raw cell text left to right,
+which is close to useless).
+"""
+
+__version__ = "0.1.1"

vocalize/__main__.py

@@ -0,0 +1,4 @@
+from .cli import run
+
+if __name__ == "__main__":
+    run()

vocalize/audio.py

@@ -0,0 +1,71 @@
+"""Save audio to disk and play it through whatever the OS has on hand.
+
+Deliberately avoids pulling in a heavy playback dependency (pydub /
+simpleaudio / ffmpeg-python) — this just shells out to a system
+player that's virtually always already installed, and fails with a
+clear message if none is found.
+"""
+
+from __future__ import annotations
+
+import platform
+import shutil
+import subprocess
+from pathlib import Path
+
+from .exceptions import AudioPlaybackError, NoAudioPlayerError
+
+_CANDIDATES = {
+    "Darwin": [["afplay"]],
+    "Linux": [["mpg123"], ["ffplay", "-nodisp", "-autoexit"], ["cvlc", "--play-and-exit"]],
+}
+
+
+def save(audio: bytes, path: Path) -> Path:
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(audio)
+    except OSError as exc:
+        raise AudioPlaybackError(f"Could not save audio to {path}: {exc}") from exc
+    return path
+
+
+def play(path: Path) -> None:
+    system = platform.system()
+
+    if system == "Windows":
+        # SoundPlayer only handles WAV, so mp3 playback on Windows likely
+        # fails cleanly rather than actually playing. Windows support is
+        # untested — treat it as a known limitation.
+        path_str = str(path).replace("'", "''")
+        cmd = [
+            "powershell",
+            "-c",
+            f"(New-Object Media.SoundPlayer '{path_str}').PlaySync();",
+        ]
+        try:
+            subprocess.run(cmd, check=True)
+        except (subprocess.CalledProcessError, OSError) as exc:
+            raise AudioPlaybackError(
+                f"powershell failed to play the audio: {exc}. "
+                f"The file is still saved at {path} — open it manually."
+            ) from exc
+        return
+
+    for candidate in _CANDIDATES.get(system, []):
+        exe = candidate[0]
+        if shutil.which(exe):
+            try:
+                subprocess.run([*candidate, str(path)], check=True)
+            except (subprocess.CalledProcessError, OSError) as exc:
+                raise AudioPlaybackError(
+                    f"{exe} failed to play the audio: {exc}. "
+                    f"The file is still saved at {path} — open it manually."
+                ) from exc
+            return
+
+    raise NoAudioPlayerError(
+        f"No supported audio player found for {system}. "
+        f"Install one of: {', '.join(c[0] for c in _CANDIDATES.get(system, []))} "
+        f"— or open the saved file manually: {path}"
+    )

vocalize/cli.py

@@ -0,0 +1,110 @@
+"""Command-line interface for vocalize.
+
+    vocalize speak "some text" --play
+    vocalize speak-file report.md --play
+    cat notes.md | vocalize speak-file - --play
+    vocalize voices
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from . import __version__
+from .audio import play as play_audio
+from .audio import save as save_audio
+from .config import DEFAULT_MODEL, DEFAULT_VOICE, Settings, resolve_api_key
+from .exceptions import TTSRequestError, VocalizeError
+from .preprocess import flatten_markdown, truncate_for_budget
+from .tts import DEFAULT_CACHE_DIR, build_client, list_voices, synthesize
+
+
+def _common_options(f):
+    f = click.option("--api-key", default=None, help="ElevenLabs API key (overrides env/.env).")(f)
+    f = click.option("--voice", "voice_id", default=DEFAULT_VOICE, show_default=True, help="Voice ID to use.")(f)
+    f = click.option("--model", "model_id", default=DEFAULT_MODEL, show_default=True, help="ElevenLabs model ID.")(f)
+    f = click.option("-o", "--output", "output_path", type=click.Path(path_type=Path), default=None,
+                      help="Save the generated audio to this path (default: "
+                      "~/.cache/vocalize/last.mp3, overwritten each run).")(f)
+    f = click.option("--play/--no-play", default=True, help="Play the audio after generating it.")(f)
+    f = click.option("--raw", is_flag=True, help="Skip markdown flattening; speak the text verbatim.")(f)
+    f = click.option("--max-chars", type=int, default=None, help="Truncate input to this many characters first.")(f)
+    return f
+
+
+@click.group()
+@click.version_option(__version__, prog_name="vocalize")
+def main() -> None:
+    """Turn text, markdown, or piped stdin into speech via ElevenLabs."""
+
+
+def _run_tts(raw_text: str, *, api_key, voice_id, model_id, output_path, play, raw, max_chars) -> None:
+    text = raw_text if raw else flatten_markdown(raw_text)
+    text, truncated = truncate_for_budget(text, max_chars)
+    if truncated:
+        click.echo(f"Note: input truncated to {max_chars} characters.", err=True)
+
+    if not text.strip():
+        raise TTSRequestError("Nothing to speak: input text is empty.")
+
+    key = resolve_api_key(api_key)
+    client = build_client(key)
+    settings = Settings(voice_id=voice_id, model_id=model_id)
+
+    click.echo(f"Requesting {len(text)} characters of audio from ElevenLabs...", err=True)
+    audio = synthesize(client, text, settings)
+
+    dest = output_path or (DEFAULT_CACHE_DIR / "last.mp3")
+    save_audio(audio, dest)
+    click.echo(f"Saved audio to {dest}", err=True)
+
+    if play:
+        play_audio(dest)
+
+
+@main.command()
+@click.argument("text")
+@_common_options
+def speak(text, api_key, voice_id, model_id, output_path, play, raw, max_chars) -> None:
+    """Speak TEXT directly."""
+    _run_tts(text, api_key=api_key, voice_id=voice_id, model_id=model_id,
+              output_path=output_path, play=play, raw=raw, max_chars=max_chars)
+
+
+@main.command("speak-file")
+@click.argument("path", type=click.File("r", encoding="utf-8"))
+@_common_options
+def speak_file(path, api_key, voice_id, model_id, output_path, play, raw, max_chars) -> None:
+    """Speak the contents of PATH (a markdown/text file), or "-" for stdin."""
+    try:
+        raw_text = path.read()
+    except UnicodeDecodeError as exc:
+        raise click.FileError(getattr(path, "name", "input"), hint="file is not valid UTF-8 text") from exc
+    _run_tts(raw_text, api_key=api_key, voice_id=voice_id, model_id=model_id,
+              output_path=output_path, play=play, raw=raw, max_chars=max_chars)
+
+
+@main.command()
+@click.option("--api-key", default=None)
+def voices(api_key) -> None:
+    """List available ElevenLabs voices and their IDs."""
+    key = resolve_api_key(api_key)
+    client = build_client(key)
+    for v in list_voices(client):
+        click.echo(f"{v['id']}\t{v['name']}")
+
+
+def run() -> None:
+    """Entry point that turns our VocalizeError family into clean CLI errors."""
+    try:
+        main()
+    except VocalizeError as exc:
+        click.echo(f"Error: {exc}", err=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    run()

vocalize/config.py

@@ -0,0 +1,55 @@
+"""Configuration loading: API key resolution and defaults.
+
+Resolution order (first one found wins):
+  1. --api-key flag passed explicitly on the CLI
+  2. ELEVENLABS_API_KEY environment variable
+  3. A .env file in the current directory (loaded via python-dotenv,
+     if it's installed — this is an optional dependency)
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from .exceptions import MissingAPIKeyError
+
+DEFAULT_VOICE = "21m00Tcm4TlvDq8ikWAM"  # "Rachel" — a stock ElevenLabs voice
+DEFAULT_MODEL = "eleven_multilingual_v2"
+DEFAULT_OUTPUT_FORMAT = "mp3_44100_128"
+
+
+def _load_dotenv_if_present() -> None:
+    try:
+        from dotenv import load_dotenv  # type: ignore
+    except ImportError:
+        return
+    # Explicit path, not dotenv's default search: bare load_dotenv() walks
+    # up from the install directory, so a console-script install would miss
+    # the user's project .env and could pick up an unrelated one.
+    load_dotenv(dotenv_path=Path.cwd() / ".env")
+
+
+def resolve_api_key(explicit: str | None = None) -> str:
+    """Find an API key from --api-key, the environment, or .env.
+
+    Raises MissingAPIKeyError if none is found.
+    """
+    if explicit:
+        return explicit
+
+    _load_dotenv_if_present()
+
+    key = os.environ.get("ELEVENLABS_API_KEY")
+    if key:
+        return key
+
+    raise MissingAPIKeyError()
+
+
+@dataclass(frozen=True)
+class Settings:
+    voice_id: str = DEFAULT_VOICE
+    model_id: str = DEFAULT_MODEL
+    output_format: str = DEFAULT_OUTPUT_FORMAT

vocalize/exceptions.py

@@ -0,0 +1,29 @@
+"""Custom exceptions for vocalize."""
+
+
+class VocalizeError(Exception):
+    """Base class for all vocalize errors."""
+
+
+class MissingAPIKeyError(VocalizeError):
+    """Raised when no ElevenLabs API key can be found."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "No ElevenLabs API key found. Set the ELEVENLABS_API_KEY "
+            "environment variable, add it to a .env file, or pass "
+            "--api-key on the command line. Get a free key at "
+            "https://elevenlabs.io/app/settings/api-keys"
+        )
+
+
+class TTSRequestError(VocalizeError):
+    """Raised when the ElevenLabs API call itself fails."""
+
+
+class NoAudioPlayerError(VocalizeError):
+    """Raised when no supported system audio player can be found."""
+
+
+class AudioPlaybackError(VocalizeError):
+    """Raised when saving or playing audio fails at the OS/subprocess level."""

vocalize/preprocess.py

@@ -0,0 +1,195 @@
+"""Turn markdown into text that sounds sensible when spoken aloud.
+
+Most TTS tools read a markdown table cell-by-cell, left to right,
+which turns a table into a stream of disconnected numbers ("Q1. 4.2
+million. Q2. 5.1 million...") with no sense of what row or column
+you're in. This module rewrites tables, lists, headers, links, and
+code as short declarative sentences before the text ever reaches the
+TTS API — the same trick a person reading a table aloud to someone
+else would use instinctively.
+
+Everything here is pure text-in, text-out, so it's fully unit
+testable without an API key or network access.
+"""
+
+from __future__ import annotations
+
+import re
+
+# One dash per column is legal GitHub-flavored markdown ("| - | - |").
+_TABLE_SEPARATOR_RE = re.compile(r"^\s*\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)*\|?\s*$")
+_HEADING_RE = re.compile(r"^(#{1,6})\s+(.*)")
+_BULLET_RE = re.compile(r"^\s*[-*+]\s+(.*)")
+_NUMBERED_RE = re.compile(r"^\s*(\d+)[.)]\s+(.*)")
+_FENCE_RE = re.compile(r"^\s*```")
+_LINK_RE = re.compile(r"\[([^\]]+)\]\(([^)]+)\)")
+_IMAGE_RE = re.compile(r"!\[([^\]]*)\]\(([^)]+)\)")
+_BOLD_ITALIC_RE = re.compile(r"(\*\*\*|___)(.+?)\1")
+_BOLD_RE = re.compile(r"(\*\*|__)(.+?)\1")
+_ITALIC_RE = re.compile(r"(\*|_)(.+?)\1")
+_INLINE_CODE_RE = re.compile(r"`([^`]+)`")
+
+# Real Claude Code responses are mostly code blocks. Announcing both ends of
+# every one of them filled the whole spoken budget with bookkeeping, so it's
+# one short mention per block, and consecutive blocks share a single mention.
+_CODE_PLACEHOLDER = "Skipping a code block."
+
+
+def _split_table_row(line: str) -> list[str]:
+    row = line.strip()
+    row = row.removeprefix("|")
+    row = row.removesuffix("|")
+    return [cell.strip() for cell in row.split("|")]
+
+
+def _is_table_start(lines: list[str], i: int) -> bool:
+    if i + 1 >= len(lines):
+        return False
+    header, sep = lines[i], lines[i + 1]
+    if "|" not in header or not _TABLE_SEPARATOR_RE.match(sep):
+        return False
+    # Prose containing a stray "|" above a horizontal rule looks like a
+    # header + separator pair, so insist the column counts line up too.
+    return len(_split_table_row(header)) == len(_split_table_row(sep))
+
+
+def _flatten_table(lines: list[str], start: int) -> tuple[str, int]:
+    """Convert a markdown table starting at `start` into spoken prose.
+
+    Returns (spoken_text, index_of_first_line_after_table).
+    """
+    headers = _split_table_row(lines[start])
+    i = start + 2  # skip header + separator row
+    rows: list[list[str]] = []
+    while i < len(lines) and "|" in lines[i] and lines[i].strip():
+        rows.append(_split_table_row(lines[i]))
+        i += 1
+
+    if not rows:
+        return "", i
+
+    noun = "row" if len(rows) == 1 else "rows"
+    sentences = [f"Table with {len(rows)} {noun}."]
+    for row in rows:
+        label = row[0] if row else ""
+        parts = []
+        # Walk by index, not dict(zip(...)): ragged rows and repeated
+        # header names would otherwise lose cells without a word.
+        for idx, value in enumerate(row):
+            if idx == 0:
+                continue  # already spoken as the row's label
+            if not value:
+                continue
+            header = headers[idx] if idx < len(headers) else f"column {idx + 1}"
+            parts.append(f"{header} is {value}")
+        if parts:
+            sentences.append(f"For {label}: " + "; ".join(parts) + ".")
+        else:
+            sentences.append(f"{label}.")
+
+    return " ".join(sentences), i
+
+
+def _strip_inline_markdown(text: str) -> str:
+    text = _IMAGE_RE.sub(lambda m: m.group(1) or "image", text)
+    text = _LINK_RE.sub(lambda m: m.group(1), text)
+    text = _BOLD_ITALIC_RE.sub(lambda m: m.group(2), text)
+    text = _BOLD_RE.sub(lambda m: m.group(2), text)
+    text = _ITALIC_RE.sub(lambda m: m.group(2), text)
+    text = _INLINE_CODE_RE.sub(lambda m: m.group(1), text)
+    return text
+
+
+def flatten_markdown(text: str) -> str:
+    """Rewrite markdown as plain, speakable prose.
+
+    - Tables become short "for X, Y is Z" sentences per row.
+    - Headings become their own sentence (so there's a natural pause).
+    - Bullet/numbered lists become "First, ... Next, ... Finally, ...".
+    - Fenced code blocks become one short spoken placeholder each, and
+      back-to-back blocks collapse into a single mention — reading code
+      character-by-character out loud helps no one, and neither does
+      announcing six code blocks in a row.
+    - Links, images, bold/italic markers, and inline code ticks are
+      stripped down to their readable text.
+    """
+    lines = text.splitlines()
+    out: list[str] = []
+    in_code_block = False
+    list_ordinal = 0
+    ordinals = [
+        "First", "Second", "Third", "Fourth", "Fifth",
+        "Sixth", "Seventh", "Eighth", "Ninth", "Tenth",
+    ]
+
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+
+        if _FENCE_RE.match(line):
+            in_code_block = not in_code_block
+            if in_code_block:
+                last = next((s for s in reversed(out) if s), None)
+                if last != _CODE_PLACEHOLDER:
+                    out.append(_CODE_PLACEHOLDER)
+            i += 1
+            continue
+
+        if in_code_block:
+            # Skip the raw code itself — it isn't worth speaking.
+            i += 1
+            continue
+
+        if not line.strip():
+            list_ordinal = 0
+            i += 1
+            continue
+
+        if _is_table_start(lines, i):
+            spoken, i = _flatten_table(lines, i)
+            out.append(spoken)
+            continue
+
+        heading_match = _HEADING_RE.match(line)
+        if heading_match:
+            out.append(_strip_inline_markdown(heading_match.group(2)).strip() + ".")
+            list_ordinal = 0
+            i += 1
+            continue
+
+        bullet_match = _BULLET_RE.match(line)
+        if bullet_match:
+            word = ordinals[list_ordinal] if list_ordinal < len(ordinals) else "Next"
+            out.append(f"{word}, {_strip_inline_markdown(bullet_match.group(1)).strip()}.")
+            list_ordinal += 1
+            i += 1
+            continue
+
+        numbered_match = _NUMBERED_RE.match(line)
+        if numbered_match:
+            out.append(
+                f"Item {numbered_match.group(1)}: "
+                f"{_strip_inline_markdown(numbered_match.group(2)).strip()}."
+            )
+            i += 1
+            continue
+
+        out.append(_strip_inline_markdown(line).strip())
+        list_ordinal = 0
+        i += 1
+
+    spoken = " ".join(s for s in out if s)
+    spoken = re.sub(r"\s+", " ", spoken).strip()
+    return spoken
+
+
+def truncate_for_budget(text: str, max_chars: int | None) -> tuple[str, bool]:
+    """Truncate to max_chars, returning (text, was_truncated).
+
+    Useful for keeping a free-tier ElevenLabs quota from being blown
+    through by one long document.
+    """
+    if max_chars is None or len(text) <= max_chars:
+        return text, False
+    cut = text[:max_chars].rsplit(" ", 1)[0]
+    return cut + "... (truncated)", True

vocalize/tts.py

@@ -0,0 +1,107 @@
+"""Thin wrapper around the ElevenLabs text-to-speech API.
+
+Kept deliberately small and dependency-injected (the client is passed
+in) so it's easy to unit test with a fake/mock client — no network
+access or real API key needed to test the logic in this file.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+from .config import Settings
+from .exceptions import TTSRequestError
+
+DEFAULT_CACHE_DIR = Path.home() / ".cache" / "vocalize"
+
+# The SDK's own default is 240s, far beyond the Stop hook's 60s subprocess
+# timeout — a hung request would otherwise outlive the hook that spawned it.
+REQUEST_TIMEOUT_SECONDS = 30
+
+
+def _cache_key(text: str, settings: Settings) -> str:
+    payload = f"{settings.voice_id}|{settings.model_id}|{settings.output_format}|{text}"
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def synthesize(
+    client,
+    text: str,
+    settings: Settings,
+    *,
+    cache_dir: Path | None = DEFAULT_CACHE_DIR,
+) -> bytes:
+    """Convert `text` to audio bytes via the ElevenLabs client.
+
+    `client` is expected to expose `.text_to_speech.convert(...)`
+    returning an iterable of bytes chunks (this matches the official
+    `elevenlabs` SDK's ElevenLabs client) — but any object with that
+    shape works, which is what makes this testable with a stub.
+
+    Results are cached on disk by a hash of (text, voice, model,
+    format), so re-running the same request — e.g. re-reading the
+    same document twice — doesn't burn API quota twice.
+    """
+    if not text.strip():
+        raise TTSRequestError("Nothing to speak: input text is empty.")
+
+    cache_path = None
+    if cache_dir is not None:
+        cache_path = cache_dir / f"{_cache_key(text, settings)}.mp3"
+        # The cache is an optimization, never a failure source: an
+        # unreadable entry is just a miss.
+        try:
+            if cache_path.exists():
+                return cache_path.read_bytes()
+        except OSError:
+            pass
+
+    try:
+        chunks = client.text_to_speech.convert(
+            text=text,
+            voice_id=settings.voice_id,
+            model_id=settings.model_id,
+            output_format=settings.output_format,
+        )
+        audio = b"".join(chunks) if not isinstance(chunks, (bytes, bytearray)) else bytes(chunks)
+    except Exception as exc:
+        raise TTSRequestError(f"ElevenLabs API request failed: {exc}") from exc
+
+    if not audio:
+        raise TTSRequestError("ElevenLabs API returned no audio data.")
+
+    if cache_path is not None:
+        # Never discard a paid API response because the cache dir is
+        # read-only — the caller's save path does the real persistence.
+        try:
+            cache_path.parent.mkdir(parents=True, exist_ok=True)
+            cache_path.write_bytes(audio)
+        except OSError:
+            pass
+
+    return audio
+
+
+def list_voices(client) -> list[dict]:
+    """Return a simplified [{"id": ..., "name": ...}, ...] list of voices."""
+    try:
+        response = client.voices.search()
+    except Exception as exc:
+        raise TTSRequestError(f"Could not list voices: {exc}") from exc
+
+    voices = getattr(response, "voices", response)
+    return [
+        {"id": getattr(v, "voice_id", getattr(v, "id", None)), "name": getattr(v, "name", "?")}
+        for v in voices
+    ]
+
+
+def build_client(api_key: str):
+    """Construct the real ElevenLabs SDK client. Imported lazily so the
+    rest of the package (and its tests) don't require the `elevenlabs`
+    package to be installed just to run unit tests against pure logic.
+    """
+    from elevenlabs.client import ElevenLabs
+
+    return ElevenLabs(api_key=api_key, timeout=REQUEST_TIMEOUT_SECONDS)

vocalize_cli-0.1.1.dist-info/METADATA

@@ -0,0 +1,249 @@
+Metadata-Version: 2.5
+Name: vocalize-cli
+Version: 0.1.1
+Summary: A CLI that turns text, markdown, or piped stdin into speech via the ElevenLabs API, with markdown-table-aware preprocessing.
+Project-URL: Homepage, https://github.com/matthager12-collab/vocalize
+Project-URL: Repository, https://github.com/matthager12-collab/vocalize
+Author: Mat
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude-code,cli,elevenlabs,markdown,text-to-speech
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: elevenlabs>=2.0
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: dotenv
+Requires-Dist: python-dotenv>=1.0; extra == 'dotenv'
+Description-Content-Type: text/markdown
+
+# vocalize
+
+[![CI](https://github.com/matthager12-collab/vocalize/actions/workflows/ci.yml/badge.svg)](https://github.com/matthager12-collab/vocalize/actions/workflows/ci.yml)
+
+A command-line tool that turns text, markdown files, or piped stdin into
+natural-sounding speech using the [ElevenLabs](https://elevenlabs.io) API —
+plus a hook that wires it directly into [Claude Code](https://claude.com/claude-code),
+so Claude's responses get read aloud automatically in your terminal or IDE.
+
+## Why this exists
+
+Text-to-speech readers are good at *voices* and bad at *structure*. Point one
+at a markdown report and it reads a table cell-by-cell, left to right, with
+no sense of which row or column you're in — "Q1. 4.2 million. Q2. 5.1
+million" instead of "for Q1, revenue is 4.2 million." Headings, bullet
+lists, and inline code fare the same way: read exactly as typed, syntax and
+all.
+
+`vocalize` fixes the part of that problem that's actually fixable without a
+vision model: a preprocessing pass (`vocalize/preprocess.py`) rewrites
+markdown into short, declarative sentences *before* it ever reaches the TTS
+API — tables become "for X, Y is Z" sentences, bullets become "First, ...
+Second, ...", links keep their text and drop the URL, and fenced code blocks
+are replaced with a spoken placeholder instead of being read character by
+character. It's a text transform, so it's fully unit tested without any
+API key or network access (see `tests/test_preprocess.py`).
+
+## Install
+
+```bash
+pipx install vocalize-cli
+```
+
+(or `uvx --from vocalize-cli vocalize` for a one-off run without installing
+anything). The package is published on PyPI as `vocalize-cli`; the command
+it installs is still `vocalize`.
+
+For a from-source or dev install:
+
+```bash
+git clone <this-repo>
+cd vocalize
+pip install -e .
+```
+
+Get a free ElevenLabs API key at
+[elevenlabs.io/app/settings/api-keys](https://elevenlabs.io/app/settings/api-keys)
+(free tier: 10,000 characters/month, API access included, no commercial
+license). Then either:
+
+```bash
+export ELEVENLABS_API_KEY=your-key-here
+```
+
+or copy `.env.example` to `.env` and fill it in (requires the optional
+`python-dotenv` extra: `pip install -e ".[dotenv]"`).
+
+## Usage
+
+```bash
+# Speak a string directly
+vocalize speak "Hello, this is a test."
+
+# Speak a markdown file — tables and formatting get flattened first
+vocalize speak-file report.md
+
+# Pipe anything in
+cat notes.md | vocalize speak-file -
+
+# List available voices and grab an ID
+vocalize voices
+
+# Use a specific voice/model, save without playing
+vocalize speak-file report.md --voice <voice-id> --model eleven_flash_v2_5 \
+  --output out.mp3 --no-play
+
+# Cap how much gets sent (handy for free-tier character budgets)
+vocalize speak-file long-report.md --max-chars 2000
+
+# Skip the markdown flattening entirely
+vocalize speak "raw **markdown** stays raw" --raw
+```
+
+Every synthesis result is cached on disk under `~/.cache/vocalize/`, keyed
+by a hash of (text, voice, model, format) — re-running the same command
+twice doesn't burn API quota twice.
+
+## Claude Code integration
+
+The hook scripts ship in the git repository, not the PyPI package — clone
+the repo to install the hook (it shells out to the `vocalize` command, so a
+pipx-installed CLI plus a cloned repo works fine together).
+
+`hooks/claude_stop_hook.py` is a [Claude Code Stop
+hook](https://docs.claude.com/en/docs/claude-code/hooks): a script Claude
+Code runs every time it finishes a response. This one reads the transcript,
+pulls out Claude's last message, and pipes it through the same `vocalize`
+CLI — so it works identically whether Claude Code is running in a bare
+terminal or inside an IDE's integrated terminal (VS Code, Cursor, etc.),
+since both use the same `~/.claude/settings.json` hook config.
+
+**On-demand mode.** If you'd rather trigger speech yourself than have every
+response spoken, skip the install and run the script with `--latest`. It
+finds your most recent Claude Code response — in any session — and speaks
+that one:
+
+```bash
+python3 hooks/claude_stop_hook.py --latest
+```
+
+Combine it with `VOCALIZE_MAX_CHARS` to control how much gets read.
+
+To install it as an automatic hook instead:
+
+```bash
+python3 hooks/install_hook.py
+```
+
+This merges a `Stop` hook entry into `~/.claude/settings.json` (backing up
+the existing file first) rather than overwriting your other hooks. Every
+Claude Code response after that gets spoken aloud automatically. Uninstall
+by removing the `vocalize` entry from the `Stop` array in that file.
+
+By default the hook truncates each response to 500 characters before
+speaking it (`DEFAULT_MAX_CHARS` in `claude_stop_hook.py`) — a Stop hook
+fires after every turn, so a long response would burn through the
+ElevenLabs free-tier quota fast. Override with `VOCALIZE_MAX_CHARS` in the
+environment.
+
+The hook looks up the `vocalize` binary on `PATH`, but Claude Code hooks
+run in Claude Code's own environment, not your interactive shell — if
+`vocalize` was installed into a virtualenv that isn't on that `PATH`, set
+`VOCALIZE_BIN` to the full path (e.g. `/path/to/.venv/bin/vocalize`) to
+point the hook at it directly.
+
+## How it's built
+
+Four decisions shaped the design:
+
+- **The markdown flattener is a pure function.** The hardest logic in the
+  project — deciding what a table, list, or code block should *sound* like —
+  takes a string and returns a string. No I/O, no client, no key. That's why
+  it has the deepest test coverage in the repo, including the edge cases
+  that bit during review: prose containing a stray `|`, single-dash GFM
+  separators, ragged rows, duplicate column names.
+- **One code path for humans and hooks.** The Claude Code hook doesn't
+  reimplement synthesis; it shells out to the same `vocalize` CLI you'd
+  type by hand (with an `--` argv guard so a response starting with a
+  bullet isn't parsed as a flag). Anything the hook can do, you can
+  reproduce and debug from your own terminal.
+- **The hook may fail; the session may not.** Every failure path in the
+  Stop hook logs one line to stderr and exits 0. A dead API key or a hung
+  request costs you the audio, never the coding session.
+- **The cache is an optimization, never a failure source.** Synthesis
+  results are content-addressed on disk; an unreadable or unwritable cache
+  degrades to a fresh API call instead of an error.
+
+## Architecture
+
+```
+vocalize/
+  __init__.py     # package version
+  __main__.py     # python -m vocalize entry point
+  preprocess.py   # markdown -> speakable text (pure function, fully unit tested)
+  config.py       # API key resolution: --api-key > $ELEVENLABS_API_KEY > .env
+  exceptions.py   # VocalizeError / TTSRequestError
+  tts.py          # ElevenLabs API wrapper + disk cache (client is injected, so
+                   # it's mockable in tests without hitting the network)
+  audio.py        # save to disk + play via the OS's native player
+                   # (afplay / mpg123 / ffplay / PowerShell, whichever exists)
+  cli.py          # click-based CLI wiring the above together
+hooks/
+  claude_stop_hook.py  # Claude Code Stop hook -> calls the vocalize CLI
+  install_hook.py      # safely merges the hook into ~/.claude/settings.json
+tests/                  # pytest, all mocked — no API key needed to run these
+```
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+All tests run offline: the ElevenLabs client is dependency-injected into
+`tts.py`, so tests pass in a fake client instead of hitting the real API.
+
+## Known limitations
+
+- **Charts and images aren't described.** Flattening markdown tables is a
+  text problem; a rendered chart is an image, and describing it well needs
+  a vision model in the loop, not a text transform. Out of scope for this
+  project, but a natural next step — pipe the image through a
+  vision-capable model first, feed its description into `vocalize` in
+  place of the chart.
+- **Free tier is 10,000 characters/month** — plenty for reading a handful
+  of documents aloud, not for continuous use. `--max-chars` and the disk
+  cache both help stretch it.
+- Table flattening handles standard GFM pipe tables; it doesn't attempt to
+  handle merged cells or nested tables (rare enough in practice that it
+  wasn't worth the complexity).
+- **Windows playback is untested.** The PowerShell `SoundPlayer` fallback
+  only plays WAV, so the mp3 files this tool generates likely won't play
+  there. Use `--no-play` and open the saved file with whatever's on hand.
+- **The disk cache under `~/.cache/vocalize` grows unbounded.** It's
+  content-addressed (keyed by a hash of text, voice, model, and format),
+  so it's always safe to delete some or all of it — nothing will break,
+  you'll just re-pay for a re-synthesized clip.
+- **`--api-key` on the command line is visible to other local processes**
+  (anything that can run `ps`). Prefer the `ELEVENLABS_API_KEY` environment
+  variable or a `.env` file instead.
+- `vocalize voices` lists only the first page of results from the
+  ElevenLabs API.
+
+## License
+
+MIT

vocalize_cli-0.1.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+vocalize/__init__.py,sha256=Jg8z92RR2rJb5Ynq8DENuI56B5kLviRc1qqaXdKSYx4,385
+vocalize/__main__.py,sha256=3U77Eu21mJ-LY27RG-JEnpbh6Z63wGOom4i-EoLtUcY,59
+vocalize/audio.py,sha256=69ZICXC39HK_YThQ4pOF9BB2UU55PSFqPjMUsLLYefI,2435
+vocalize/cli.py,sha256=FXF6IHPWyKDK9HjubSd62JYW4_UCpb7mXVGbubp6TjU,4156
+vocalize/config.py,sha256=nroeTvy4_YX6fLLrpGC-lFJHTKp9xlWb02dSwOxXmzQ,1570
+vocalize/exceptions.py,sha256=RlWiLUfFjAOXGvqNgxYxTWRSHmsOk5WP225XBCU0rrA,884
+vocalize/preprocess.py,sha256=dc7_lsHYg8GD-r96UiVt8xn5JkOGAgCTovSDEQq86UU,7028
+vocalize/tts.py,sha256=VB5-F4HSar2FLIPQEMMIfn0VdOq-BR3VqwlVzMlkM8k,3706
+vocalize_cli-0.1.1.dist-info/METADATA,sha256=BJ6zwQ9ZZhD0ckk97b70YFKMLWoZogTfcO7hxiQZzJ0,10335
+vocalize_cli-0.1.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+vocalize_cli-0.1.1.dist-info/entry_points.txt,sha256=YGjS-M7KnLEoUE-77AbtU1QiVYa4qksmBJL1MRBDZA0,46
+vocalize_cli-0.1.1.dist-info/licenses/LICENSE,sha256=yCYTCxMZWkE-ARTs1NnfsD06fDpU7uDLUMgscQj3oI8,1060
+vocalize_cli-0.1.1.dist-info/RECORD,,

vocalize_cli-0.1.1.dist-info/WHEEL

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

vocalize_cli-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vocalize = vocalize.cli:run

vocalize_cli-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mat
+
+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.