speech2text-linux

中文说明

A small Ubuntu 22.04 hotkey speech-to-text helper. Press one shortcut to start recording, press it again to stop recording and send the audio to Tencent Cloud ASR, then copy the transcript to the clipboard. You can then use DeepSeek to clean the transcript or organize it into brief and detailed versions.

1. Install

cd <project-dir>
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -U pip
python -m pip install -e .
chmod +x scripts/s2t-shortcut

System tools:

sudo apt install alsa-utils xclip libnotify-bin

The current implementation records 16 kHz mono WAV files with arecord; it does not require ffmpeg.

2. Configure API Keys

cp .env.example .env

Then edit .env:

TENCENTCLOUD_SECRET_ID=...
TENCENTCLOUD_SECRET_KEY=...
TENCENTCLOUD_REGION=ap-guangzhou
TENCENT_ASR_ENGINE=16k_zh-PY

DEEPSEEK_API_KEY=...
DEEPSEEK_MODEL=deepseek-v4-flash
DEEPSEEK_BASE_URL=https://api.deepseek.com

scripts/s2t-shortcut loads .env from the project directory automatically, which is more reliable than depending on desktop shortcuts to inherit your shell environment.

DeepSeek has announced that the legacy model names deepseek-chat and deepseek-reasoner will stop working on 2026-07-24. This project uses deepseek-v4-flash by default.

3. Commands

scripts/s2t-shortcut record-toggle
scripts/s2t-shortcut clean
scripts/s2t-shortcut summary --style brief
scripts/s2t-shortcut summary --style detailed
scripts/s2t-shortcut status

You can also test Tencent ASR with an existing WAV file:

scripts/s2t-shortcut transcribe-file /path/to/audio.wav

4. Ubuntu Shortcut Setup

Add custom shortcuts in Settings -> Keyboard -> View and Customize Shortcuts -> Custom Shortcuts.

If you are already in the project directory, test these commands first:

./scripts/s2t-shortcut record-toggle
./scripts/s2t-shortcut clean
./scripts/s2t-shortcut summary --style brief
./scripts/s2t-shortcut summary --style detailed

Ubuntu custom shortcuts usually need absolute paths. Run pwd in the project directory, then replace <project-dir> with that path:

Purpose	Command
Start/stop recording and ASR	<project-dir>/scripts/s2t-shortcut record-toggle
Clean clipboard text	<project-dir>/scripts/s2t-shortcut clean
Brief organized text	<project-dir>/scripts/s2t-shortcut summary --style brief
Detailed organized text	<project-dir>/scripts/s2t-shortcut summary --style detailed

Suggested shortcuts:

• Ctrl+Alt+R: recording toggle
• Ctrl+Alt+C: clean text
• Ctrl+Alt+B: brief organized text
• Ctrl+Alt+D: detailed organized text

5. Behavior and Limits

• Recordings are stored under /tmp/speech2text-<uid>/recordings/ by default.
• The latest result is stored at /tmp/speech2text-<uid>/last_result.json by default.
• History is appended to /tmp/speech2text-<uid>/history.jsonl by default.
• Set S2T_CACHE_DIR if you want to use another location.
• Tencent one-sentence ASR is checked locally with a default limit of 60 seconds and 3 MB. You can adjust the local checks with S2T_MAX_SECONDS and S2T_MAX_BYTES, but Tencent Cloud still enforces its own service limits.
• The tool writes to the clipboard only. It does not auto-paste into the current window, which avoids desktop focus issues.