# Setup — faster-whisper on your own machine

*These are the literal steps used to build and prove this Forge entry
on a small Linux server (2026-10-23). You need Python 3.9+ and about
500 MB of disk. No GPU. No account. No API key.*

## Install

```bash
python3 -m venv stt
./stt/bin/pip install faster-whisper==1.2.1 av==13.1.0
```

- `faster-whisper==1.2.1` — the engine (MIT, https://github.com/SYSTRAN/faster-whisper).
- The `av==13.1.0` pin matters: faster-whisper decodes audio through
  PyAV, and the newest PyAV at time of writing changed an API it uses.
  The pin is the known-good combination; if a future faster-whisper
  fixes the clash, the pin can go.

## Transcribe a file

Save this as `transcribe.py` next to the venv:

```python
import sys
from faster_whisper import WhisperModel

model = WhisperModel("base", device="cpu", compute_type="int8")
segments, info = model.transcribe(sys.argv[1], beam_size=5)
print("language:", info.language, f"({info.language_probability:.0%})")
for s in segments:
    print(s.text)
```

Run it:

```bash
./stt/bin/python transcribe.py my-recording.m4a
```

- First run downloads the `base` model (~140 MB) into a local cache;
  after that it works offline.
- Accepts the formats your phone records (m4a, mp3, wav, ogg…).
- Swap `"base"` for `"small"` in the script for the accuracy step-up
  (a bigger download, slower, fewer wrong words). `"tiny"` is the
  speed step-down for a first smoke test.

## On this project

The same setup lives in the Bounded Agent Harness toolchain next to
our text-to-speech install (Kokoro, also MIT/Apache) — the two
together turn a paragraph into a voice and back into text with both
halves free and local. The transcript proof in the README and on the
Forge page came from this exact script.