The Problem

Desktop‑style dictation on the Raspberry Pi is limited to cloud services or heavyweight desktop apps. Users who need a fast, offline, keyboard‑driven transcription tool must set up a full‑stack solution, which adds latency and complexity.

What This Does

pi-transcribe provides a Pi‑native extension that captures audio, runs a local speech‑to‑text model, and injects the result into the Pi editor. The core logic lives in src/:

  • src/index.ts – registers the terminal shortcut, parses the /transcribe command, and orchestrates settings, model selection and the capture lifecycle.
  • src/audio.ts – wraps the microphone API, converts raw frames, and exposes start/stop used by the shortcut handler.
  • src/catalog.generated.ts – a 2 868‑line generated list of available models and languages (the current high‑risk “oversized file”).

Configuration lives in src/settings.ts and the UI for choosing models, microphones and Chinese‑output options is split across src/settings-menu.ts, src/model-picker.ts and src/shortcuts.ts.

How It Is Wired

Execution begins when the user presses the registered shortcut (default Ctrl‑Alt‑Z). The shortcut handler (defined in src/index.ts → toggleCapture) calls ensureSettings → configureFirstRun → configureModel. Those functions read/write the JSON settings file via src/settings.ts (readSettings, writeSettings).

If a capture is not active, toggleCapture creates a CapturedAudio instance (new CapturedAudio() in src/audio.ts) and calls its start method. start registers a frame‑read loop that eventually invokes handleInput → refresh (13 calls) and updates the on‑screen level meter (src/visualizer.ts).

When the user stops recording, stopAndTranscribe (also in src/index.ts) calls showTranscribeStatus, which constructs a TranscriptionBackend (src/transcription.ts). The backend's transcribe method selects the appropriate model from src/catalog.ts (via canonicalLanguage, modelSupportsLanguage) and streams audio to the model. The result is inserted at the editor cursor by the Pi extension runtime (outside this repo).

Key functions with the widest blast radius:

  • ensureSettings – reaches 30 functions, called from two places.
  • toggleCapture – reaches 47 functions, called from one place.
  • canonicalLanguage – called from 7 distinct locations, central to language resolution.

The most connected modules are src/settings (6 inbound, 2 outbound imports) and src/catalog (5 inbound, 1 outbound). No circular dependencies were detected, which simplifies isolated changes.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/pi-transcribe
cd pi-transcribe

# Install dependencies (npm is the package manager)
npm install --ignore-scripts

# Register the extension with Pi (replace with your Pi install path)
pi -e /absolute/path/to/pi-transcribe

The extension automatically creates ~/.config/pi-transcribe/settings.json on first run. No additional environment variables are required. To change the shortcut or default model, edit src/settings.ts or use the /transcribe command inside Pi as documented in the README.

Real‑World Use

A developer working on a Pi‑based kiosk can add the extension, press Ctrl‑Alt‑Z, dictate a log entry, and have it appear instantly in the editor without leaving the device or exposing audio to external services. The flow is entirely local: microphone → src/audio.ts → model selected from catalog.generated.ts → transcription → editor insertion.

Code Health & Issues

  • High – No test suite – 16 source files, zero test files.
  • High – No CI pipeline – No .github/workflows or similar; builds are never automatically verified.
  • Medium – No Dependabot – Only package.json/package-lock.json present; no automated dependency updates.
  • High – Oversized generated file – src/catalog.generated.ts (2 868 lines) is a maintenance hotspot; consider splitting by language or model.
  • Medium – Duplicated logic – Repeated 6‑line blocks in src/model-picker.ts and src/shortcuts.ts; extract to a shared helper.

The Bottom Line

pi-transcribe delivers a functional offline dictation experience for the Pi, with a clear shortcut‑driven workflow and a modest codebase. However, the lack of tests, CI and automated dependency management makes the project risky for production use. Engineers should prioritize adding a test harness, CI pipeline, and refactoring the large generated catalog before extending the code.