vocalize-cli 0.1.1__tar.gz → 0.2.0__tar.gz

{vocalize_cli-0.1.1 → vocalize_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vocalize-cli
-Version: 0.1.1
+Version: 0.2.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
@@ -20,6 +20,7 @@ Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
 Requires-Python: >=3.10
 Requires-Dist: click>=8.1
 Requires-Dist: elevenlabs>=2.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
 Provides-Extra: dev
 Requires-Dist: build; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'
@@ -109,13 +110,64 @@ vocalize speak-file report.md --voice <voice-id> --model eleven_flash_v2_5 \
 # Cap how much gets sent (handy for free-tier character budgets)
 vocalize speak-file long-report.md --max-chars 2000
 
+# Slow it down a little
+vocalize speak-file report.md --speed 0.9
+
 # 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.
+by a hash of (text, voice, model, format, speed) — re-running the same
+command twice doesn't burn API quota twice.
+
+## Configuration
+
+Each setting is resolved on its own, taking the first source that supplies
+it: CLI flag, then environment variable, then config file, then the
+built-in default.
+
+There's an interactive way to set the file up, if you'd rather not write
+TOML by hand. It walks through three lists — voice (with a live preview of
+the highlighted one), model, and speed — shows you a summary, and writes the
+config file below. Unrecognised top-level keys already in that file are
+carried through; comments and layout are not preserved. A file containing a
+TOML table or array is left alone entirely, with a message saying to edit it
+by hand.
+
+```bash
+vocalize config
+```
+
+Hotkeys: `↑`/`↓` or `k`/`j` move, `Enter` selects, `p` previews the
+highlighted voice, `m` types a value by hand, `q` or `Esc` cancels without
+writing anything.
+
+| Setting | Flag | Env var | Config file key | Default |
+|---|---|---|---|---|
+| 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 |
+| 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
+back to `~/.config/vocalize/config.toml`. Flat keys, no sections:
+
+```toml
+voice = "21m00Tcm4TlvDq8ikWAM"
+model = "eleven_flash_v2_5"
+speed = 0.95
+```
+
+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.
+`speed` must be a number between 0.7 and 1.2 — anything else is a one-line
+error naming the source it came from.
+
+The API key is separate and never read from this file: use `--api-key`,
+`ELEVENLABS_API_KEY`, or a `.env` file.
 
 ## Claude Code integration
 
@@ -194,7 +246,7 @@ 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
+  config.py       # API key resolution + settings: flag > env > config.toml > default
   exceptions.py   # VocalizeError / TTSRequestError
   tts.py          # ElevenLabs API wrapper + disk cache (client is injected, so
                    # it's mockable in tests without hitting the network)
@@ -235,7 +287,8 @@ All tests run offline: the ElevenLabs client is dependency-injected into
   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),
+  content-addressed (keyed by a hash of text, voice, model, format, and
+  speed),
   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**

{vocalize_cli-0.1.1 → vocalize_cli-0.2.0}/README.md

@@ -77,13 +77,64 @@ vocalize speak-file report.md --voice <voice-id> --model eleven_flash_v2_5 \
 # Cap how much gets sent (handy for free-tier character budgets)
 vocalize speak-file long-report.md --max-chars 2000
 
+# Slow it down a little
+vocalize speak-file report.md --speed 0.9
+
 # 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.
+by a hash of (text, voice, model, format, speed) — re-running the same
+command twice doesn't burn API quota twice.
+
+## Configuration
+
+Each setting is resolved on its own, taking the first source that supplies
+it: CLI flag, then environment variable, then config file, then the
+built-in default.
+
+There's an interactive way to set the file up, if you'd rather not write
+TOML by hand. It walks through three lists — voice (with a live preview of
+the highlighted one), model, and speed — shows you a summary, and writes the
+config file below. Unrecognised top-level keys already in that file are
+carried through; comments and layout are not preserved. A file containing a
+TOML table or array is left alone entirely, with a message saying to edit it
+by hand.
+
+```bash
+vocalize config
+```
+
+Hotkeys: `↑`/`↓` or `k`/`j` move, `Enter` selects, `p` previews the
+highlighted voice, `m` types a value by hand, `q` or `Esc` cancels without
+writing anything.
+
+| Setting | Flag | Env var | Config file key | Default |
+|---|---|---|---|---|
+| 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 |
+| 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
+back to `~/.config/vocalize/config.toml`. Flat keys, no sections:
+
+```toml
+voice = "21m00Tcm4TlvDq8ikWAM"
+model = "eleven_flash_v2_5"
+speed = 0.95
+```
+
+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.
+`speed` must be a number between 0.7 and 1.2 — anything else is a one-line
+error naming the source it came from.
+
+The API key is separate and never read from this file: use `--api-key`,
+`ELEVENLABS_API_KEY`, or a `.env` file.
 
 ## Claude Code integration
 
@@ -162,7 +213,7 @@ 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
+  config.py       # API key resolution + settings: flag > env > config.toml > default
   exceptions.py   # VocalizeError / TTSRequestError
   tts.py          # ElevenLabs API wrapper + disk cache (client is injected, so
                    # it's mockable in tests without hitting the network)
@@ -203,7 +254,8 @@ All tests run offline: the ElevenLabs client is dependency-injected into
   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),
+  content-addressed (keyed by a hash of text, voice, model, format, and
+  speed),
   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**

{vocalize_cli-0.1.1 → vocalize_cli-0.2.0}/pyproject.toml

@@ -25,6 +25,7 @@ classifiers = [
 dependencies = [
     "elevenlabs>=2.0",
     "click>=8.1",
+    "tomli>=2.0; python_version < '3.11'",
 ]
 
 [project.urls]

{vocalize_cli-0.1.1 → vocalize_cli-0.2.0}/tests/test_cli.py

@@ -8,15 +8,17 @@ from vocalize.cli import main
 def _patch_tts(monkeypatch, audio=b"fake-mp3-bytes"):
     monkeypatch.setattr(cli_module, "build_client", lambda key: object())
     captured_text = []
+    captured_settings = []
 
     def fake_synthesize(client, text, settings):
         captured_text.append(text)
+        captured_settings.append(settings)
         return audio
 
     monkeypatch.setattr(cli_module, "synthesize", fake_synthesize)
     played = {}
     monkeypatch.setattr(cli_module, "play_audio", lambda path: played.setdefault("path", path))
-    return played, captured_text
+    return played, captured_text, captured_settings
 
 
 def test_speak_writes_audio_file(monkeypatch, tmp_path):
@@ -34,7 +36,7 @@ def test_speak_writes_audio_file(monkeypatch, tmp_path):
 
 
 def test_speak_plays_by_default(monkeypatch, tmp_path):
-    played, _captured_text = _patch_tts(monkeypatch)
+    played, _captured_text, _captured_settings = _patch_tts(monkeypatch)
     out_file = tmp_path / "out.mp3"
     runner = CliRunner()
 
@@ -62,7 +64,7 @@ def test_speak_file_reads_from_stdin(monkeypatch, tmp_path):
 
 
 def test_speak_file_reads_from_path(monkeypatch, tmp_path):
-    _played, captured_text = _patch_tts(monkeypatch)
+    _played, captured_text, _captured_settings = _patch_tts(monkeypatch)
     src = tmp_path / "notes.md"
     src.write_text("| a | b |\n|---|---|\n| 1 | 2 |\n")
     out_file = tmp_path / "out.mp3"
@@ -80,7 +82,7 @@ def test_speak_file_reads_from_path(monkeypatch, tmp_path):
 
 
 def test_raw_flag_skips_flattening(monkeypatch, tmp_path):
-    _played, captured_text = _patch_tts(monkeypatch)
+    _played, captured_text, _captured_settings = _patch_tts(monkeypatch)
     src = tmp_path / "notes.md"
     src.write_text("| a | b |\n|---|---|\n| 1 | 2 |\n")
     out_file = tmp_path / "out.mp3"
@@ -100,7 +102,7 @@ def test_raw_flag_skips_flattening(monkeypatch, tmp_path):
 
 
 def test_max_chars_truncates_and_notes(monkeypatch, tmp_path):
-    _played, captured_text = _patch_tts(monkeypatch)
+    _played, captured_text, _captured_settings = _patch_tts(monkeypatch)
     out_file = tmp_path / "out.mp3"
     runner = CliRunner()
 
@@ -212,3 +214,59 @@ def test_default_output_lands_in_cache_dir(monkeypatch, tmp_path):
 
     assert result.exit_code == 0, result.output
     assert (tmp_path / "last.mp3").exists()
+
+
+def _isolate_config(monkeypatch, tmp_path):
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "empty-config"))
+    for var in ("VOCALIZE_VOICE", "VOCALIZE_MODEL", "VOCALIZE_SPEED"):
+        monkeypatch.delenv(var, raising=False)
+
+
+def test_speed_flag_reaches_the_settings(monkeypatch, tmp_path):
+    _isolate_config(monkeypatch, tmp_path)
+    _played, _captured_text, captured_settings = _patch_tts(monkeypatch)
+    out_file = tmp_path / "out.mp3"
+    runner = CliRunner()
+
+    result = runner.invoke(
+        main,
+        [
+            "speak", "hello", "--api-key", "fake-key",
+            "--output", str(out_file), "--no-play", "--speed", "1.1",
+        ],
+    )
+
+    assert result.exit_code == 0, result.output
+    assert captured_settings[0].speed == 1.1
+
+
+def test_no_speed_flag_leaves_speed_unset(monkeypatch, tmp_path):
+    _isolate_config(monkeypatch, tmp_path)
+    _played, _captured_text, captured_settings = _patch_tts(monkeypatch)
+    out_file = tmp_path / "out.mp3"
+    runner = CliRunner()
+
+    result = runner.invoke(
+        main,
+        ["speak", "hello", "--api-key", "fake-key", "--output", str(out_file), "--no-play"],
+    )
+
+    assert result.exit_code == 0, result.output
+    assert captured_settings[0].speed is None
+
+
+def test_invalid_speed_gives_a_clean_error_not_a_traceback(monkeypatch, tmp_path, capsys):
+    _isolate_config(monkeypatch, tmp_path)
+    monkeypatch.setattr(
+        "sys.argv",
+        ["vocalize", "speak", "hello", "--api-key", "fake-key", "--no-play", "--speed", "5"],
+    )
+
+    with pytest.raises(SystemExit) as excinfo:
+        cli_module.run()
+
+    assert excinfo.value.code == 1
+    captured = capsys.readouterr()
+    assert captured.err.startswith("Error: ")
+    assert "--speed" in captured.err
+    assert "Traceback" not in captured.err

vocalize_cli-0.2.0/tests/test_config.py

@@ -0,0 +1,167 @@
+import os
+
+import pytest
+
+from vocalize.config import (
+    DEFAULT_MODEL,
+    DEFAULT_VOICE,
+    _load_dotenv_if_present,
+    config_path,
+    resolve_api_key,
+    resolve_settings,
+)
+from vocalize.exceptions import ConfigError, MissingAPIKeyError
+
+# Bound at import time on purpose: conftest's autouse fixture replaces the
+# module attribute, so this reference is the only way to reach the real one.
+real_load_dotenv = _load_dotenv_if_present
+
+
+def test_explicit_key_wins_over_everything(monkeypatch):
+    monkeypatch.setenv("ELEVENLABS_API_KEY", "env-key")
+    assert resolve_api_key("explicit-key") == "explicit-key"
+
+
+def test_falls_back_to_env_var(monkeypatch):
+    monkeypatch.setenv("ELEVENLABS_API_KEY", "env-key")
+    assert resolve_api_key(None) == "env-key"
+
+
+def test_raises_clear_error_when_nothing_found(monkeypatch):
+    monkeypatch.delenv("ELEVENLABS_API_KEY", raising=False)
+    with pytest.raises(MissingAPIKeyError):
+        resolve_api_key(None)
+
+
+def test_dotenv_loader_reads_the_env_file_in_the_cwd(monkeypatch, tmp_path):
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / ".env").write_text("ELEVENLABS_API_KEY=from-cwd-file\n", encoding="utf-8")
+    # setenv before delenv so monkeypatch restores the var whether or not it
+    # was set beforehand — the real loader writes straight to os.environ.
+    monkeypatch.setenv("ELEVENLABS_API_KEY", "placeholder")
+    monkeypatch.delenv("ELEVENLABS_API_KEY")
+
+    real_load_dotenv()
+
+    assert os.environ["ELEVENLABS_API_KEY"] == "from-cwd-file"
+
+
+def _isolate(monkeypatch, tmp_path, body=None):
+    """Point the config loader at tmp_path and clear the setting env vars."""
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+    for var in ("VOCALIZE_VOICE", "VOCALIZE_MODEL", "VOCALIZE_SPEED"):
+        monkeypatch.delenv(var, raising=False)
+    path = tmp_path / "vocalize" / "config.toml"
+    if body is not None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(body, encoding="utf-8")
+    return path
+
+
+def test_config_path_honours_xdg_config_home(monkeypatch, tmp_path):
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+    assert config_path() == tmp_path / "vocalize" / "config.toml"
+
+
+def test_config_path_falls_back_to_dot_config(monkeypatch, tmp_path):
+    monkeypatch.delenv("XDG_CONFIG_HOME", raising=False)
+    monkeypatch.setattr("pathlib.Path.home", classmethod(lambda cls: tmp_path))
+    assert config_path() == tmp_path / ".config" / "vocalize" / "config.toml"
+
+
+def test_missing_config_file_gives_the_built_in_defaults(monkeypatch, tmp_path):
+    _isolate(monkeypatch, tmp_path)
+
+    settings = resolve_settings()
+
+    assert settings.voice_id == DEFAULT_VOICE
+    assert settings.model_id == DEFAULT_MODEL
+    assert settings.speed is None
+
+
+def test_config_file_beats_the_default(monkeypatch, tmp_path):
+    _isolate(monkeypatch, tmp_path, 'voice = "file-voice"\nmodel = "file-model"\nspeed = 0.9\n')
+
+    settings = resolve_settings()
+
+    assert settings.voice_id == "file-voice"
+    assert settings.model_id == "file-model"
+    assert settings.speed == 0.9
+
+
+def test_env_var_beats_the_config_file(monkeypatch, tmp_path):
+    _isolate(monkeypatch, tmp_path, 'voice = "file-voice"\nmodel = "file-model"\nspeed = 0.9\n')
+    monkeypatch.setenv("VOCALIZE_VOICE", "env-voice")
+    monkeypatch.setenv("VOCALIZE_MODEL", "env-model")
+    monkeypatch.setenv("VOCALIZE_SPEED", "1.1")
+
+    settings = resolve_settings()
+
+    assert settings.voice_id == "env-voice"
+    assert settings.model_id == "env-model"
+    assert settings.speed == 1.1
+
+
+def test_flag_beats_env_var_and_config_file(monkeypatch, tmp_path):
+    _isolate(monkeypatch, tmp_path, 'voice = "file-voice"\nmodel = "file-model"\nspeed = 0.9\n')
+    monkeypatch.setenv("VOCALIZE_VOICE", "env-voice")
+    monkeypatch.setenv("VOCALIZE_MODEL", "env-model")
+    monkeypatch.setenv("VOCALIZE_SPEED", "1.1")
+
+    settings = resolve_settings(voice_id="flag-voice", model_id="flag-model", speed=0.8)
+
+    assert settings.voice_id == "flag-voice"
+    assert settings.model_id == "flag-model"
+    assert settings.speed == 0.8
+
+
+def test_unknown_config_key_warns_but_still_loads_the_known_ones(monkeypatch, tmp_path, capsys):
+    _isolate(monkeypatch, tmp_path, 'voice = "file-voice"\nvoise = "typo"\n')
+
+    settings = resolve_settings()
+
+    assert settings.voice_id == "file-voice"
+    captured = capsys.readouterr()
+    assert "vocalize: unknown config key 'voise'" in captured.err
+    assert captured.err.count("unknown config key") == 1
+
+
+def test_malformed_config_file_gives_a_clean_error(monkeypatch, tmp_path):
+    path = _isolate(monkeypatch, tmp_path, "voice = \n")
+
+    with pytest.raises(ConfigError) as excinfo:
+        resolve_settings()
+
+    assert str(path) in str(excinfo.value)
+
+
+@pytest.mark.parametrize("value", ["fast", "0.2", "5"])
+def test_invalid_speed_from_the_env_var_is_rejected(monkeypatch, tmp_path, value):
+    _isolate(monkeypatch, tmp_path)
+    monkeypatch.setenv("VOCALIZE_SPEED", value)
+
+    with pytest.raises(ConfigError) as excinfo:
+        resolve_settings()
+
+    assert "VOCALIZE_SPEED" in str(excinfo.value)
+
+
+@pytest.mark.parametrize("literal", ['"fast"', "0.2", "5"])
+def test_invalid_speed_from_the_config_file_is_rejected(monkeypatch, tmp_path, literal):
+    path = _isolate(monkeypatch, tmp_path, f"speed = {literal}\n")
+
+    with pytest.raises(ConfigError) as excinfo:
+        resolve_settings()
+
+    assert "'speed'" in str(excinfo.value)
+    assert str(path) in str(excinfo.value)
+
+
+@pytest.mark.parametrize("value", ["fast", 0.2, 5])
+def test_invalid_speed_from_the_flag_is_rejected(monkeypatch, tmp_path, value):
+    _isolate(monkeypatch, tmp_path)
+
+    with pytest.raises(ConfigError) as excinfo:
+        resolve_settings(speed=value)
+
+    assert "--speed" in str(excinfo.value)

{vocalize_cli-0.1.1 → vocalize_cli-0.2.0}/tests/test_tts.py

@@ -1,3 +1,4 @@
+import hashlib
 from pathlib import Path
 from types import SimpleNamespace
 
@@ -5,7 +6,7 @@ import pytest
 
 from vocalize.config import Settings
 from vocalize.exceptions import TTSRequestError
-from vocalize.tts import list_voices, synthesize
+from vocalize.tts import _cache_key, list_voices, synthesize
 
 
 class FakeTTSNamespace:
@@ -109,3 +110,37 @@ def test_list_voices_returns_id_and_name():
     result = list_voices(client)
 
     assert result == [{"id": "abc123", "name": "Rachel"}]
+
+
+def test_speed_is_passed_through_as_voice_settings(tmp_path):
+    client = FakeClient()
+    settings = Settings(voice_id="v1", model_id="m1", speed=1.1)
+
+    synthesize(client, "hi", settings, cache_dir=tmp_path)
+
+    assert client.text_to_speech.calls[0]["voice_settings"].speed == 1.1
+
+
+def test_unset_speed_sends_no_voice_settings_kwarg(tmp_path):
+    client = FakeClient()
+    settings = Settings(voice_id="v1", model_id="m1")
+
+    synthesize(client, "hi", settings, cache_dir=tmp_path)
+
+    assert "voice_settings" not in client.text_to_speech.calls[0]
+
+
+def test_cache_key_differs_by_speed():
+    unset = Settings(voice_id="v1", model_id="m1")
+    faster = Settings(voice_id="v1", model_id="m1", speed=1.1)
+
+    assert _cache_key("hi", unset) != _cache_key("hi", faster)
+
+
+def test_cache_key_is_unchanged_when_speed_is_unset():
+    # Pins the pre-speed payload scheme so caches written by older
+    # versions keep hitting.
+    settings = Settings(voice_id="v1", model_id="m1", output_format="f1")
+    old_payload = f"{settings.voice_id}|{settings.model_id}|{settings.output_format}|hi"
+
+    assert _cache_key("hi", settings) == hashlib.sha256(old_payload.encode("utf-8")).hexdigest()