sys2txt 0.1.1__tar.gz

sys2txt-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Joe Heffer
+
+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.

sys2txt-0.1.1/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: sys2txt
+Version: 0.1.1
+Summary: Record system audio and transcribe to text using AI
+Author-email: Joe Heffer <jheffer@gmail.com>
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: faster-whisper>=1.0.0
+Requires-Dist: openai-whisper>=20231117
+Provides-Extra: dev
+Requires-Dist: ruff>=0.8.0; extra == "dev"
+Dynamic: license-file
+
+[![CI](https://github.com/Joe-Heffer/sys2txt/actions/workflows/ci.yml/badge.svg)](https://github.com/Joe-Heffer/sys2txt/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/sys2txt.svg)](https://badge.fury.io/py/sys2txt)
+[![Python versions](https://img.shields.io/pypi/pyversions/sys2txt.svg)](https://pypi.org/project/sys2txt/)
+
+# System audio to text
+
+Record system audio and automatically transcribe to text using ✨AI✨.
+
+## Overview
+
+`sys2txt` is a command-line tool that records your system audio (via PulseAudio/PipeWire monitor sources) with `ffmpeg` and transcribes it locally using [Whisper](https://github.com/openai/whisper). It supports both:
+
+- On-demand: Record until you stop, then transcribe once
+- Live-ish: Segment the recording every *N* seconds and transcribe each segment as it’s created (prints continuously)
+
+You can use either the `openai-whisper` (Python) reference implementation or the [`faster-whisper`](https://github.com/SYSTRAN/faster-whisper) engine if installed. The tool auto-selects `faster-whisper` when available for better speed on CPU and especially GPU.
+
+## Installation
+
+### Prerequisites
+
+- Ubuntu with PulseAudio or PipeWire (default on modern Ubuntu)
+- ffmpeg
+- Python 3.9+ (recommended)
+
+### Install
+
+1) System packages
+
+```bash
+sudo apt update
+sudo apt install -y ffmpeg python3-venv python3-pip
+```
+
+2) Create a virtual environment and install sys2txt
+
+```bash
+cd sys2txt
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+This installs both faster-whisper (for speed) and openai-whisper (reference implementation). The tool auto-selects faster-whisper when available or falls back to openai-whisper.
+
+## Quick start
+
+Record and transcribe once (press Ctrl-C to stop recording):
+
+```bash
+sys2txt once --model small.en
+```
+
+Live segmented transcription (prints ongoing transcript every 8s by default; Ctrl-C to stop):
+
+```bash
+sys2txt live --model small.en --segment-seconds 8
+```
+
+### Useful flags
+
+- `--source <pulse_source_name>` - Explicit PulseAudio/PipeWire source (e.g., alsa_output.pci-0000_00_1f.3.analog-stereo.monitor)
+- `--list-sources` - List available Pulse sources and exit
+- `--model <size>` - tiny|base|small|medium|large-v2 (default: small)
+- `--engine <auto|faster|whisper>` - Force a specific engine (default: auto)
+- `--language <code>` - Force language code (e.g., en). Omit to auto-detect
+- `--output <path>` - Write final transcript to a file (in live mode, appends)
+- `--duration <seconds>` - (once mode) Record fixed duration instead of waiting for Ctrl-C
+- `--segment-seconds <n>` - (live mode) Segment length in seconds (default: 8)
+- `--timestamps` - Print timestamps alongside text
+
+## Examples
+
+Record 30s of system audio from the default monitor and transcribe:
+
+```bash
+sys2txt once --duration 30 --model small --output transcript.txt
+```
+
+Use a specific PulseAudio source:
+
+```bash
+sys2txt once --source alsa_output.usb-Focusrite_Scarlett.monitor --model base
+```
+
+Live mode with shorter latency and timestamps:
+
+```bash
+sys2txt live --segment-seconds 5 --timestamps
+```
+
+Force the reference openai-whisper engine:
+
+```bash
+sys2txt once --engine whisper --model base
+```
+
+Transcribe an existing audio file:
+
+```bash
+sys2txt once --input recording.wav --model small
+```
+
+### Just want one-liners (no sys2txt)?
+
+Find the default sink and its monitor source:
+
+```bash
+pactl get-default-sink
+pactl list short sources | grep monitor
+```
+
+Record 30s of system audio from the default monitor to a WAV at 16 kHz mono (good for Whisper):
+
+```bash
+ffmpeg -hide_banner -loglevel error -f pulse -i "$(pactl get-default-sink).monitor" -ac 1 -ar 16000 -t 30 out.wav
+```
+
+Transcribe with openai-whisper CLI:
+
+```bash
+whisper out.wav --model small --task transcribe --language en
+```
+
+## Tips and troubleshooting
+
+- If you get silence, ensure you are using the monitor source for your output device (the name ends with `.monitor`). Use `--list-sources` to view options.
+- Make sure the application you want to capture is playing through the same output sink as your default sink. You can manage routes with `pavucontrol`.
+- PipeWire systems expose PulseAudio-compatible sources, so `-f pulse` in ffmpeg still works.
+- For better performance on CPU, use faster-whisper with model `base` or `small`. For the best accuracy, use `medium` or `large-v2` (these are heavier).
+- GPU acceleration for faster-whisper requires a compatible ctranslate2 CUDA wheel. Set `SYS2TXT_DEVICE=cuda` to enable it. If not available, it will run on CPU.
+
+## Development
+
+Install with development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Run unit tests:
+
+```bash
+python -m unittest discover -s tests -p "test_*.py"
+```
+
+Format and lint code:
+
+```bash
+ruff format src/
+ruff check src/
+```

sys2txt-0.1.1/README.md

@@ -0,0 +1,152 @@
+[![CI](https://github.com/Joe-Heffer/sys2txt/actions/workflows/ci.yml/badge.svg)](https://github.com/Joe-Heffer/sys2txt/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/sys2txt.svg)](https://badge.fury.io/py/sys2txt)
+[![Python versions](https://img.shields.io/pypi/pyversions/sys2txt.svg)](https://pypi.org/project/sys2txt/)
+
+# System audio to text
+
+Record system audio and automatically transcribe to text using ✨AI✨.
+
+## Overview
+
+`sys2txt` is a command-line tool that records your system audio (via PulseAudio/PipeWire monitor sources) with `ffmpeg` and transcribes it locally using [Whisper](https://github.com/openai/whisper). It supports both:
+
+- On-demand: Record until you stop, then transcribe once
+- Live-ish: Segment the recording every *N* seconds and transcribe each segment as it’s created (prints continuously)
+
+You can use either the `openai-whisper` (Python) reference implementation or the [`faster-whisper`](https://github.com/SYSTRAN/faster-whisper) engine if installed. The tool auto-selects `faster-whisper` when available for better speed on CPU and especially GPU.
+
+## Installation
+
+### Prerequisites
+
+- Ubuntu with PulseAudio or PipeWire (default on modern Ubuntu)
+- ffmpeg
+- Python 3.9+ (recommended)
+
+### Install
+
+1) System packages
+
+```bash
+sudo apt update
+sudo apt install -y ffmpeg python3-venv python3-pip
+```
+
+2) Create a virtual environment and install sys2txt
+
+```bash
+cd sys2txt
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+This installs both faster-whisper (for speed) and openai-whisper (reference implementation). The tool auto-selects faster-whisper when available or falls back to openai-whisper.
+
+## Quick start
+
+Record and transcribe once (press Ctrl-C to stop recording):
+
+```bash
+sys2txt once --model small.en
+```
+
+Live segmented transcription (prints ongoing transcript every 8s by default; Ctrl-C to stop):
+
+```bash
+sys2txt live --model small.en --segment-seconds 8
+```
+
+### Useful flags
+
+- `--source <pulse_source_name>` - Explicit PulseAudio/PipeWire source (e.g., alsa_output.pci-0000_00_1f.3.analog-stereo.monitor)
+- `--list-sources` - List available Pulse sources and exit
+- `--model <size>` - tiny|base|small|medium|large-v2 (default: small)
+- `--engine <auto|faster|whisper>` - Force a specific engine (default: auto)
+- `--language <code>` - Force language code (e.g., en). Omit to auto-detect
+- `--output <path>` - Write final transcript to a file (in live mode, appends)
+- `--duration <seconds>` - (once mode) Record fixed duration instead of waiting for Ctrl-C
+- `--segment-seconds <n>` - (live mode) Segment length in seconds (default: 8)
+- `--timestamps` - Print timestamps alongside text
+
+## Examples
+
+Record 30s of system audio from the default monitor and transcribe:
+
+```bash
+sys2txt once --duration 30 --model small --output transcript.txt
+```
+
+Use a specific PulseAudio source:
+
+```bash
+sys2txt once --source alsa_output.usb-Focusrite_Scarlett.monitor --model base
+```
+
+Live mode with shorter latency and timestamps:
+
+```bash
+sys2txt live --segment-seconds 5 --timestamps
+```
+
+Force the reference openai-whisper engine:
+
+```bash
+sys2txt once --engine whisper --model base
+```
+
+Transcribe an existing audio file:
+
+```bash
+sys2txt once --input recording.wav --model small
+```
+
+### Just want one-liners (no sys2txt)?
+
+Find the default sink and its monitor source:
+
+```bash
+pactl get-default-sink
+pactl list short sources | grep monitor
+```
+
+Record 30s of system audio from the default monitor to a WAV at 16 kHz mono (good for Whisper):
+
+```bash
+ffmpeg -hide_banner -loglevel error -f pulse -i "$(pactl get-default-sink).monitor" -ac 1 -ar 16000 -t 30 out.wav
+```
+
+Transcribe with openai-whisper CLI:
+
+```bash
+whisper out.wav --model small --task transcribe --language en
+```
+
+## Tips and troubleshooting
+
+- If you get silence, ensure you are using the monitor source for your output device (the name ends with `.monitor`). Use `--list-sources` to view options.
+- Make sure the application you want to capture is playing through the same output sink as your default sink. You can manage routes with `pavucontrol`.
+- PipeWire systems expose PulseAudio-compatible sources, so `-f pulse` in ffmpeg still works.
+- For better performance on CPU, use faster-whisper with model `base` or `small`. For the best accuracy, use `medium` or `large-v2` (these are heavier).
+- GPU acceleration for faster-whisper requires a compatible ctranslate2 CUDA wheel. Set `SYS2TXT_DEVICE=cuda` to enable it. If not available, it will run on CPU.
+
+## Development
+
+Install with development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Run unit tests:
+
+```bash
+python -m unittest discover -s tests -p "test_*.py"
+```
+
+Format and lint code:
+
+```bash
+ruff format src/
+ruff check src/
+```

sys2txt-0.1.1/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=80", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sys2txt"
+version = "0.1.1"
+description = "Record system audio and transcribe to text using AI"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [
+    {name = "Joe Heffer", email = "jheffer@gmail.com"}
+]
+dependencies = [
+    "faster-whisper>=1.0.0",
+    "openai-whisper>=20231117",
+]
+
+[project.scripts]
+sys2txt = "sys2txt.__main__:main"
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.8.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+ignore = []

sys2txt-0.1.1/setup.cfg

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

sys2txt-0.1.1/src/sys2txt/__init__.py

@@ -0,0 +1 @@
+

sys2txt-0.1.1/src/sys2txt/__main__.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+"""Main entry point for sys2txt CLI."""
+
+import argparse
+import os
+import sys
+import tempfile
+from datetime import datetime
+
+from .audio import record_once, segment_and_transcribe_live
+from .constants import WHISPER_MODEL
+from .pulse import get_default_monitor_source, list_pulse_sources
+from .transcribe import transcribe_file
+
+
+def get_timestamp_filename() -> str:
+    """Generate a timestamp-based filename for output files.
+
+    Returns:
+        A filename string in the format: YYYY-MM-DD_HH-MM-SS.txt
+    """
+    return datetime.now().strftime("%Y-%m-%d_%H-%M-%S.txt")
+
+
+def ensure_output_dir() -> str:
+    """Ensure the output directory exists and return its path.
+
+    Returns:
+        Absolute path to the output directory
+    """
+    output_dir = os.path.join(os.getcwd(), "output")
+    os.makedirs(output_dir, exist_ok=True)
+    return output_dir
+
+
+def main():
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(description="Record Ubuntu system audio and transcribe with Whisper.")
+    sub = parser.add_subparsers(dest="mode", required=True)
+
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument(
+        "--source", help="PulseAudio source name (e.g., <sink>.monitor). Defaults to auto.", default=None
+    )
+    common.add_argument(
+        "--model",
+        dest="model_size",
+        default=WHISPER_MODEL,
+        help=f"Whisper model size (default: {WHISPER_MODEL})",
+    )
+    common.add_argument(
+        "--engine", choices=["auto", "faster", "whisper"], default="auto", help="Transcription engine (default: auto)"
+    )
+    common.add_argument("--language", default=None, help="Force language code (e.g., en). Defaults to auto-detect")
+    common.add_argument("--timestamps", action="store_true", help="Print timestamps with transcript")
+    common.add_argument("--list-sources", action="store_true", help="List PulseAudio sources and exit")
+
+    once = sub.add_parser("once", parents=[common], help="Record once and transcribe after")
+    once.add_argument("--duration", type=int, default=None, help="Record for N seconds instead of Ctrl-C")
+    once.add_argument("--output", default=None, help="Write transcript to file")
+    once.add_argument("--input", default=None, help="Skip recording and transcribe this existing audio file")
+
+    live = sub.add_parser("live", parents=[common], help="Segmented live transcription")
+    live.add_argument("--segment-seconds", type=int, default=8, help="Segment length in seconds (default: 8)")
+    live.add_argument("--output", default=None, help="Append live transcript to this file as it's produced")
+
+    args = parser.parse_args()
+
+    if args.list_sources:
+        sources = list_pulse_sources()
+        if not sources:
+            print("No PulseAudio sources found. Is PulseAudio/PipeWire running?", file=sys.stderr)
+            sys.exit(1)
+        print("Available PulseAudio sources:")
+        for name, _ in sources:
+            print("  ", name)
+        return
+
+    # Determine source
+    source = args.source or get_default_monitor_source()
+
+    if args.mode == "once":
+        # Determine output file path
+        output_dir = ensure_output_dir()
+        if args.output:
+            # If user specified a path, use it as-is (could be relative or absolute)
+            output_file = args.output
+        else:
+            # Generate timestamp-based filename in output/ directory
+            output_file = os.path.join(output_dir, get_timestamp_filename())
+
+        if args.input:
+            audio_path = args.input
+        else:
+            # Make a temp WAV, record until duration/ctrl-c, then transcribe
+            with tempfile.TemporaryDirectory(prefix="sys2txt_") as tmp:
+                wav = os.path.join(tmp, "capture.wav")
+                record_once(source=source, out_wav=wav, sample_rate=16000, channels=1, duration=args.duration)
+                audio_path = wav
+                text = transcribe_file(
+                    audio_path,
+                    engine=args.engine,
+                    model_size=args.model_size,
+                    language=args.language,
+                    timestamps=args.timestamps,
+                )
+                print(text)
+                with open(output_file, "w", encoding="utf-8") as w:
+                    w.write(text + "\n")
+                print(f"Transcript saved to: {output_file}")
+                return
+        # If input provided, just transcribe it
+        text = transcribe_file(
+            audio_path,
+            engine=args.engine,
+            model_size=args.model_size,
+            language=args.language,
+            timestamps=args.timestamps,
+        )
+        print(text)
+        with open(output_file, "w", encoding="utf-8") as w:
+            w.write(text + "\n")
+        print(f"Transcript saved to: {output_file}")
+
+    elif args.mode == "live":
+        # Determine output file path
+        output_dir = ensure_output_dir()
+        if args.output:
+            # If user specified a path, use it as-is (could be relative or absolute)
+            output_file = args.output
+        else:
+            # Generate timestamp-based filename in output/ directory
+            output_file = os.path.join(output_dir, get_timestamp_filename())
+
+        print(f"Live transcript will be saved to: {output_file}")
+
+        def transcribe_segment(file_path: str, segment_index: int) -> str:
+            """Transcribe a segment and format with optional timestamp prefix."""
+            text = transcribe_file(
+                file_path,
+                engine=args.engine,
+                model_size=args.model_size,
+                language=args.language,
+                timestamps=args.timestamps,
+            )
+            if args.timestamps:
+                # Add segment time window prefix
+                start = segment_index * args.segment_seconds
+                end = start + args.segment_seconds
+                prefix = f"[{start:>5d}-{end:>5d}s] "
+                return prefix + text.strip()
+            else:
+                return text.strip()
+
+        segment_and_transcribe_live(
+            source=source,
+            sample_rate=16000,
+            channels=1,
+            segment_seconds=args.segment_seconds,
+            transcribe_callback=transcribe_segment,
+            output_path=output_file,
+        )
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except RuntimeError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except KeyboardInterrupt:
+        pass