vocalize-cli 0.10.1__tar.gz → 0.10.2__tar.gz

{vocalize_cli-0.10.1 → vocalize_cli-0.10.2}/.gitignore

@@ -11,5 +11,6 @@ dist/
 venv/
 *.mp3
 *.wav
+!vocalize/assets/cues/*.wav
 .claude/
 uv.lock

{vocalize_cli-0.10.1 → vocalize_cli-0.10.2}/CHANGELOG.md

@@ -3,6 +3,32 @@
 All notable changes to this project are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## 0.10.2 - 2026-09-02
+
+### Added
+
+- **`[stt] cues`** picks what a dictation's feedback sounds — say instead
+  of, or alongside, the Tink/Pop/Glass system sounds. `"sounds"` (default)
+  is unchanged; `"words"` speaks "Start.", "Stopped.", "Ready." in their
+  place; `"both"` speaks the word and then plays the sound. The word files
+  ship in `vocalize/assets/cues/`, generated with the local Kokoro voice.
+  A spoken "Start." plays *before* the recorder launches — played once the
+  microphone was open it would be recorded and transcribed along with the
+  dictation. In `"both"` mode the Tink still plays *after* the microphone
+  opens, so the two cues keep distinct meanings: the word is "get ready",
+  the sound is "talk now". The plain Tink is unaffected.
+
+### Known issue
+
+- In `"words"` mode there is no cue for the moment the microphone actually
+  opens, which is a second or so after "Start." finishes (LaunchServices
+  start-up plus the input device switching on). People start talking too
+  soon and lose their first word. The fix — open and warm the microphone
+  first, play the cue, and only then capture — is tracked in
+  [#2](https://github.com/matthager12-collab/vocalize/issues/2). Until
+  then: in `"words"` mode, wait a beat after "Start."; in `"both"` mode,
+  talk after the Tink.
+
 ## 0.10.1 - 2026-09-02
 
 Three fixes found in the first owner-present run of 0.10.0's dictation.

{vocalize_cli-0.10.1 → vocalize_cli-0.10.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vocalize-cli
-Version: 0.10.1
+Version: 0.10.2
 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
@@ -485,6 +485,8 @@ terminal, if you'd rather trigger it that way.
 - **A third press while transcribing is refused**: a Pop, and "Still
   transcribing the last dictation." Wait for the clipboard notification, or
   `--cancel`, before dictating again.
+- Can't tell Tink from Pop from Glass yet? Set `[stt] cues = "words"` and
+  vocalize says "Start.", "Stopped.", "Ready." instead.
 
 ### `vocalize listen`
 
@@ -519,6 +521,7 @@ input_device = ""      # "" = system default; else an exact name from --list-dev
 cleanup = false        # send the transcript (never audio) to Claude first
 max_seconds = 120      # 1-600; the recorder self-stops here, dictate backstops it
 sounds = true          # the Tink/Pop/Glass feedback sounds
+cues = "sounds"        # "sounds" | "words" | "both" — speak "Start."/"Stopped."/"Ready." instead
 ```
 
 | Key | Allowed values | Default |
@@ -530,6 +533,7 @@ sounds = true          # the Tink/Pop/Glass feedback sounds
 | `paste` | reserved — not implemented in 0.10.0 | `false` |
 | `max_seconds` | integer, 1–600 | `120` |
 | `sounds` | `true` / `false` | `true` |
+| `cues` | `sounds`, `words`, `both` | `sounds` |
 
 An unknown key warns on stderr; a bad value is a `ConfigError` naming it —
 every one of these becomes a subprocess argument eventually, so nothing

{vocalize_cli-0.10.1 → vocalize_cli-0.10.2}/README.md

@@ -449,6 +449,8 @@ terminal, if you'd rather trigger it that way.
 - **A third press while transcribing is refused**: a Pop, and "Still
   transcribing the last dictation." Wait for the clipboard notification, or
   `--cancel`, before dictating again.
+- Can't tell Tink from Pop from Glass yet? Set `[stt] cues = "words"` and
+  vocalize says "Start.", "Stopped.", "Ready." instead.
 
 ### `vocalize listen`
 
@@ -483,6 +485,7 @@ input_device = ""      # "" = system default; else an exact name from --list-dev
 cleanup = false        # send the transcript (never audio) to Claude first
 max_seconds = 120      # 1-600; the recorder self-stops here, dictate backstops it
 sounds = true          # the Tink/Pop/Glass feedback sounds
+cues = "sounds"        # "sounds" | "words" | "both" — speak "Start."/"Stopped."/"Ready." instead
 ```
 
 | Key | Allowed values | Default |
@@ -494,6 +497,7 @@ sounds = true          # the Tink/Pop/Glass feedback sounds
 | `paste` | reserved — not implemented in 0.10.0 | `false` |
 | `max_seconds` | integer, 1–600 | `120` |
 | `sounds` | `true` / `false` | `true` |
+| `cues` | `sounds`, `words`, `both` | `sounds` |
 
 An unknown key warns on stderr; a bad value is a `ConfigError` naming it —
 every one of these becomes a subprocess argument eventually, so nothing

{vocalize_cli-0.10.1 → vocalize_cli-0.10.2}/docs/dictation.md

@@ -147,6 +147,16 @@ never runs two transcriptions over the same recording, and it never
 silently drops one either. Wait for the clipboard notification, or use
 `--cancel`.
 
+New to the sounds and can't tell Tink from Pop from Glass? Set
+`[stt] cues = "words"` and vocalize says "Start.", "Stopped." and "Ready."
+instead, or `"both"` to hear the word and then its sound — see the `[stt]`
+table below. Timing matters: "Start." is spoken *before* the microphone
+opens (so it is never in your recording), and the microphone is open
+about a second later — the Tink marks that moment. So in `"both"` mode
+talk after the Tink; in `"words"` mode give it a beat after "Start.".
+Closing that gap is
+[#2](https://github.com/matthager12-collab/vocalize/issues/2).
+
 ## `vocalize listen`
 
 The terminal-facing primitive behind the hotkey:
@@ -216,6 +226,7 @@ cleanup = false
 paste = false
 max_seconds = 120
 sounds = true
+cues = "sounds"  # "sounds" | "words" | "both"
 ```
 
 | Key | Type / allowlist | Default | Notes |
@@ -226,7 +237,8 @@ sounds = true
 | `cleanup` | `true` / `false` | `false` | see `--cleanup` above |
 | `paste` | reserved | `false` | not implemented in 0.10.0 — setting it does nothing |
 | `max_seconds` | integer, 1–600 | `120` | the recorder self-stops here; `dictate` backstops it a few seconds later in case the recorder doesn't |
-| `sounds` | `true` / `false` | `true` | the Tink/Pop/Glass feedback; `false` silences all three |
+| `sounds` | `true` / `false` | `true` | the Tink/Pop/Glass feedback; `false` silences all three (words included) |
+| `cues` | `sounds`, `words`, `both` | `sounds` | `"words"` speaks "Start.", "Stopped.", "Ready." instead of the system sounds; `"both"` speaks the word and then plays the sound — for the start cue, the word before the microphone opens and the Tink once it has. Has no effect while `sounds = false`. |
 
 Every value here eventually becomes a subprocess argument — the recorder's
 `--device`, or the whisper worker's `--model`/`--language` — so each one is
@@ -243,6 +255,7 @@ stt.model=small.en
 stt.language=en
 stt.cleanup=false
 stt.max_seconds=120
+stt.cues=sounds
 ```
 
 ### The input-device gotcha

{vocalize_cli-0.10.1 → vocalize_cli-0.10.2}/docs/roadmap.md

@@ -6,7 +6,8 @@ Future work, with the research behind each item. Status legend: **planned** = an
 |---|---|---|---|
 | Hotkey-triggered local dictation (voice → text via a local Whisper model, Quick Action toggle, clipboard output, optional cleanup) | **shipped** in 0.10.0, usable from 0.10.1 | [#1](https://github.com/matthager12-collab/vocalize/issues/1) · [plan](plans/2026-09-next-features/plan.md) | [analysis](next-features-analysis.md) · [full design](research/2026-09-01-dictation-design.md) · [voicebox findings](research/2026-09-01-voicebox-findings.md) |
 | `vocalize status` one-screen readiness check | **shipped** in 0.10.0 | [#1](https://github.com/matthager12-collab/vocalize/issues/1) | [analysis](next-features-analysis.md) |
-| Spoken cues for dictation (`[stt] cues = "words"`: "start" / "stopped" / "ready" instead of, or as well as, the sounds) | building | — | owner request, 2026-09-02 |
+| Spoken cues for dictation (`[stt] cues = "words"`: "start" / "stopped" / "ready" instead of, or as well as, the sounds) | **shipped** in 0.10.2 | — | owner request, 2026-09-02 |
+| Cue timing: the "talk now" cue must follow the *open* microphone and never be recorded (recorder warms the input, reports ready, waits for a `go` marker; `dictate` plays the cue, then touches `go`) | planned | [#2](https://github.com/matthager12-collab/vocalize/issues/2) | first live use of 0.10.2: people talk after "Start." and lose the first word |
 | Config portal (`vocalize portal`, stdlib local web page on top of the same readiness rows) | planned — runs 7–10 of the [plan](plans/2026-09-next-features/plan.md) | [#1](https://github.com/matthager12-collab/vocalize/issues/1) | [analysis](next-features-analysis.md) · [full design](research/2026-09-01-config-portal-design.md) |
 
 ## Decisions (2026-09-01, closed 2026-09-02)

{vocalize_cli-0.10.1 → vocalize_cli-0.10.2}/tests/test_cli.py

@@ -624,8 +624,10 @@ def test_settings_prints_the_stt_lines(monkeypatch, tmp_path):
     _isolate_overflow_env(monkeypatch, tmp_path)
     cfg = tmp_path / "vocalize" / "config.toml"
     cfg.parent.mkdir(parents=True, exist_ok=True)
-    cfg.write_text('[stt]\nmodel = "base.en"\ncleanup = true\nmax_seconds = 30\n',
-                   encoding="utf-8")
+    cfg.write_text(
+        '[stt]\nmodel = "base.en"\ncleanup = true\nmax_seconds = 30\ncues = "sounds"\n',
+        encoding="utf-8",
+    )
 
     result = CliRunner().invoke(main, ["settings"])
 
@@ -634,6 +636,7 @@ def test_settings_prints_the_stt_lines(monkeypatch, tmp_path):
     assert "stt.language=en" in result.output
     assert "stt.cleanup=true" in result.output
     assert "stt.max_seconds=30" in result.output
+    assert "stt.cues=sounds" in result.output
 
 
 def test_settings_prints_defaults_when_nothing_is_configured(monkeypatch, tmp_path):

{vocalize_cli-0.10.1 → vocalize_cli-0.10.2}/tests/test_config.py

@@ -697,6 +697,30 @@ def test_a_non_boolean_stt_flag_is_refused(monkeypatch, tmp_path, key):
     assert f"stt.{key}" in str(excinfo.value)
 
 
+@pytest.mark.parametrize("value", ['"chime"', "1"])
+def test_an_invalid_stt_cues_value_is_refused(monkeypatch, tmp_path, value):
+    with pytest.raises(ConfigError) as excinfo:
+        _load_stt(monkeypatch, tmp_path, f"[stt]\ncues = {value}\n")
+
+    message = str(excinfo.value)
+    assert "stt.cues" in message
+    assert "sounds" in message and "words" in message and "both" in message
+
+
+@pytest.mark.parametrize("value", ["sounds", "words", "both"])
+def test_each_stt_cues_mode_is_accepted(monkeypatch, tmp_path, value):
+    from vocalize.config import resolve_stt
+
+    data = _load_stt(monkeypatch, tmp_path, f'[stt]\ncues = "{value}"\n')
+    assert resolve_stt(data)["cues"] == value
+
+
+def test_stt_cues_defaults_to_sounds(monkeypatch, tmp_path):
+    from vocalize.config import resolve_stt
+
+    assert resolve_stt(_load_stt(monkeypatch, tmp_path, ""))["cues"] == "sounds"
+
+
 def test_an_stt_value_that_is_not_a_table_is_refused(monkeypatch, tmp_path):
     with pytest.raises(ConfigError) as excinfo:
         _load_stt(monkeypatch, tmp_path, 'stt = "small.en"\n')

vocalize_cli-0.10.2/tests/test_cue_assets.py

@@ -0,0 +1,28 @@
+"""The shipped `[stt] cues` word files: present, small, and well-formed.
+
+Not a test of speech quality — just the shape that `dictate._play` and the
+packaged wheel both depend on: a real mono 16-bit WAV, short and light
+enough to ship and to speak without lagging behind the sound it replaces.
+"""
+
+import wave
+from pathlib import Path
+
+import pytest
+
+from vocalize.dictate import _CUE_WORDS
+
+MAX_SECONDS = 1.5
+MAX_BYTES = 80_000
+
+
+@pytest.mark.parametrize("path", list(_CUE_WORDS.values()), ids=lambda p: p.name)
+def test_a_cue_word_file_is_a_small_mono_16_bit_wav(path: Path):
+    assert path.is_file(), f"missing cue asset: {path}"
+    assert path.stat().st_size <= MAX_BYTES
+
+    with wave.open(str(path), "rb") as reader:
+        assert reader.getnchannels() == 1
+        assert reader.getsampwidth() == 2
+        duration = reader.getnframes() / reader.getframerate()
+    assert duration <= MAX_SECONDS

{vocalize_cli-0.10.1 → vocalize_cli-0.10.2}/tests/test_dictate.py

@@ -399,6 +399,91 @@ def test_the_second_press_transcribes_and_copies_to_the_clipboard(
     assert any(dictate._NOTIFY_COPIED in line for line in harness.notifications())
 
 
+# --- spoken cues (`[stt] cues`) ----------------------------------------
+
+
+def test_words_mode_speaks_start_stop_and_done(
+    recorder, transcriber, harness, monkeypatch
+):
+    recorder()
+    transcriber()
+
+    original_launch = dictate._launch_recorder
+
+    def launch_after_start_cue(workdir, settings):
+        # The spoken "Start." must finish before the microphone opens, or
+        # it would be recorded and transcribed along with the dictation.
+        assert "start.wav" in harness.played
+        return original_launch(workdir, settings)
+
+    monkeypatch.setattr(dictate, "_launch_recorder", launch_after_start_cue)
+
+    assert start(cues="words") == 0
+    assert press_again(monkeypatch, cues="words") == 0
+
+    assert harness.played == ["start.wav", "stopped.wav", "ready.wav"]
+
+
+def test_both_mode_speaks_the_word_then_plays_the_sound(
+    recorder, transcriber, harness, monkeypatch
+):
+    recorder()
+    transcriber()
+
+    original_launch = dictate._launch_recorder
+
+    def launch_between_word_and_sound(workdir, settings):
+        # "Start." is "get ready" and plays before the microphone opens;
+        # the Tink is "talk now" and must wait until the recorder reports
+        # it is recording — otherwise the sound promises a microphone that
+        # is still a second away.
+        assert harness.played == ["start.wav"]
+        return original_launch(workdir, settings)
+
+    monkeypatch.setattr(dictate, "_launch_recorder", launch_between_word_and_sound)
+
+    assert start(cues="both") == 0
+    assert press_again(monkeypatch, cues="both") == 0
+
+    assert harness.played == [
+        "start.wav", "Tink.aiff",
+        "stopped.wav", "Pop.aiff",
+        "ready.wav", "Glass.aiff",
+    ]
+
+
+def test_sounds_false_silences_words_too(recorder, transcriber, harness, monkeypatch):
+    recorder()
+    transcriber()
+
+    assert start(cues="words", sounds=False) == 0
+    assert press_again(monkeypatch, cues="words", sounds=False) == 0
+
+    assert harness.played == []
+
+
+def test_a_missing_cue_word_file_falls_back_to_the_sound(
+    recorder, transcriber, harness, monkeypatch, tmp_path
+):
+    empty = tmp_path / "no-cues"
+    empty.mkdir()
+    monkeypatch.setattr(
+        dictate, "_CUE_WORDS",
+        {
+            dictate._SOUND_START: empty / "start.wav",
+            dictate._SOUND_STOP: empty / "stopped.wav",
+            dictate._SOUND_DONE: empty / "ready.wav",
+        },
+    )
+    recorder()
+    transcriber()
+
+    assert start(cues="words") == 0
+    assert press_again(monkeypatch, cues="words") == 0
+
+    assert harness.played == ["Tink.aiff", "Pop.aiff", "Glass.aiff"]
+
+
 def test_the_working_directory_and_session_are_gone_after_a_stop(
     recorder, transcriber, monkeypatch
 ):

{vocalize_cli-0.10.1 → vocalize_cli-0.10.2}/vocalize/__init__.py

@@ -7,4 +7,4 @@ formatting into something that actually sounds good spoken aloud
 which is close to useless).
 """
 
-__version__ = "0.10.1"
+__version__ = "0.10.2"

vocalize_cli-0.10.2/vocalize/assets/cues/README.md

@@ -0,0 +1,11 @@
+# Dictation cue words
+
+Spoken alternatives to the Tink/Pop/Glass system sounds (`[stt] cues`).
+
+Generated with the local Kokoro voice `af_heart`, one word per file:
+
+    vocalize speak "Start." --provider kokoro --voice af_heart --no-play -o vocalize/assets/cues/start.wav
+    vocalize speak "Stopped." --provider kokoro --voice af_heart --no-play -o vocalize/assets/cues/stopped.wav
+    vocalize speak "Ready." --provider kokoro --voice af_heart --no-play -o vocalize/assets/cues/ready.wav
+
+Kokoro-82M is Apache-2.0 licensed.

{vocalize_cli-0.10.1 → vocalize_cli-0.10.2}/vocalize/cli.py

@@ -490,6 +490,7 @@ def settings() -> None:
     click.echo(f"stt.language={stt['language']}")
     click.echo(f"stt.cleanup={'true' if stt['cleanup'] else 'false'}")
     click.echo(f"stt.max_seconds={stt['max_seconds']}")
+    click.echo(f"stt.cues={stt['cues']}")
 
 
 @main.command()

{vocalize_cli-0.10.1 → vocalize_cli-0.10.2}/vocalize/config.py

@@ -57,8 +57,12 @@ KNOWN_STT_KEYS = (
     "paste",
     "max_seconds",
     "sounds",
+    "cues",
 )
 
+# What `cues` may be: the fixed system sounds, spoken words instead, or both.
+STT_CUE_MODES = ("sounds", "words", "both")
+
 # `paste` is reserved by DEC-006 and deliberately does nothing in 0.10.0.
 STT_DEFAULTS = {
     "model": "small.en",
@@ -68,6 +72,7 @@ STT_DEFAULTS = {
     "paste": False,
     "max_seconds": 120,
     "sounds": True,
+    "cues": "sounds",
 }
 
 # The recorder self-stops at max_seconds and `dictate` backstops it, so this
@@ -291,6 +296,13 @@ def _validate_stt_table(value, path: Path) -> None:
         if flag is not None and not isinstance(flag, bool):
             raise ConfigError(f"Invalid stt.{key} {flag!r} in {path}: expected true or false.")
 
+    cues = value.get("cues")
+    if cues is not None and cues not in STT_CUE_MODES:
+        raise ConfigError(
+            f"Invalid stt.cues {cues!r} in {path}. Expected one of: "
+            f"{', '.join(STT_CUE_MODES)}."
+        )
+
 
 def _validate_input_device(device, path: Path) -> None:
     if not isinstance(device, str):

{vocalize_cli-0.10.1 → vocalize_cli-0.10.2}/vocalize/dictate.py

@@ -136,6 +136,16 @@ _SOUND_START = _SOUND_DIR / "Tink.aiff"
 _SOUND_STOP = _SOUND_DIR / "Pop.aiff"
 _SOUND_DONE = _SOUND_DIR / "Glass.aiff"
 
+# Spoken alternatives to the three system sounds (`[stt] cues`), shipped
+# with the package — same package-relative pattern as
+# `local/install.py`'s `_RECORDER_DIR`.
+_CUES_DIR = Path(__file__).resolve().parent / "assets" / "cues"
+_CUE_WORDS = {
+    _SOUND_START: _CUES_DIR / "start.wav",
+    _SOUND_STOP: _CUES_DIR / "stopped.wav",
+    _SOUND_DONE: _CUES_DIR / "ready.wav",
+}
+
 # Every notification this module can ever show. Fixed strings, no
 # interpolation: a transcript must never reach Notification Center, and
 # `_notify` enforces that by refusing anything not in this set.
@@ -309,17 +319,34 @@ def _recorder_pid(workdir: Path) -> int | None:
 # --- feedback: sounds and notifications -------------------------------
 
 
-def _play(sound: Path, stt: dict) -> None:
-    """One feedback sound, through the machine-wide playback lock.
+def _play(sound: Path, stt: dict, *, only: str | None = None) -> None:
+    """One feedback cue, through the machine-wide playback lock.
 
     Through `audio.play` and not a raw `afplay` so a sound queues behind
     (and can be stopped with) any read in progress — the overlap 0.9.1
     fixed. Never fatal: a missing system sound must not lose a dictation.
+
+    `[stt] cues` picks what plays instead of (or alongside) the sound:
+    "sounds" (default) is unchanged; "words" speaks the cue word in place
+    of the sound; "both" speaks it and then plays the sound. A missing
+    word file — a package installed without `vocalize/assets/cues/`, say
+    — falls back to the sound rather than saying nothing at all.
+
+    `only` plays just the "word" half or just the "sound" half of the cue,
+    for the one caller that needs them at different moments: `_start`
+    speaks before the microphone opens and plays the sound after.
     """
     if not stt.get("sounds", True):
         return
+    cues = stt.get("cues", "sounds")
+    word = _CUE_WORDS.get(sound) if cues in ("words", "both") else None
+    if word is not None and not word.is_file():
+        word = None  # fall back to the sound
     try:
-        audio.play(sound)
+        if word is not None and only != "sound":
+            audio.play(word)
+        if only != "word" and (word is None or cues == "both"):
+            audio.play(sound)
     except Exception:  # noqa: BLE001, S110 — feedback is never worth failing a dictation for
         pass
 
@@ -1039,6 +1066,14 @@ def _start(workdir: Path, stt: dict) -> int:
     # that read saves its place, and this dictation offers it back once the
     # transcript has landed (DEC-003).
     audio.stop_playback(remember=True)
+    # A spoken "Start." has to finish *before* the microphone opens, or it
+    # is recorded and transcribed along with the dictation (`audio.play`
+    # blocks until playback ends). The Tink plays *after* the recorder
+    # reports it is recording, as it always has — so in "both" mode the
+    # two cues keep distinct meanings: the word is "get ready", the sound
+    # is "the microphone is open, talk now". The gap between them is the
+    # recorder's start-up; closing it is issue #2.
+    _play(_SOUND_START, stt, only="word")
     try:
         _launch_recorder(workdir, stt)
     except DictationError:
@@ -1056,7 +1091,7 @@ def _start(workdir: Path, stt: dict) -> int:
         _play(_SOUND_STOP, stt)
         _notify(_NOTIFY_RECORDER_FAILED)
         return 1
-    _play(_SOUND_START, stt)
+    _play(_SOUND_START, stt, only="sound")
     return 0