lystn 0.1.0__tar.gz

lystn-0.1.0/.gitignore

@@ -0,0 +1,86 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+*.egg
+.eggs/
+build/
+dist/
+wheels/
+.installed.cfg
+MANIFEST
+
+# Virtual envs
+.venv/
+venv/
+env/
+ENV/
+.conda/
+
+# Editor / OS
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+Desktop.ini
+
+# Tauri / Node (if/when the desktop app lands)
+node_modules/
+**/dist/
+**/target/
+src-tauri/target/
+.next/
+
+# Lystn-specific
+hook.log
+server.log
+summary.log
+*.wav
+*.mp3
+*.flac
+*.pt
+*.pth
+*.onnx
+lystn_debug.wav
+.lystn/
+cache/
+
+# Models cache (HuggingFace downloads Kokoro here)
+.cache/
+hf_cache/
+
+# Secrets
+.env
+.env.*
+!.env.example
+*.key
+*.pem
+secrets/
+
+# Coverage / test
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+coverage.xml
+*.cover
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Build artifacts
+*.spec
+pip-wheel-metadata/
+
+# Local-only docs/notes
+NOTES.md
+TODO.md
+SCRATCH.md

lystn-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do
+          not modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions for
+      use, reproduction, or distribution of Your modifications, or for any
+      such Derivative Works as a whole, provided Your use, reproduction,
+      and distribution of the Work otherwise complies with the conditions
+      stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Burak Akın Yener
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

lystn-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: lystn
+Version: 0.1.0
+Summary: Listen to AI coding assistant responses via Kokoro TTS.
+Project-URL: Homepage, https://github.com/burakayener/Lystn
+Project-URL: Repository, https://github.com/burakayener/Lystn
+Project-URL: Issues, https://github.com/burakayener/Lystn/issues
+Author: Burak Akın Yener
+License: Apache-2.0
+License-File: LICENSE
+Keywords: adhd,claude,claude-code,codex,tts,voice
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: numpy>=1.24
+Requires-Dist: requests>=2.31
+Requires-Dist: sounddevice>=0.4.6
+Requires-Dist: websocket-client>=1.7
+Description-Content-Type: text/markdown
+
+# lystn CLI
+
+Cross-platform command-line client for the Lystn TTS server. Replaces
+the Windows-only PowerShell hook with a Python package that works on
+Windows, Mac, and Linux.
+
+## Install
+
+```bash
+pipx install -e .          # from this folder, while developing
+# or once published:
+pipx install lystn
+```
+
+`pipx` puts `lystn` on your PATH in an isolated environment — no
+conflicts with your other Python packages.
+
+## Configure
+
+```bash
+lystn config set server http://127.0.0.1:7878     # local server (default)
+lystn config set voice af_heart                    # any voice from `lystn voices`
+lystn config set api_key sk_...                    # only needed for cloud server later
+lystn config show
+```
+
+Config lives at:
+- Windows: `%APPDATA%\lystn\config.json`
+- Mac/Linux: `~/.config/lystn/config.json`
+
+## Use
+
+```bash
+lystn test                          # speak "Lystn is connected and working."
+lystn speak "Hello there."          # speak the argument
+echo "Hello there." | lystn speak   # speak stdin
+lystn voices                        # list voices
+lystn doctor                        # check server reachable
+```
+
+## Wire into Claude Code
+
+```bash
+lystn install
+```
+
+Prints a JSON snippet — copy the `hooks` block into
+`~/.claude/settings.json`. Restart Claude Code. Every completed
+response will be spoken aloud.
+
+The hook is fire-and-forget: if the Lystn server is down or the text
+is empty, the hook exits silently and doesn't break Claude's UI.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `lystn speak [TEXT]` | Speak text from argument or stdin |
+| `lystn hook` | Claude Code Stop-hook entry — reads JSON from stdin |
+| `lystn test` | Speak a short connection-test message |
+| `lystn voices` | List voices the server offers |
+| `lystn doctor` | Print config + server health |
+| `lystn config show` | Show current config |
+| `lystn config set KEY VALUE` | Update config (`server`, `voice`, `api_key`) |
+| `lystn install` | Print the Claude Code settings snippet |
+
+## Requirements
+
+- Python 3.10+
+- A running Lystn server (local Kokoro for now; cloud server later)
+- Audio output device (`sounddevice` handles it cross-platform)

lystn-0.1.0/README.md

@@ -0,0 +1,71 @@
+# lystn CLI
+
+Cross-platform command-line client for the Lystn TTS server. Replaces
+the Windows-only PowerShell hook with a Python package that works on
+Windows, Mac, and Linux.
+
+## Install
+
+```bash
+pipx install -e .          # from this folder, while developing
+# or once published:
+pipx install lystn
+```
+
+`pipx` puts `lystn` on your PATH in an isolated environment — no
+conflicts with your other Python packages.
+
+## Configure
+
+```bash
+lystn config set server http://127.0.0.1:7878     # local server (default)
+lystn config set voice af_heart                    # any voice from `lystn voices`
+lystn config set api_key sk_...                    # only needed for cloud server later
+lystn config show
+```
+
+Config lives at:
+- Windows: `%APPDATA%\lystn\config.json`
+- Mac/Linux: `~/.config/lystn/config.json`
+
+## Use
+
+```bash
+lystn test                          # speak "Lystn is connected and working."
+lystn speak "Hello there."          # speak the argument
+echo "Hello there." | lystn speak   # speak stdin
+lystn voices                        # list voices
+lystn doctor                        # check server reachable
+```
+
+## Wire into Claude Code
+
+```bash
+lystn install
+```
+
+Prints a JSON snippet — copy the `hooks` block into
+`~/.claude/settings.json`. Restart Claude Code. Every completed
+response will be spoken aloud.
+
+The hook is fire-and-forget: if the Lystn server is down or the text
+is empty, the hook exits silently and doesn't break Claude's UI.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `lystn speak [TEXT]` | Speak text from argument or stdin |
+| `lystn hook` | Claude Code Stop-hook entry — reads JSON from stdin |
+| `lystn test` | Speak a short connection-test message |
+| `lystn voices` | List voices the server offers |
+| `lystn doctor` | Print config + server health |
+| `lystn config show` | Show current config |
+| `lystn config set KEY VALUE` | Update config (`server`, `voice`, `api_key`) |
+| `lystn install` | Print the Claude Code settings snippet |
+
+## Requirements
+
+- Python 3.10+
+- A running Lystn server (local Kokoro for now; cloud server later)
+- Audio output device (`sounddevice` handles it cross-platform)

lystn-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "lystn"
+version = "0.1.0"
+description = "Listen to AI coding assistant responses via Kokoro TTS."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Burak Akın Yener" }]
+keywords = ["tts", "claude", "claude-code", "codex", "voice", "adhd"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "click>=8.1",
+    "requests>=2.31",
+    "websocket-client>=1.7",
+    "sounddevice>=0.4.6",
+    "numpy>=1.24",
+]
+
+[project.scripts]
+lystn = "lystn.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/burakayener/Lystn"
+Repository = "https://github.com/burakayener/Lystn"
+Issues = "https://github.com/burakayener/Lystn/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lystn"]

lystn-0.1.0/src/lystn/__init__.py

@@ -0,0 +1,2 @@
+"""Lystn — listen to AI coding assistant responses."""
+__version__ = "0.1.0"

lystn-0.1.0/src/lystn/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

lystn-0.1.0/src/lystn/clean.py

@@ -0,0 +1,69 @@
+"""Text cleaning for TTS — port of the original PowerShell hook regexes.
+
+Strips URLs, code blocks, markdown, file paths — anything that sounds bad
+or slows Kokoro down. Caps length to a safe ceiling.
+"""
+from __future__ import annotations
+
+import re
+
+DEFAULT_MAX_CHARS = 3500
+
+_RE_FENCED_CODE = re.compile(r"```[\s\S]*?```", re.MULTILINE)
+_RE_INDENTED_CODE = re.compile(r"(?m)^    [^\n]+\n?")
+_RE_INLINE_CODE = re.compile(r"`[^`\n]+`")
+_RE_MD_LINK = re.compile(r"\[([^\]]+)\]\([^)]+\)")
+_RE_URL_HTTP = re.compile(r"https?://\S+")
+_RE_URL_WWW = re.compile(r"www\.\S+")
+_RE_WIN_PATH = re.compile(r"[A-Za-z]:\\\S+")
+_RE_UNIX_PATH = re.compile(r"(?<=\s)/[\w./\-]+")
+_RE_FILENAME = re.compile(
+    r"\b[\w\-]+\.(?:py|ts|tsx|js|jsx|json|md|rs|go|java|cs|cpp|c|h|html|"
+    r"css|sh|bat|ps1|yaml|yml|toml|xml|sql|rb|php|swift|kt)\b"
+)
+_RE_HEADER = re.compile(r"(?m)^#{1,6}\s+")
+_RE_BULLET = re.compile(r"(?m)^[\-*+]\s+")
+_RE_NUMBER_LIST = re.compile(r"(?m)^\d+\.\s+")
+_RE_BLOCKQUOTE = re.compile(r"(?m)^>\s*")
+_RE_TABLE_ROW = re.compile(r"(?m)^\|.*\|\s*$")
+_RE_TABLE_SEP = re.compile(r"(?m)^[\-|: ]+$")
+_RE_BOLD_STAR = re.compile(r"\*\*([^*]+)\*\*")
+_RE_BOLD_UNDER = re.compile(r"__([^_]+)__")
+_RE_ITALIC_STAR = re.compile(r"(?<!\*)\*([^*\n]+)\*(?!\*)")
+_RE_ITALIC_UNDER = re.compile(r"(?<!_)_([^_\n]+)_(?!_)")
+_RE_SPACES = re.compile(r"[ \t]+")
+_RE_NEWLINES = re.compile(r"\n{2,}")
+
+
+def clean_for_tts(text: str, max_chars: int = DEFAULT_MAX_CHARS) -> str:
+    """Strip noise from `text` so Kokoro doesn't mangle or stall on it."""
+    if not text:
+        return ""
+
+    t = text
+    t = _RE_FENCED_CODE.sub(" code block omitted. ", t)
+    t = _RE_INDENTED_CODE.sub("", t)
+    t = _RE_INLINE_CODE.sub("", t)
+    t = _RE_MD_LINK.sub(r"\1", t)
+    t = _RE_URL_HTTP.sub("", t)
+    t = _RE_URL_WWW.sub("", t)
+    t = _RE_WIN_PATH.sub("", t)
+    t = _RE_UNIX_PATH.sub("", t)
+    t = _RE_FILENAME.sub("", t)
+    t = _RE_HEADER.sub("", t)
+    t = _RE_BULLET.sub("", t)
+    t = _RE_NUMBER_LIST.sub("", t)
+    t = _RE_BLOCKQUOTE.sub("", t)
+    t = _RE_TABLE_ROW.sub("", t)
+    t = _RE_TABLE_SEP.sub("", t)
+    t = _RE_BOLD_STAR.sub(r"\1", t)
+    t = _RE_BOLD_UNDER.sub(r"\1", t)
+    t = _RE_ITALIC_STAR.sub(r"\1", t)
+    t = _RE_ITALIC_UNDER.sub(r"\1", t)
+    t = _RE_SPACES.sub(" ", t)
+    t = _RE_NEWLINES.sub(". ", t)
+    t = t.strip()
+
+    if len(t) > max_chars:
+        t = t[:max_chars] + " ... response truncated."
+    return t

lystn-0.1.0/src/lystn/cli.py

@@ -0,0 +1,403 @@
+"""Lystn CLI — `lystn <command> ...`."""
+from __future__ import annotations
+
+import json
+import sys
+import traceback
+from datetime import datetime
+
+import click
+
+from . import __version__, client, config
+from .clean import clean_for_tts
+from .player import play_chunks, resolve_device
+
+
+def _hook_log(msg: str) -> None:
+    """Append a diagnostic line to ~/.config/lystn/hook.log (or %APPDATA% equiv).
+
+    The Stop hook runs as a Claude Code subprocess so its stdout is invisible.
+    A file log is the only way to find out why a hook silently failed.
+    """
+    try:
+        log_path = config.config_dir() / "hook.log"
+        with log_path.open("a", encoding="utf-8") as f:
+            f.write(f"[{datetime.now().isoformat(timespec='seconds')}] {msg}\n")
+    except Exception:
+        # Logging itself failed — nothing useful we can do.
+        pass
+
+
+def _stream_and_play(
+    server: str,
+    text: str,
+    voice: str | None,
+    api_key: str | None,
+    device: int | str | None = None,
+) -> None:
+    """Synthesize via the server and play chunks as they arrive."""
+    chunks = client.synthesize(server, text, voice=voice, api_key=api_key)
+    play_chunks(chunks, device=device)
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__, prog_name="lystn")
+def main() -> None:
+    """Listen to AI coding assistant responses.
+
+    Set up: `lystn config set server <url>` then wire `lystn hook` into
+    your Claude Code Stop hook (see `lystn install --help`).
+    """
+
+
+@main.command()
+@click.argument("text", required=False)
+@click.option("--voice", default=None, help="Voice override.")
+@click.option("--server", default=None, help="Server URL override.")
+def speak(text: str | None, voice: str | None, server: str | None) -> None:
+    """Speak TEXT (or stdin if omitted)."""
+    if not text:
+        text = sys.stdin.read()
+    cleaned = clean_for_tts(text)
+    if not cleaned:
+        click.echo("nothing to speak", err=True)
+        return
+    cfg = config.load()
+    srv = server or cfg["server"]
+    _stream_and_play(
+        srv, cleaned, voice or cfg["voice"], cfg["api_key"], cfg.get("device")
+    )
+
+
+@main.command()
+def hook() -> None:
+    """Claude Code Stop-hook entry point. Reads JSON from stdin."""
+    _hook_log("hook invoked")
+    _log_audio_device()
+    raw = sys.stdin.read()
+    if not raw:
+        _hook_log("empty stdin, exiting")
+        return
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as e:
+        _hook_log(f"bad JSON on stdin: {e}")
+        return
+    text = payload.get("last_assistant_message") or ""
+    cleaned = clean_for_tts(text)
+    if len(cleaned) < 3:
+        _hook_log(f"cleaned text too short ({len(cleaned)} chars), skipping")
+        return
+    cfg = config.load()
+    device = cfg.get("device")
+    resolved = resolve_device(device)
+    _hook_log(
+        f"speaking {len(cleaned)} chars via {cfg['server']} "
+        f"(device cfg={device!r}, resolved={resolved})"
+    )
+    try:
+        _stream_and_play(
+            cfg["server"], cleaned, cfg["voice"], cfg["api_key"], device
+        )
+        _hook_log("playback complete")
+    except Exception as e:
+        _hook_log(f"playback FAILED: {type(e).__name__}: {e}")
+        _hook_log(traceback.format_exc())
+        # Still don't propagate — Claude's UI must not break.
+
+
+def _resolve_default_output() -> int | None:
+    """Return the index of sounddevice's default output device, or None."""
+    import sounddevice as sd
+    default = sd.default.device
+    # default may be: int, (in, out) tuple/list, or sd._InputOutputPair
+    try:
+        _in, out_idx = default
+    except (TypeError, ValueError):
+        out_idx = default
+    if out_idx is None:
+        return None
+    try:
+        out_idx = int(out_idx)
+    except (TypeError, ValueError):
+        return None
+    return out_idx if out_idx >= 0 else None
+
+
+def _log_audio_device() -> None:
+    """Log which audio output device sounddevice will use."""
+    try:
+        import sounddevice as sd
+        out_idx = _resolve_default_output()
+        if out_idx is None:
+            _hook_log(f"audio: NO default output device (sd.default.device={sd.default.device!r})")
+            return
+        info = sd.query_devices(out_idx)
+        hostapi = sd.query_hostapis(info["hostapi"])["name"]
+        _hook_log(
+            f"audio: default out [{out_idx}] {info['name']} "
+            f"({hostapi}, {info['max_output_channels']} ch, "
+            f"{int(info['default_samplerate'])} Hz)"
+        )
+    except Exception as e:
+        _hook_log(f"audio: device query failed: {e}")
+
+
+@main.command()
+@click.option("--server", default=None)
+def test(server: str | None) -> None:
+    """Speak a short test message."""
+    cfg = config.load()
+    srv = server or cfg["server"]
+    _stream_and_play(
+        srv,
+        "Lystn is connected and working.",
+        cfg["voice"],
+        cfg["api_key"],
+        cfg.get("device"),
+    )
+
+
+@main.command()
+def voices() -> None:
+    """List available voices from the server."""
+    cfg = config.load()
+    try:
+        for v in client.voices(cfg["server"]):
+            marker = " *" if v == cfg["voice"] else ""
+            click.echo(f"{v}{marker}")
+    except Exception as e:
+        click.echo(f"error: {e}", err=True)
+        sys.exit(1)
+
+
+@main.command()
+def doctor() -> None:
+    """Check connection to the Lystn server."""
+    cfg = config.load()
+    click.echo(f"server: {cfg['server']}")
+    click.echo(f"voice:  {cfg['voice']}")
+    click.echo(f"key:    {'set' if cfg['api_key'] else 'not set'}")
+    device_cfg = cfg.get("device")
+    if device_cfg is None:
+        click.echo("device: system default")
+    else:
+        resolved = resolve_device(device_cfg)
+        if resolved is None:
+            click.echo(f"device: {device_cfg!r} (NOT FOUND — will fall back)")
+        else:
+            try:
+                import sounddevice as sd
+                info = sd.query_devices(resolved)
+                hostapi = sd.query_hostapis(info["hostapi"])["name"]
+                click.echo(
+                    f"device: {device_cfg!r} -> [{resolved}] {info['name']} ({hostapi})"
+                )
+            except Exception:
+                click.echo(f"device: {device_cfg!r} -> [{resolved}]")
+    ok = client.health(cfg["server"])
+    click.echo(f"health: {'ok' if ok else 'unreachable'}")
+    click.echo(f"log:    {config.config_dir() / 'hook.log'}")
+    sys.exit(0 if ok else 1)
+
+
+@main.command()
+@click.option("--pick", is_flag=True, help="Interactively choose and save a device.")
+def devices(pick: bool) -> None:
+    """List audio output devices sounddevice can see.
+
+    With --pick, prompts for an index and saves it to config.
+    """
+    try:
+        import sounddevice as sd
+        cfg = config.load()
+        configured = cfg.get("device")
+        configured_idx = resolve_device(configured)
+        out_idx = _resolve_default_output()
+        click.echo(f"default output index: {out_idx}")
+        if configured is not None:
+            click.echo(f"configured: {configured!r} -> {configured_idx}")
+        click.echo()
+        rows = []
+        for i, d in enumerate(sd.query_devices()):
+            if d["max_output_channels"] <= 0:
+                continue
+            hostapi = sd.query_hostapis(d["hostapi"])["name"]
+            markers = []
+            if i == out_idx:
+                markers.append("system default")
+            if i == configured_idx:
+                markers.append("configured")
+            tag = f"  <- {', '.join(markers)}" if markers else ""
+            click.echo(
+                f"[{i:>2}] {d['name']} ({hostapi}, "
+                f"{d['max_output_channels']} ch, "
+                f"{int(d['default_samplerate'])} Hz){tag}"
+            )
+            rows.append(i)
+        if not pick:
+            return
+        click.echo()
+        choice = click.prompt(
+            "Enter device index to save (or blank to use system default)",
+            default="",
+            show_default=False,
+        )
+        choice = choice.strip()
+        if choice == "":
+            config.set_value("device", None)
+            click.echo("device: cleared (system default)")
+            return
+        try:
+            idx = int(choice)
+        except ValueError:
+            click.echo("not a number, aborting", err=True)
+            sys.exit(1)
+        if idx not in rows:
+            click.echo(f"index {idx} is not a valid output device", err=True)
+            sys.exit(1)
+        config.set_value("device", idx)
+        click.echo(f"saved device: {idx}")
+    except Exception as e:
+        click.echo(f"error: {e}", err=True)
+        sys.exit(1)
+
+
+@main.command()
+@click.argument("text", required=False)
+@click.option("--out", default="lystn_debug.wav", help="Output WAV path.")
+def dump(text: str | None, out: str) -> None:
+    """Synthesize TEXT and save to a WAV file instead of playing.
+
+    Use this to verify the server is producing real audio when the hook
+    can't be heard — open the WAV in any media player.
+    """
+    import wave
+    import numpy as np
+    if not text:
+        text = sys.stdin.read()
+    cleaned = clean_for_tts(text or "Lystn dump test.")
+    cfg = config.load()
+    chunks = list(client.synthesize(cfg["server"], cleaned,
+                                    voice=cfg["voice"],
+                                    api_key=cfg["api_key"]))
+    if not chunks:
+        click.echo("no audio chunks returned from server", err=True)
+        sys.exit(1)
+    pcm_f32 = np.frombuffer(b"".join(chunks), dtype=np.float32)
+    pcm_i16 = np.clip(pcm_f32 * 32767, -32768, 32767).astype(np.int16)
+    with wave.open(out, "wb") as w:
+        w.setnchannels(1)
+        w.setsampwidth(2)
+        w.setframerate(24000)
+        w.writeframes(pcm_i16.tobytes())
+    click.echo(f"wrote {len(pcm_i16)} samples ({len(pcm_i16)/24000:.2f}s) to {out}")
+
+
+@main.command()
+@click.option("--tail", default=20, help="Show last N lines.")
+def log(tail: int) -> None:
+    """Show recent hook.log lines."""
+    log_path = config.config_dir() / "hook.log"
+    if not log_path.exists():
+        click.echo(f"no log yet at {log_path}")
+        return
+    with log_path.open("r", encoding="utf-8") as f:
+        lines = f.readlines()
+    for line in lines[-tail:]:
+        click.echo(line.rstrip())
+
+
+@main.group()
+def config_cmd() -> None:
+    """View or change saved settings."""
+
+
+main.add_command(config_cmd, name="config")
+
+
+@config_cmd.command("show")
+def config_show() -> None:
+    """Print the current config."""
+    cfg = config.load()
+    if cfg.get("api_key"):
+        cfg["api_key"] = cfg["api_key"][:4] + "…(hidden)"
+    click.echo(json.dumps(cfg, indent=2))
+    click.echo(f"\nfile: {config.config_path()}")
+
+
+@config_cmd.command("set")
+@click.argument(
+    "key", type=click.Choice(["server", "api_key", "voice", "device"])
+)
+@click.argument("value")
+def config_set(key: str, value: str) -> None:
+    """Set KEY to VALUE.
+
+    For `device`, VALUE can be an integer index (see `lystn devices`),
+    a substring of a device name (e.g. `AirPods`), or `default` to clear.
+    """
+    if key == "device":
+        if value.lower() in ("default", "none", ""):
+            config.set_value("device", None)
+            click.echo("device: cleared (system default)")
+            return
+        try:
+            stored: int | str = int(value)
+        except ValueError:
+            stored = value
+        resolved = resolve_device(stored)
+        if resolved is None:
+            click.echo(
+                f"warning: {value!r} did not match any output device; "
+                "saving anyway, will fall back to system default at playback time",
+                err=True,
+            )
+        config.set_value("device", stored)
+        click.echo(f"saved device: {stored!r} (resolved to {resolved})")
+        return
+    config.set_value(key, value)
+    click.echo(f"saved {key}")
+
+
+@main.command()
+def install() -> None:
+    """Print the Claude Code Stop-hook snippet to wire `lystn hook`."""
+    import shutil
+    lystn_path = shutil.which("lystn") or "lystn"
+    # Claude Code runs hook commands through bash on Windows, which eats
+    # backslashes. Forward slashes work for both bash and Windows path
+    # resolution.
+    lystn_path = lystn_path.replace("\\", "/")
+    snippet = {
+        "hooks": {
+            "Stop": [
+                {
+                    "matcher": "*",
+                    "hooks": [
+                        {"type": "command", "command": f"{lystn_path} hook"}
+                    ],
+                }
+            ],
+            "UserPromptSubmit": [
+                {
+                    "matcher": "*",
+                    "hooks": [
+                        {
+                            "type": "command",
+                            "command": (
+                                "echo Your final response will be spoken aloud "
+                                "by a TTS engine. Keep it short and "
+                                "conversational. Skip markdown, headers, and "
+                                "code blocks unless explicitly asked."
+                            ),
+                        }
+                    ],
+                }
+            ],
+        }
+    }
+    click.echo("Add the following `hooks` key inside the top-level object")
+    click.echo("of ~/.claude/settings.json (merge with existing keys, comma-separated):\n")
+    inner = json.dumps(snippet["hooks"], indent=2)
+    click.echo(f'"hooks": {inner}')

lystn-0.1.0/src/lystn/client.py

@@ -0,0 +1,121 @@
+"""Client for the Lystn TTS server.
+
+Posts text to /speak, then connects to the /stream WebSocket and yields
+binary PCM chunks as they arrive. Stops yielding on the {event: end}
+JSON message.
+"""
+from __future__ import annotations
+
+import json
+import queue
+import threading
+from typing import Iterator
+
+import requests
+import websocket
+
+
+def synthesize(
+    server: str,
+    text: str,
+    voice: str | None = None,
+    api_key: str | None = None,
+    timeout: float = 5.0,
+) -> Iterator[bytes]:
+    """POST text to the server, yield PCM chunks streamed back via WS.
+
+    Caller is responsible for playing the chunks. Closes the WS on `end`.
+    """
+    ws_url = _http_to_ws(server) + "/stream"
+    speak_url = server.rstrip("/") + "/speak"
+
+    chunk_q: queue.Queue = queue.Queue()
+    started = threading.Event()
+    finished = threading.Event()
+
+    def on_open(_ws):
+        started.set()
+        _ws.send("hello")  # server's recv loop needs a kick
+
+    def on_message(_ws, msg):
+        if isinstance(msg, (bytes, bytearray)):
+            chunk_q.put(bytes(msg))
+            return
+        try:
+            payload = json.loads(msg)
+        except json.JSONDecodeError:
+            return
+        if payload.get("event") == "end":
+            chunk_q.put(None)
+            finished.set()
+        elif payload.get("event") == "error":
+            chunk_q.put(None)
+            finished.set()
+
+    def on_close(*_):
+        chunk_q.put(None)
+        finished.set()
+
+    def on_error(*_):
+        chunk_q.put(None)
+        finished.set()
+
+    ws = websocket.WebSocketApp(
+        ws_url,
+        on_open=on_open,
+        on_message=on_message,
+        on_close=on_close,
+        on_error=on_error,
+    )
+    t = threading.Thread(target=ws.run_forever, daemon=True)
+    t.start()
+
+    if not started.wait(timeout=timeout):
+        ws.close()
+        raise ConnectionError(f"Could not connect to {ws_url} in {timeout}s")
+
+    headers = {"Content-Type": "application/json"}
+    if api_key:
+        headers["X-Lystn-Key"] = api_key
+
+    body = {"text": text}
+    if voice:
+        body["voice"] = voice
+
+    try:
+        r = requests.post(speak_url, json=body, headers=headers, timeout=timeout)
+        r.raise_for_status()
+    except requests.RequestException:
+        ws.close()
+        raise
+
+    try:
+        while True:
+            item = chunk_q.get()
+            if item is None:
+                return
+            yield item
+    finally:
+        ws.close()
+
+
+def voices(server: str, timeout: float = 5.0) -> list[str]:
+    r = requests.get(server.rstrip("/") + "/voices", timeout=timeout)
+    r.raise_for_status()
+    return list(r.json().get("voices", []))
+
+
+def health(server: str, timeout: float = 3.0) -> bool:
+    try:
+        r = requests.get(server.rstrip("/") + "/health", timeout=timeout)
+        return r.ok
+    except requests.RequestException:
+        return False
+
+
+def _http_to_ws(url: str) -> str:
+    if url.startswith("https://"):
+        return "wss://" + url[len("https://"):]
+    if url.startswith("http://"):
+        return "ws://" + url[len("http://"):]
+    return url

lystn-0.1.0/src/lystn/config.py

@@ -0,0 +1,57 @@
+"""User config stored as JSON in the platform's config dir."""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+DEFAULTS: dict[str, Any] = {
+    "server": "http://127.0.0.1:7878",
+    "api_key": None,
+    "voice": "af_heart",
+    "device": None,
+}
+
+
+def config_dir() -> Path:
+    if os.name == "nt":
+        base = os.environ.get("APPDATA") or str(Path.home() / "AppData" / "Roaming")
+    else:
+        base = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    d = Path(base) / "lystn"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def config_path() -> Path:
+    return config_dir() / "config.json"
+
+
+def load() -> dict[str, Any]:
+    p = config_path()
+    if not p.exists():
+        return dict(DEFAULTS)
+    try:
+        with p.open("r", encoding="utf-8") as f:
+            data = json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return dict(DEFAULTS)
+    merged = dict(DEFAULTS)
+    merged.update({k: v for k, v in data.items() if v is not None})
+    return merged
+
+
+def save(cfg: dict[str, Any]) -> None:
+    with config_path().open("w", encoding="utf-8") as f:
+        json.dump(cfg, f, indent=2)
+
+
+def get(key: str) -> Any:
+    return load().get(key, DEFAULTS.get(key))
+
+
+def set_value(key: str, value: Any) -> None:
+    cfg = load()
+    cfg[key] = value
+    save(cfg)

lystn-0.1.0/src/lystn/player.py

@@ -0,0 +1,210 @@
+"""Audio playback for streamed PCM chunks.
+
+Two backends:
+
+- Windows: write the audio to a temp WAV and play it via the OS default
+  audio path (winsound). This is the same path the browser and Media Player
+  use, and it works on machines where PortAudio/sounddevice is silent
+  (a real, common failure with Bluetooth + virtual audio drivers).
+- Other platforms: stream chunks live through a sounddevice OutputStream.
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import tempfile
+import wave
+from typing import Iterable
+
+import numpy as np
+import sounddevice as sd
+
+SAMPLE_RATE = 24_000
+
+
+def resolve_device(device: int | str | None) -> int | None:
+    """Resolve a config `device` value to a concrete sounddevice index.
+
+    - None or empty: return None (use system default).
+    - int or numeric string: return that index if it exists and has output.
+    - non-numeric string: case-insensitive substring match on device name.
+
+    On Windows, when multiple host APIs expose the same device (e.g. MME,
+    WASAPI, DirectSound), prefer DirectSound. It always resamples and is the
+    most universally audible backend; WASAPI shared mode and MME both
+    silently swallow audio on some setups (Bluetooth, virtual mixers).
+    """
+    if device is None or device == "":
+        return None
+
+    devices = sd.query_devices()
+    hostapis = sd.query_hostapis()
+
+    def hostapi_name(d) -> str:
+        return hostapis[d["hostapi"]]["name"]
+
+    def wasapi_score(d) -> int:
+        name = hostapi_name(d).lower()
+        if "directsound" in name:
+            return 3
+        if "wasapi" in name:
+            return 2
+        if "mme" in name:
+            return 1
+        return 0
+
+    try:
+        idx = int(device)
+    except (TypeError, ValueError):
+        idx = None
+
+    if idx is not None:
+        if 0 <= idx < len(devices) and devices[idx]["max_output_channels"] > 0:
+            return idx
+        return None
+
+    needle = str(device).lower().strip()
+    matches = [
+        (i, d) for i, d in enumerate(devices)
+        if d["max_output_channels"] > 0 and needle in d["name"].lower()
+    ]
+    if not matches:
+        return None
+    matches.sort(key=lambda pair: wasapi_score(pair[1]), reverse=True)
+    return matches[0][0]
+
+
+def _device_samplerate(index: int | None) -> int:
+    """Native default output rate for `index` (or the system default)."""
+    try:
+        if index is None:
+            default = sd.default.device
+            try:
+                _in, index = default
+            except (TypeError, ValueError):
+                index = default
+        info = sd.query_devices(index)
+        rate = int(info["default_samplerate"])
+        return rate if rate > 0 else SAMPLE_RATE
+    except Exception:
+        return SAMPLE_RATE
+
+
+class Player:
+    """Plays 24kHz mono float32 PCM, resampled to the device's native rate.
+
+    Opening an OutputStream at Kokoro's 24kHz rate plays *silently* on some
+    Windows backends (notably DirectSound and Bluetooth). Opening at the
+    device's own default rate and resampling the audio up to match is the
+    reliable path: it's what plain `sd.play` does, and it's audible
+    everywhere we've tested.
+    """
+
+    def __init__(
+        self,
+        sample_rate: int = SAMPLE_RATE,
+        device: int | str | None = None,
+    ):
+        self.sample_rate = sample_rate
+        self.device = resolve_device(device)
+        self.out_rate = _device_samplerate(self.device)
+        self._stream: sd.OutputStream | None = None
+
+    def __enter__(self) -> "Player":
+        self._stream = sd.OutputStream(
+            samplerate=self.out_rate,
+            channels=1,
+            dtype="float32",
+            blocksize=0,
+            device=self.device,
+        )
+        self._stream.start()
+        return self
+
+    def __exit__(self, *_exc) -> None:
+        if self._stream is not None:
+            try:
+                self._stream.stop()
+            finally:
+                self._stream.close()
+                self._stream = None
+
+    def _resample(self, arr: np.ndarray) -> np.ndarray:
+        if self.out_rate == self.sample_rate or arr.size == 0:
+            return arr
+        n_out = int(round(arr.size * self.out_rate / self.sample_rate))
+        if n_out <= 0:
+            return arr
+        src_idx = np.linspace(0.0, 1.0, arr.size, endpoint=False)
+        dst_idx = np.linspace(0.0, 1.0, n_out, endpoint=False)
+        return np.interp(dst_idx, src_idx, arr).astype(np.float32)
+
+    def write_pcm_bytes(self, chunk: bytes) -> None:
+        if not chunk:
+            return
+        arr = np.frombuffer(chunk, dtype=np.float32)
+        assert self._stream is not None, "Player not started"
+        self._stream.write(self._resample(arr))
+
+
+def _write_wav(chunks: Iterable[bytes], sample_rate: int) -> tuple[str, float]:
+    """Buffer float32 PCM chunks into a temp WAV. Returns (path, seconds)."""
+    pcm = b"".join(chunks)
+    if not pcm:
+        return "", 0.0
+    arr = np.frombuffer(pcm, dtype=np.float32)
+    pcm16 = np.clip(arr * 32767.0, -32768, 32767).astype(np.int16)
+    path = os.path.join(tempfile.gettempdir(), "lystn_play.wav")
+    with wave.open(path, "wb") as w:
+        w.setnchannels(1)
+        w.setsampwidth(2)
+        w.setframerate(sample_rate)
+        w.writeframes(pcm16.tobytes())
+    return path, len(pcm16) / float(sample_rate)
+
+
+def _play_via_media_foundation(chunks: Iterable[bytes], sample_rate: int) -> None:
+    """Play through Windows Media Foundation (System.Windows.Media.MediaPlayer).
+
+    This is the modern audio path Windows Media Player uses. It works on
+    machines where the legacy MME path (winsound) and PortAudio are silent —
+    a common failure with Bluetooth headphones and virtual audio drivers.
+    Windowless; follows the system default output like any normal app.
+    """
+    path, seconds = _write_wav(chunks, sample_rate)
+    if not path:
+        return
+    uri = path.replace("'", "''")
+    ps = (
+        "Add-Type -AssemblyName PresentationCore;"
+        "$p=New-Object System.Windows.Media.MediaPlayer;"
+        f"$p.Open([uri]'{uri}');$p.Play();"
+        f"Start-Sleep -Milliseconds {int(seconds * 1000) + 1200};"
+        "$p.Stop();$p.Close()"
+    )
+    subprocess.run(
+        ["powershell", "-NoProfile", "-NonInteractive", "-Command", ps],
+        creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
+        check=False,
+    )
+
+
+def play_chunks(
+    chunks: Iterable[bytes],
+    sample_rate: int = SAMPLE_RATE,
+    device: int | str | None = None,
+) -> None:
+    """Play a stream of float32 PCM chunks synchronously.
+
+    On Windows we go through Media Foundation, which is far more reliable
+    than PortAudio/MME for Bluetooth and virtual-audio setups. `device` is
+    ignored there — playback follows the Windows default output, just like
+    the browser. On other platforms we stream via sounddevice.
+    """
+    if sys.platform == "win32":
+        _play_via_media_foundation(chunks, sample_rate)
+        return
+    with Player(sample_rate, device=device) as p:
+        for c in chunks:
+            p.write_pcm_bytes(c)