@carlitose86/pi-telegram-stt

Local, pluggable speech-to-text for Pi Telegram voice notes (ports and adapters: whisper.cpp, any command).

Packages

Package details

extension

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-cpp and command engines, plus registerEngine() 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)

  1. Install whisper.cpp (whisper-cli) and ffmpeg.
  2. Download a GGML model of your choice, for example ggml-large-v3-turbo.bin (best quality) or ggml-small.bin (faster), from the whisper.cpp models page.
  3. 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