vocalize-cli 0.3.0__tar.gz → 0.5.0__tar.gz

{vocalize_cli-0.3.0 → vocalize_cli-0.5.0}/.gitignore

@@ -11,3 +11,4 @@ dist/
 venv/
 *.mp3
 *.wav
+.claude/

{vocalize_cli-0.3.0 → vocalize_cli-0.5.0}/CHANGELOG.md

@@ -3,6 +3,53 @@
 All notable changes to this project are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## 0.5.0 - 2026-08-31
+
+### Added
+
+- `vocalize stop` — stops in-progress playback from any terminal. play()
+  now records the player's PID in `~/.cache/vocalize/play.pid` while audio
+  runs; stop kills it only when the PID, its recorded launch timestamp,
+  and a known player name all still match — a recycled PID is never
+  touched — and a SIGTERM'd playback counts as a clean exit for the
+  speak command that started it. Overlapping plays keep the newest
+  record: the survivor is what stop stops.
+- Chunked synthesis: input longer than the `eleven_multilingual_v2` model's
+  10,000-character per-request cap is now split into chunks — preferring
+  paragraph, then sentence, then word boundaries — synthesized sequentially,
+  and concatenated into one audio file, instead of failing outright. Each
+  chunk still goes through the existing disk cache individually, so a
+  partially-cached long document only pays for the chunks it's missing.
+- `--chunk-chars` flag to control the split size (default: 9,500).
+- Configurable overflow behaviour: a new `overflow` setting (`truncate` |
+  `ask` | `never`) decides what happens when input exceeds the character
+  cap. `ask` prompts on the controlling terminal and degrades to
+  `truncate` with a note when there is none. Resolved like every other
+  setting: `--overflow` > `VOCALIZE_OVERFLOW` > config file > `truncate`.
+- `max_chars` can now come from the environment (`VOCALIZE_MAX_CHARS`) and
+  the config file, not just the `--max-chars` flag.
+- `--default-max-chars`: a fallback cap that sits below flag, env, and
+  config file — for wrapper scripts that want a protective default
+  without overriding the user's own settings.
+
+### Changed
+
+- The Stop hook no longer reads `VOCALIZE_MAX_CHARS` itself; it passes
+  `--default-max-chars 500` and lets the CLI resolve the user's real
+  settings. Its subprocess timeout now scales with the text length
+  (60s base, ~12 chars/s, 900s ceiling) instead of killing any clip
+  longer than a minute; on timeout the whole process group is killed,
+  so the `afplay` child can't keep playing as an orphan.
+- The Stop hook launches `vocalize` in its own session (no controlling
+  terminal), so an inherited `overflow = "ask"` degrades to truncate
+  there instead of blocking on a prompt nobody sees.
+
+## 0.4.0
+
+### Added
+
+- `vocalize usage` — ElevenLabs quota and local cache at a glance.
+
 ## 0.3.0
 
 ### Added

{vocalize_cli-0.3.0 → vocalize_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vocalize-cli
-Version: 0.3.0
+Version: 0.5.0
 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
@@ -139,6 +139,9 @@ cat notes.md | vocalize speak-file -
 # List available voices and grab an ID
 vocalize voices
 
+# Check your quota and cache
+vocalize usage
+
 # 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
@@ -157,6 +160,17 @@ Every synthesis result is cached on disk under `~/.cache/vocalize/`, keyed
 by a hash of (text, voice, model, format, speed) — re-running the same
 command twice doesn't burn API quota twice.
 
+`vocalize stop` (from any terminal) stops playback immediately — the
+player's identity (process ID plus launch timestamp) is tracked in
+`~/.cache/vocalize/play.pid`, and stop refuses to touch a process that no
+longer matches the full record — a recycled PID is never killed. A
+stopped read exits cleanly; the mp3 stays cached.
+
+Long inputs are also split automatically — at paragraph boundaries where
+possible, then sentences, then words — into requests no bigger than
+`--chunk-chars` (default 9500), so a long read no longer fails the API's
+own per-request cap.
+
 ## Configuration
 
 Each setting is resolved on its own, taking the first source that supplies
@@ -186,7 +200,8 @@ writing anything.
 | Voice ID | `--voice` | `VOCALIZE_VOICE` | `voice` | `21m00Tcm4TlvDq8ikWAM` ("Rachel") |
 | Model ID | `--model` | `VOCALIZE_MODEL` | `model` | `eleven_multilingual_v2` |
 | Speed | `--speed` | `VOCALIZE_SPEED` | `speed` | unset — the API's own 1.0 |
-| Max characters | `--max-chars` | `VOCALIZE_MAX_CHARS` (hook only) | not read from the config file | unset on the CLI; 500 in the hook |
+| Max characters | `--max-chars` | `VOCALIZE_MAX_CHARS` | `max_chars` | unset on the CLI; the hook supplies a 500 fallback |
+| Overflow mode | `--overflow` | `VOCALIZE_OVERFLOW` | `overflow` | `truncate` |
 | Hook binary | — | `VOCALIZE_BIN` | not read from the config file | `vocalize` as found on `PATH` |
 
 The config file is TOML at `$XDG_CONFIG_HOME/vocalize/config.toml`, falling
@@ -196,8 +211,20 @@ back to `~/.config/vocalize/config.toml`. Flat keys, no sections:
 voice = "21m00Tcm4TlvDq8ikWAM"
 model = "eleven_flash_v2_5"
 speed = 0.95
+max_chars = 1000
+overflow = "ask"
 ```
 
+`overflow` decides what happens when input is longer than the resolved
+`max_chars` cap: `truncate` (the default) cuts it at the cap, `ask` prompts
+on the controlling terminal first — and degrades to `truncate` with a note
+when there is no terminal to ask on (the Stop hook runs vocalize detached
+from the terminal precisely so this always happens there; pipes and scripts
+usually have no terminal either) — and `never` speaks the whole thing
+regardless. With no cap set anywhere there is no overflow, so the mode
+never fires. Hook-triggered speech still lives under the hook's 15-minute
+watchdog described below, whatever the mode.
+
 Not having a config file is normal and silent. A file that isn't valid TOML
 is an error naming the file; a key that isn't recognised is a warning on
 stderr, so a typo doesn't pass unnoticed but doesn't stop the run either.
@@ -246,11 +273,21 @@ 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.
+By default the hook caps each response at 500 characters before speaking
+it — a Stop hook fires after every turn, so a long response would burn
+through the ElevenLabs free-tier quota fast. That 500 is only a fallback
+(`--default-max-chars`, supplied by the hook): a `VOCALIZE_MAX_CHARS` env
+var, a `max_chars` in the config file, or an `overflow` mode of `never`
+all override it, resolved by `vocalize` itself with the usual precedence.
+
+The hook launches `vocalize` in its own session, detached from the
+terminal, so an `overflow` of `ask` degrades to truncate there instead of
+writing a Y/n prompt into the middle of a session nobody is watching. Its
+subprocess timeout scales with the length of the text being spoken (about
+twelve characters a second, plus a minute of headroom), capped at a hard
+15-minute ceiling as a watchdog against hung processes — a read that
+would outlast the ceiling is stopped there, and the whole process group
+is killed so no orphaned audio keeps playing.
 
 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
@@ -258,6 +295,55 @@ run in Claude Code's own environment, not your interactive shell — if
 `VOCALIZE_BIN` to the full path (e.g. `/path/to/.venv/bin/vocalize`) to
 point the hook at it directly.
 
+### Speaking files, artifacts, and more
+
+Two primitives cover almost everything: `vocalize speak-file <path>` speaks
+any local file (markdown flattened first), and the hook's `--latest` mode
+speaks the most recent Claude Code response. Anything Claude itself has to
+fetch — a claude.ai artifact, for instance — has to be fetched *by Claude*
+(the CLI has no session), summarized, written to a file, and spoken from
+the file:
+
+```bash
+vocalize speak-file /path/to/summary.txt
+```
+
+Never interpolate the summary into the command line itself — see guard 4.
+
+**Web pages.** The CLI has no URL support, by design — it can't fetch
+anything. For a URL, Claude fetches the page itself, in an isolated
+subagent with a locked-down tool set, and produces either a short spoken
+digest or a verbatim extract of the core content. That text comes back to
+the main session the same way any other summary does: written to a file
+and passed to `speak-file`.
+
+If you wire this into a slash command of your own, treat it as a security
+surface, because **every character you speak is sent to ElevenLabs**. The
+guard principles that matter, in order:
+
+1. Resolve paths (`realpath`, expand `~`, casefold) and check an
+   **allow-list** of speakable directories — symlinks and `../` defeat
+   string matching on the raw argument.
+2. Hard-refuse secret-shaped files (`.env*`, keys, credentials) and your
+   sensitive directories; confirm before speaking anything else unusual.
+3. Summarize long or fetched content in an **isolated subagent** that
+   returns only the summary — content you fetched can carry instructions
+   aimed at your session.
+4. Pass summaries as a file path (as above) — never build the shell
+   command by interpolating model-written text into a quoted string. A
+   summary a model wrote can contain `$(...)`, and the shell will run it;
+   `printf '%s' "<summary>"` is exactly that bug.
+5. Confirm before any read that will spend real quota; a free tier is
+   10,000 characters a month.
+6. Remember the disk cache: everything spoken leaves an mp3 under
+   `~/.cache/vocalize/`.
+7. Fetching is a second egress. Fetch only the URL the user typed — a page
+   can carry text telling its reader to fetch another URL, with data
+   smuggled out in the query string.
+8. Refuse non-public hosts. `localhost` and `169.254.169.254` are
+   reachable from your machine and nowhere else; parse the URL with the
+   `ipaddress` module rather than pattern-matching the string.
+
 ## How it's built
 
 Four decisions shaped the design:
@@ -314,10 +400,11 @@ All tests run offline: the ElevenLabs client is dependency-injected into
 
 - **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.
+  a vision model in the loop, not a text transform. That's out of scope for
+  the CLI itself, but the next step now lives outside it, where it belongs:
+  the `/speak` command's web-page mode renders a page in a browser, hands it
+  to a vision-capable subagent, and the diagram description comes back as
+  plain text — same as any other content this tool speaks.
 - **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.

{vocalize_cli-0.3.0 → vocalize_cli-0.5.0}/README.md

@@ -105,6 +105,9 @@ cat notes.md | vocalize speak-file -
 # List available voices and grab an ID
 vocalize voices
 
+# Check your quota and cache
+vocalize usage
+
 # 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
@@ -123,6 +126,17 @@ Every synthesis result is cached on disk under `~/.cache/vocalize/`, keyed
 by a hash of (text, voice, model, format, speed) — re-running the same
 command twice doesn't burn API quota twice.
 
+`vocalize stop` (from any terminal) stops playback immediately — the
+player's identity (process ID plus launch timestamp) is tracked in
+`~/.cache/vocalize/play.pid`, and stop refuses to touch a process that no
+longer matches the full record — a recycled PID is never killed. A
+stopped read exits cleanly; the mp3 stays cached.
+
+Long inputs are also split automatically — at paragraph boundaries where
+possible, then sentences, then words — into requests no bigger than
+`--chunk-chars` (default 9500), so a long read no longer fails the API's
+own per-request cap.
+
 ## Configuration
 
 Each setting is resolved on its own, taking the first source that supplies
@@ -152,7 +166,8 @@ writing anything.
 | Voice ID | `--voice` | `VOCALIZE_VOICE` | `voice` | `21m00Tcm4TlvDq8ikWAM` ("Rachel") |
 | Model ID | `--model` | `VOCALIZE_MODEL` | `model` | `eleven_multilingual_v2` |
 | Speed | `--speed` | `VOCALIZE_SPEED` | `speed` | unset — the API's own 1.0 |
-| Max characters | `--max-chars` | `VOCALIZE_MAX_CHARS` (hook only) | not read from the config file | unset on the CLI; 500 in the hook |
+| Max characters | `--max-chars` | `VOCALIZE_MAX_CHARS` | `max_chars` | unset on the CLI; the hook supplies a 500 fallback |
+| Overflow mode | `--overflow` | `VOCALIZE_OVERFLOW` | `overflow` | `truncate` |
 | Hook binary | — | `VOCALIZE_BIN` | not read from the config file | `vocalize` as found on `PATH` |
 
 The config file is TOML at `$XDG_CONFIG_HOME/vocalize/config.toml`, falling
@@ -162,8 +177,20 @@ back to `~/.config/vocalize/config.toml`. Flat keys, no sections:
 voice = "21m00Tcm4TlvDq8ikWAM"
 model = "eleven_flash_v2_5"
 speed = 0.95
+max_chars = 1000
+overflow = "ask"
 ```
 
+`overflow` decides what happens when input is longer than the resolved
+`max_chars` cap: `truncate` (the default) cuts it at the cap, `ask` prompts
+on the controlling terminal first — and degrades to `truncate` with a note
+when there is no terminal to ask on (the Stop hook runs vocalize detached
+from the terminal precisely so this always happens there; pipes and scripts
+usually have no terminal either) — and `never` speaks the whole thing
+regardless. With no cap set anywhere there is no overflow, so the mode
+never fires. Hook-triggered speech still lives under the hook's 15-minute
+watchdog described below, whatever the mode.
+
 Not having a config file is normal and silent. A file that isn't valid TOML
 is an error naming the file; a key that isn't recognised is a warning on
 stderr, so a typo doesn't pass unnoticed but doesn't stop the run either.
@@ -212,11 +239,21 @@ 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.
+By default the hook caps each response at 500 characters before speaking
+it — a Stop hook fires after every turn, so a long response would burn
+through the ElevenLabs free-tier quota fast. That 500 is only a fallback
+(`--default-max-chars`, supplied by the hook): a `VOCALIZE_MAX_CHARS` env
+var, a `max_chars` in the config file, or an `overflow` mode of `never`
+all override it, resolved by `vocalize` itself with the usual precedence.
+
+The hook launches `vocalize` in its own session, detached from the
+terminal, so an `overflow` of `ask` degrades to truncate there instead of
+writing a Y/n prompt into the middle of a session nobody is watching. Its
+subprocess timeout scales with the length of the text being spoken (about
+twelve characters a second, plus a minute of headroom), capped at a hard
+15-minute ceiling as a watchdog against hung processes — a read that
+would outlast the ceiling is stopped there, and the whole process group
+is killed so no orphaned audio keeps playing.
 
 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
@@ -224,6 +261,55 @@ run in Claude Code's own environment, not your interactive shell — if
 `VOCALIZE_BIN` to the full path (e.g. `/path/to/.venv/bin/vocalize`) to
 point the hook at it directly.
 
+### Speaking files, artifacts, and more
+
+Two primitives cover almost everything: `vocalize speak-file <path>` speaks
+any local file (markdown flattened first), and the hook's `--latest` mode
+speaks the most recent Claude Code response. Anything Claude itself has to
+fetch — a claude.ai artifact, for instance — has to be fetched *by Claude*
+(the CLI has no session), summarized, written to a file, and spoken from
+the file:
+
+```bash
+vocalize speak-file /path/to/summary.txt
+```
+
+Never interpolate the summary into the command line itself — see guard 4.
+
+**Web pages.** The CLI has no URL support, by design — it can't fetch
+anything. For a URL, Claude fetches the page itself, in an isolated
+subagent with a locked-down tool set, and produces either a short spoken
+digest or a verbatim extract of the core content. That text comes back to
+the main session the same way any other summary does: written to a file
+and passed to `speak-file`.
+
+If you wire this into a slash command of your own, treat it as a security
+surface, because **every character you speak is sent to ElevenLabs**. The
+guard principles that matter, in order:
+
+1. Resolve paths (`realpath`, expand `~`, casefold) and check an
+   **allow-list** of speakable directories — symlinks and `../` defeat
+   string matching on the raw argument.
+2. Hard-refuse secret-shaped files (`.env*`, keys, credentials) and your
+   sensitive directories; confirm before speaking anything else unusual.
+3. Summarize long or fetched content in an **isolated subagent** that
+   returns only the summary — content you fetched can carry instructions
+   aimed at your session.
+4. Pass summaries as a file path (as above) — never build the shell
+   command by interpolating model-written text into a quoted string. A
+   summary a model wrote can contain `$(...)`, and the shell will run it;
+   `printf '%s' "<summary>"` is exactly that bug.
+5. Confirm before any read that will spend real quota; a free tier is
+   10,000 characters a month.
+6. Remember the disk cache: everything spoken leaves an mp3 under
+   `~/.cache/vocalize/`.
+7. Fetching is a second egress. Fetch only the URL the user typed — a page
+   can carry text telling its reader to fetch another URL, with data
+   smuggled out in the query string.
+8. Refuse non-public hosts. `localhost` and `169.254.169.254` are
+   reachable from your machine and nowhere else; parse the URL with the
+   `ipaddress` module rather than pattern-matching the string.
+
 ## How it's built
 
 Four decisions shaped the design:
@@ -280,10 +366,11 @@ All tests run offline: the ElevenLabs client is dependency-injected into
 
 - **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.
+  a vision model in the loop, not a text transform. That's out of scope for
+  the CLI itself, but the next step now lives outside it, where it belongs:
+  the `/speak` command's web-page mode renders a page in a browser, hands it
+  to a vision-capable subagent, and the diagram description comes back as
+  plain text — same as any other content this tool speaks.
 - **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.

{vocalize_cli-0.3.0 → vocalize_cli-0.5.0}/hooks/claude_stop_hook.py

@@ -28,15 +28,32 @@ from __future__ import annotations
 import json
 import os
 import shutil
+import signal
 import subprocess
 import sys
 from pathlib import Path
 
 # Keep spoken responses short by default — a Stop hook fires after every
 # turn, and a long response would eat the ElevenLabs free-tier quota fast.
-# Override with VOCALIZE_MAX_CHARS in the environment.
+# Passed as vocalize's --default-max-chars, which sits BELOW the user's own
+# settings: a --max-chars flag, VOCALIZE_MAX_CHARS in the environment, or
+# max_chars in the config file all override it (vocalize resolves those
+# itself — this hook deliberately doesn't).
 DEFAULT_MAX_CHARS = 500
 
+# Playback runs inside the vocalize subprocess and speech is roughly 12
+# characters a second, so a fixed timeout kills long clips mid-play. Scale
+# with the text instead; the ceiling still stops a hung process from
+# outliving the session. Truncation (if any) happens inside vocalize, so
+# the untruncated length is an upper bound, never too tight.
+TIMEOUT_BASE_SECONDS = 60
+TIMEOUT_CEILING_SECONDS = 900
+CHARS_PER_SECOND = 12
+
+
+def _speech_timeout(text: str) -> int:
+    return min(TIMEOUT_CEILING_SECONDS, TIMEOUT_BASE_SECONDS + len(text) // CHARS_PER_SECOND)
+
 
 def _extract_last_assistant_text(transcript_path: str) -> str:
     last_text_parts: list[str] = []
@@ -118,21 +135,34 @@ def main() -> int:
         # tool isn't installed / not on PATH in this shell.
         return 0
 
-    max_chars = os.environ.get("VOCALIZE_MAX_CHARS", str(DEFAULT_MAX_CHARS))
-
     # Options first, then "--", then the text. Click treats any argv token
     # starting with "-" as an option, so a reply that opens with a bullet
     # ("- fixed the parser") or an arrow ("-> next") would otherwise make
     # vocalize exit 2 with "No such option" and speak nothing. The "--"
     # end-of-options separator makes the text unambiguously an argument.
+    #
+    # start_new_session detaches vocalize from the controlling terminal, on
+    # purpose, for two reasons: (1) overflow "ask" then finds no /dev/tty
+    # and degrades to truncate instead of writing a Y/n prompt into the
+    # middle of a Claude Code session that nobody knows to answer; (2) the
+    # new process group lets the timeout path kill vocalize AND the afplay
+    # child it spawned — subprocess.run's own timeout kills only the direct
+    # child and leaves the audio playing.
+    argv = [vocalize_bin, "speak", "--default-max-chars", str(DEFAULT_MAX_CHARS),
+            "--play", "--", text]
+    timeout = _speech_timeout(text)
     try:
-        result = subprocess.run(
-            [vocalize_bin, "speak", "--max-chars", max_chars, "--play", "--", text],
-            timeout=60,
-            check=False,
-        )
-        if result.returncode != 0:
-            print(f"vocalize hook: vocalize exited {result.returncode}", file=sys.stderr)
+        proc = subprocess.Popen(argv, start_new_session=True)
+        try:
+            returncode = proc.wait(timeout=timeout)
+        except subprocess.TimeoutExpired:
+            os.killpg(proc.pid, signal.SIGKILL)  # pgid == pid: it leads the new session
+            proc.wait()
+            print(f"vocalize hook: speech timed out after {timeout}s; "
+                  "killed the process group", file=sys.stderr)
+            return 0
+        if returncode != 0:
+            print(f"vocalize hook: vocalize exited {returncode}", file=sys.stderr)
     except Exception as exc:  # noqa: BLE001 — must not crash the Stop hook
         # A speech failure should never break the coding session, so this
         # still returns 0 — but it's logged to stderr rather than swallowed