@carlitose86/pi-telegram-stt
v0.1.0
Published
Local, pluggable speech-to-text for Pi Telegram voice notes (ports and adapters: whisper.cpp, any command).
Maintainers
Readme
pi-telegram-stt
Local, pluggable speech-to-text for Pi Telegram Reactive: send a voice note from Telegram and it is transcribed on your own PC into the Pi prompt, with the engine and model you choose.
- Audio never leaves your machine (unless you configure a command that sends it).
- Nothing is downloaded automatically: you install the engine and pick the model.
- Language is auto-detected by the model; you can force one.
- Ports and adapters: built-in
whisper-cppandcommandengines, plusregisterEngine()for third-party engines.
Install
Requires @carlitose86/pi-telegram-reactive connected in Pi.
pi install npm:@carlitose86/pi-telegram-stt
# or from Git
pi install git:github.com/carlitose/pi-telegram-sttThen /reload Pi.
Configure
Create ~/.pi/agent/telegram-stt.json (or $PI_CODING_AGENT_DIR/telegram-stt.json). It is read on every voice note, so edits apply without reload. Without this file the package stays passive.
whisper.cpp (recommended)
- Install whisper.cpp (
whisper-cli) and ffmpeg. - Download a GGML model of your choice, for example
ggml-large-v3-turbo.bin(best quality) orggml-small.bin(faster), from the whisper.cpp models page. - Configure:
{
"engine": "whisper-cpp",
"engines": {
"whisper-cpp": {
"binary": "whisper-cli",
"model": "C:/models/ggml-large-v3-turbo.bin",
"threads": 4
}
}
}binary and ffmpeg accept an executable name on PATH, an absolute path, or an argv array (for example ["wsl", "whisper-cli"]).
Any other engine (command)
Use any program that prints the transcript on stdout. Placeholders: {file} original audio, {wav} 16 kHz mono WAV (converted with ffmpeg), {language} optional hint (dropped when empty). No shell is involved.
{
"engine": "command",
"engines": {
"command": { "template": ["my-stt", "--input", "{wav}", "--lang", "{language}"] }
}
}Common options
| Key | Default | Meaning |
| --- | --- | --- |
| engine | — | whisper-cpp, command, or a third-party engine id |
| language | auto-detect | Force a language code such as it |
| timeoutMs | 120000 | Per-step timeout; the process is killed when exceeded |
Check
Run /telegram-stt-status in Pi: it shows the selected engine and why it is not ready (missing binary, ffmpeg, or model).
Operator-configured inboundHandlers in telegram.json still take priority; this package is the bridge's registered transcription provider fallback.
Add an engine
import { registerEngine, type SttEngine } from "@carlitose86/pi-telegram-stt";
registerEngine("my-engine", (options): SttEngine => ({
id: "my-engine",
isAvailable: async () => ({ ok: true }),
isReady: async () => ({ ok: true }),
transcribe: async ({ path, language }) => ({ text: await myTranscribe(path, language) }),
}));Then set "engine": "my-engine"; options come from engines["my-engine"].
Design
See docs/specs/local-stt-adapters.md. The port idea is inspired by FluidVoice's TranscriptionProvider; no code is copied.
License
MIT
