{
  "kind": "recipe",
  "id": "voice",
  "title": "Speech to text",
  "what": "Turn meetings and voice notes into text, offline.",
  "html": "https://insidethemachine.ai/do/voice",
  "md": "https://insidethemachine.ai/do/voice.md",
  "json": "https://insidethemachine.ai/do/voice.json",
  "memory": {
    "min_gb": 8,
    "good_gb": 16
  },
  "minutes": 10,
  "platform_priority": [
    "macos-apple-silicon",
    "linux",
    "windows"
  ],
  "tools": [
    {
      "slug": "whisper-cpp",
      "name": "whisper.cpp",
      "md": "https://insidethemachine.ai/setups/whisper-cpp.md"
    },
    {
      "slug": "handy",
      "name": "Handy",
      "md": "https://insidethemachine.ai/setups/handy.md"
    }
  ],
  "placeholders": {
    "{MODEL}": null,
    "{WHISPER}": {
      "under_16_gb": "base.en",
      "from_16_gb": "large-v3-turbo"
    }
  },
  "model_by_memory_gb": null,
  "frontier": {
    "name": "Claude Opus 5.5",
    "aa": 57.6
  },
  "tested": "Run end to end on an Apple M4 Mac with 16 GB on 2026-10-15.",
  "recipe": {
    "id": "voice",
    "get": "Accurate speech-to-text for meetings, interviews and voice notes, without sending audio anywhere.",
    "model": "whisper",
    "steps": [
      {
        "title": "Install the build tools",
        "body": "whisper.cpp is built on your computer. These tools do that. Skip the first line if you already have it.",
        "cmds": [
          {
            "run": "xcode-select --install"
          },
          {
            "run": "brew install cmake ffmpeg",
            "note": "Needs Homebrew (brew.sh)"
          }
        ]
      },
      {
        "title": "Get whisper.cpp and a voice model",
        "body": "The voice model turns sound into words.",
        "cmds": [
          {
            "run": "git clone https://github.com/ggml-org/whisper.cpp.git && cd whisper.cpp"
          },
          {
            "run": "sh ./models/download-ggml-model.sh {WHISPER}"
          }
        ]
      },
      {
        "title": "Build it",
        "body": "This takes a minute or two.",
        "cmds": [
          {
            "run": "cmake -B build && cmake --build build -j --config Release"
          }
        ]
      },
      {
        "title": "Test it",
        "body": "It comes with a short sample speech.",
        "cmds": [
          {
            "run": "./build/bin/whisper-cli -m models/ggml-{WHISPER}.bin -f samples/jfk.wav"
          }
        ],
        "expect": "It prints the words of the sample speech."
      },
      {
        "title": "Use your own audio",
        "body": "whisper.cpp reads 16-bit WAV files. Convert your file first, then transcribe it to a text file.",
        "cmds": [
          {
            "run": "ffmpeg -i input.m4a -ar 16000 -ac 1 -c:a pcm_s16le output.wav"
          },
          {
            "run": "./build/bin/whisper-cli -m models/ggml-{WHISPER}.bin -f output.wav -otxt"
          }
        ],
        "expect": "output.wav.txt has your transcript."
      }
    ],
    "alt": {
      "slug": "handy",
      "title": "Want to dictate instead? Use Handy.",
      "body": "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.",
      "href": "/setups/handy"
    },
    "undo": [
      {
        "run": "cd .. && rm -rf whisper.cpp",
        "note": "Removes the code, the build and the voice model"
      },
      {
        "run": "brew uninstall cmake",
        "note": "Only if you installed it for this"
      }
    ],
    "know": [
      "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."
    ],
    "fix": [
      {
        "q": "An “xcrun: error” when you build",
        "a": "The build tools are missing. Run `xcode-select --install` again and finish the window that opens."
      },
      {
        "q": "“cmake: command not found”",
        "a": "Run `brew install cmake`, then build again."
      },
      {
        "q": "It cannot read your audio file",
        "a": "whisper.cpp needs a 16-bit WAV file. Convert your file with the ffmpeg line in step 5 first."
      }
    ],
    "after": [
      "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)."
    ],
    "win": {
      "body": "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."
    },
    "tested": "Run end to end on an Apple M4 Mac with 16 GB on 2026-10-15."
  }
}