voce 0.2.0__tar.gz

voce-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.DS_Store
+docs/hearing/.corpus/
+.claude/worktrees/
+site/app/py/
+.wrangler/

voce-0.2.0/AGENTS.md

@@ -0,0 +1,80 @@
+# Working on voce with a coding agent
+
+This file is for Claude Code, Codex, Cursor and other agents, and for the people driving them. Read it before
+changing anything. [docs/architecture.md](docs/architecture.md) explains the design in full, and
+[CONTRIBUTING.md](CONTRIBUTING.md) has the human version of the same rules.
+
+## What voce is
+
+A terminal app that reads Markdown aloud, highlighting each sentence and word as it is spoken, and reads code the
+way a person says it out loud. Python 3.9+, one runtime dependency (Pygments), plus Kokoro for the local voice.
+It runs on macOS and Linux; the UI is plain `curses`.
+
+## Set up, check, test
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e '.[dev]'
+.venv/bin/ruff check .          # must pass
+.venv/bin/pytest                # must pass; fast, no network, never touches real state
+.venv/bin/voce --check README.md   # how a file will read, with no audio: a quick end-to-end check
+```
+
+CI runs ruff and pytest on macOS and Linux, on Python 3.9 and 3.13. Write code that runs on 3.9
+(`from __future__ import annotations` is used throughout).
+
+## Where things are
+
+- `src/voce/speech/words.py`: how code is read, per language, as data. **Most feature requests about how
+  something sounds belong here.**
+- `src/voce/speech/code.py`: the tokeniser that turns a line of code into words.
+- `src/voce/speech/prose.py`, `sentences.py`: prose rewrites and sentence splitting.
+- `src/voce/markdown/`: Markdown into blocks of plain text with styled spans.
+- `src/voce/document.py`: blocks into units to say (sentences, code lines, table rows, diff hunks).
+- `src/voce/voices.py`: the voice engines and the audio cache. `player.py`: playback.
+- `src/voce/ui/`: the curses reader. `reader.py` is the state machine, `view.py` the layout and mouse.
+- `src/voce/sources/`: where text comes from (Claude Code transcripts, clipboard, stdin).
+- `site/`: the website and the web app (static, no build step). `relay/`: the web app's sign-in relay.
+
+## Rules that keep voce working
+
+- **One plain text per block.** Every block has a single `text` that is shown, spoken and highlighted; styles are
+  spans over it. New Markdown features must fit that shape.
+- **Keep the spoken text stable.** Audio is cached by the exact text sent to the voice. Changing what
+  `speech.speakable` produces, or how blocks are split into units, makes every user fetch audio again. Do it only
+  when it makes the reading better, and say so in the pull request.
+- **Use the manual's own names.** Operators are named as the language's official docs name them (the PHP
+  manual's "identical", MDN's "strict equality"), not nicknames.
+- **No network in tests.** Stand in for engines, `gh`, `git` remotes and the clipboard. Tests use `tmp_path`
+  and never touch `~/.local/state/voce` or `~/.cache/voce`.
+- **No new runtime dependencies** without a strong reason. Standard library first.
+- **Write for people.** Messages, help and docs use plain words and short sentences. Error messages say what
+  to do next.
+- **Add a test** for any change to parsing, splitting, code reading, layout, a source or the reader.
+
+## Adding a language
+
+A good first change. In `src/voce/speech/words.py`, add a `Language` with its comment markers, the words it says
+differently and its operator names, then its fence names in `LANGUAGES`:
+
+```python
+RUBY = Language("ruby", comments=("#",), words={"attr_accessor": "attribute accessor"},
+                operators={"=>": "hash rocket", "<=>": "spaceship", "&.": "safe navigation"})
+# in LANGUAGES: "ruby": RUBY, "rb": RUBY,
+```
+
+If the language has an operator the tokeniser doesn't know, add it to the `op` alternation in
+`speech/code.py`. Then add cases to `tests/test_speech.py`: a line of code and exactly how it should sound. To
+find what reads badly, run real code through it:
+
+```bash
+.venv/bin/python -c "from voce.speech.code import spoken_line; from voce.speech.words import language; \
+print(spoken_line('puts user&.name', language('ruby')))"
+```
+
+`docs/hearing/corpus.py` does the same over a whole repository of real code.
+
+## Pull requests
+
+Keep each one to one change, with a commit message that says what a user notices. Run ruff and pytest
+first. Don't commit generated audio, caches or anything under `.venv`.

voce-0.2.0/CHANGELOG.md

@@ -0,0 +1,150 @@
+# Changelog
+
+All notable changes to voce are listed here. The format follows [Keep a Changelog](https://keepachangelog.com),
+and versions follow [Semantic Versioning](https://semver.org).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-10-21
+
+### Added
+
+- **Linux.** voce runs on Linux as well as macOS. It plays audio with mpv or ffplay, or with `pw-play`,
+  `paplay` or `aplay` at one speed, and uses `wl-clipboard`, `xclip` or `xsel` for the clipboard. Kokoro is the
+  voice there too. On Windows it runs in WSL. `--plain-player` is the new name for `--afplay`, which still works.
+- **On PyPI.** `pipx install voce` or `uv tool install voce`.
+- **Built to be extended with a coding agent.** `AGENTS.md` (and `CLAUDE.md`, which points to it) tells Claude
+  Code, Codex or Cursor how voce is laid out, how to test it and what to keep stable.
+- **Voices that work out of the box.** Kokoro, a small open voice model, runs on the Mac: free, offline, no key.
+  The model (350 MB) is downloaded once. It is the voice when no cloud engine is set up; on Python 3.9, where
+  Kokoro can't run, the Mac's voices are used as before.
+- **Azure, ElevenLabs and OpenAI** beside Google. Each is used as soon as its key is set (`VOCE_AZURE_KEY` and
+  `VOCE_AZURE_REGION`, `VOCE_ELEVENLABS_API_KEY`, `VOCE_OPENAI_API_KEY`), with eight voices to cycle through,
+  the month's characters counted against each one's free allowance, and a fallback to Kokoro when one fails.
+  `--engine` picks one; `--voice` picks a voice and the engine follows from the name; `voce --voices` shows what
+  is set up. <kbd>V</kbd> in the reader moves to the next engine, and <kbd>v</kbd> now cycles the Mac's voices too.
+- **Pick up on another device.** `voce --sync OWNER/REPO` keeps your places, settings and a prepared copy of each
+  document in a private git repository, made on GitHub for you when `gh` is signed in; any git URL works too.
+  Every run pulls first and pushes when you stop. A prepared copy (`prepared/<hash>.json`) is the document as voce
+  shows and says it, so a phone or a browser needs only it and a voice; the reader writes one for whatever it
+  opens, and `--prepare` and `--sync` write them for the playlist, with `prepared/index.json` listing them.
+- **A web app**, at [jaystewartuk.github.io/voce/app](https://jaystewartuk.github.io/voce/app/): the same
+  library on a phone or in any browser, played by the device's own voice or by Kokoro running in the page, with
+  your place written back. Sign in with GitHub and choose the repository; the voce GitHub App reaches only that
+  one, and a stateless relay (`relay/`) does the code-for-token swap a page can't. Static files on GitHub Pages
+  otherwise. A fine-grained token can be pasted instead.
+- **The web app reads for itself.** voce's reading code runs in the browser (Pyodide), so the app can take a
+  playlist README straight from any repository voce can reach, or a Markdown file from the device, and read it
+  with nothing prepared on a Mac first. Prepared copies carry a stamp of the reading code and are made again
+  when it changes, so a better way of saying something reaches every device.
+- `c` copies the sentence being read and `C` its paragraph; a click on a code block copies the code. Shift-drag
+  still selects text the terminal's own way.
+- Inline code is read the same way: `array_values` in a sentence is "array values", and `===` on its own is
+  "identical". Before, the voice got the raw text, so study notes had to spell names out in prose.
+- `docs/hearing/check.py` fetches tricky phrases from the real voice, transcribes them with whisper.cpp and
+  checks what was heard. It is how rewrites for the voice are verified and new ones found.
+- **Diffs.** A fenced `diff` block in any Markdown is highlighted with added lines in the file's
+  syntax, removed lines in red and context dimmed, and read as above. Name the file's language after the word
+  diff (```` ```diff python ````) to have the added lines highlighted and read in that language.
+- **Languages.** Code is read in each language's own words. PHP is the full set; Python ("returns", "floor
+  divided by", "dunder init"), JavaScript and TypeScript (MDN's "is strictly equal to", "optional chaining",
+  "spread"), shell and SQL have starters; Markdown and text are read as prose. Inline code in a sentence is
+  read in the language most of the document's code is in. A language is a few lines of data in
+  `speech/words.py`.
+- Paths and file names are said with their slashes and the extension by letter: `src/voce/cli.py` is "source
+  slash voce slash C L I dot P Y". A line of prose inside code, such as a doc comment, is read as prose.
+- Link reference definitions (`[name]: url`, and the `[//]: # (comment)` idiom) are neither shown nor read.
+- **Doc comments.** The lines of a `/** ... */` block are read as a person reads them: `@param  array|string
+  $columns  The columns` is "parameter array or string, columns, The columns", `@return` is "returns",
+  `array<int, string>` is "array of int, string", `\Closure(TValue): bool` is "Closure taking T Value returning
+  bool", `{@inheritdoc}` is "inherit doc", and the opening and closing lines are silent.
+- `docs/hearing/corpus.py` reads a whole code base the way voce would and reports the words that came out odd,
+  so the rules can be checked against real code. `corpora.txt` names the code bases; laravel/framework is the
+  first, and a framework in another language is one more line.
+- `fn` is "arrow function", the manual's name, and the `=>` that follows its parameters is "returns": `fn ($x)
+  => $x * 2` is "arrow function x returns x times 2". A `=>` inside the body is still "double arrow".
+- PHP, after reading laravel/framework: `<?php` is "P H P open tag", `#[AsCommand]` is "attribute As Command",
+  `$list[] = $item` is "list append item", `$a ? $b : $c` is "a then b else c", `Stringable|string` in a
+  signature is "Stringable or string", `instanceof` is "instance of", `endforeach` is "end for each", and
+  some two hundred of the standard library's names are said in full, `rtrim` as "R trim" and `realpath` as
+  "real path". A string of one symbol is said by name, `'@'` as "an at sign" and `'>='` as "greater than or
+  equal to", and `"{$this->name}"` inside a string is read as code, and a path in a string,
+  `'routes/web.php'`, as a path. An abbreviation inside a camel-case name
+  is said as it would be on its own: `expectsJson` is "expects JSON", `getId` is "get I D".
+
+### Changed
+
+- **Pausing in the web app holds your place in the sentence.** With the Kokoro voice, playing again within half a
+  minute picks up about a second before where you stopped, at the gap before a word, so the cut-off word is heard
+  whole. After a longer pause, or with the device's own voice, the sentence starts again as before.
+- **The web app's play button is the whole player bar** between the previous and next arrows, so you can pause
+  without looking. Tapping the sentence being read plays or pauses too; tapping any other sentence still goes there.
+- **The web app marks the word being read** inside the highlighted sentence, from how long Kokoro makes each
+  sound (or from the device's own voice, where it reports words). A line of code said differently from how it's
+  shown keeps only its line marked. It can be turned off in settings. Kokoro now downloads the timestamped copy of
+  the same model, once.
+- **State is laid out for syncing.** Your place in each document is its own small file under
+  `~/.local/state/voce/places/`, named by a hash of the document's text rather than its path, so the same file
+  resumes on any machine however it got there. Settings and the month's character counts have their own files.
+  Point `VOCE_STATE` at a synced folder to pick up on another Mac where you left off. An existing `state.json` is
+  migrated once and kept as `state-v1.json`.
+- The usage file counts characters per engine. Existing counts are kept as Google's.
+- The code is arranged for people who want to extend it: `markdown/` (inline, blocks, tables), `speech/`
+  (sentences, prose, code, the word tables), `sources/` (Claude's reply, the clipboard), `commands.py`
+  for the printing commands, `ui/session.py` for the curses session and `ui/view.py` for where things sit on
+  the screen, leaving `ui/reader.py` to what happens in time. Every source raises one `SourceError`.
+- The text sent to the voice changes for inline code with a slash, a file name or an operator in it, and for
+  text with a middle dot or a diff count such as "(+12 −3)", so those sentences are fetched again once.
+- Drag across any text to copy it, without moving the voice. The text holds still while the button is down,
+  the selection shows as you drag, and it is on the clipboard when you let go. Whole blocks come out as they
+  are in the document, so a drag down a code block copies real lines.
+- The title bar fills from the left as the file is read, and the status bar says how far through you are as a
+  percentage, in place of the sentence count.
+- The sentence being read stays on one row, two fifths of the way down, and the text glides up to meet it a
+  line or so a frame instead of jumping when it drifted too far. Clicking a sentence or carrying on after a
+  pause brings it to the same row, and the end of a file rises to it too, so the eye never has to drop.
+- Code blocks are read, line by line, the way a pairing partner says code aloud: names as words (`array_values`
+  is "array values", `usort` is "U sort"), operators by the PHP manual's names (`===` is "is identical to", `==` is
+  "is equal to", `=>` is "double arrow", `??` is "null coalescing", `<=>` is "spaceship", `++` is "increment"), brackets silent,
+  strings by their contents, and a trailing comment as prose after a short pause. The line being read sits on the band and the word being
+  spoken is marked, as in prose, and a click on a line of code starts reading there. `--skip-code` keeps the
+  old behaviour, showing code without reading it, where a click still copies the block.
+
+### Fixed
+
+- PHP code blocks are highlighted even when they do not start with an opening `<?php` tag, as snippets in notes
+  rarely do.
+- "PHP 8" is read as the language version, not as eight Philippine pesos; likewise BSD, CRC and CVE before a
+  version-like number. Sums of money such as "PHP 500" are still money.
+- The mouse wheel scrolls down as well as up on macOS, whose own ncurses has no fifth button and reports
+  wheel-down differently.
+- Pausing just as a sentence ends, in the short silence after it, no longer plays that sentence again when you
+  carry on: the reader moves to the next one.
+
+## [0.1.0] - 2026-10-17
+
+The first public release.
+
+### Added
+
+- Reads Markdown aloud in the terminal, highlighting the sentence being read and the word being spoken.
+- Shows inline styles (bold, italic, code, links, strikethrough), aligned tables, task lists and syntax-highlighted
+  code. Code is shown but not read. Tables are read row by row.
+- `voce -r` reads Claude Code's latest reply in the current folder, straight from the session transcript.
+- `voce -c` reads the clipboard, and `voce -` reads standard input.
+- Several files in one go: `voce a.md b.md`.
+- Mac voices out of the box. Google Chirp 3 HD voices with an API key or gcloud, eight to cycle through, any
+  language.
+- A per-sentence audio cache, so listening again is free and works offline.
+- A native Swift player for gapless playback, a true pause and a word highlight that keeps time, with `afplay` as
+  a fallback.
+- Your place is kept per file and found again by its text after edits. Files reload when they change on disk.
+- Playlists from a README's "Listen in this order" section, with a menu, progress, parts and quizzes.
+- `--export` writes files, a reply, the clipboard or a playlist as one MP3.
+- `--prepare` fetches audio ahead of time, `--check` reports how files will read, and `--minutes` keeps playlist
+  durations current.
+- A click on a sentence jumps to it. The mouse wheel scrolls.
+
+[Unreleased]: https://github.com/jaystewartuk/voce/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/jaystewartuk/voce/releases/tag/v0.2.0
+[0.1.0]: https://github.com/jaystewartuk/voce/releases/tag/v0.1.0

voce-0.2.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

voce-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,93 @@
+# Contributing to voce
+
+Thank you for helping. Bug reports, ideas and pull requests are all welcome, including ones written with a coding
+agent: point it at [AGENTS.md](AGENTS.md) first.
+
+## Set up
+
+```bash
+git clone https://github.com/jaystewartuk/voce
+cd voce
+python3 -m venv .venv
+.venv/bin/pip install -e '.[dev]'
+.venv/bin/voce README.md
+```
+
+## Before you open a pull request
+
+```bash
+.venv/bin/ruff check .
+.venv/bin/pytest
+```
+
+Both run in CI on macOS and Linux. The tests never touch your real state or cache, and never call Google.
+
+Some guidelines:
+
+- **Keep the plain-text model.** Every block has one plain `text` that is shown, spoken and highlighted; styles
+  are spans over it. New Markdown features should fit that shape. See [docs/architecture.md](docs/architecture.md).
+- **Keep the voice's text stable.** Audio is cached by the exact text sent to the voice. A change to
+  `speech.speakable` or to how blocks are split makes everyone re-fetch audio, so make such changes on purpose.
+- **Add a test** for any change to parsing, sentence splitting, code reading, layout, a source or the reader.
+- **Write for people.** Messages, help text and docs use plain words and short sentences.
+
+## Adding a language
+
+How code is read is data in `src/voce/speech/words.py`. A language is a `Language` with the words it says
+differently from the common ones, its operator names, and how its comments start:
+
+```python
+RUBY = Language("ruby", comments=("#",), words={"attr_accessor": "attribute accessor", "puts": "puts"},
+                operators={"=>": "hash rocket", "<=>": "spaceship", "&.": "safe navigation"})
+```
+
+Then add its fence labels and Pygments aliases to `LANGUAGES` (`"ruby": RUBY, "rb": RUBY`). Code fences, diffs
+of `.rb` files and inline code in documents about Ruby will use it. If the language has an operator the
+tokeniser in `speech/code.py` doesn't know, add it to the `op` alternation there. Use the names from the
+language's own manual, and add a line to `tests/test_speech.py` with a line of code and how it should sound.
+
+## Adding a source
+
+A source is a module in `src/voce/sources/` that turns something into a Markdown file and raises a `SourceError`
+when it can't. `sources.resolve` is the one place the command line is turned into a file; add a flag to
+`cli.parser` and a branch there. Keep the code that talks to the outside world apart from the code that writes
+the Markdown, and stand the outside world in for in tests so none of them needs the network.
+
+## Re-recording the demo
+
+The GIF in the README and the screenshot are made with [vhs](https://github.com/charmbracelet/vhs):
+
+```bash
+brew install vhs
+docs/demo/record.sh
+```
+
+The script reads `docs/demo/reply.md` through a throwaway Claude Code transcript, with empty state and cache
+folders, so nothing from your machine appears in the recording.
+
+## Checking what the voice says
+
+Voices misread some text: Google turns "PHP 8" into "eight Philippine pesos". `speech.speakable` rewrites such
+text before it is spoken, and `docs/hearing/check.py` checks those rewrites by ear: it fetches each phrase in
+`docs/hearing/phrases.txt` from the real voice, transcribes it with whisper.cpp and compares.
+
+```bash
+brew install whisper-cpp ffmpeg
+curl -LO https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin
+.venv/bin/python docs/hearing/check.py --model ggml-base.en.bin
+```
+
+Run it with `--raw` to hear the text as written, which is how to confirm a misreading before adding a rewrite.
+It uses your Google voice and counts towards your monthly characters, so it is not part of the test suite.
+
+## The website
+
+The site in `site/` is a single static page with no build step. Open `site/index.html` in a browser to work on it.
+It is published to GitHub Pages by `.github/workflows/pages.yml` on every push to `main` that touches `site/`.
+
+## Releasing
+
+1. Update `__version__` in `src/voce/__init__.py` and move `CHANGELOG.md`'s Unreleased section under the version.
+2. Commit, then tag and push: `git tag v0.2.0 && git push origin main v0.2.0`.
+3. The `release` workflow builds the package, checks the tag matches the version, publishes to PyPI with
+   trusted publishing (no token is stored anywhere) and makes the GitHub release from the changelog section.

voce-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jay Stewart
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.