vinowhisper 0.3.0__tar.gz

vinowhisper-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Karan Shukla
+
+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.

vinowhisper-0.3.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: vinowhisper
+Version: 0.3.0
+Summary: NPU-accelerated local live captioning for Linux, via OpenVINO GenAI Whisper
+Author: Karan Shukla
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/karanshukla/vinoWhisper
+Project-URL: Repository, https://github.com/karanshukla/vinoWhisper
+Project-URL: Issues, https://github.com/karanshukla/vinoWhisper/issues
+Project-URL: Changelog, https://github.com/karanshukla/vinoWhisper/blob/main/CHANGELOG.md
+Keywords: whisper,openvino,npu,captions,speech-to-text,pipewire,linux
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <3.14,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openvino>=2026.3.1
+Requires-Dist: openvino-genai>=2026.3.1.0
+Requires-Dist: openvino-tokenizers>=2026.3.1.0
+Requires-Dist: optimum[openvino]
+Requires-Dist: flask
+Requires-Dist: werkzeug
+Requires-Dist: requests
+Requires-Dist: numpy
+Requires-Dist: rich
+Dynamic: license-file
+
+# vinoWhisper
+
+[![CI](https://github.com/karanshukla/vinoWhisper/actions/workflows/ci.yml/badge.svg)](https://github.com/karanshukla/vinoWhisper/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/karanshukla/vinoWhisper/blob/main/LICENSE)
+[![Python](https://img.shields.io/badge/python-3.11%20|%203.12%20|%203.13-blue)](https://github.com/karanshukla/vinoWhisper/blob/main/pyproject.toml)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+NPU-accelerated local live captioning for Linux, using OpenVINO GenAI's
+`WhisperPipeline` on an Intel NPU. Named after
+[vinoAuthFace](https://github.com/karanshukla/vinoAuthFace), same idea of
+OpenVINO doing the NPU work, different feature.
+
+Point it at whatever is playing and it captions in your terminal. Nothing
+leaves the machine. Start it and it goes; there is nothing to interact with.
+
+<img width="1237" height="530" alt="image" src="https://github.com/user-attachments/assets/f263eabf-f1f4-4ab2-9b68-bc50eaf92ea0" />
+
+The transcript scrolls above that bar in your terminal's own scrollback, so it
+is still there after you quit and your terminal's selection and search still
+work on it. `hearing…` is the words heard once but still waiting on a second
+cycle to agree, which is the two-cycle commit delay made visible rather than
+felt as a freeze.
+
+## Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/karanshukla/vinoWhisper/main/scripts/install.sh | bash
+```
+
+That installs [uv](https://docs.astral.sh/uv/), clones the repo, builds the
+environment, and hands over to `vinowhisper-setup`, which is where every
+machine-specific decision happens: your capture tool, your NPU driver, the
+model export your device needs, and systemd units generated against the paths
+that actually exist. It prints every command before running it and asks first.
+
+From a checkout, or to see what it would do without doing it:
+
+```bash
+git clone https://github.com/karanshukla/vinoWhisper && cd vinoWhisper
+uv sync
+uv run vinowhisper-setup --dry-run   # the whole plan, nothing changed
+uv run vinowhisper-setup             # for real, one prompt per step
+```
+
+Or from PyPI, if you would rather wire up the machine yourself:
+
+```bash
+pip install vinowhisper   # needs Python 3.11-3.13
+vinowhisper-setup         # still worth running: NPU driver, model export, units
+```
+
+`pip install` gets you the five commands and the Python dependencies. It cannot
+get you an NPU driver, a model export or systemd units, which is what
+`vinowhisper-setup` is for either way. See
+[docs/install.md](https://github.com/karanshukla/vinoWhisper/blob/main/docs/install.md) for the OpenVINO version
+floor and why this could not be a pip install until 2026-08-31.
+
+## Commands
+
+```
+vinowhisper-caption                       # caption system audio
+vinowhisper-caption --source mic          # caption yourself
+vinowhisper-caption --list-targets        # capture one app instead of the whole sink
+vinowhisper-caption --debug               # per-cycle timings, levels, raw transcript
+vinowhisper-caption --record ~/sess       # save the session for replay
+vinowhisper-caption --plain > out.txt     # no status bar (implied when piping)
+
+vinowhisper-setup                         # guided install; re-runnable, idempotent
+vinowhisper-setup --dry-run               # print the plan, change nothing
+vinowhisper-setup --print-units           # the systemd units it would generate
+
+vinowhisper-doctor                        # devices, model, audio, live levels
+vinowhisper-doctor --json                 # the same, for a bug report
+vinowhisper-doctor --no-probe             # skip the 2s-per-target level capture
+
+vinowhisper-replay ~/sess --restitch      # re-run the merge logic offline
+vinowhisper-replay ~/sess --sweep 8,12,20 # measure what --window actually costs
+```
+
+## Hardware
+
+The NPU is the point. Everything below it exists so a broken driver degrades
+the tool instead of bricking it.
+
+| Device | Selected | Model export | What you get |
+|---|---|---|---|
+| **NPU** (`Intel(R) AI Boost`) | first | `--disable-stateful` | ~1.19s per 30s window, measured 2026-08-03 |
+| **GPU** (Arc / Xe) | second | stateful | Untested here. Works in principle; watch the lag figure |
+| **CPU** | last resort | stateful | Runs. Competes with everything else on the machine, and lags |
+
+Selection is automatic and a fallback is never silent: it shows up in the
+server journal, in `/health`, in `vinowhisper-doctor`, and on the status bar as
+a red border. The two model exports are not interchangeable, and the NPU needs
+a userspace driver half that no distro packages completely.
+[docs/hardware.md](https://github.com/karanshukla/vinoWhisper/blob/main/docs/hardware.md) covers all of it, including what to do
+when the NPU does not show up.
+
+Audio capture works on PipeWire (`pw-record`) or PulseAudio (`parec`), picked
+automatically, and package names for eight distro families live in one table in
+[`vinowhisper/distro.py`](https://github.com/karanshukla/vinoWhisper/blob/main/vinowhisper/distro.py). **If a name is wrong for your
+distro, that is expected, and it is the fastest thing here to fix.**
+
+## Docs
+
+| | |
+|---|---|
+| [Installing](https://github.com/karanshukla/vinoWhisper/blob/main/docs/install.md) | What the installer does, the OpenVINO version floor and why, pinning the window on top |
+| [Hardware](https://github.com/karanshukla/vinoWhisper/blob/main/docs/hardware.md) | Device selection, the two model exports, and every way the NPU fails to appear |
+| [Audio capture](https://github.com/karanshukla/vinoWhisper/blob/main/docs/audio.md) | PipeWire vs PulseAudio, distro coverage, and what actually silences a capture (it is not the mute button) |
+| [Latency](https://github.com/karanshukla/vinoWhisper/blob/main/docs/latency.md) | Why captions trail the audio, the one knob that changes it, and why the wording drifts |
+| [Debugging](https://github.com/karanshukla/vinoWhisper/blob/main/docs/debugging.md) | `--record`, offline replay, and what `vinowhisper-doctor` measures |
+| [Architecture](https://github.com/karanshukla/vinoWhisper/blob/main/docs/architecture.md) | Socket activation and scale-to-zero, and how to stop it |
+
+## More
+
+- Design doc, benchmarks, and the three export bugs hit getting to a working
+  NPU pipeline:
+  [wildcat-lake-linux/input/f5-voice-typing.md](https://github.com/karanshukla/wildcat-lake-linux/blob/main/input/f5-voice-typing.md)
+- [CONTRIBUTING.md](https://github.com/karanshukla/vinoWhisper/blob/main/CONTRIBUTING.md), where the useful contributions are distro
+  corrections and reports from hardware that isn't this laptop
+- [SECURITY.md](https://github.com/karanshukla/vinoWhisper/blob/main/SECURITY.md), what stays on the machine and what the loopback
+  server's trust boundary actually is
+- [CHANGELOG.md](https://github.com/karanshukla/vinoWhisper/blob/main/CHANGELOG.md)
+
+MIT licensed.

vinowhisper-0.3.0/README.md

@@ -0,0 +1,125 @@
+# vinoWhisper
+
+[![CI](https://github.com/karanshukla/vinoWhisper/actions/workflows/ci.yml/badge.svg)](https://github.com/karanshukla/vinoWhisper/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/karanshukla/vinoWhisper/blob/main/LICENSE)
+[![Python](https://img.shields.io/badge/python-3.11%20|%203.12%20|%203.13-blue)](https://github.com/karanshukla/vinoWhisper/blob/main/pyproject.toml)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+NPU-accelerated local live captioning for Linux, using OpenVINO GenAI's
+`WhisperPipeline` on an Intel NPU. Named after
+[vinoAuthFace](https://github.com/karanshukla/vinoAuthFace), same idea of
+OpenVINO doing the NPU work, different feature.
+
+Point it at whatever is playing and it captions in your terminal. Nothing
+leaves the machine. Start it and it goes; there is nothing to interact with.
+
+<img width="1237" height="530" alt="image" src="https://github.com/user-attachments/assets/f263eabf-f1f4-4ab2-9b68-bc50eaf92ea0" />
+
+The transcript scrolls above that bar in your terminal's own scrollback, so it
+is still there after you quit and your terminal's selection and search still
+work on it. `hearing…` is the words heard once but still waiting on a second
+cycle to agree, which is the two-cycle commit delay made visible rather than
+felt as a freeze.
+
+## Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/karanshukla/vinoWhisper/main/scripts/install.sh | bash
+```
+
+That installs [uv](https://docs.astral.sh/uv/), clones the repo, builds the
+environment, and hands over to `vinowhisper-setup`, which is where every
+machine-specific decision happens: your capture tool, your NPU driver, the
+model export your device needs, and systemd units generated against the paths
+that actually exist. It prints every command before running it and asks first.
+
+From a checkout, or to see what it would do without doing it:
+
+```bash
+git clone https://github.com/karanshukla/vinoWhisper && cd vinoWhisper
+uv sync
+uv run vinowhisper-setup --dry-run   # the whole plan, nothing changed
+uv run vinowhisper-setup             # for real, one prompt per step
+```
+
+Or from PyPI, if you would rather wire up the machine yourself:
+
+```bash
+pip install vinowhisper   # needs Python 3.11-3.13
+vinowhisper-setup         # still worth running: NPU driver, model export, units
+```
+
+`pip install` gets you the five commands and the Python dependencies. It cannot
+get you an NPU driver, a model export or systemd units, which is what
+`vinowhisper-setup` is for either way. See
+[docs/install.md](https://github.com/karanshukla/vinoWhisper/blob/main/docs/install.md) for the OpenVINO version
+floor and why this could not be a pip install until 2026-08-31.
+
+## Commands
+
+```
+vinowhisper-caption                       # caption system audio
+vinowhisper-caption --source mic          # caption yourself
+vinowhisper-caption --list-targets        # capture one app instead of the whole sink
+vinowhisper-caption --debug               # per-cycle timings, levels, raw transcript
+vinowhisper-caption --record ~/sess       # save the session for replay
+vinowhisper-caption --plain > out.txt     # no status bar (implied when piping)
+
+vinowhisper-setup                         # guided install; re-runnable, idempotent
+vinowhisper-setup --dry-run               # print the plan, change nothing
+vinowhisper-setup --print-units           # the systemd units it would generate
+
+vinowhisper-doctor                        # devices, model, audio, live levels
+vinowhisper-doctor --json                 # the same, for a bug report
+vinowhisper-doctor --no-probe             # skip the 2s-per-target level capture
+
+vinowhisper-replay ~/sess --restitch      # re-run the merge logic offline
+vinowhisper-replay ~/sess --sweep 8,12,20 # measure what --window actually costs
+```
+
+## Hardware
+
+The NPU is the point. Everything below it exists so a broken driver degrades
+the tool instead of bricking it.
+
+| Device | Selected | Model export | What you get |
+|---|---|---|---|
+| **NPU** (`Intel(R) AI Boost`) | first | `--disable-stateful` | ~1.19s per 30s window, measured 2026-08-03 |
+| **GPU** (Arc / Xe) | second | stateful | Untested here. Works in principle; watch the lag figure |
+| **CPU** | last resort | stateful | Runs. Competes with everything else on the machine, and lags |
+
+Selection is automatic and a fallback is never silent: it shows up in the
+server journal, in `/health`, in `vinowhisper-doctor`, and on the status bar as
+a red border. The two model exports are not interchangeable, and the NPU needs
+a userspace driver half that no distro packages completely.
+[docs/hardware.md](https://github.com/karanshukla/vinoWhisper/blob/main/docs/hardware.md) covers all of it, including what to do
+when the NPU does not show up.
+
+Audio capture works on PipeWire (`pw-record`) or PulseAudio (`parec`), picked
+automatically, and package names for eight distro families live in one table in
+[`vinowhisper/distro.py`](https://github.com/karanshukla/vinoWhisper/blob/main/vinowhisper/distro.py). **If a name is wrong for your
+distro, that is expected, and it is the fastest thing here to fix.**
+
+## Docs
+
+| | |
+|---|---|
+| [Installing](https://github.com/karanshukla/vinoWhisper/blob/main/docs/install.md) | What the installer does, the OpenVINO version floor and why, pinning the window on top |
+| [Hardware](https://github.com/karanshukla/vinoWhisper/blob/main/docs/hardware.md) | Device selection, the two model exports, and every way the NPU fails to appear |
+| [Audio capture](https://github.com/karanshukla/vinoWhisper/blob/main/docs/audio.md) | PipeWire vs PulseAudio, distro coverage, and what actually silences a capture (it is not the mute button) |
+| [Latency](https://github.com/karanshukla/vinoWhisper/blob/main/docs/latency.md) | Why captions trail the audio, the one knob that changes it, and why the wording drifts |
+| [Debugging](https://github.com/karanshukla/vinoWhisper/blob/main/docs/debugging.md) | `--record`, offline replay, and what `vinowhisper-doctor` measures |
+| [Architecture](https://github.com/karanshukla/vinoWhisper/blob/main/docs/architecture.md) | Socket activation and scale-to-zero, and how to stop it |
+
+## More
+
+- Design doc, benchmarks, and the three export bugs hit getting to a working
+  NPU pipeline:
+  [wildcat-lake-linux/input/f5-voice-typing.md](https://github.com/karanshukla/wildcat-lake-linux/blob/main/input/f5-voice-typing.md)
+- [CONTRIBUTING.md](https://github.com/karanshukla/vinoWhisper/blob/main/CONTRIBUTING.md), where the useful contributions are distro
+  corrections and reports from hardware that isn't this laptop
+- [SECURITY.md](https://github.com/karanshukla/vinoWhisper/blob/main/SECURITY.md), what stays on the machine and what the loopback
+  server's trust boundary actually is
+- [CHANGELOG.md](https://github.com/karanshukla/vinoWhisper/blob/main/CHANGELOG.md)
+
+MIT licensed.

vinowhisper-0.3.0/pyproject.toml

@@ -0,0 +1,204 @@
+[project]
+name = "vinowhisper"
+version = "0.3.0"
+description = "NPU-accelerated local live captioning for Linux, via OpenVINO GenAI Whisper"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Karan Shukla" }]
+keywords = ["whisper", "openvino", "npu", "captions", "speech-to-text", "pipewire", "linux"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+# Python 3.14 is unusable here: it made functools.partial a descriptor, which
+# breaks optimum's `NORMALIZED_CONFIG_CLASS = SomeConfig.with_args(...)` class-
+# attribute idiom (self gets auto-bound as an extra positional arg). Confirmed
+# 2026-08-03 across every optimum/optimum-intel/transformers version tried —
+# root cause, not a version-pairing issue. Use 3.13 until upstream fixes it.
+requires-python = ">=3.11,<3.14"
+dependencies = [
+    # 2026.3.1 is the floor because it is the first *stable* release that can
+    # build the NPU static Whisper pipeline. Stable 2026.2.1 could not: its
+    # pipeline_static.cpp pattern-matcher did not recognize the optimum-intel
+    # export's SDPA attention-mask node shape
+    # (OPENVINO_ASSERT(!self_attn_nodes.empty())), which is why this project
+    # pinned the nightly wheel index from 2026-08-03 until 2026-08-31.
+    # Re-measured 2026-08-31 on the Wildcat Lake NPU against the same
+    # --disable-stateful export, WhisperPipeline(..., STATIC_PIPELINE=True):
+    # 2026.3.1 stable builds in 2.0s and decodes, as do nightly 2026.4.0.dev-
+    # 20260805 and 2026.5.0.dev20260831. Stable caught up, so the nightly
+    # index, the global prerelease policy and the weekly resolve canary are
+    # all gone and these resolve from PyPI like anything else.
+    "openvino>=2026.3.1",
+    "openvino-genai>=2026.3.1.0",
+    # Pulled in transitively by openvino-genai and still listed directly: the
+    # NPU pipeline hard-depends on it, and a transitive-only dependency is one
+    # upstream packaging change away from disappearing silently.
+    "openvino-tokenizers>=2026.3.1.0",
+    "optimum[openvino]",
+    "flask",
+    "werkzeug",
+    "requests",
+    "numpy",
+    # Status bar only. Rich rather than Textual because the transcript is
+    # append-only (see stitch.py), so it belongs in the terminal's own
+    # scrollback and only the status line needs to redraw.
+    "rich",
+]
+
+[project.urls]
+Homepage = "https://github.com/karanshukla/vinoWhisper"
+Repository = "https://github.com/karanshukla/vinoWhisper"
+Issues = "https://github.com/karanshukla/vinoWhisper/issues"
+Changelog = "https://github.com/karanshukla/vinoWhisper/blob/main/CHANGELOG.md"
+
+[project.scripts]
+vinowhisper-caption = "vinowhisper.caption:main"
+vinowhisper-server = "vinowhisper.server:main"
+vinowhisper-replay = "vinowhisper.replay:main"
+vinowhisper-doctor = "vinowhisper.doctor:main"
+vinowhisper-setup = "vinowhisper.wizard:main"
+
+[build-system]
+requires = ["setuptools>=77"]  # PEP 639 license expressions
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+# Without this, setuptools' flat-layout auto-discovery sees the top-level
+# systemd/ directory (unit files, not a package) and refuses to build,
+# thinking it found two packages. Confirmed failing 2026-08-03.
+packages = ["vinowhisper"]
+
+# ── uv ────────────────────────────────────────────────────────────────────────
+
+[dependency-groups]
+# Deliberately installable on its own (`uv sync --only-group dev`): CI has no
+# NPU, no audio server and no reason to download ~400MB of OpenVINO to run
+# tests that are forbidden from importing it. Nothing under tests/ imports
+# openvino, transcriber or server, which is what keeps this split honest.
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.6",
+    "mypy>=1.10",
+    "poethepoet>=0.27",
+    "bump-my-version>=0.24",
+    "types-requests",
+    "numpy",
+    "rich",
+]
+
+# ── Tasks ─────────────────────────────────────────────────────────────────────
+
+[tool.poe.tasks]
+lint  = "ruff check ."
+fmt   = "ruff format --check ."
+types = "mypy vinowhisper/"
+test  = "pytest -v --tb=short"
+fix.sequence = [{ cmd = "ruff check --fix ." }, { cmd = "ruff format ." }]
+security.cmd = "uvx --from bandit[toml] bandit -c pyproject.toml -r vinowhisper/"
+security.help = "the same Bandit scan the Bandit workflow runs"
+check.sequence = ["lint", "fmt", "types", "test"]
+check.help = "everything CI runs, locally"
+doctor = "python -m vinowhisper.doctor"
+
+# ── Ruff ──────────────────────────────────────────────────────────────────────
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+ignore = [
+    "E501",   # line length is the formatter's job
+    "SIM108", # ternary-instead-of-if is often less readable
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["vinowhisper"]
+
+# ── Mypy ──────────────────────────────────────────────────────────────────────
+
+[tool.mypy]
+# Deliberately not pinned to python_version = "3.11". Numpy's own stubs use
+# 3.12-only syntax (`type X = ...`), and mypy parses them against the target
+# version, so pinning 3.11 while running on 3.12 fails inside numpy with a
+# syntax error before it checks any of this project's code. The floor is
+# enforced where it belongs anyway: requires-python and ruff's target-version.
+#
+# openvino_genai ships no stubs, and CI type-checks without it installed at all
+# (see the dev group note above).
+ignore_missing_imports = true
+warn_unused_ignores = false
+
+# ── Pytest ────────────────────────────────────────────────────────────────────
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "-q"
+# The package is imported from the source tree, not from an install: CI never
+# installs the project itself, because that would drag in the OpenVINO nightly
+# stack it deliberately does without.
+pythonpath = ["."]
+
+# ── Coverage ──────────────────────────────────────────────────────────────────
+
+[tool.coverage.run]
+source = ["vinowhisper"]
+# Not covered by design: these need an NPU, an audio server, or a live socket.
+omit = ["vinowhisper/transcriber.py", "vinowhisper/server.py", "vinowhisper/replay.py"]
+
+[tool.coverage.report]
+show_missing = true
+
+# ── Bandit ────────────────────────────────────────────────────────────────────
+
+# Read with `bandit -c pyproject.toml` (needs the `toml` extra). The Bandit
+# workflow passes the same flag, so CI and `poe security` agree.
+[tool.bandit]
+exclude_dirs = ["tests", ".venv", ".git", "build", "dist"]
+# Three blanket skips, each because the finding is this tool's entire job
+# rather than a defect in it. B602 (shell=True) stays ON, and is the one that
+# would actually matter: there is no shell anywhere in this codebase, and if
+# one ever appears it should fail this scan.
+skips = [
+    # blacklist — flags the `import subprocess` line itself, in a program whose
+    # purpose is to drive pw-record, parec, pactl, optimum-cli and systemctl.
+    "B404",
+    # subprocess_without_shell_equals_true. Every call site builds a literal
+    # argv list and passes it without a shell, so there is nothing to inject
+    # into: the variable parts are PipeWire node names read from pw-dump and a
+    # --target the user typed, both of which arrive as single argv elements.
+    "B603",
+    # start_process_with_partial_path. Deliberate: pw-record, parec and pactl
+    # live in different places on different distros, and hardcoding /usr/bin
+    # would break the fallbacks this release exists to add. PATH resolution is
+    # the portable behaviour here, and the tools are located with shutil.which
+    # before use.
+    "B607",
+]
+
+# ── bump-my-version ───────────────────────────────────────────────────────────
+
+[tool.bumpversion]
+current_version = "0.3.0"
+commit = true
+tag = true
+tag_name = "v{new_version}"
+pre_commit_hooks = ["uv lock", "git add uv.lock"]
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'

vinowhisper-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vinowhisper-0.3.0/tests/test_audio.py

@@ -0,0 +1,101 @@
+"""RingBuffer and level helpers.
+
+The ring buffer replaced a `np.concatenate([buf, chunk])[-cap:]` that copied
+~1.9MB twice per 100ms read. The interesting cases are all about the wrap:
+writing across the end, reading across it, and a chunk larger than the whole
+buffer, which must not corrupt the write index.
+"""
+
+import numpy as np
+import pytest
+
+from vinowhisper.audio import RingBuffer, normalize, rms
+
+
+def ramp(count: int, start: int = 0) -> np.ndarray:
+    return np.arange(start, start + count, dtype=np.float32)
+
+
+def test_capacity_must_be_positive():
+    with pytest.raises(ValueError):
+        RingBuffer(0)
+
+
+def test_reads_back_what_was_written():
+    buffer = RingBuffer(10)
+    buffer.write(ramp(4))
+    assert list(buffer.read_last(4)) == [0, 1, 2, 3]
+    assert buffer.total_written == 4
+
+
+def test_read_more_than_written_returns_what_there_is():
+    buffer = RingBuffer(10)
+    buffer.write(ramp(3))
+    assert list(buffer.read_last(100)) == [0, 1, 2]
+    assert buffer.read_last(0).size == 0
+
+
+def test_keeps_the_newest_samples_when_it_wraps():
+    buffer = RingBuffer(5)
+    buffer.write(ramp(8))  # 0..7, so 3..7 survive
+    assert list(buffer.read_last(5)) == [3, 4, 5, 6, 7]
+    # total_written is monotonic — the caption loop measures new audio with it.
+    assert buffer.total_written == 8
+
+
+def test_read_spanning_the_wrap_point_stays_in_order():
+    buffer = RingBuffer(5)
+    buffer.write(ramp(3))
+    buffer.write(ramp(4, start=3))  # writes 3,4,5,6 across the boundary
+    assert list(buffer.read_last(5)) == [2, 3, 4, 5, 6]
+
+
+def test_chunk_larger_than_capacity_keeps_the_tail_and_the_count():
+    buffer = RingBuffer(4)
+    buffer.write(ramp(10))
+    assert list(buffer.read_last(4)) == [6, 7, 8, 9]
+    assert buffer.total_written == 10
+    # The write index must still be consistent afterwards.
+    buffer.write(ramp(2, start=10))
+    assert list(buffer.read_last(4)) == [8, 9, 10, 11]
+
+
+def test_empty_write_is_a_noop():
+    buffer = RingBuffer(4)
+    buffer.write(np.zeros(0, dtype=np.float32))
+    assert buffer.total_written == 0
+
+
+def test_rms_of_silence_and_of_a_constant():
+    assert rms(np.zeros(0, dtype=np.float32)) == 0.0
+    assert rms(np.zeros(100, dtype=np.float32)) == 0.0
+    assert rms(np.full(100, 0.5, dtype=np.float32)) == pytest.approx(0.5)
+
+
+def test_normalize_boosts_quiet_audio_towards_the_target():
+    quiet = np.full(100, 0.01, dtype=np.float32)
+    boosted, gain = normalize(quiet, target_rms=0.05, max_gain=20.0)
+    assert gain == pytest.approx(5.0)
+    assert rms(boosted) == pytest.approx(0.05, rel=1e-3)
+
+
+def test_normalize_never_attenuates():
+    loud = np.full(100, 0.5, dtype=np.float32)
+    same, gain = normalize(loud, target_rms=0.05, max_gain=20.0)
+    assert gain == 1.0
+    assert np.array_equal(same, loud)
+
+
+def test_normalize_respects_max_gain_and_clips():
+    very_quiet = np.full(100, 0.001, dtype=np.float32)
+    boosted, gain = normalize(very_quiet, target_rms=0.05, max_gain=20.0)
+    assert gain == 20.0
+    assert boosted.dtype == np.float32
+    assert boosted.max() <= 1.0
+
+
+def test_normalize_leaves_digital_silence_alone():
+    silence = np.zeros(100, dtype=np.float32)
+    same, gain = normalize(silence, target_rms=0.05, max_gain=20.0)
+    assert gain == 1.0
+    assert np.array_equal(same, silence)