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

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

@@ -3,6 +3,35 @@
 All notable changes to this project are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## 0.7.0 - 2026-08-31
+
+### Added
+
+- `vocalize clip` — speaks the macOS clipboard (pbpaste). Stops any
+  current playback first, refuses an empty clipboard, and refuses
+  credential-shaped content: a single high-entropy token, or one starting
+  with a known secret prefix (sk-, pypi-, ghp\_, op://, eyJ, …), is never
+  echoed or sent to ElevenLabs. `--allow-secret` bypasses the guard.
+- `--ask-dialog` on speak/speak-file/clip — when overflow is `ask` and no
+  terminal is attached, ask via a native macOS dialog (Truncate / Speak
+  all / Cancel, 30 s timeout defaulting to Truncate) instead of silently
+  truncating. Off by default; the Claude Code Stop hook never uses it.
+- macOS Quick Actions: "Speak with Vocalize" (highlight text in any app →
+  right-click → Services, or a keyboard shortcut) and "Stop Vocalize".
+  Install with `python3 hooks/install_quick_action.py`; the checked-in
+  bundles live in `hooks/quick_actions/`.
+
+## 0.6.0 - 2026-08-31
+
+### Added
+
+- `vocalize settings` — prints the resolved settings, one key=value per
+  line, so wrapper scripts (like the /speak slash command) can read the
+  effective `overflow` and `max_chars` instead of hardcoding them.
+- `--print-length` on the Stop hook: prints the response's character count
+  instead of speaking, so a wrapper can decide to ask about truncation
+  interactively before any audio is spent.
+
 ## 0.5.0 - 2026-08-31
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vocalize-cli
-Version: 0.5.0
+Version: 0.7.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
@@ -136,6 +136,9 @@ vocalize speak-file report.md
 # Pipe anything in
 cat notes.md | vocalize speak-file -
 
+# Speak whatever is on the macOS clipboard
+vocalize clip
+
 # List available voices and grab an ID
 vocalize voices
 
@@ -171,6 +174,14 @@ 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.
 
+`vocalize clip` stops any current playback first, then speaks the
+clipboard. It refuses content shaped like a secret — a single
+high-entropy token, or one starting with a known credential prefix
+(`sk-`, `pypi-`, `ghp_`, `op://`, `eyJ`, …) — without echoing it anywhere;
+`--allow-secret` bypasses the guard when you're sure. This is a
+habit-breaking guard for text copied out of a password manager, not a
+full secret scanner.
+
 ## Configuration
 
 Each setting is resolved on its own, taking the first source that supplies
@@ -225,6 +236,10 @@ 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.
 
+`vocalize settings` prints the resolved values (one `key=value` per
+line, env and config applied) — handy for wrapper scripts and for checking
+which source won.
+
 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.
@@ -237,6 +252,35 @@ in the current directory, then the OS keychain. `vocalize auth login` sets
 up the keychain entry; `vocalize auth status` shows which of those sources
 is currently supplying the key.
 
+## macOS Quick Actions (highlight → speak)
+
+Two Services let you use vocalize from any app without a terminal:
+
+- **Speak with Vocalize** — highlight text anywhere, right-click →
+  Services → Speak with Vocalize. It stops whatever was already playing
+  and reads the selection. If the selection is over your cap and your
+  overflow mode is `ask`, a native dialog asks Truncate / Speak all /
+  Cancel (that's the `--ask-dialog` flag at work).
+- **Stop Vocalize** — appears in every app's application menu → Services;
+  silences playback from anywhere.
+
+Install both:
+
+```bash
+python3 hooks/install_quick_action.py
+```
+
+This copies the bundles from `hooks/quick_actions/` into
+`~/Library/Services/` with this machine's absolute `vocalize` path baked
+in, then refreshes the Services registry. To trigger them from the
+keyboard, assign shortcuts under System Settings → Keyboard → Keyboard
+Shortcuts → Services → Text.
+
+Some Electron apps (Claude Code desktop among them) don't expose the
+Services menu for text selected in their own window. There, copy the
+selection and use `/speak clip` (or `vocalize clip` in a terminal)
+instead.
+
 ## Claude Code integration
 
 The hook scripts ship in the git repository, not the PyPI package — clone

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

@@ -102,6 +102,9 @@ vocalize speak-file report.md
 # Pipe anything in
 cat notes.md | vocalize speak-file -
 
+# Speak whatever is on the macOS clipboard
+vocalize clip
+
 # List available voices and grab an ID
 vocalize voices
 
@@ -137,6 +140,14 @@ 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.
 
+`vocalize clip` stops any current playback first, then speaks the
+clipboard. It refuses content shaped like a secret — a single
+high-entropy token, or one starting with a known credential prefix
+(`sk-`, `pypi-`, `ghp_`, `op://`, `eyJ`, …) — without echoing it anywhere;
+`--allow-secret` bypasses the guard when you're sure. This is a
+habit-breaking guard for text copied out of a password manager, not a
+full secret scanner.
+
 ## Configuration
 
 Each setting is resolved on its own, taking the first source that supplies
@@ -191,6 +202,10 @@ 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.
 
+`vocalize settings` prints the resolved values (one `key=value` per
+line, env and config applied) — handy for wrapper scripts and for checking
+which source won.
+
 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.
@@ -203,6 +218,35 @@ in the current directory, then the OS keychain. `vocalize auth login` sets
 up the keychain entry; `vocalize auth status` shows which of those sources
 is currently supplying the key.
 
+## macOS Quick Actions (highlight → speak)
+
+Two Services let you use vocalize from any app without a terminal:
+
+- **Speak with Vocalize** — highlight text anywhere, right-click →
+  Services → Speak with Vocalize. It stops whatever was already playing
+  and reads the selection. If the selection is over your cap and your
+  overflow mode is `ask`, a native dialog asks Truncate / Speak all /
+  Cancel (that's the `--ask-dialog` flag at work).
+- **Stop Vocalize** — appears in every app's application menu → Services;
+  silences playback from anywhere.
+
+Install both:
+
+```bash
+python3 hooks/install_quick_action.py
+```
+
+This copies the bundles from `hooks/quick_actions/` into
+`~/Library/Services/` with this machine's absolute `vocalize` path baked
+in, then refreshes the Services registry. To trigger them from the
+keyboard, assign shortcuts under System Settings → Keyboard → Keyboard
+Shortcuts → Services → Text.
+
+Some Electron apps (Claude Code desktop among them) don't expose the
+Services menu for text selected in their own window. There, copy the
+selection and use `/speak clip` (or `vocalize clip` in a terminal)
+instead.
+
 ## Claude Code integration
 
 The hook scripts ship in the git repository, not the PyPI package — clone

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

@@ -9,6 +9,10 @@
    that response. Run it when you want speech instead of installing the
    hook and getting it after every turn.
 
+Add `--print-length` to either mode to print the response's character
+count instead of speaking — for wrappers deciding whether to ask about
+truncation before committing to audio.
+
 Either way it pulls the most recent assistant text message out of the
 transcript and pipes it through the `vocalize` CLI (the same one used
 directly from the command line), so there's exactly one code path for
@@ -125,6 +129,15 @@ def main() -> int:
 
     text = _extract_last_assistant_text(transcript_path)
     if not text.strip():
+        if "--print-length" in sys.argv[1:]:
+            print(0)
+        return 0
+
+    if "--print-length" in sys.argv[1:]:
+        # Report the response's size without speaking — the /speak command
+        # uses this to decide whether to ask about truncation in-app. Raw
+        # (pre-flattening) length: close enough for an ask threshold.
+        print(len(text))
         return 0
 
     # VOCALIZE_BIN wins over PATH so a venv install still resolves when the

vocalize_cli-0.7.0/hooks/install_quick_action.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""Copy the vocalize Quick Actions into ~/Library/Services/.
+
+Unlike install_hook.py there is no shared settings file to merge into —
+each Service is a self-contained bundle, so "install" is: copy the bundle
+with this machine's absolute vocalize path baked in. Re-running simply
+overwrites the same two bundles.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from xml.sax.saxutils import escape as xml_escape
+
+TEMPLATES_DIR = Path(__file__).resolve().parent / "quick_actions"
+SERVICES_DIR = Path.home() / "Library" / "Services"
+BUNDLE_NAMES = ("Speak with Vocalize.workflow", "Stop Vocalize.workflow")
+PLACEHOLDER = "__VOCALIZE_BIN__"
+PBS = "/System/Library/CoreServices/pbs"
+
+# The path lands inside BIN="..." in the Quick Action's zsh script. These
+# characters could escape those quotes, so refuse rather than try to quote.
+_UNSAFE_PATH_CHARS = set('"\\`$')
+
+
+def _resolve_vocalize_bin() -> Path:
+    repo_venv = Path(__file__).resolve().parent.parent / ".venv" / "bin" / "vocalize"
+    if repo_venv.is_file():
+        return repo_venv
+    on_path = shutil.which("vocalize")
+    if on_path:
+        return Path(on_path).resolve()
+    print(
+        "Could not find a vocalize binary (checked .venv/bin/vocalize next to "
+        "this repo, then PATH). Install vocalize first.",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+
+def _install_one(name: str, bin_path: str) -> None:
+    src = TEMPLATES_DIR / name
+    dest = SERVICES_DIR / name
+    if dest.exists():
+        shutil.rmtree(dest)
+    shutil.copytree(src, dest)
+
+    wflow = dest / "Contents" / "Resources" / "document.wflow"
+    text = wflow.read_text(encoding="utf-8")
+    wflow.write_text(text.replace(PLACEHOLDER, xml_escape(bin_path)), encoding="utf-8")
+
+
+def main() -> int:
+    bin_path = str(_resolve_vocalize_bin())
+    if _UNSAFE_PATH_CHARS & set(bin_path):
+        print(
+            f"Refusing to install: the resolved vocalize path contains characters "
+            f"that would break the Quick Action script: {bin_path!r}",
+            file=sys.stderr,
+        )
+        return 1
+
+    SERVICES_DIR.mkdir(parents=True, exist_ok=True)
+    for name in BUNDLE_NAMES:
+        _install_one(name, bin_path)
+        print(f"Installed {name} -> {SERVICES_DIR / name}")
+
+    # Nudge the Services registry so the new entries appear without a logout.
+    subprocess.run([PBS, "-update"], check=False)
+
+    print(f"\nUsing vocalize at: {bin_path}")
+    print('Highlight text in any app, then right-click -> Services -> "Speak with Vocalize".')
+    print("Keyboard shortcuts: System Settings -> Keyboard -> Keyboard Shortcuts -> Services.")
+    print("If the actions don't appear, re-open the Services submenu once, or log out and in.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

vocalize_cli-0.7.0/hooks/quick_actions/Speak with Vocalize.workflow/Contents/Info.plist

@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>NSServices</key>
+	<array>
+		<dict>
+			<key>NSMenuItem</key>
+			<dict>
+				<key>default</key>
+				<string>Speak with Vocalize</string>
+			</dict>
+			<key>NSMessage</key>
+			<string>runWorkflowAsService</string>
+			<key>NSSendTypes</key>
+			<array>
+				<string>public.utf8-plain-text</string>
+			</array>
+		</dict>
+	</array>
+	<key>CFBundleDevelopmentRegion</key>
+	<string>en_US</string>
+	<key>CFBundleIdentifier</key>
+	<string>cards.arda.vocalize.speak</string>
+	<key>CFBundleName</key>
+	<string>Speak with Vocalize</string>
+	<key>CFBundleShortVersionString</key>
+	<string>1.0</string>
+</dict>
+</plist>

vocalize_cli-0.7.0/hooks/quick_actions/Speak with Vocalize.workflow/Contents/Resources/document.wflow

@@ -0,0 +1,205 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>AMApplicationBuild</key>
+	<string>346</string>
+	<key>AMApplicationVersion</key>
+	<string>2.3</string>
+	<key>AMDocumentVersion</key>
+	<string>2</string>
+	<key>actions</key>
+	<array>
+		<dict>
+			<key>action</key>
+			<dict>
+				<key>AMAccepts</key>
+				<dict>
+					<key>Container</key>
+					<string>List</string>
+					<key>Optional</key>
+					<true/>
+					<key>Types</key>
+					<array>
+						<string>com.apple.cocoa.string</string>
+					</array>
+				</dict>
+				<key>AMActionVersion</key>
+				<string>2.0.3</string>
+				<key>AMApplication</key>
+				<array>
+					<string>Automator</string>
+				</array>
+				<key>AMParameterProperties</key>
+				<dict>
+					<key>COMMAND_STRING</key>
+					<dict/>
+					<key>CheckedForUserDefaultShell</key>
+					<dict/>
+					<key>inputMethod</key>
+					<dict/>
+					<key>shell</key>
+					<dict/>
+					<key>source</key>
+					<dict/>
+				</dict>
+				<key>AMProvides</key>
+				<dict>
+					<key>Container</key>
+					<string>List</string>
+					<key>Types</key>
+					<array>
+						<string>com.apple.cocoa.string</string>
+					</array>
+				</dict>
+				<key>ActionBundlePath</key>
+				<string>/System/Library/Automator/Run Shell Script.action</string>
+				<key>ActionName</key>
+				<string>Run Shell Script</string>
+				<key>ActionParameters</key>
+				<dict>
+					<key>COMMAND_STRING</key>
+					<string># Selected text arrives on stdin. The only interpolated value is the
+# vocalize path, baked in by hooks/install_quick_action.py.
+BIN="__VOCALIZE_BIN__"
+if [[ ! -x "$BIN" ]]; then
+  /usr/bin/osascript -e 'display notification "vocalize not found — re-run hooks/install_quick_action.py" with title "Vocalize"'
+  exit 1
+fi
+"$BIN" stop &gt;/dev/null 2&gt;&amp;1
+exec "$BIN" speak-file - --play --ask-dialog</string>
+					<key>CheckedForUserDefaultShell</key>
+					<false/>
+					<key>inputMethod</key>
+					<integer>0</integer>
+					<key>shell</key>
+					<string>/bin/zsh</string>
+					<key>source</key>
+					<string></string>
+				</dict>
+				<key>BundleIdentifier</key>
+				<string>com.apple.RunShellScript</string>
+				<key>CFBundleVersion</key>
+				<string>2.0.3</string>
+				<key>CanShowSelectedItemsWhenRun</key>
+				<false/>
+				<key>CanShowWhenRun</key>
+				<true/>
+				<key>Category</key>
+				<array>
+					<string>AMCategoryUtilities</string>
+				</array>
+				<key>Class Name</key>
+				<string>RunShellScriptAction</string>
+				<key>InputUUID</key>
+				<string>8A4A21F5-3C6E-4F58-9C1D-2B7E6A90D101</string>
+				<key>Keywords</key>
+				<array>
+					<string>Shell</string>
+					<string>Script</string>
+					<string>Command</string>
+					<string>Run</string>
+					<string>Unix</string>
+				</array>
+				<key>OutputUUID</key>
+				<string>8A4A21F5-3C6E-4F58-9C1D-2B7E6A90D102</string>
+				<key>UUID</key>
+				<string>8A4A21F5-3C6E-4F58-9C1D-2B7E6A90D103</string>
+				<key>UnlocalizedApplications</key>
+				<array>
+					<string>Automator</string>
+				</array>
+				<key>arguments</key>
+				<dict>
+					<key>0</key>
+					<dict>
+						<key>default value</key>
+						<integer>0</integer>
+						<key>name</key>
+						<string>inputMethod</string>
+						<key>required</key>
+						<string>0</string>
+						<key>type</key>
+						<string>0</string>
+						<key>uuid</key>
+						<string>0</string>
+					</dict>
+					<key>1</key>
+					<dict>
+						<key>default value</key>
+						<string></string>
+						<key>name</key>
+						<string>source</string>
+						<key>required</key>
+						<string>0</string>
+						<key>type</key>
+						<string>0</string>
+						<key>uuid</key>
+						<string>1</string>
+					</dict>
+					<key>2</key>
+					<dict>
+						<key>default value</key>
+						<false/>
+						<key>name</key>
+						<string>CheckedForUserDefaultShell</string>
+						<key>required</key>
+						<string>0</string>
+						<key>type</key>
+						<string>0</string>
+						<key>uuid</key>
+						<string>2</string>
+					</dict>
+					<key>3</key>
+					<dict>
+						<key>default value</key>
+						<string></string>
+						<key>name</key>
+						<string>COMMAND_STRING</string>
+						<key>required</key>
+						<string>0</string>
+						<key>type</key>
+						<string>0</string>
+						<key>uuid</key>
+						<string>3</string>
+					</dict>
+					<key>4</key>
+					<dict>
+						<key>default value</key>
+						<string>/bin/sh</string>
+						<key>name</key>
+						<string>shell</string>
+						<key>required</key>
+						<string>0</string>
+						<key>type</key>
+						<string>0</string>
+						<key>uuid</key>
+						<string>4</string>
+					</dict>
+				</dict>
+				<key>isViewVisible</key>
+				<true/>
+			</dict>
+			<key>isViewVisible</key>
+			<true/>
+		</dict>
+	</array>
+	<key>connectors</key>
+	<dict/>
+	<key>workflowMetaData</key>
+	<dict>
+		<key>serviceApplicationBundleID</key>
+		<string></string>
+		<key>serviceApplicationPath</key>
+		<string></string>
+		<key>serviceInputTypeIdentifier</key>
+		<string>com.apple.Automator.text</string>
+		<key>serviceOutputTypeIdentifier</key>
+		<string>com.apple.Automator.nothing</string>
+		<key>serviceProcessesInput</key>
+		<integer>1</integer>
+		<key>workflowTypeIdentifier</key>
+		<string>com.apple.Automator.servicesMenu</string>
+	</dict>
+</dict>
+</plist>

vocalize_cli-0.7.0/hooks/quick_actions/Stop Vocalize.workflow/Contents/Info.plist

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>NSServices</key>
+	<array>
+		<dict>
+			<key>NSMenuItem</key>
+			<dict>
+				<key>default</key>
+				<string>Stop Vocalize</string>
+			</dict>
+			<key>NSMessage</key>
+			<string>runWorkflowAsService</string>
+		</dict>
+	</array>
+	<key>CFBundleDevelopmentRegion</key>
+	<string>en_US</string>
+	<key>CFBundleIdentifier</key>
+	<string>cards.arda.vocalize.stop</string>
+	<key>CFBundleName</key>
+	<string>Stop Vocalize</string>
+	<key>CFBundleShortVersionString</key>
+	<string>1.0</string>
+</dict>
+</plist>