s2t 0.2.8

Speech to Text (s2t): Record audio, run Whisper, export formats, and copy transcript to clipboard.

s2t

Record audio from your microphone, run Whisper to transcribe it, export common formats, and optionally copy the transcript to your clipboard.

Install

Two distinct paths — pick the one matching your role. Do not mix them.

• Use s2t from anywhere in the terminal (recommended for end users): install via pipx, which keeps s2t in its own isolated venv and exposes it on your PATH.
  • From PyPI: pipx install s2t
  • From a local wheel built in this checkout: make install-pipx
• Develop on the working tree: install editable into the project .venv (not on PATH outside the project; intentional).
  • make setup (creates .venv and installs dev extras), then either source .venv/bin/activate or call .venv/bin/s2t directly.

Rule of thumb: development = project .venv, daily use = pipx. The two installs coexist cleanly because pipx lives in ~/.local/bin/s2t and the dev install lives in ./.venv/bin/s2t; whichever wins on PATH is determined by whether the project venv is active.

Requirements: Python 3.11–3.12. No mandatory external binaries. ffmpeg is optional (only for MP3 encoding/decoding).

System requirements (Linux)

• Some environments need system libraries for audio I/O:
  • Debian/Ubuntu: sudo apt-get install libportaudio2 libsndfile1
  • Fedora/RHEL: sudo dnf install portaudio libsndfile
• Optional for MP3: ffmpeg (sudo apt-get install ffmpeg or brew install ffmpeg).
• Optional backends:
  • faster-whisper (CTranslate2): pip install faster-whisper (GPU via CUDA on NVIDIA; CPU works well with int8).
  • whisper.cpp (Metal/CPU): pip install whispercpp (requires local gguf models; experimental GPU on Apple varies by build).

Usage

• Start interactive recording and transcribe:
  • s2t
• Short options:
  • Language: -l de (long: --lang de)
  • Model: -m large-v3 (long: --model large-v3)
  • Backend: --backend whisper|faster|whispercpp (default: whisper)
  • Device: --device auto|cpu|cuda|mps (default: auto)
  • Sample rate: -r 48000 (long: --rate 48000)
  • Channels: -c 2 (long: --channels 2)
  • Output dir: -o transcripts (long: --outdir transcripts) — default is transcripts/ if omitted
  • Translate to English: -t (long: --translate). You may still provide --lang as an input-language hint if you want.
  • List available models and exit: -L (long: --list-models)
  • Recording format: -f flac|wav|mp3 (long: --recording-format), default flac. MP3 requires ffmpeg; if absent, it falls back to FLAC with a warning.
  • Note: There is no minimum chunk duration; cuts are chosen at the longest pause within the window.
  • Observation window (for block-based splitting): -b 20.0 or --buffer-sec 20.0 (default 20.0). Cuts at the longest pause within each window.
  • Chunk segmentation: by default each recorded chunk becomes one Whisper segment; pass --no-chunk-segmentation to keep Whisper's native segmentation per chunk.
  • Written prompt: -p "TEXT" or --prompt="TEXT" — pass a text prompt to guide Whisper's transcription (terminology, spelling, style). Use the = syntax for prompts starting with a dash. Just -p / --prompt (without argument) asks interactively.
  • Spoken prompt: --speak-prompt — speak your prompt first, then press SPACE to use it as prompt and continue with your main content. If you press ENTER instead of SPACE, no prompt is used; the spoken audio is transcribed as normal payload and the session ends.
  • Keep chunk files: --keep-chunks — by default, per‑chunk audio and per‑chunk Whisper outputs are deleted after the final merge.
  • Open transcript for editing: -e (long: --edit) — opens the generated .txt in your shell editor ($VISUAL/$EDITOR).
• Examples:
  • Transcribe in German using large-v3: s2t -l de -m large-v3
  • Translate any input to English: s2t -t
  • Write outputs under transcripts/: s2t -o transcripts
  • List local model names: s2t -L

Interactive Controls

• Key bindings (while recording)
  • ENTER: Split now (manual cut). Ends the current segment immediately.
  • Q (or q): Finish the session and process final outputs.
  • SPACE: Toggle pause/resume. On pause, the current buffer is drained (single best cut), then a PAUSED marker is shown.
  • c (lowercase): Copy the recent source-language transcript to the clipboard since the last c or C action. Prints a visible console marker.
  • C (uppercase): Copy the full source-language transcript (since the beginning) to the clipboard. Prints a distinct console marker.
  • t (lowercase): Copy the recent translated transcript (e.g., English when using -t) since the last t or T action.
  • T (uppercase): Copy the full translated transcript (since the beginning). Requires translation mode (-t or --translate-to).
• Written prompt (-p/--prompt)
  • Pass a text prompt to guide Whisper (e.g. s2t --prompt="Dr. Müller, Angiographie"), or just s2t --prompt to type it interactively.
• Spoken prompt (--speak-prompt)
  • Speak your prompt first, then press ENTER. The app waits until your prompt is transcribed, prints a separator, and then you start speaking your main content.

Segmentation Behavior

• Windowed splitting (default): The recorder analyzes a sliding window of length --buffer-sec (default 20 seconds) and cuts at the longest detected pause.
  • If no suitable pause is found within the window, a hard cut occurs at the window boundary.
  • A small audio overlap (--overlap-ms, default 200) is applied between consecutive segments to avoid trimming syllables at cut points.

Outputs are written into a timestamped folder under the chosen output directory (default is transcripts/), e.g. transcripts/2025-01-31T14-22-05+0200/, containing:

• Per‑chunk outputs: chunk_####.flac/.wav plus chunk_####.txt/.srt/.vtt/.tsv/.json (deleted by default unless --keep-chunks)
• Final outputs: transcription.flac/.wav (and transcription.mp3 if requested and ffmpeg available), plus transcription.txt/.srt/.vtt/.tsv/.json
  • Transcript is written to .txt; clipboard copying is optional and disabled by default.

Auto-splitting details

• ENTER splits immediately; Q finishes the recording.
• Windowed: cuts at the longest pause within the selected window (fallback: window boundary).
• There is no fixed minimum duration per chunk.

Makefile (optional)

• Setup venv + dev deps: make setup
• Lint/format/test: make lint, make format, make test; combined gate: make check
• Build sdist/wheel: make build (runs check first)
• Publish to PyPI/TestPyPI: make publish, make publish-test (run after build)
• Install current working tree as a global CLI via pipx: make install-pipx
• Verify the published PyPI release via pipx: make verify-pypi
• Both targets use the project venv's pipx (declared in [dev] extras and auto-installed if missing) — no system-level pipx required for development.
• Run CLI: make record ARGS='-l de -t -o transcripts'
• List models: make list-models
• Show package version: make version

Notes on models

• The local openai-whisper CLI supports models like: tiny, base, small, medium, large-v1, large-v2, large-v3 and their .en variants.
• The name turbo refers to OpenAI’s hosted model family and is not provided by the local whisper CLI. If you pass -m turbo, the command may fail; choose a supported local model instead.

Development & Release

• For developer setup and contribution guidelines, see CONTRIBUTING.md.
• For the release process, see docs/RELEASING.md.