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

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

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

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

@@ -3,6 +3,128 @@
 All notable changes to this project are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## 0.11.0 - 2026-09-05
+
+### Added
+
+- **A web portal page** (`vocalize portal`) for the whole config surface: reorder
+  the provider chain; set each provider's voice, speed and monthly budget with a
+  live preview; store and check API keys (masked, `autocomplete="off"`); watch
+  usage; and drive the local Kokoro and whisper installs with progress — no more
+  hand-editing `config.toml`. Five tabs (Chain, Providers, Keys, Usage, Local)
+  plus a persistent readiness sidebar reading `/api/state`, with buttons on the
+  rows that map to a vocalize command the portal already runs. Every save goes
+  through the same compare-and-swap the CLI uses, so a change made elsewhere
+  while the page was open is refused rather than silently overwritten. Ships as
+  static HTML and JS with no framework, no inline script and no external
+  resource — the whole surface has to work with the network cable pulled — over
+  a loopback-only, one-time-code session (DEC-004).
+- **A voice picker on the Providers tab.** `GET /api/voices/<name>` returns the
+  provider's own `list_voices()`, paginated and cached for the life of the
+  portal process, so the field is a real dropdown of the account's actual
+  voices with the current value pre-selected, and `"Type a voice id…"` for an
+  id the list doesn't carry — rather than a hand-typed guess.
+
+### Fixed
+
+- **`vocalize voices` and `vocalize usage` printed the ElevenLabs API key to
+  stderr when the API quoted it back.** The SDK's `ApiError` renders the whole
+  response body and header dict, and both commands printed that text verbatim —
+  so a key the API named in an error reached terminal scrollback, any session
+  log, and whatever the user pasted into a bug report. `auth.scrub` already
+  existed for exactly this, but three callers never reached it. The scrub now
+  happens inside `tts` itself, below every caller, against the key the client
+  was built with. Found by the 0.11.0 release review (DEC-021).
+- **The portal's `say` voice list failed on the first ask.** The route gave every
+  provider the two-second budget meant for network probes, and enumerating the
+  system voices takes longer than that on a current Mac — so the one provider
+  needing no key, no account and no network was the one that said "couldn't
+  fetch the list". Offline lists get their own budget now.
+- **A key of four characters or fewer was shown in full** by `vocalize auth
+  status` and on the portal's Keys tab — a truncated paste, or another tool's
+  short secret in the same environment variable, reproduced whole in output the
+  design treats as safe to screenshot. Anything under eight characters now masks
+  to `…` alone.
+- **The portal's Keys tab pointed at Keychain Access** to remove a stored key.
+  It now names `vocalize auth logout --provider <name>`, which reads the entry
+  back and refuses to claim a removal it cannot verify.
+- **The ElevenLabs SDK client followed a redirect and re-sent the API key
+  wherever it pointed, cross-origin, over plain http.** The SDK's httpx client
+  follows a 3xx by default; every ElevenLabs endpoint is a fixed URL, so a
+  redirect was never legitimate and the key had no business leaving the
+  original origin. Present since 0.9.0, when the ElevenLabs provider first
+  shipped. Closed by building the client with `follow_redirects=False` — the
+  same rule the urllib-based providers already held via `_http._NoRedirects` —
+  and proven on two real loopback HTTP servers: the second origin never sees
+  the request.
+- **Nothing could rewrite a config file containing an `[stt]` table** —
+  which is every config a dictation user has had since 0.10.0 added the
+  table. The serialiser wrote flat keys and `[providers.*]` and had no
+  case for any other table, so `stt` reached the scalar renderer as a
+  `dict` and raised: "The config file has a table under 'stt'. The wizard
+  only manages flat keys, so it will not rewrite this file — edit that
+  file by hand." That refusal came out of `vocalize wizard` before it
+  asked its first question, and out of `vocalize chain google say` instead
+  of a write. The only way out was to delete the `[stt]` table, run the
+  command, and put it back. `[stt]` is now rendered as its own table, so
+  both commands rewrite the file and leave the dictation settings alone.
+  The rewritten file puts `[stt]` ahead of `[providers.*]` whatever order
+  they were in before — identical TOML, a one-off cosmetic diff.
+- **Two writers saving at the same moment could lose one of the two
+  changes.** The config write compared the file against the fingerprint it
+  had read and then renamed a temp file over it, with the two steps not
+  held together, so two saves that overlapped could both see an unchanged
+  file, both write, and both report success while only the second survived.
+  The compare and the rename now happen under one lock. Two `vocalize`
+  *processes* saving in the same instant can still race — the fingerprint
+  check narrows that to a window of microseconds, and closing it entirely
+  needs a lock file, which is deliberately not what this is.
+- **A config save rendered through a fixed `config.toml.tmp`**, so two
+  writers at once could render through the same temp file and leave one of
+  them writing a file the other had already renamed away — reported as
+  "Could not write config file", or worse, reported as success for bytes
+  that were not in the file. Each writer now gets its own temp file, made
+  with `mkstemp` in the same directory, still `0600`, and still renamed
+  into place atomically. The predictable name a local process could
+  pre-plant as a symlink is gone with it.
+
+### Known limitation
+
+- **Any other process on the Mac can close the portal with five wrong or
+  missing-origin requests to `/api/session`**, no code and no token needed —
+  the same guard that stops a cross-origin web page from doing it has no way
+  to tell that traffic apart from a local script's. This is availability
+  only: nothing is read or changed, the portal just exits. Rerun
+  `vocalize portal` and carry on. Accepted rather than fixed, since anything
+  able to send that traffic locally could kill the process outright anyway
+  (DEC-018).
+
+## 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.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vocalize-cli
-Version: 0.10.1
+Version: 0.11.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
@@ -216,6 +216,9 @@ 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.
 
+There's also a settings page in the browser — see
+[Settings portal](#settings-portal) below.
+
 | Setting | Flag | Env var | Config file key | Default |
 |---|---|---|---|---|
 | API key | `--api-key` | `ELEVENLABS_API_KEY` | not read from the config file | stored via `vocalize auth` |
@@ -295,6 +298,41 @@ configures a TTS provider — see
 [Dictation](#dictation-speech-to-text) below for every key and its
 allowlist.
 
+## Settings portal
+
+A page in your own browser for the whole config surface above, so you don't
+have to hand-edit `config.toml` or click through `vocalize config` one
+setting at a time.
+
+```bash
+vocalize portal              # opens your browser at a one-time link
+vocalize portal --no-browser # prints the link instead (headless, SSH)
+```
+
+Five tabs:
+
+- **Chain** — reorder providers, or add and remove one.
+- **Providers** — each provider's voice, model, speed, and monthly budget,
+  with a live preview of the voice you're looking at.
+- **Keys** — store or check an API key; the field is masked and never
+  offers to autocomplete.
+- **Usage** — this month's spend and quota per provider.
+- **Local** — install or update the on-device Kokoro and whisper models,
+  with progress.
+
+The opening link works once and for 60 seconds; after that, run the command
+again for a new one. The server only ever listens on `127.0.0.1`, and it
+closes itself on Ctrl-C or after fifteen minutes with nothing to do. Nothing
+you change on the page reaches disk until you press Save on that tab — and
+a save made against a config file that's changed on disk since the page
+loaded is refused rather than silently overwritten, the same protection
+`vocalize chain` and `vocalize config` already have.
+
+It assumes a single-user machine: everything that reads or changes your
+settings is behind that one-time token, but any other process on the Mac
+can still reach the port and close the portal under you. Nothing leaks if
+that happens — it's a shutdown, not a read — just run the command again.
+
 ## Providers and fallback
 
 vocalize tries providers in order — a **chain** — until one speaks. The
@@ -485,6 +523,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 +559,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 +571,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.11.0}/README.md

@@ -180,6 +180,9 @@ 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.
 
+There's also a settings page in the browser — see
+[Settings portal](#settings-portal) below.
+
 | Setting | Flag | Env var | Config file key | Default |
 |---|---|---|---|---|
 | API key | `--api-key` | `ELEVENLABS_API_KEY` | not read from the config file | stored via `vocalize auth` |
@@ -259,6 +262,41 @@ configures a TTS provider — see
 [Dictation](#dictation-speech-to-text) below for every key and its
 allowlist.
 
+## Settings portal
+
+A page in your own browser for the whole config surface above, so you don't
+have to hand-edit `config.toml` or click through `vocalize config` one
+setting at a time.
+
+```bash
+vocalize portal              # opens your browser at a one-time link
+vocalize portal --no-browser # prints the link instead (headless, SSH)
+```
+
+Five tabs:
+
+- **Chain** — reorder providers, or add and remove one.
+- **Providers** — each provider's voice, model, speed, and monthly budget,
+  with a live preview of the voice you're looking at.
+- **Keys** — store or check an API key; the field is masked and never
+  offers to autocomplete.
+- **Usage** — this month's spend and quota per provider.
+- **Local** — install or update the on-device Kokoro and whisper models,
+  with progress.
+
+The opening link works once and for 60 seconds; after that, run the command
+again for a new one. The server only ever listens on `127.0.0.1`, and it
+closes itself on Ctrl-C or after fifteen minutes with nothing to do. Nothing
+you change on the page reaches disk until you press Save on that tab — and
+a save made against a config file that's changed on disk since the page
+loaded is refused rather than silently overwritten, the same protection
+`vocalize chain` and `vocalize config` already have.
+
+It assumes a single-user machine: everything that reads or changes your
+settings is behind that one-time token, but any other process on the Mac
+can still reach the port and close the portal under you. Nothing leaks if
+that happens — it's a shutdown, not a read — just run the command again.
+
 ## Providers and fallback
 
 vocalize tries providers in order — a **chain** — until one speaks. The
@@ -449,6 +487,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 +523,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 +535,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.11.0}/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.11.0}/docs/installation.md

@@ -75,6 +75,19 @@ Smoke test (also proves stdin + preprocessing):
 echo "vocalize is alive" | vocalize speak-file -
 ```
 
+### Or: finish setup in a browser
+
+Everything above — keys, the chain, the local models — can be done from one
+page instead:
+
+```bash
+vocalize portal
+```
+
+It opens a one-time link at `127.0.0.1` (valid for 60 seconds), and writes
+nothing until you save. See [README § Settings portal](../README.md#settings-portal)
+for what each tab does.
+
 ## Layer 2 — the `/speak` command in Claude Code
 
 Until the repo ships this (tracked as an open gap), create it by hand at