@carlitose86/pi-telegram-stt
Local, pluggable speech-to-text for Pi Telegram voice notes (ports and adapters: whisper.cpp, any command).
Package details
Install @carlitose86/pi-telegram-stt from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:@carlitose86/pi-telegram-stt- Package
@carlitose86/pi-telegram-stt- Version
0.1.0- Published
- Nov 14, 2026
- Downloads
- 328/mo · 328/wk
- Author
- carlitose86
- License
- MIT
- Types
- extension
- Size
- 27.5 KB
- Dependencies
- 1 dependency · 1 peer
Pi manifest JSON
{
"extensions": [
"./dist/extension.js"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
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-stt
Then /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