sttop 0.1.0__py3-none-any.whl

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

sttop/__main__.py

@@ -0,0 +1,193 @@
+"""Command line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .config import CONFIG_PATH, Config, ConfigError, write_default_config
+from .stt import BACKENDS
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="sttop",
+        description="Live speech-to-text monitor. Taps mic + system audio, "
+        "transcribes and labels speakers in real time, writes Markdown.",
+    )
+    parser.add_argument("--version", action="version", version=f"sttop {__version__}")
+    parser.add_argument("-c", "--config", type=Path, help=f"default: {CONFIG_PATH}")
+
+    # `--config` reads as a global option, so accept it on either side of the
+    # subcommand. SUPPRESS is what makes that work: without it the subcommand's
+    # own default would overwrite a value already given before the subcommand.
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument(
+        "-c", "--config", type=Path, default=argparse.SUPPRESS, help=argparse.SUPPRESS
+    )
+
+    sub = parser.add_subparsers(dest="command")
+
+    def command(name: str, summary: str) -> argparse.ArgumentParser:
+        return sub.add_parser(name, help=summary, parents=[common])
+
+    record = command("record", "start a session (default)")
+    record.add_argument("-t", "--title", help="session title, used in the filename")
+    record.add_argument("--mic", help="mic source name or substring")
+    record.add_argument("--system", help="system/monitor source name or substring")
+    record.add_argument("-m", "--model", help="override the backend's default model")
+    record.add_argument("--backend", choices=list(BACKENDS))
+    record.add_argument(
+        "--language", help="force a language, e.g. es (default: autodetect)"
+    )
+    record.add_argument("--no-diarize", action="store_true", help="skip speaker id")
+    record.add_argument("--save-wav", action="store_true", help="keep the raw audio")
+
+    devices_cmd = command("devices", "list audio sources")
+    devices_cmd.add_argument(
+        "--test", action="store_true", help="record 1s from each and report levels"
+    )
+
+    command("sessions", "list recorded sessions")
+    command("theme", "show the detected terminal colour scheme")
+    command("config", "write a default config file")
+
+    return parser
+
+
+#: Global options that may appear before the subcommand, and whether the option
+#: swallows the token after it.
+_GLOBAL_OPTIONS = {"-c": True, "--config": True, "-h": False, "--help": False,
+                   "--version": False}
+
+
+def with_default_command(argv: list[str], commands: set[str]) -> list[str]:
+    """Insert `record` when no subcommand was given.
+
+    `sttop -t standup` means `sttop record -t standup`. Rather than parse twice
+    and hope the first attempt fails cleanly - it does not, since `-t` is a
+    record option and argparse rejects it outright - the command is filled in
+    before parsing, so there is only ever one well-formed parse.
+    """
+    index = 0
+    while index < len(argv):
+        token = argv[index]
+        if token in commands:
+            return argv
+        option, joined, _ = token.partition("=")
+        if option not in _GLOBAL_OPTIONS:
+            break  # a record option, or a positional - record starts here
+        # Skip the global option, plus its value when given as a separate
+        # token (`-c path`) rather than joined on (`--config=path`).
+        index += 2 if _GLOBAL_OPTIONS[option] and not joined else 1
+    return [*argv[:index], "record", *argv[index:]]
+
+
+def cmd_devices(config: Config, args) -> int:
+    from .audio import capture, devices
+
+    try:
+        sources = devices.list_sources()
+        mic = devices.resolve(config.audio.mic_source, monitor=False)
+        system = devices.resolve(config.audio.system_source, monitor=True)
+    except devices.AudioError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    print(f"mic     -> {mic}")
+    print(f"system  -> {system}\n")
+    for source in sources:
+        role = "mic" if source.name == mic else "sys" if source.name == system else "   "
+        kind = "monitor" if source.is_monitor else "input  "
+        line = f"{role} {kind} {source.state:<10} {source.name}"
+        if args.test:
+            try:
+                peak = capture.check_source(source.name, seconds=1.0)
+                line += f"   peak {peak:.3f}" + ("" if peak > 0.001 else "  (silent)")
+            except Exception as exc:
+                line += f"   [failed: {str(exc).splitlines()[0][:40]}]"
+        print(line)
+    return 0
+
+
+def cmd_theme(config: Config) -> int:
+    from .terminal import detect_theme, theme_sources
+
+    for name, verdict in theme_sources():
+        print(f"{name:<12}{verdict or '<no answer>'}")
+    print(f"configured  {config.ui.theme}")
+    print(f"\nusing       {detect_theme(config.ui.theme)}")
+    return 0
+
+
+def cmd_sessions(config: Config) -> int:
+    from .journal import list_sessions
+
+    directory = Path(config.sessions_dir)
+    paths = list_sessions(directory)
+    if not paths:
+        print(f"no sessions yet in {directory}")
+        return 0
+    for path in paths:
+        size = path.stat().st_size
+        print(f"{path.name:<52} {size / 1024:6.1f} KiB")
+    print(f"\n{len(paths)} session(s) in {directory}")
+    return 0
+
+
+def cmd_record(config: Config, args) -> int:
+    from .tui import SttopApp
+
+    if args.mic:
+        config.audio.mic_source = args.mic
+    if args.system:
+        config.audio.system_source = args.system
+    if args.model:
+        config.stt.model = args.model
+    if args.backend:
+        config.stt.backend = args.backend
+    if args.language:
+        config.stt.language = args.language
+    if args.no_diarize:
+        config.diarize.enabled = False
+    if args.save_wav:
+        config.audio.save_wav = True
+
+    path = SttopApp(config, args.title).run()
+    if path:
+        print(f"transcript: {path}")
+    return 0
+
+
+COMMANDS = {"record", "devices", "sessions", "theme", "config"}
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    parser = build_parser()
+    args = parser.parse_args(with_default_command(argv, COMMANDS))
+
+    if args.command == "config":  # writing a config must not require a valid one
+        path = write_default_config(args.config)
+        print(f"wrote {path}")
+        return 0
+
+    try:
+        config = Config.load(args.config)
+    except ConfigError as exc:
+        print(f"error: bad config: {exc}", file=sys.stderr)
+        return 1
+
+    if args.command == "devices":
+        return cmd_devices(config, args)
+    if args.command == "sessions":
+        return cmd_sessions(config)
+    if args.command == "theme":
+        return cmd_theme(config)
+    return cmd_record(config, args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sttop/audio/__init__.py

@@ -0,0 +1 @@
+"""Audio capture and voice-activity segmentation."""

sttop/audio/capture.py

@@ -0,0 +1,228 @@
+"""Capture a PulseAudio/PipeWire source as 16 kHz mono PCM via ffmpeg.
+
+ffmpeg is used instead of a PortAudio binding because monitor sources (the
+"what you hear" side of the capture) are exposed cleanly by the pulse backend,
+whereas PortAudio device indices for monitors are inconsistent under PipeWire.
+
+Reading is an asyncio task, not a thread: it is blocking I/O on a pipe, which
+is exactly what an event loop handles well, and it makes cancellation and
+shutdown structured rather than hand-rolled from events and joins.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import shutil
+import subprocess
+import wave
+from collections import deque
+from collections.abc import Callable
+from pathlib import Path
+
+import numpy as np
+
+from .. import FRAME_BYTES, SAMPLE_RATE
+from .devices import AudioError
+
+FrameCallback = Callable[[bytes], None]
+ErrorCallback = Callable[[str], None]
+
+#: Keep only the tail of ffmpeg's stderr - all we ever report is the last line,
+#: and an unbounded buffer would grow for the whole session.
+_STDERR_TAIL_LINES = 5
+
+#: `level` is a meter reading, not a measurement: speech sits well below full
+#: scale, so it is gained up to fill the bar, and smoothed asymmetrically -
+#: rising fast, falling slow - so brief peaks stay visible for a frame or two.
+_GAIN = 4.0
+_ATTACK = 0.5
+_RELEASE = 0.15
+
+
+def _ffmpeg_command(pulse_source: str, *extra: str) -> list[str]:
+    """The one true ffmpeg invocation: one pulse source in, 16 kHz mono s16le
+    out on stdout. `extra` is inserted between the input and output options."""
+    return [
+        "ffmpeg",
+        "-hide_banner",
+        "-loglevel", "error",
+        "-nostdin",
+        "-f", "pulse",
+        "-i", pulse_source,
+        *extra,
+        "-ac", "1",
+        "-ar", str(SAMPLE_RATE),
+        "-f", "s16le",
+        "-",
+    ]
+
+
+class SourceCapture:
+    """Streams one audio source, handing fixed-size PCM frames to a callback.
+
+    `on_frame` runs on the event loop, so it must stay cheap - VAD only. Any
+    real work belongs behind the queue the segmenter feeds.
+    """
+
+    def __init__(
+        self,
+        label: str,
+        pulse_source: str,
+        on_frame: FrameCallback,
+        on_error: ErrorCallback | None = None,
+        wav_path: Path | None = None,
+    ) -> None:
+        self.label = label
+        self.pulse_source = pulse_source
+        self._on_frame = on_frame
+        self._on_error = on_error
+        self._wav_path = wav_path
+
+        self._proc: asyncio.subprocess.Process | None = None
+        self._task: asyncio.Task | None = None
+        self._stderr_task: asyncio.Task | None = None
+        self._stderr_tail: deque[str] = deque(maxlen=_STDERR_TAIL_LINES)
+        self._wav: wave.Wave_write | None = None
+        self._stopping = False
+
+        #: Smoothed 0..1 loudness, for the level meters in the TUI.
+        self.level: float = 0.0
+        self.frames_seen: int = 0
+
+    async def start(self) -> None:
+        if not shutil.which("ffmpeg"):
+            raise AudioError("ffmpeg not found on PATH")
+
+        self._proc = await asyncio.create_subprocess_exec(
+            *_ffmpeg_command(self.pulse_source),
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        try:
+            self._open_wav()
+        except Exception:
+            # Half-started is not a state a caller can clean up: whoever gets
+            # the exception has no capture object to stop.
+            await self.stop()
+            raise
+
+        self._task = asyncio.create_task(self._pump(), name=f"capture-{self.label}")
+        self._stderr_task = asyncio.create_task(
+            self._drain_stderr(), name=f"capture-{self.label}-stderr"
+        )
+
+    def _open_wav(self) -> None:
+        if self._wav_path is None:
+            return
+        self._wav_path.parent.mkdir(parents=True, exist_ok=True)
+        self._wav = wave.open(str(self._wav_path), "wb")
+        self._wav.setnchannels(1)
+        self._wav.setsampwidth(2)
+        self._wav.setframerate(SAMPLE_RATE)
+
+    async def _pump(self) -> None:
+        assert self._proc is not None and self._proc.stdout is not None
+        try:
+            while True:
+                frame = await self._proc.stdout.readexactly(FRAME_BYTES)
+                self.frames_seen += 1
+                self._update_level(frame)
+                if self._wav is not None:
+                    self._wav.writeframes(frame)
+                self._on_frame(frame)
+        except asyncio.CancelledError:
+            raise
+        except asyncio.IncompleteReadError:
+            # The pipe closed: either we are stopping, or the source went away.
+            if not self._stopping:
+                self._report_failure()
+        except Exception as exc:
+            # Anything else kills this task, and a dead pump is silent: frames
+            # stop arriving and the meter freezes at its last value, which
+            # reads as a working capture. Say so instead.
+            self._report_failure(f"{type(exc).__name__}: {exc}")
+
+    async def _drain_stderr(self) -> None:
+        """Read stderr continuously. Not only for the message - an unread pipe
+        fills at 64 KiB and would block ffmpeg, stalling capture entirely."""
+        pipe = self._proc.stderr if self._proc is not None else None
+        if pipe is None:
+            return
+        async for raw in pipe:
+            line = raw.decode(errors="replace").strip()
+            if line:
+                self._stderr_tail.append(line)
+
+    def _update_level(self, frame: bytes) -> None:
+        samples = np.frombuffer(frame, dtype=np.int16).astype(np.float32) / 32768.0
+        rms = float(np.sqrt(np.mean(samples * samples)))
+        weight = _ATTACK if rms > self.level else _RELEASE
+        self.level = (1 - weight) * self.level + weight * min(rms * _GAIN, 1.0)
+
+    def _report_failure(self, detail: str | None = None) -> None:
+        # A source that has stopped producing must not keep a live-looking
+        # meter, or the UI contradicts the warning printed right below it.
+        self.level = 0.0
+        if self._on_error is None:
+            return
+        if detail is None:
+            code = self._proc.returncode if self._proc is not None else None
+            detail = (
+                self._stderr_tail[-1] if self._stderr_tail else f"ffmpeg exited {code}"
+            )
+        self._on_error(f"[{self.label}] {detail}")
+
+    async def stop(self) -> None:
+        """Terminate ffmpeg, await the reader tasks, close the WAV. Idempotent.
+
+        Every step runs even if an earlier one failed: teardown that gives up
+        halfway leaves an ffmpeg running and a WAV missing its last seconds,
+        which is worse than whatever raised.
+        """
+        self._stopping = True
+
+        if self._proc is not None and self._proc.returncode is None:
+            with contextlib.suppress(ProcessLookupError):
+                self._proc.terminate()
+
+        for attr in ("_task", "_stderr_task"):
+            task = getattr(self, attr)
+            if task is not None:
+                task.cancel()
+                # The task may already have died of something other than the
+                # cancellation; it was reported when it happened.
+                with contextlib.suppress(asyncio.CancelledError, Exception):
+                    await task
+                setattr(self, attr, None)
+
+        if self._proc is not None:
+            with contextlib.suppress(TimeoutError):
+                await asyncio.wait_for(self._proc.wait(), timeout=3)
+            if self._proc.returncode is None:
+                self._proc.kill()
+                await self._proc.wait()
+            self._proc = None
+
+        if self._wav is not None:
+            with contextlib.suppress(Exception):
+                self._wav.close()
+            self._wav = None
+        self.level = 0.0
+
+
+def check_source(pulse_source: str, seconds: float = 1.0) -> float:
+    """Record briefly and report peak level - used by `sttop devices --test`."""
+    proc = subprocess.run(
+        _ffmpeg_command(pulse_source, "-t", str(seconds)),
+        capture_output=True,
+        timeout=seconds + 10,
+    )
+    if proc.returncode != 0:
+        raise AudioError(
+            proc.stderr.decode(errors="replace").strip() or "capture failed"
+        )
+    if not proc.stdout:
+        return 0.0
+    samples = np.frombuffer(proc.stdout, dtype=np.int16).astype(np.float32) / 32768.0
+    return float(np.max(np.abs(samples))) if samples.size else 0.0

sttop/audio/devices.py

@@ -0,0 +1,90 @@
+"""PulseAudio/PipeWire source discovery via pactl."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from dataclasses import dataclass
+
+
+class AudioError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class Source:
+    index: int
+    name: str
+    driver: str
+    spec: str
+    state: str
+
+    @property
+    def is_monitor(self) -> bool:
+        return self.name.endswith(".monitor")
+
+
+def _pactl(*args: str) -> str:
+    if not shutil.which("pactl"):
+        raise AudioError("pactl not found - sttop needs PipeWire or PulseAudio")
+    try:
+        out = subprocess.run(
+            ["pactl", *args], capture_output=True, text=True, timeout=5, check=True
+        )
+    except subprocess.CalledProcessError as exc:
+        raise AudioError(f"pactl {' '.join(args)} failed: {exc.stderr.strip()}") from exc
+    except subprocess.TimeoutExpired as exc:
+        raise AudioError("pactl timed out - is the audio server running?") from exc
+    return out.stdout.strip()
+
+
+def list_sources() -> list[Source]:
+    sources = []
+    for line in _pactl("list", "short", "sources").splitlines():
+        parts = line.split("\t")
+        if len(parts) < 5 or not parts[0].isdigit():
+            continue  # a header or some other row shape we do not understand
+        index, name, driver, spec, state = parts[:5]
+        sources.append(Source(int(index), name, driver, spec, state))
+    return sources
+
+
+def default_sink_monitor() -> str:
+    """The monitor source carrying whatever is currently playing on this machine."""
+    sink = _pactl("get-default-sink")
+    if not sink or sink == "@DEFAULT_SINK@":
+        raise AudioError("no default sink - cannot capture system audio")
+    return f"{sink}.monitor"
+
+
+def default_source() -> str:
+    """The default recording source, i.e. the active microphone."""
+    source = _pactl("get-default-source")
+    if not source or source == "@DEFAULT_SOURCE@":
+        raise AudioError("no default source - cannot capture the microphone")
+    return source
+
+
+def resolve(requested: str | None, *, monitor: bool) -> str:
+    """Resolve a configured source name, falling back to the sensible default.
+
+    A requested name may be a full source name or a unique substring of one,
+    so you can write `system_source = "hdmi"` instead of the full alsa id.
+
+    Blank means "no preference", the same as unset - otherwise the empty string
+    goes on to match every source and resolution fails as ambiguous, which is a
+    baffling way to punish someone for writing `mic_source = ""`.
+    """
+    if requested is None or not requested.strip():
+        return default_sink_monitor() if monitor else default_source()
+
+    names = [s.name for s in list_sources()]
+    if requested in names:
+        return requested
+
+    matches = [n for n in names if requested in n]
+    if len(matches) == 1:
+        return matches[0]
+    if not matches:
+        raise AudioError(f"no audio source matching {requested!r}")
+    raise AudioError(f"{requested!r} is ambiguous, matches: {', '.join(matches)}")

sttop/audio/segmenter.py

@@ -0,0 +1,170 @@
+"""Turn a continuous PCM frame stream into utterance-sized speech segments."""
+
+from __future__ import annotations
+
+import time
+from collections import deque
+from collections.abc import Callable
+from dataclasses import dataclass
+
+import webrtcvad
+
+from .. import FRAME_MS, SAMPLE_RATE
+from ..config import VadConfig
+
+FRAME_S = FRAME_MS / 1000.0
+
+#: Window the trigger decision is measured over, and the fraction of it that
+#: must be speech before a segment opens. Measured against the *full* window,
+#: not the frames seen so far, so a single stray voiced frame at stream start
+#: cannot trigger. Kept separate from `pad_ms`: how much audio to keep from
+#: before speech onset is a question about clipped syllables, while this is a
+#: question about sensitivity, and tuning one must not silently move the other.
+TRIGGER_WINDOW_MS = 300
+TRIGGER_RATIO = 0.6
+
+
+@dataclass(frozen=True)
+class Segment:
+    """A contiguous run of speech from one source."""
+
+    source: str
+    pcm: bytes
+    start: float  # seconds since session start
+    end: float
+
+    @property
+    def duration(self) -> float:
+        return self.end - self.start
+
+
+class Segmenter:
+    """Voice-activity state machine over 20 ms frames.
+
+    Collects frames while speech is present, and emits a Segment once the
+    speaker has been quiet for `silence_ms` (or the segment hits its ceiling).
+    A rolling pre-roll buffer is prepended so the first syllable isn't clipped.
+    """
+
+    def __init__(
+        self,
+        source: str,
+        config: VadConfig,
+        on_segment: Callable[[Segment], None],
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self.source = source
+        self._on_segment = on_segment
+        self._clock = clock
+
+        self._vad = webrtcvad.Vad(config.aggressiveness)
+        self._pad_frames = max(1, config.pad_ms // FRAME_MS)
+        self._silence_frames = max(1, config.silence_ms // FRAME_MS)
+        self._max_frames = max(1, int(config.max_segment_s / FRAME_S))
+        self._min_frames = max(1, config.min_segment_ms // FRAME_MS)
+
+        self._trigger_frames = max(1, TRIGGER_WINDOW_MS // FRAME_MS)
+        self._preroll: deque[bytes] = deque(maxlen=self._pad_frames)
+        self._voiced: deque[bool] = deque(maxlen=self._trigger_frames)
+        self._buffer: list[bytes] = []
+        self._triggered = False
+        self._silence_run = 0
+        self._segment_start_index = 0
+        self._voiced_count = 0  # speech frames in the open segment
+
+        self._index = 0  # frames consumed since the stream opened
+        self._origin: float | None = None  # session time of frame 0
+        self._paused = False
+
+    @property
+    def paused(self) -> bool:
+        return self._paused
+
+    @paused.setter
+    def paused(self, value: bool) -> None:
+        """Pausing closes any open utterance, so resuming never splices audio
+        from either side of the gap into a single segment."""
+        if value and not self._paused:
+            self.close()
+        self._paused = value
+
+    def feed(self, frame: bytes) -> None:
+        if self._origin is None:
+            self._origin = self._clock()
+        index = self._index
+        self._index += 1
+
+        if self._paused:
+            return
+
+        speech = self._vad.is_speech(frame, SAMPLE_RATE)
+
+        if not self._triggered:
+            self._preroll.append(frame)
+            self._voiced.append(speech)
+            # Enough of the recent window is speech - open a segment.
+            if sum(self._voiced) >= TRIGGER_RATIO * self._trigger_frames:
+                self._triggered = True
+                self._segment_start_index = index - len(self._preroll) + 1
+                self._buffer = list(self._preroll)
+                self._voiced_count = sum(self._voiced)
+                self._silence_run = 0
+                self._preroll.clear()
+                self._voiced.clear()
+            return
+
+        self._buffer.append(frame)
+        self._voiced_count += speech
+        self._silence_run = 0 if speech else self._silence_run + 1
+
+        if self._silence_run >= self._silence_frames:
+            self._flush(trailing_silence=self._silence_run)
+        elif len(self._buffer) >= self._max_frames:
+            # Carry the silence run across the split: the speaker may already
+            # be most of the way to a pause, and restarting the count would
+            # hold the next segment open for a further full silence_ms.
+            carried = self._silence_run
+            self._flush(trailing_silence=0)
+            # Long monologue: stay open so the next chunk continues immediately.
+            self._triggered = True
+            self._segment_start_index = index + 1
+            self._buffer = []
+            self._voiced_count = 0
+            self._silence_run = carried
+
+    def _flush(self, trailing_silence: int) -> None:
+        frames = self._buffer
+        # Drop the silence we used as an end-of-utterance signal, keeping one
+        # frame so the last word has a little air after it.
+        if trailing_silence:
+            keep = max(0, len(frames) - trailing_silence + 1)
+            frames = frames[:keep]
+
+        voiced_count = self._voiced_count
+        self._triggered = False
+        self._buffer = []
+        self._voiced_count = 0
+        self._silence_run = 0
+        self._preroll.clear()
+        self._voiced.clear()
+
+        # Measure against actual speech, not padded length - otherwise the
+        # pre-roll alone can push a blip over the minimum.
+        if voiced_count < self._min_frames:
+            return
+
+        origin = self._origin or 0.0
+        start = origin + self._segment_start_index * FRAME_S
+        self._on_segment(
+            Segment(
+                source=self.source,
+                pcm=b"".join(frames),
+                start=start,
+                end=start + len(frames) * FRAME_S,
+            )
+        )
+
+    def close(self) -> None:
+        """Emit whatever is still buffered - call when the stream ends."""
+        if self._triggered and self._buffer:
+            self._flush(trailing_silence=0)