stt2desktop 0.0.1__py3-none-any.whl

stt2desktop/__init__.py

@@ -0,0 +1,8 @@
+"""
+stt2desktop
+local STT for KDE using faster-whisper
+"""
+
+# See https://packaging.python.org/en/latest/specifications/version-specifiers/
+__version__ = '0.0.1'
+__author__ = 'Jens Diemer <stt2desktop@jensdiemer.de>'

stt2desktop/__main__.py

@@ -0,0 +1,10 @@
+"""
+Allow stt2desktop to be executable
+through `python -m stt2desktop`.
+"""
+
+from stt2desktop.cli_app import main
+
+
+if __name__ == '__main__':
+    main()

stt2desktop/cli_app/__init__.py

@@ -0,0 +1,41 @@
+"""
+CLI for usage
+"""
+
+import logging
+import sys
+from collections.abc import Sequence
+
+from cli_base.autodiscover import import_all_files
+from cli_base.cli_tools.version_info import print_version
+from rich import print  # noqa
+from tyro.extras import SubcommandApp
+
+import stt2desktop
+from stt2desktop import constants
+
+
+logger = logging.getLogger(__name__)
+
+app = SubcommandApp()
+
+# Register all CLI commands, just by import all files in this package:
+import_all_files(package=__package__, init_file=__file__)
+
+
+@app.command
+def version():
+    """Print version and exit"""
+    # Pseudo command, because the version always printed on every CLI call ;)
+    sys.exit(0)
+
+
+def main(args: Sequence[str] | None = None):
+    print_version(stt2desktop)
+    app.cli(
+        prog='./cli.py',
+        description=constants.CLI_EPILOG,
+        use_underscores=False,  # use hyphens instead of underscores
+        sort_subcommands=True,
+        args=args,
+    )

stt2desktop/cli_app/listen.py

@@ -0,0 +1,85 @@
+import logging
+from typing import Annotated
+
+import tyro
+from cli_base.cli_tools.verbosity import setup_logging
+from cli_base.tyro_commands import TyroVerbosityArgType
+from pynput import keyboard
+from rich import print
+
+from stt2desktop.cli_app import app
+from stt2desktop.constants import (
+    DEFAULT_HOTKEY,
+    DEFAULT_SAMPLE_RATE,
+    DEFAULT_WHISPER_COMPUTE_TYPE,
+    DEFAULT_WHISPER_DEVICE,
+    DEFAULT_WHISPER_MODEL,
+    DEFAULT_WHISPER_NUM_WORKERS,
+    IS_WAYLAND,
+    WhisperModel,
+)
+from stt2desktop.get_bin import get_wtype_bin, get_xdotool_bin
+from stt2desktop.stt import Recorder, load_whisper_model
+
+
+logger = logging.getLogger(__name__)
+
+
+@app.command
+def listen(
+    verbosity: TyroVerbosityArgType,
+    model: Annotated[
+        WhisperModel, tyro.conf.arg(help='Whisper model to use for transcription.')
+    ] = DEFAULT_WHISPER_MODEL,
+    hotkey: Annotated[
+        keyboard.Key,
+        tyro.conf.arg(help='Key to hold for recording. Release to transcribe and insert text.'),
+    ] = DEFAULT_HOTKEY,
+    sample_rate: Annotated[
+        int, tyro.conf.arg(help='Audio sample rate in Hz. Whisper expects 16000.')
+    ] = DEFAULT_SAMPLE_RATE,
+    device: Annotated[
+        str, tyro.conf.arg(help='Device to run inference on, e.g. cpu or cuda.')
+    ] = DEFAULT_WHISPER_DEVICE,
+    compute_type: Annotated[
+        str, tyro.conf.arg(help='Quantization type, e.g. int8, float16, float32.')
+    ] = DEFAULT_WHISPER_COMPUTE_TYPE,
+    num_workers: Annotated[
+        int,
+        tyro.conf.arg(help='Number of parallel transcription workers. Defaults to CPU count.'),
+    ] = DEFAULT_WHISPER_NUM_WORKERS,
+):
+    """Start the STT listener. Hold the hotkey to record, release to transcribe and insert."""
+    setup_logging(verbosity=verbosity)
+
+    # Before start, check if needed binaries are available:
+    if IS_WAYLAND:
+        get_wtype_bin()
+    else:
+        get_xdotool_bin()
+
+    model = load_whisper_model(
+        model_size=model,
+        device=device,
+        compute_type=compute_type,
+        num_workers=num_workers,
+    )
+    recorder = Recorder(model=model, sample_rate=sample_rate)
+
+    def on_press(key):
+        if key == hotkey:
+            recorder.start()
+
+    def on_release(key):
+        if key == hotkey:
+            recorder.stop()
+
+    print(f'Ready. Hold [bold]{hotkey.name}[/bold] to record, release to transcribe.')
+    print('Press Ctrl+C to exit.')
+    try:
+        with keyboard.Listener(on_press=on_press, on_release=on_release) as listener:
+            listener.join()
+    except KeyboardInterrupt:
+        print('\nExiting...')
+    finally:
+        recorder.stop()

stt2desktop/cli_dev/__init__.py

@@ -0,0 +1,70 @@
+"""
+CLI for development
+"""
+
+import importlib
+import logging
+import sys
+from collections.abc import Sequence
+
+from bx_py_utils.path import assert_is_file
+from cli_base.autodiscover import import_all_files
+from cli_base.cli_tools.dev_tools import run_coverage, run_nox, run_unittest_cli
+from cli_base.cli_tools.version_info import print_version
+from typeguard import install_import_hook
+from tyro.extras import SubcommandApp
+
+import stt2desktop
+from stt2desktop import constants
+
+
+# Check type annotations via typeguard in all tests.
+# Sadly we must activate this here and can't do this in ./tests/__init__.py
+install_import_hook(packages=('stt2desktop',))
+
+# reload the module, after the typeguard import hook is activated:
+importlib.reload(stt2desktop)
+
+
+logger = logging.getLogger(__name__)
+
+
+PACKAGE_ROOT = constants.BASE_PATH.parent
+assert_is_file(PACKAGE_ROOT / 'pyproject.toml')  # Exists only in cloned git repo
+
+
+app = SubcommandApp()
+
+
+# Register all CLI commands, just by import all files in this package:
+import_all_files(package=__package__, init_file=__file__)
+
+
+@app.command
+def version():
+    """Print version and exit"""
+    # Pseudo command, because the version always printed on every CLI call ;)
+    sys.exit(0)
+
+
+def main(args: Sequence[str] | None = None):
+    print_version(stt2desktop)
+
+    if len(sys.argv) >= 2:
+        # Check if we can just pass a command call to origin CLI:
+        command = sys.argv[1]
+        command_map = {
+            'test': run_unittest_cli,
+            'nox': run_nox,
+            'coverage': run_coverage,
+        }
+        if real_func := command_map.get(command):
+            real_func(argv=sys.argv, exit_after_run=True)
+
+    app.cli(
+        prog='./dev-cli.py',
+        description=constants.CLI_EPILOG,
+        use_underscores=False,  # use hyphens instead of underscores
+        sort_subcommands=True,
+        args=args,
+    )

stt2desktop/cli_dev/__main__.py

@@ -0,0 +1,10 @@
+"""
+Allow stt2desktop to be executable
+through `python -m stt2desktop.cli_dev`.
+"""
+
+from stt2desktop.cli_dev import main
+
+
+if __name__ == '__main__':
+    main()

stt2desktop/cli_dev/code_style.py

@@ -0,0 +1,12 @@
+from cli_base.cli_tools.code_style import assert_code_style
+from cli_base.tyro_commands import TyroVerbosityArgType
+
+from stt2desktop.cli_dev import PACKAGE_ROOT, app
+
+
+@app.command
+def lint(verbosity: TyroVerbosityArgType = 1):
+    """
+    Check/fix code style by run: "ruff check --fix"
+    """
+    assert_code_style(package_root=PACKAGE_ROOT, verbose=bool(verbosity), sys_exit=True)

stt2desktop/cli_dev/packaging.py

@@ -0,0 +1,62 @@
+import logging
+
+from cli_base.cli_tools.dev_tools import run_unittest_cli
+from cli_base.cli_tools.subprocess_utils import ToolsExecutor
+from cli_base.cli_tools.verbosity import setup_logging
+from cli_base.run_pip_audit import run_pip_audit
+from cli_base.tyro_commands import TyroVerbosityArgType
+from manageprojects.utilities.publish import publish_package
+
+import stt2desktop
+from stt2desktop.cli_dev import PACKAGE_ROOT, app
+
+
+logger = logging.getLogger(__name__)
+
+
+@app.command
+def install():
+    """
+    Install requirements and 'stt2desktop' via pip as editable.
+    """
+    tools_executor = ToolsExecutor(cwd=PACKAGE_ROOT)
+    tools_executor.verbose_check_call('uv', 'sync')
+    tools_executor.verbose_check_call('uv', 'pip', 'install', '--no-deps', '-e', '.')
+
+
+@app.command
+def pip_audit(verbosity: TyroVerbosityArgType):
+    """
+    Run pip-audit check against current requirements files
+    """
+    setup_logging(verbosity=verbosity)
+    run_pip_audit(base_path=PACKAGE_ROOT, verbosity=verbosity)
+
+
+@app.command
+def update(verbosity: TyroVerbosityArgType):
+    """
+    Update dependencies (uv.lock) and git pre-commit hooks
+    """
+    setup_logging(verbosity=verbosity)
+
+    tools_executor = ToolsExecutor(cwd=PACKAGE_ROOT)
+    tools_executor.verbose_check_call('uv', 'lock', '--upgrade')
+
+    run_pip_audit(base_path=PACKAGE_ROOT, verbosity=verbosity)
+
+    # Install new dependencies in current .venv:
+    tools_executor.verbose_check_call('uv', 'sync')
+
+    # Update git pre-commit hooks:
+    tools_executor.verbose_check_call('pre-commit', 'autoupdate')
+
+
+@app.command
+def publish():
+    """
+    Build and upload this project to PyPi
+    """
+    run_unittest_cli(verbose=False, exit_after_run=False)  # Don't publish a broken state
+
+    publish_package(module=stt2desktop, package_path=PACKAGE_ROOT)

stt2desktop/cli_dev/testing.py

@@ -0,0 +1,52 @@
+from cli_base.cli_tools.dev_tools import run_coverage, run_nox, run_unittest_cli
+from cli_base.cli_tools.subprocess_utils import verbose_check_call
+from cli_base.cli_tools.test_utils.snapshot import UpdateTestSnapshotFiles
+from cli_base.tyro_commands import TyroVerbosityArgType
+
+from stt2desktop.cli_dev import PACKAGE_ROOT, app
+
+
+@app.command
+def mypy(verbosity: TyroVerbosityArgType):
+    """Run Mypy (configured in pyproject.toml)"""
+    verbose_check_call('mypy', '.', cwd=PACKAGE_ROOT, verbose=verbosity > 0, exit_on_error=True)
+
+
+@app.command
+def update_test_snapshot_files(verbosity: TyroVerbosityArgType):
+    """
+    Update all test snapshot files (by remove and recreate all snapshot files)
+    """
+    with UpdateTestSnapshotFiles(root_path=PACKAGE_ROOT, verbose=verbosity > 0):
+        # Just recreate them by running tests:
+        run_unittest_cli(
+            extra_env={
+                'RAISE_SNAPSHOT_ERRORS': '0',  # Recreate snapshot files without error
+            },
+            verbose=verbosity > 1,
+            exit_after_run=False,
+        )
+
+
+@app.command  # Dummy command
+def test():
+    """
+    Run unittests
+    """
+    run_unittest_cli()
+
+
+@app.command  # Dummy command
+def coverage():
+    """
+    Run tests and show coverage report.
+    """
+    run_coverage()
+
+
+@app.command  # Dummy "nox" command
+def nox():
+    """
+    Run nox
+    """
+    run_nox()

stt2desktop/cli_dev/update_readme_history.py

@@ -0,0 +1,33 @@
+import logging
+import sys
+from pathlib import Path
+
+from cli_base.cli_tools import git_history
+from cli_base.cli_tools.verbosity import setup_logging
+from cli_base.tyro_commands import TyroVerbosityArgType
+from rich import print
+
+from stt2desktop.cli_dev import app
+
+
+logger = logging.getLogger(__name__)
+
+
+@app.command
+def update_readme_history(verbosity: TyroVerbosityArgType):
+    """
+    Update project history base on git commits/tags in README.md
+
+    Will be exited with 1 if the README.md was updated otherwise with 0.
+
+    Also, callable via e.g.:
+        python -m cli_base update-readme-history -v
+    """
+    setup_logging(verbosity=verbosity)
+
+    logger.debug('%s called. CWD: %s', __name__, Path.cwd())
+    updated = git_history.update_readme_history(verbosity=verbosity)
+    exit_code = 1 if updated else 0
+    if verbosity:
+        print(f'{exit_code=}')
+    sys.exit(exit_code)

stt2desktop/constants.py

@@ -0,0 +1,28 @@
+import os
+from enum import StrEnum
+from pathlib import Path
+
+from faster_whisper.utils import available_models
+from pynput import keyboard
+
+import stt2desktop
+
+
+CLI_EPILOG = 'Project Homepage: https://github.com/jedie/stt2desktop'
+
+BASE_PATH = Path(stt2desktop.__file__).parent
+
+IS_WAYLAND = bool(os.environ.get('WAYLAND_DISPLAY'))
+
+WhisperModel = StrEnum(
+    'WhisperModel',
+    [(m.replace('-', '_').replace('.', '_'), m) for m in available_models()],
+)
+
+# Default values used in the CLI
+DEFAULT_WHISPER_MODEL = WhisperModel.small
+DEFAULT_WHISPER_DEVICE = 'auto'  # Let faster-whisper decide the best device
+DEFAULT_WHISPER_COMPUTE_TYPE = 'int8'
+DEFAULT_WHISPER_NUM_WORKERS = os.cpu_count() or 1
+DEFAULT_SAMPLE_RATE = 16000
+DEFAULT_HOTKEY = keyboard.Key.scroll_lock

stt2desktop/get_bin.py

@@ -0,0 +1,29 @@
+import functools
+import shutil
+import sys
+from pathlib import Path
+
+from cli_base.cli_tools.subprocess_utils import verbose_check_call
+
+
+def get_bin(name: str, hint: str) -> Path:
+    bin_path = shutil.which(name)
+    if bin_path is None:
+        print(f'[red]Error: {name} is not installed or not found in PATH.[/red]')
+        print(hint)
+        sys.exit(1)
+    return Path(bin_path)
+
+
+@functools.cache
+def get_wtype_bin() -> Path:
+    wtype_bin = get_bin('wtype', hint='wtype is required for Wayland support: sudo apt install wtype')
+    verbose_check_call(wtype_bin, 'version')
+    return wtype_bin
+
+
+@functools.cache
+def get_xdotool_bin() -> Path:
+    xdotool_bin = get_bin('xdotool', hint='xdotool is required for X11 support: sudo apt install xdotool')
+    verbose_check_call(xdotool_bin, 'version')
+    return xdotool_bin

stt2desktop/stt.py

@@ -0,0 +1,107 @@
+import logging
+import subprocess
+import threading
+from concurrent.futures import Future, ThreadPoolExecutor
+
+import numpy as np
+import sounddevice as sd
+from faster_whisper import WhisperModel
+from rich import print
+
+from stt2desktop.constants import IS_WAYLAND
+from stt2desktop.get_bin import get_wtype_bin, get_xdotool_bin
+
+
+logger = logging.getLogger(__name__)
+
+
+def load_whisper_model(*, model_size: str, device: str, compute_type: str, num_workers: int) -> WhisperModel:
+    print(f'Loading model {model_size} ({device=} {compute_type=} {num_workers=})...')
+    model = WhisperModel(model_size, device=device, compute_type=compute_type, num_workers=num_workers)
+    print('[green]Model loaded.[/green]')
+    return model
+
+
+def transcribe(model: WhisperModel, audio: np.ndarray) -> str:
+    if len(audio) == 0:
+        return ''
+    logger.debug('Transcribing %d samples', len(audio))
+    segments, _ = model.transcribe(audio, beam_size=5)
+    result = ' '.join(seg.text for seg in segments).strip()
+    logger.debug('Transcription: %r', result)
+    return result
+
+
+def record_until_event(*, stop_event: threading.Event, sample_rate: int) -> np.ndarray:
+    """Record from the default microphone until stop_event is set."""
+    chunks: list[np.ndarray] = []
+
+    def callback(indata, frames, time, status):
+        if status:
+            logger.warning('Audio input status: %r', status)
+        chunks.append(indata.copy())
+
+    logger.debug('Recording started')
+    with sd.InputStream(samplerate=sample_rate, channels=1, dtype='float32', callback=callback):
+        stop_event.wait()
+    logger.debug('Recording stopped, got %d chunks', len(chunks))
+
+    if not chunks:
+        return np.array([], dtype='float32')
+    return np.concatenate(chunks, axis=0).flatten()
+
+
+def inject_text(text: str) -> None:
+    """Inject text at the current cursor position."""
+    if IS_WAYLAND:
+        # wtype types text directly into the focused window
+        wtype_bin = get_wtype_bin()
+        subprocess.run((wtype_bin, '--', text), check=True)
+    else:
+        # xdotool types text by simulating key events
+        xdotool_bin = get_xdotool_bin()
+        subprocess.run(
+            (xdotool_bin, 'type', '--clearmodifiers', '--delay', '0', '--', text),
+            check=True,
+        )
+
+
+def record_and_inject(
+    *,
+    model: WhisperModel,
+    stop_event: threading.Event,
+    sample_rate: int,
+) -> None:
+    audio = record_until_event(stop_event=stop_event, sample_rate=sample_rate)
+    print('[cyan]Transcribing...[/cyan]')
+    text = transcribe(model, audio)
+    if text:
+        print(f'[green]Inserting:[/green] {text}')
+        inject_text(text)
+    else:
+        print('[dim]No speech detected.[/dim]')
+
+
+class Recorder:
+    def __init__(self, *, model: WhisperModel, sample_rate: int):
+        self._model = model
+        self._sample_rate = sample_rate
+        self._stop_event: threading.Event | None = None
+        self._future: Future | None = None
+        self._executor = ThreadPoolExecutor(max_workers=1)
+
+    def start(self):
+        if self._future and not self._future.done():
+            return
+        self._stop_event = threading.Event()
+        self._future = self._executor.submit(
+            record_and_inject,
+            model=self._model,
+            stop_event=self._stop_event,
+            sample_rate=self._sample_rate,
+        )
+        print('[yellow]Recording...[/yellow]')
+
+    def stop(self):
+        if self._stop_event is not None:
+            self._stop_event.set()

stt2desktop/tests/__init__.py

@@ -0,0 +1,36 @@
+import os
+import unittest.util
+from pathlib import Path
+
+from bx_py_utils.test_utils.deny_requests import deny_any_real_request
+from cli_base.cli_tools.verbosity import MAX_LOG_LEVEL, setup_logging
+from rich import print
+from typeguard import install_import_hook
+
+
+# Check type annotations via typeguard in all tests:
+install_import_hook(packages=('stt2desktop',))
+
+
+def pre_configure_tests() -> None:
+    print(f'Configure unittests via "load_tests Protocol" from {Path(__file__).relative_to(Path.cwd())}')
+
+    # Hacky way to display more "assert"-Context in failing tests:
+    _MIN_MAX_DIFF = unittest.util._MAX_LENGTH - unittest.util._MIN_DIFF_LEN
+    unittest.util._MAX_LENGTH = int(os.environ.get('UNITTEST_MAX_LENGTH', 2000))
+    unittest.util._MIN_DIFF_LEN = unittest.util._MAX_LENGTH - _MIN_MAX_DIFF
+
+    # Deny any request via docket/urllib3 because tests they should mock all requests:
+    deny_any_real_request()
+
+    # Display DEBUG logs in tests:
+    setup_logging(verbosity=MAX_LOG_LEVEL)
+
+
+def load_tests(loader, tests, pattern):
+    """
+    Use unittest "load_tests Protocol" as a hook to setup test environment before running tests.
+    https://docs.python.org/3/library/unittest.html#load-tests-protocol
+    """
+    pre_configure_tests()
+    return loader.discover(start_dir=Path(__file__).parent, pattern=pattern)

stt2desktop/tests/test_doctests.py

@@ -0,0 +1,10 @@
+from bx_py_utils.test_utils.unittest_utils import BaseDocTests
+
+import stt2desktop
+
+
+class DocTests(BaseDocTests):
+    def test_doctests(self):
+        self.run_doctests(
+            modules=(stt2desktop,),
+        )

stt2desktop/tests/test_project_setup.py

@@ -0,0 +1,49 @@
+import subprocess
+from unittest import TestCase
+
+from bx_py_utils.path import assert_is_file
+from cli_base.cli_tools.code_style import assert_code_style
+from cli_base.cli_tools.subprocess_utils import ToolsExecutor
+from manageprojects.test_utils.project_setup import (
+    check_editor_config,
+    get_py_max_line_length,
+)
+from packaging.version import Version
+
+from stt2desktop import __version__
+from stt2desktop.cli_dev import PACKAGE_ROOT
+
+
+class ProjectSetupTestCase(TestCase):
+    def test_version(self):
+        self.assertIsNotNone(__version__)
+
+        version = Version(__version__)  # Will raise InvalidVersion() if wrong formatted
+        self.assertEqual(str(version), __version__)
+
+        cli_bin = PACKAGE_ROOT / 'cli.py'
+        assert_is_file(cli_bin)
+
+        output = subprocess.check_output([cli_bin, 'version'], text=True)
+        self.assertIn(f'stt2desktop v{__version__}', output)
+
+        dev_cli_bin = PACKAGE_ROOT / 'dev-cli.py'
+        assert_is_file(dev_cli_bin)
+
+        output = subprocess.check_output([dev_cli_bin, 'version'], text=True)
+        self.assertIn(f'stt2desktop v{__version__}', output)
+
+    def test_code_style(self):
+        return_code = assert_code_style(package_root=PACKAGE_ROOT)
+        self.assertEqual(return_code, 0, 'Code style error, see output above!')
+
+    def test_check_editor_config(self):
+        check_editor_config(package_root=PACKAGE_ROOT)
+
+        max_line_length = get_py_max_line_length(package_root=PACKAGE_ROOT)
+        self.assertEqual(max_line_length, 119)
+
+    def test_pre_commit_hooks(self):
+        executor = ToolsExecutor(cwd=PACKAGE_ROOT)
+        for command in ('migrate-config', 'validate-config', 'validate-manifest'):
+            executor.verbose_check_call('pre-commit', command, exit_on_error=True)

stt2desktop/tests/test_readme.py

@@ -0,0 +1,83 @@
+from bx_py_utils.auto_doc import assert_readme_block
+from bx_py_utils.path import assert_is_file
+from cli_base.cli_tools.test_utils.assertion import assert_in
+from cli_base.cli_tools.test_utils.rich_test_utils import NoColorEnvRich, invoke
+from manageprojects.tests.base import BaseTestCase
+
+from stt2desktop import constants
+from stt2desktop.cli_dev import PACKAGE_ROOT
+from stt2desktop.constants import DEFAULT_WHISPER_NUM_WORKERS
+
+
+def assert_cli_help_in_readme(text_block: str, marker: str):
+    README_PATH = PACKAGE_ROOT / 'README.md'
+    assert_is_file(README_PATH)
+
+    text_block = text_block.replace(constants.CLI_EPILOG, '')
+    text_block = f'```\n{text_block.strip()}\n```'
+    assert_readme_block(
+        readme_path=README_PATH,
+        text_block=text_block,
+        start_marker_line=f'[comment]: <> (✂✂✂ auto generated {marker} start ✂✂✂)',
+        end_marker_line=f'[comment]: <> (✂✂✂ auto generated {marker} end ✂✂✂)',
+    )
+
+
+class ReadmeTestCase(BaseTestCase):
+    def test_main_help(self):
+        with NoColorEnvRich():
+            stdout = invoke(
+                cli_bin=PACKAGE_ROOT / 'cli.py',
+                args=['--help'],
+                strip_line_prefix='usage: ',
+            )
+        assert_in(
+            content=stdout,
+            parts=(
+                'usage: ./cli.py [-h]',
+                ' version ',
+                'Print version and exit',
+                constants.CLI_EPILOG,
+            ),
+        )
+        assert_cli_help_in_readme(text_block=stdout, marker='main help')
+
+    def test_listen_help(self):
+        with NoColorEnvRich():
+            stdout = invoke(
+                cli_bin=PACKAGE_ROOT / 'cli.py',
+                args=['listen', '--help'],
+                strip_line_prefix='usage: ./cli.py listen ',
+            )
+        cpu_count_part = f'Defaults to CPU count. (default: {DEFAULT_WHISPER_NUM_WORKERS})'
+        assert_in(
+            content=stdout,
+            parts=(
+                'usage: ./cli.py listen ',
+                ' --hotkey ',
+                ' --model ',
+                cpu_count_part,
+            ),
+        )
+        stdout = stdout.replace(cpu_count_part, 'Defaults to CPU count. (default:XY)').strip()
+        assert_cli_help_in_readme(text_block=stdout, marker='listen help')
+
+    def test_dev_help(self):
+        with NoColorEnvRich():
+            stdout = invoke(
+                cli_bin=PACKAGE_ROOT / 'dev-cli.py',
+                args=['--help'],
+                strip_line_prefix='usage: ',
+            )
+        assert_in(
+            content=stdout,
+            parts=(
+                'usage: ./dev-cli.py [-h]',
+                ' lint ',
+                ' coverage ',
+                ' update-readme-history ',
+                ' publish ',
+                constants.CLI_EPILOG,
+            ),
+        )
+        assert_cli_help_in_readme(text_block=stdout, marker='dev help')

stt2desktop/tests/test_readme_history.py

@@ -0,0 +1,9 @@
+from unittest import TestCase
+
+from cli_base.cli_tools.git_history import update_readme_history
+
+
+class ReadmeHistoryTestCase(TestCase):
+    def test_readme_history(self):
+        with self.assertLogs():
+            update_readme_history(raise_update_error=True)

stt2desktop-0.0.1.dist-info/METADATA

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: stt2desktop
+Version: 0.0.1
+Summary: Local speech-to-text for desktop using faster-whisper
+Project-URL: Documentation, https://github.com/jedie/stt2desktop
+Project-URL: Source, https://github.com/jedie/stt2desktop
+Author-email: Jens Diemer <stt2desktop@jensdiemer.de>
+License: GPL-3.0-or-later
+Requires-Python: >=3.12
+Requires-Dist: bx-py-utils
+Requires-Dist: cli-base-utilities>=0.27.1
+Requires-Dist: faster-whisper
+Requires-Dist: pynput
+Requires-Dist: rich
+Requires-Dist: sounddevice
+Requires-Dist: tyro
+Description-Content-Type: text/markdown
+
+# stt2desktop
+
+[![tests](https://github.com/jedie/stt2desktop/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/jedie/stt2desktop/actions/workflows/tests.yml)
+[![codecov](https://codecov.io/github/jedie/stt2desktop/branch/main/graph/badge.svg)](https://app.codecov.io/github/jedie/stt2desktop)
+[![stt2desktop @ PyPi](https://img.shields.io/pypi/v/stt2desktop?label=stt2desktop%20%40%20PyPi)](https://pypi.org/project/stt2desktop/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/stt2desktop)](https://github.com/jedie/stt2desktop/blob/main/pyproject.toml)
+[![License GPL-3.0-or-later](https://img.shields.io/pypi/l/stt2desktop)](https://github.com/jedie/stt2desktop/blob/main/LICENSE)
+
+Local speech-to-text for desktop using [faster-whisper](https://github.com/SYSTRAN/faster-whisper).
+
+Let's you dictate text into any application without sending audio to any cloud services.
+Everything runs locally on your machine — no internet connection required after the initial model was download.
+
+## How it works
+
+1. Run `./cli.py listen` — the Whisper model is loaded into memory (downloaded on first run).
+2. Hold **Scroll Lock** to record from your microphone.
+3. Release **Scroll Lock** — the audio is transcribed locally by faster-whisper (CPU, `int8`).
+4. The text is typed into the focused window via `wtype` (Wayland) or `xdotool` (X11).
+
+## Setup
+
+Requirements: Python 3.12+, [`uv`](https://github.com/astral-sh/uv), a working microphone, and either `wtype` (Wayland) or `xdotool` (X11):
+
+```bash
+sudo apt install wtype     # Wayland
+sudo apt install xdotool   # X11
+```
+
+Then run:
+
+```bash
+./cli.py listen
+```
+
+[comment]: <> (✂✂✂ auto generated listen help start ✂✂✂)
+```
+usage: ./cli.py listen [-h] [LISTEN OPTIONS]
+
+Start the STT listener. Hold the hotkey to record, release to transcribe and insert.
+
+╭─ options ────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ -h, --help          show this help message and exit                                                                  │
+│ -v, --verbosity     Verbosity level; e.g.: -v, -vv, -vvv, etc. (repeatable)                                          │
+│ --model {tiny_en,tiny,base_en,base,small_en,small,medium_en,medium,large_v1,large_v2,large_v3,large,distil_large_v2, │
+│ distil_medium_en,distil_small_en,distil_large_v3,distil_large_v3_5,large_v3_turbo,turbo}                             │
+│                     Whisper model to use for transcription. (default: small)                                         │
+│ --hotkey {alt,alt_l,alt_r,alt_gr,backspace,caps_lock,cmd,cmd_l,cmd_r,ctrl,ctrl_l,ctrl_r,delete,down,end,enter,esc,   │
+│ f1,f2,f3,f4,f5,f6,f7,f8,f9,f10,f11,f12,f13,f14,f15,f16,f17,f18,f19,f20,home,left,page_down,page_up,right,shift,      │
+│ shift_l,shift_r,space,tab,up,media_play_pause,media_volume_mute,media_volume_down,media_volume_up,media_previous,    │
+│ media_next,insert,menu,num_lock,pause,print_screen,scroll_lock}                                                      │
+│                     Key to hold for recording. Release to transcribe and insert text. (default: scroll_lock)         │
+│ --sample-rate INT   Audio sample rate in Hz. Whisper expects 16000. (default: 16000)                                 │
+│ --device STR        Device to run inference on, e.g. cpu or cuda. (default: auto)                                    │
+│ --compute-type STR  Quantization type, e.g. int8, float16, float32. (default: int8)                                  │
+│ --num-workers INT   Number of parallel transcription workers. Defaults to CPU count. (default:XY)                   │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+```
+[comment]: <> (✂✂✂ auto generated listen help end ✂✂✂)
+
+### Available models
+
+| Model | Size | Speed | Accuracy |
+|-------|------|-------|----------|
+| `tiny` | ~75 MB | fastest | lowest |
+| `base` | ~145 MB | fast | good (default) |
+| `small` | ~460 MB | slower | better |
+| `medium` | ~1.5 GB | slow | high |
+
+Larger models produce more accurate transcriptions but take longer to process. For most use cases `base` or `small` is a good starting point.
+
+## CLI
+
+[comment]: <> (✂✂✂ auto generated main help start ✂✂✂)
+```
+usage: ./cli.py [-h] {listen,version}
+
+
+
+╭─ options ─────────────────────────────────────────────────────────────────────────────────────────╮
+│ -h, --help   show this help message and exit                                                      │
+╰───────────────────────────────────────────────────────────────────────────────────────────────────╯
+╭─ subcommands ─────────────────────────────────────────────────────────────────────────────────────╮
+│ (required)                                                                                        │
+│   • listen   Start the STT listener. Hold the hotkey to record, release to transcribe and insert. │
+│   • version  Print version and exit                                                               │
+╰───────────────────────────────────────────────────────────────────────────────────────────────────╯
+```
+[comment]: <> (✂✂✂ auto generated main help end ✂✂✂)
+
+
+## start development
+
+At least `uv` is needed. Install e.g.: via pipx:
+```bash
+apt-get install pipx
+pipx install uv
+```
+
+Clone the project and just start the CLI help commands.
+A virtual environment will be created/updated automatically.
+
+```bash
+~$ git clone https://github.com/jedie/stt2desktop.git
+~$ cd stt2desktop
+~/stt2desktop$ ./cli.py --help
+~/stt2desktop$ ./dev-cli.py --help
+```
+
+[comment]: <> (✂✂✂ auto generated dev help start ✂✂✂)
+```
+usage: ./dev-cli.py [-h] {coverage,install,lint,mypy,nox,pip-audit,publish,test,update,update-readme-history,update-test-snapshot-files,version}
+
+
+
+╭─ options ────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ -h, --help    show this help message and exit                                                                        │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+╭─ subcommands ────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ (required)                                                                                                           │
+│   • coverage  Run tests and show coverage report.                                                                    │
+│   • install   Install requirements and 'stt2desktop' via pip as editable.                                            │
+│   • lint      Check/fix code style by run: "ruff check --fix"                                                        │
+│   • mypy      Run Mypy (configured in pyproject.toml)                                                                │
+│   • nox       Run nox                                                                                                │
+│   • pip-audit                                                                                                        │
+│               Run pip-audit check against current requirements files                                                 │
+│   • publish   Build and upload this project to PyPi                                                                  │
+│   • test      Run unittests                                                                                          │
+│   • update    Update dependencies (uv.lock) and git pre-commit hooks                                                 │
+│   • update-readme-history                                                                                            │
+│               Update project history base on git commits/tags in README.md Will be exited with 1 if the README.md    │
+│               was updated otherwise with 0.                                                                          │
+│                                                                                                                      │
+│               Also, callable via e.g.:                                                                               │
+│                   python -m cli_base update-readme-history -v                                                        │
+│   • update-test-snapshot-files                                                                                       │
+│               Update all test snapshot files (by remove and recreate all snapshot files)                             │
+│   • version   Print version and exit                                                                                 │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+```
+[comment]: <> (✂✂✂ auto generated dev help end ✂✂✂)
+
+
+## History
+
+[comment]: <> (✂✂✂ auto generated history start ✂✂✂)
+
+* [**dev**](https://github.com/jedie/stt2desktop/compare/b407f8f...main)
+  * 2026-03-26 - Add POC
+  * 2026-03-26 - init
+
+[comment]: <> (✂✂✂ auto generated history end ✂✂✂)

stt2desktop-0.0.1.dist-info/RECORD

@@ -0,0 +1,22 @@
+stt2desktop/__init__.py,sha256=D2_c_60RhAe2VD2IrFDTBzVzJgqchFg9lAevaag8f-s,217
+stt2desktop/__main__.py,sha256=qoH1ZrA02HBmz5E16WpDaGfi3jUnm4s8tkyEbfaRjU0,154
+stt2desktop/constants.py,sha256=nnjqZZ_Ym2oM_rqaxSxWPJum3nxOxYUT-U_L5pSbEfk,769
+stt2desktop/get_bin.py,sha256=X-gV5BYOqlDdmHh--VNZsYS2U4rSyJNxHiKtwTQuDQo,831
+stt2desktop/stt.py,sha256=25rjDtxWMknrn5lQ3ByV3v8JsrCxAUH6tR7KN9tHOfY,3508
+stt2desktop/cli_app/__init__.py,sha256=DmwDpQ2ga-FbkOLtPCyllv6ID-_GelIpV_WTNcYK1s0,951
+stt2desktop/cli_app/listen.py,sha256=siFfL17pt40oJSNVZWStqfGzG1WbLNMnGuJUeS_REhU,2618
+stt2desktop/cli_dev/__init__.py,sha256=cCFldU21Py496ZIDxPWEvjCNKZT0x92sDJNMqgmGcII,1889
+stt2desktop/cli_dev/__main__.py,sha256=e36uw5SUShOGKBRaC21xB5Rw2AmTQ-uKTDmCCnXjwx4,162
+stt2desktop/cli_dev/code_style.py,sha256=BAXhqvmVPuDqC8D0AjIN0EJHPbT3GdzbIqePaEMHc6Y,386
+stt2desktop/cli_dev/packaging.py,sha256=WvuV-kNHkoOnZSvwdqatNwMn8GoTcPsH9BpdxvpoWus,1814
+stt2desktop/cli_dev/testing.py,sha256=yiXBX4LzVU6Eh12rj2ENJqt6V57l3XKB9D-gCMV2Kbw,1384
+stt2desktop/cli_dev/update_readme_history.py,sha256=12swOa8O7y5Tkuw4pLN_cT_4zTTfSHe4VYlwHdnl_5k,896
+stt2desktop/tests/__init__.py,sha256=-uUIzVrd-btVeP7UME5oDmUpNNVA9tr1ufaKhBUlRR4,1334
+stt2desktop/tests/test_doctests.py,sha256=EGemZFe1HDN2HCBdxeIC_EDjA0OMVV0hfH3RoEbj-t4,217
+stt2desktop/tests/test_project_setup.py,sha256=zkmzVwDDi6NW-ndSpvdWpYiwx9PLuuz8xEq-d9owmmM,1788
+stt2desktop/tests/test_readme.py,sha256=R3_tXsr2CSzAnJomJ0sWPGfU9BV2R-tyC5ErerJXFtU,2910
+stt2desktop/tests/test_readme_history.py,sha256=PbxF_yRspyRwkVCQosZXevIHrsla3WFBTUVeLI0bb-s,263
+stt2desktop-0.0.1.dist-info/METADATA,sha256=2Dj2dEDxCtEsCqVDfCbiD3TnZzkEGNqquSaC89ju9l8,12134
+stt2desktop-0.0.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+stt2desktop-0.0.1.dist-info/entry_points.txt,sha256=ezr7yveS5bFKyhDtKg_Xq2jd6_e3cfHm9soM8rnS_II,58
+stt2desktop-0.0.1.dist-info/RECORD,,

stt2desktop-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

stt2desktop-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+stt2desktop = stt2desktop.__main__:main