kingbootoshi

Whisper Stream Server

Name: Whisper Stream Server
Author: kingbootoshi

AI community

SOURCE https://github.com/kingbootoshi/whisper-stream-server

Description

Transcribing audio using local dictation via whisper.cpp for use in AI apps.

Installation

This entry records only its repository, not the path inside it, so there is no exact command to give. Open the source below and copy the folder into ~/.claude/skills/, or the file into ~/.claude/agents/.

README

Local Mac Audio Transcription

Real-time speech-to-text transcription server using [whisper.cpp](https://github.com/ggerganov/whisper.cpp) with WebSocket streaming. Optimized for Apple Silicon with Metal GPU acceleration.

Features

Real-time streaming transcription via WebSocket
Batch transcription via HTTP WAV upload (POST /v1/transcribe)
Voice Activity Detection (VAD) - automatically detects speech end and emits final transcripts
Metal GPU acceleration on Apple Silicon (M1/M2/M3/M4)
Multi-client support with context pooling (configurable parallel sessions)
Low latency (~300-500ms inference on M-series chips)
24/7 operation - designed for always-on deployments via launchd

Quick Start

Prerequisites

macOS with Apple Silicon (M1/M2/M3/M4)
CMake 3.14+
Xcode Command Line Tools

# Install build tools
brew install cmake
xcode-select --install

# Clone this repo
git clone https://github.com/kingbootoshi/local-mac-audio-transcription.git
cd local-mac-audio-transcription

Build

./scripts/build.sh

The build script uses CMake FetchContent to automatically download whisper.cpp. No manual cloning required.

Run

./scripts/run.sh

Or with custom options:

./build/whisper-stream-server \
  --model models/ggml-base.en.bin \
  --vad-model models/ggml-silero-vad.bin \
  --port 9090 \
  --contexts 2

Test with Browser Client

cd examples/web-client
npm install
npm run dev

Open http://localhost:5173, click **Connect**, then **Start Recording**.

Project Structure

local-mac-audio-transcription/
├── src/                        # C++ server source
│   ├── main.cpp               # Entry point, WebSocket handlers
│   ├── whisper_server.cpp     # Core transcription + VAD logic
│   ├── whisper_server.hpp
│   ├── audio_buffer.cpp       # Thread-safe audio buffer
│   ├── audio_buffer.hpp
│   └── json.hpp               # nlohmann/json (auto-downloade