# Recipe: Speech to text

Accurate speech-to-text for meetings, interviews and voice notes, without sending audio anywhere.

URL: https://insidethemachine.ai/do/voice
Memory: needs 8 GB+, best with 16 GB+. Platform: macOS (Apple silicon) first.
Run end to end on an Apple M4 Mac with 16 GB on 2026-10-15.

## Voice model (replace {WHISPER})

- under 16 GB: base.en
- 16 GB+: large-v3-turbo

## Steps

1. **Install the build tools**: whisper.cpp is built on your computer. These tools do that. Skip the first line if you already have it.
   ```sh
   xcode-select --install
   ```
   ```sh
   brew install cmake ffmpeg
   ```
   (Needs Homebrew (brew.sh))
2. **Get whisper.cpp and a voice model**: The voice model turns sound into words.
   ```sh
   git clone https://github.com/ggml-org/whisper.cpp.git && cd whisper.cpp
   ```
   ```sh
   sh ./models/download-ggml-model.sh {WHISPER}
   ```
3. **Build it**: This takes a minute or two.
   ```sh
   cmake -B build && cmake --build build -j --config Release
   ```
4. **Test it**: It comes with a short sample speech.
   ```sh
   ./build/bin/whisper-cli -m models/ggml-{WHISPER}.bin -f samples/jfk.wav
   ```
   Expect: It prints the words of the sample speech.
5. **Use your own audio**: whisper.cpp reads 16-bit WAV files. Convert your file first, then transcribe it to a text file.
   ```sh
   ffmpeg -i input.m4a -ar 16000 -ac 1 -c:a pcm_s16le output.wav
   ```
   ```sh
   ./build/bin/whisper-cli -m models/ggml-{WHISPER}.bin -f output.wav -otxt
   ```
   Expect: output.wav.txt has your transcript.

## Alternative

Want to dictate instead? Use Handy. Handy is a free app. Hold a key, talk, and your words are typed into any app. It runs offline. Download it from handy.computer. (https://insidethemachine.ai/setups/handy)

## Rollback

- `cd .. && rm -rf whisper.cpp` (Removes the code, the build and the voice model)
- `brew uninstall cmake` (Only if you installed it for this)

## One-command install

```bash
curl -fsSL https://insidethemachine.ai/install/voice.sh | bash             # install, then check
curl -fsSL https://insidethemachine.ai/install/voice.sh | bash -s -- plan     # print only
curl -fsSL https://insidethemachine.ai/install/voice.sh | bash -s -- rollback --yes
```

Run status and Windows: https://insidethemachine.ai/install/voice.md. The script picks {MODEL} from the machine's memory (override: ITM_RAM, ITM_MODEL).

## Notes

- Needs about 2 GB of free disk space.
- Models ending in .en are English only and a bit faster.
- On a 16 GB M4 Mac, a short clip took under 2 seconds.
- Long files take time. A Mac with more memory can use the bigger, more accurate model.

## If something goes wrong

- An “xcrun: error” when you build: The build tools are missing. Run `xcode-select --install` again and finish the window that opens.
- “cmake: command not found”: Run `brew install cmake`, then build again.
- It cannot read your audio file: whisper.cpp needs a 16-bit WAV file. Convert your file with the ffmpeg line in step 5 first.

## After it works

- Try it: record a voice note on your phone, send it to your Mac, convert it and transcribe it.
- Want subtitles? Add `-osrt` to the whisper-cli line to make a subtitle file.
- For typing by voice in any app, try Handy (the box above).

## Windows / Linux (not tested by us)

On Linux, the same steps work. Install cmake and ffmpeg with your package manager instead of brew. On Windows, the Handy app (handy.computer) is the easiest way to start.