sttop 0.1.0__tar.gz

sttop-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: ci
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: sudo apt-get update && sudo apt-get install -y ffmpeg
+      - run: uv sync --extra dev
+      # The audio-hardware tests stay opt-in; CI has no sound server.
+      - run: uv run --extra dev pytest -q
+      - run: uv run ruff check .

sttop-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,32 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    # Trusted publishing: PyPI verifies this workflow's identity, no token needed.
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

sttop-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+sessions/
+*.wav
+dist/

sttop-0.1.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: sttop
+Version: 0.1.0
+Summary: Live speech-to-text monitor for the terminal. Taps mic + system audio, transcribes and labels speakers in real time, stores everything locally.
+Project-URL: Homepage, https://github.com/v4rgas/sttop
+Project-URL: Repository, https://github.com/v4rgas/sttop
+Project-URL: Issues, https://github.com/v4rgas/sttop/issues
+Author: v4rgas
+License: MIT
+Keywords: diarization,speech-to-text,terminal,transcription,tui,whisper
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+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 :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: faster-whisper>=1.0.3
+Requires-Dist: numpy>=1.24
+Requires-Dist: onnx-asr[cpu,hub]>=0.12
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: speechbrain>=1.0
+Requires-Dist: textual>=0.80
+Requires-Dist: torch>=2.2
+Requires-Dist: torchaudio>=2.2
+Requires-Dist: webrtcvad-wheels>=2.0.14
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sttop
+
+Live speech-to-text monitor for the terminal — `htop`, but for what is being said.
+
+Taps your **microphone** and your **system audio output** as two independent streams,
+transcribes both in real time, labels who is speaking, and appends every line to a
+Markdown file as it happens. Fully local: no network, no API keys, nothing leaves
+the machine.
+
+```
+ sttop  ● rec 04:12   mic ███·······  sys ██████····   parakeet-tdt/cpu onnx · ecapa @0.50 · queue 0 · 37 lines · 3 voices
+ writing → ~/.local/share/sttop/sessions/2026-08-10-1432-standup.md
+
+ 03:58  you    so the migration lands friday?
+ 04:02  spk1   friday is tight, monday is safer
+ 04:09  spk2   +1 on monday
+
+ q quit   space pause   r rename speaker
+```
+
+## Why two streams
+
+Capturing the mic and the speaker output separately means **you** are identified for
+free — anything on the mic is you, no model required, never wrong. Voice embeddings
+then only have to split the *remote* side into individual participants, which is a
+much easier problem than diarizing a single mixed track.
+
+## Install
+
+Needs `ffmpeg` and PipeWire or PulseAudio (`pactl`).
+
+```bash
+uvx --index https://download.pytorch.org/whl/cpu sttop
+```
+
+The `--index` flag matters. Speaker labelling needs torch, and the stock PyPI torch
+bundles CUDA — about 2.5GB of nvidia wheels that buy nothing here, since
+CTranslate2 has no ROCm backend and CPU inference keeps up with live audio fine.
+The flag points torch at the CPU builds and falls back to PyPI for everything else.
+
+To install it permanently rather than running it ad hoc:
+
+```bash
+uv tool install --index https://download.pytorch.org/whl/cpu sttop
+```
+
+From a checkout, `uv sync` reads the CPU index out of `pyproject.toml` already:
+
+```bash
+git clone https://github.com/v4rgas/sttop && cd sttop
+uv sync
+```
+
+## Use
+
+```bash
+uv run sttop                       # record with defaults
+uv run sttop -t "standup"          # title the session (used in the filename)
+uv run sttop --backend whisper -m small
+uv run sttop devices --test        # list audio sources, record 1s from each
+uv run sttop sessions              # list past transcripts
+uv run sttop config                # write ~/.config/sttop/config.toml
+uv run sttop theme                 # show the detected terminal colour scheme
+```
+
+Keys: `q` quit · `space` pause · `r` rename a speaker (`spk1=Ana`, rewrites past lines too).
+
+## Output
+
+One Markdown file per session in `~/.local/share/sttop/sessions/`, flushed after every
+line — kill it mid-meeting and the transcript so far is already on disk.
+
+```markdown
+# standup
+
+- started: 2026-08-10 14:32:01 -04
+- mic: `alsa_input.pci-0000_08_00.6.analog-stereo`
+- system: `alsa_output.pci-0000_08_00.6.analog-stereo.monitor`
+- backend: `parakeet-tdt/cpu onnx`
+
+## Transcript
+
+- `03:58` **you** — so the migration lands friday?
+
+- `04:02` **spk1** — friday is tight, monday is safer
+```
+
+## How it works
+
+```
+ffmpeg -f pulse (mic)      ─┐
+                            ├─ webrtcvad segmenter ─→ queue ─→ parakeet ─→ ecapa ─→ journal.md
+ffmpeg -f pulse (monitor)  ─┘
+```
+
+Audio is cut into utterances by voice-activity detection (a segment closes after
+700 ms of silence, or at 15 s for a monologue), and only speech reaches the model.
+
+**One thread boundary, and it is the model.** The two capture readers and the
+consumer are asyncio tasks — they are blocking pipe I/O, which is what an event
+loop is for — while transcription and voice embedding run in a single-worker
+`ThreadPoolExecutor`. So the UI needs no cross-thread marshalling, shutdown is
+ordinary task cancellation, and utterances stay in the order they were spoken. The
+executor is single-worker on purpose: transcription is CPU-bound and already
+internally parallel, so a second worker would only thrash the cache. When it falls
+behind, the queue absorbs the lag — visible as `queue N` in the status bar — rather
+than dropping audio.
+
+Speaker labels come from online clustering of ECAPA-TDNN voice embeddings: each
+utterance is matched against running centroids by cosine similarity. A confident
+match (≥ `threshold`) joins that speaker and updates its centroid; a near miss
+(within `margin` below it) joins without touching the centroid; only a clearly
+distant voice opens a new speaker. That hysteresis matters — without it a single
+noisy embedding mints a phantom participant, and one person ends up spread across
+`spk1`/`spk2`/`spk3`. Being online means labels are assigned as audio arrives and are
+never revised, which is the price of real time. Segments under 1.5 s are too short to
+embed reliably and inherit the previous speaker, or show as `spk?`.
+
+## Backends
+
+**parakeet** (default) — NVIDIA Parakeet TDT 0.6b v3 through onnxruntime. Multilingual
+across 25 European languages with autodetection, punctuated output, and roughly 19×
+real time on CPU. Needs neither torch nor the NeMo toolkit, since onnx-asr runs the
+exported graph directly. On the same 11 s clip where `whisper tiny` produced a
+hallucinated lead-in and lost its punctuation, Parakeet returned the sentence verbatim.
+
+**whisper** — faster-whisper/CTranslate2, if you want Whisper's language coverage.
+CTranslate2 ships **CUDA and CPU backends only — there is no ROCm build**, so on an AMD
+GPU this runs on CPU no matter what torch reports. The device is detected at startup
+(`cuda` if CTranslate2 sees one, else `cpu`) and shown in the status bar.
+
+To push a Radeon card at the *diarization* half, resync torch against the ROCm index
+(see the comment in `pyproject.toml`).
+
+## Config
+
+`~/.config/sttop/config.toml`. Run `sttop config` to write a default with every
+knob and its documentation in it; the comments come from the source, so the file
+never drifts from the code. Anything you leave out keeps its default, and blank
+means "you decide" wherever a default is picked for you.
+
+```toml
+sessions_dir = "~/.local/share/sttop/sessions"
+
+[audio]
+mic_source = ""        # substring match against pactl source names; blank = default
+system_source = ""     # blank = monitor of the default sink
+save_wav = false
+
+[vad]
+aggressiveness = 2     # 0 permissive .. 3 strict
+silence_ms = 700
+max_segment_s = 15.0
+
+[stt]
+backend = "parakeet"   # parakeet | whisper
+model = ""             # blank = the backend's default model
+device = "auto"        # whisper only
+language = ""          # blank = autodetect
+
+[ui]
+theme = "auto"         # auto follows your terminal; or gruvbox, nord, ...
+
+[diarize]
+enabled = true
+threshold = 0.50       # lower = fewer, broader speakers
+margin = 0.15          # grey zone that attaches instead of opening a speaker
+```
+
+## Theming
+
+By default sttop paints with the `ansi-dark` / `ansi-light` Textual themes, which
+use only the terminal's own 16 ANSI colours — so it inherits whatever palette you
+already have rather than imposing its own. Which of the two is picked by reading
+`COLORFGBG`, and failing that by asking the terminal for its background colour over
+OSC 11 (supported by ghostty, kitty, alacritty, wezterm, foot, xterm). If nothing
+answers, it assumes dark. Run `sttop theme` to see what was detected.
+
+Set `ui.theme` to any Textual theme name (`gruvbox`, `nord`, `catppuccin-mocha`,
+`solarized-light`, …) to override the terminal-following behaviour.
+
+## Tests
+
+```bash
+uv run --extra dev pytest
+```
+
+The audio-dependent path is exercised by `tests/test_pipeline.py`, which plays a speech
+sample into the default sink and reads it back off the monitor. It needs real audio
+hardware and downloads a model, so it is opt-in:
+
+```bash
+STTOP_INTEGRATION=1 uv run --extra dev pytest
+```
+
+## License
+
+MIT

sttop-0.1.0/README.md

@@ -0,0 +1,198 @@
+# sttop
+
+Live speech-to-text monitor for the terminal — `htop`, but for what is being said.
+
+Taps your **microphone** and your **system audio output** as two independent streams,
+transcribes both in real time, labels who is speaking, and appends every line to a
+Markdown file as it happens. Fully local: no network, no API keys, nothing leaves
+the machine.
+
+```
+ sttop  ● rec 04:12   mic ███·······  sys ██████····   parakeet-tdt/cpu onnx · ecapa @0.50 · queue 0 · 37 lines · 3 voices
+ writing → ~/.local/share/sttop/sessions/2026-08-10-1432-standup.md
+
+ 03:58  you    so the migration lands friday?
+ 04:02  spk1   friday is tight, monday is safer
+ 04:09  spk2   +1 on monday
+
+ q quit   space pause   r rename speaker
+```
+
+## Why two streams
+
+Capturing the mic and the speaker output separately means **you** are identified for
+free — anything on the mic is you, no model required, never wrong. Voice embeddings
+then only have to split the *remote* side into individual participants, which is a
+much easier problem than diarizing a single mixed track.
+
+## Install
+
+Needs `ffmpeg` and PipeWire or PulseAudio (`pactl`).
+
+```bash
+uvx --index https://download.pytorch.org/whl/cpu sttop
+```
+
+The `--index` flag matters. Speaker labelling needs torch, and the stock PyPI torch
+bundles CUDA — about 2.5GB of nvidia wheels that buy nothing here, since
+CTranslate2 has no ROCm backend and CPU inference keeps up with live audio fine.
+The flag points torch at the CPU builds and falls back to PyPI for everything else.
+
+To install it permanently rather than running it ad hoc:
+
+```bash
+uv tool install --index https://download.pytorch.org/whl/cpu sttop
+```
+
+From a checkout, `uv sync` reads the CPU index out of `pyproject.toml` already:
+
+```bash
+git clone https://github.com/v4rgas/sttop && cd sttop
+uv sync
+```
+
+## Use
+
+```bash
+uv run sttop                       # record with defaults
+uv run sttop -t "standup"          # title the session (used in the filename)
+uv run sttop --backend whisper -m small
+uv run sttop devices --test        # list audio sources, record 1s from each
+uv run sttop sessions              # list past transcripts
+uv run sttop config                # write ~/.config/sttop/config.toml
+uv run sttop theme                 # show the detected terminal colour scheme
+```
+
+Keys: `q` quit · `space` pause · `r` rename a speaker (`spk1=Ana`, rewrites past lines too).
+
+## Output
+
+One Markdown file per session in `~/.local/share/sttop/sessions/`, flushed after every
+line — kill it mid-meeting and the transcript so far is already on disk.
+
+```markdown
+# standup
+
+- started: 2026-08-10 14:32:01 -04
+- mic: `alsa_input.pci-0000_08_00.6.analog-stereo`
+- system: `alsa_output.pci-0000_08_00.6.analog-stereo.monitor`
+- backend: `parakeet-tdt/cpu onnx`
+
+## Transcript
+
+- `03:58` **you** — so the migration lands friday?
+
+- `04:02` **spk1** — friday is tight, monday is safer
+```
+
+## How it works
+
+```
+ffmpeg -f pulse (mic)      ─┐
+                            ├─ webrtcvad segmenter ─→ queue ─→ parakeet ─→ ecapa ─→ journal.md
+ffmpeg -f pulse (monitor)  ─┘
+```
+
+Audio is cut into utterances by voice-activity detection (a segment closes after
+700 ms of silence, or at 15 s for a monologue), and only speech reaches the model.
+
+**One thread boundary, and it is the model.** The two capture readers and the
+consumer are asyncio tasks — they are blocking pipe I/O, which is what an event
+loop is for — while transcription and voice embedding run in a single-worker
+`ThreadPoolExecutor`. So the UI needs no cross-thread marshalling, shutdown is
+ordinary task cancellation, and utterances stay in the order they were spoken. The
+executor is single-worker on purpose: transcription is CPU-bound and already
+internally parallel, so a second worker would only thrash the cache. When it falls
+behind, the queue absorbs the lag — visible as `queue N` in the status bar — rather
+than dropping audio.
+
+Speaker labels come from online clustering of ECAPA-TDNN voice embeddings: each
+utterance is matched against running centroids by cosine similarity. A confident
+match (≥ `threshold`) joins that speaker and updates its centroid; a near miss
+(within `margin` below it) joins without touching the centroid; only a clearly
+distant voice opens a new speaker. That hysteresis matters — without it a single
+noisy embedding mints a phantom participant, and one person ends up spread across
+`spk1`/`spk2`/`spk3`. Being online means labels are assigned as audio arrives and are
+never revised, which is the price of real time. Segments under 1.5 s are too short to
+embed reliably and inherit the previous speaker, or show as `spk?`.
+
+## Backends
+
+**parakeet** (default) — NVIDIA Parakeet TDT 0.6b v3 through onnxruntime. Multilingual
+across 25 European languages with autodetection, punctuated output, and roughly 19×
+real time on CPU. Needs neither torch nor the NeMo toolkit, since onnx-asr runs the
+exported graph directly. On the same 11 s clip where `whisper tiny` produced a
+hallucinated lead-in and lost its punctuation, Parakeet returned the sentence verbatim.
+
+**whisper** — faster-whisper/CTranslate2, if you want Whisper's language coverage.
+CTranslate2 ships **CUDA and CPU backends only — there is no ROCm build**, so on an AMD
+GPU this runs on CPU no matter what torch reports. The device is detected at startup
+(`cuda` if CTranslate2 sees one, else `cpu`) and shown in the status bar.
+
+To push a Radeon card at the *diarization* half, resync torch against the ROCm index
+(see the comment in `pyproject.toml`).
+
+## Config
+
+`~/.config/sttop/config.toml`. Run `sttop config` to write a default with every
+knob and its documentation in it; the comments come from the source, so the file
+never drifts from the code. Anything you leave out keeps its default, and blank
+means "you decide" wherever a default is picked for you.
+
+```toml
+sessions_dir = "~/.local/share/sttop/sessions"
+
+[audio]
+mic_source = ""        # substring match against pactl source names; blank = default
+system_source = ""     # blank = monitor of the default sink
+save_wav = false
+
+[vad]
+aggressiveness = 2     # 0 permissive .. 3 strict
+silence_ms = 700
+max_segment_s = 15.0
+
+[stt]
+backend = "parakeet"   # parakeet | whisper
+model = ""             # blank = the backend's default model
+device = "auto"        # whisper only
+language = ""          # blank = autodetect
+
+[ui]
+theme = "auto"         # auto follows your terminal; or gruvbox, nord, ...
+
+[diarize]
+enabled = true
+threshold = 0.50       # lower = fewer, broader speakers
+margin = 0.15          # grey zone that attaches instead of opening a speaker
+```
+
+## Theming
+
+By default sttop paints with the `ansi-dark` / `ansi-light` Textual themes, which
+use only the terminal's own 16 ANSI colours — so it inherits whatever palette you
+already have rather than imposing its own. Which of the two is picked by reading
+`COLORFGBG`, and failing that by asking the terminal for its background colour over
+OSC 11 (supported by ghostty, kitty, alacritty, wezterm, foot, xterm). If nothing
+answers, it assumes dark. Run `sttop theme` to see what was detected.
+
+Set `ui.theme` to any Textual theme name (`gruvbox`, `nord`, `catppuccin-mocha`,
+`solarized-light`, …) to override the terminal-following behaviour.
+
+## Tests
+
+```bash
+uv run --extra dev pytest
+```
+
+The audio-dependent path is exercised by `tests/test_pipeline.py`, which plays a speech
+sample into the default sink and reads it back off the monitor. It needs real audio
+hardware and downloads a model, so it is opt-in:
+
+```bash
+STTOP_INTEGRATION=1 uv run --extra dev pytest
+```
+
+## License
+
+MIT

sttop-0.1.0/pyproject.toml

@@ -0,0 +1,82 @@
+[project]
+name = "sttop"
+version = "0.1.0"
+description = "Live speech-to-text monitor for the terminal. Taps mic + system audio, transcribes and labels speakers in real time, stores everything locally."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "v4rgas" }]
+keywords = ["speech-to-text", "transcription", "whisper", "diarization", "tui", "terminal"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "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 :: Utilities",
+]
+dependencies = [
+    "textual>=0.80",
+    "numpy>=1.24",
+    "faster-whisper>=1.0.3",
+    "webrtcvad-wheels>=2.0.14",
+    "platformdirs>=4.0",
+    "onnx-asr[cpu,hub]>=0.12",
+    # Speaker identification. Pulls torch, but the CPU wheels keep it manageable
+    # and a transcript without speaker labels is not worth much.
+    "torch>=2.2",
+    "torchaudio>=2.2",
+    "speechbrain>=1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.6",
+]
+
+[project.scripts]
+sttop = "sttop.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/v4rgas/sttop"
+Repository = "https://github.com/v4rgas/sttop"
+Issues = "https://github.com/v4rgas/sttop/issues"
+
+# Default torch to the CPU wheels. The stock PyPI torch bundles CUDA (~2.5GB) and
+# CTranslate2 (faster-whisper) has no ROCm backend anyway, so a GPU build buys
+# nothing here. To use an AMD GPU for diarization, resync against
+# https://download.pytorch.org/whl/rocm6.2 instead.
+[[tool.uv.index]]
+name = "pytorch-cpu"
+url = "https://download.pytorch.org/whl/cpu"
+explicit = true
+
+[tool.uv.sources]
+torch = { index = "pytorch-cpu" }
+torchaudio = { index = "pytorch-cpu" }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["sttop"]
+
+[tool.ruff]
+line-length = 90
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+# The wav and journal handles stay open for the length of a session by design,
+# so a context manager cannot express their lifetime.
+ignore = ["SIM115"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

sttop-0.1.0/sttop/__init__.py

@@ -0,0 +1,8 @@
+"""sttop - live speech-to-text monitor for the terminal."""
+
+__version__ = "0.1.0"
+
+SAMPLE_RATE = 16_000
+FRAME_MS = 20
+FRAME_SAMPLES = SAMPLE_RATE * FRAME_MS // 1000  # 320 samples
+FRAME_BYTES = FRAME_SAMPLES * 2  # int16 mono