pi-ptts0.1.0
On-demand spoken Pi responses through local Phonon ptts
Untested on omp
This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.
Reports 0
No reports yet.
Readme
Pi ptts
On-demand spoken summaries of Pi responses through the local Phonon ptts CLI. Speech synthesis runs on-device; summarization uses your configured Pi model.
Installation
Requires macOS, Node.js 22.19.0 or newer, Pi, and Phonon's ptts executable on PATH. The package does not install Phonon, its models, or its voices. The extension uses Pi's agent_settled event, buildSessionProjection, and model-registry streamSimple API; it was developed against Pi 1.3.0.
After the package is published to npm:
pi install npm:pi-ptts
Run /reload in an existing Pi session, or start a new session. Try /ptts after Pi has completed a response, or /ptts Explain what this project does to ask a question and hear its summary.
If you already load a local copy from ~/.pi/agent/extensions/ptts/, move that directory outside Pi's auto-loaded extensions directory before installing the npm package. Keep it as your source checkout; do not load both copies, because they register the same commands.
To try a source checkout without installing it:
pi -e /path/to/pi-ptts/index.ts
This also requires that no other copy of the extension is loaded.
Commands
/pttssummarizes the last completed assistant response on the active branch and speaks the summary./ptts <question>sends the question to the normal Pi agent, then summarizes and speaks its completed response./ptts-stopcancels a pending voice summary, summary generation, synthesis, or playback. It does not stop the normal Pi agent; use Escape for that.
Both modes show the spoken summary in the transcript. A footer status shows progress. Ordinary Pi responses are not automatically spoken. Wait for the agent to finish before starting /ptts; only one voice request runs at a time.
Question mode uses the normal Pi agent with its full session context, system instructions, and active tools. Pi can inspect files, run commands, and use its other enabled capabilities as usual. Once the run has fully settled, including any automatic retries or continuations, the extension summarizes only the final assistant response and speaks that summary. Cancelled, failed, or incomplete responses are not spoken. Bare /ptts still summarizes the last completed response without asking Pi a new question.
Only summarization uses a separate, tool-free model call. It receives the completed response, not a shortened conversation or an independent question to answer. The summary must preserve Pi's findings and caveats rather than answer the question again. Main-agent and summary generation use the configured model/provider, which may be remote and charge for usage. Only speech synthesis runs on-device. Summary usage is saved in the voice message details and is not added to Pi's main-agent usage totals; the normal agent run is accounted for as usual.
Requirements and configuration
Requires ptts on PATH, a configured Pi model, and macOS afplay. Defaults to English. Phonon may download its model or selected voice on first use; later synthesis uses the local cache.
Optional environment variables, set before starting Pi:
| Variable | Default | Purpose |
|---|---|---|
PTTS_BIN |
ptts |
Executable path; not a shell command or argument list |
PTTS_VOICE |
CLI default | Bundled/catalog voice name or local voice path |
PTTS_MODEL |
CLI default | Local Phonon model directory or Hugging Face model reference |
PTTS_LANG |
en |
Normalization/spoken language: en, fr, de, es, pt, or none |
Use ptts --list-voices to see the catalog. Model and voice compatibility depends on your installed Phonon checkpoint.
Audio cleanup
Each job uses a private OS temporary directory, not the project directory. Pi runs ptts --lang en --output <temporary-path> -- <text>, then waits for afplay to finish before deleting the entire temporary directory.
Cleanup also runs after synthesis/playback failures, cancellation, session changes, tree navigation, reload, and orderly shutdown. A pending voice request is discarded on session changes. Child processes are terminated and awaited before their files are removed. A hung child receives SIGKILL after one second. Each subprocess times out after three minutes; summary generation and audio playback together have a five-minute limit, starting after the normal Pi agent finishes.
A forced Pi kill, machine crash, or filesystem error can leave temporary files. Existing audio files in your project, including speech.wav, are never touched.
Tests
Run from a source checkout; tests are not included in the npm package. Node.js runs the TypeScript source directly, so no build step is needed.
cd /path/to/pi-ptts
npm test
The tests use mocked agent events, model responses, and temporary fake executables; they do not call a paid model or play sound. Six focused tests cover both command modes, waiting for the final tool-informed response, stopping summary generation, literal argument handling, and temporary-file cleanup after audio success, failure, or cancellation. Retry recovery, session changes, input validation, and timeouts no longer have dedicated tests.