wyoming-whisper-rs/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

whisper-rs provides safe Rust bindings to whisper.cpp, a C++ speech recognition library. It's a two-crate workspace:

• whisper-rs (root) — Safe public API
• whisper-rs-sys (sys/) — FFI bindings generated via bindgen, with a CMake-based build of the whisper.cpp submodule

The upstream C++ source lives in sys/whisper.cpp/ (git submodule — clone with --recursive).

Build Commands

cargo build                                    # Default build
cargo build --release --features vulkan        # With Vulkan GPU support
cargo build --release --features hipblas       # With AMD ROCm support
cargo build --release --features cuda          # With NVIDIA CUDA support
cargo test                                     # Run all tests
cargo fmt                                      # Format code
cargo clippy                                   # Lint

Running examples (require a GGML model file and a WAV audio file):

cargo run --example basic_use -- model.bin audio.wav
cargo run --example audio_transcription -- model.bin audio.wav
cargo run --example vad -- model.bin audio.wav output.wav

Skipping bindgen (use pre-generated bindings): set WHISPER_DONT_GENERATE_BINDINGS=1.

All WHISPER_* and CMAKE_* env vars are forwarded to the CMake build.

Architecture

whisper-rs (safe Rust API)
  → whisper-rs-sys (bindgen FFI)
    → whisper.cpp (C++ submodule, built via CMake)
      → GGML (tensor library with CPU/GPU backends)

Key types and their relationships:

• WhisperContext — Arc-wrapped model handle, thread-safe, created from a model file
• WhisperState — Inference state created from a context; multiple states can share one context
• FullParams — Transcription configuration (sampling strategy, language, callbacks)
• WhisperSegment / WhisperToken — Result types with timestamps and probabilities

Core flow: WhisperContext::new_with_params() → ctx.create_state() → state.full(params, &audio_data) → iterate segments via state.as_iter()

Module layout in src/:

• whisper_ctx.rs — Raw context wrapper (WhisperInnerContext)
• whisper_ctx_wrapper.rs — Safe public WhisperContext
• whisper_state/ — State management, segments, tokens, iterators
• whisper_params.rs — FullParams, SamplingStrategy (Greedy / BeamSearch)
• whisper_vad.rs — Voice Activity Detection
• whisper_grammar.rs — GBNF grammar-constrained decoding
• vulkan.rs — Vulkan device enumeration (behind vulkan feature)

Build System (sys/build.rs)

The build script:

1. Copies whisper.cpp sources into OUT_DIR
2. Runs bindgen on wrapper.h to generate FFI bindings (falls back to src/bindings.rs on failure)
3. Configures and builds whisper.cpp via CMake with feature-dependent flags (GGML_CUDA, GGML_HIP, GGML_VULKAN, GGML_METAL, etc.)
4. Statically links: whisper, ggml, ggml-base, ggml-cpu, plus backend-specific libs

Feature Flags

Feature	Purpose
cuda	NVIDIA GPU (needs CUDA toolkit)
hipblas	AMD GPU via ROCm
metal	Apple Metal GPU
vulkan	Vulkan GPU
openblas	OpenBLAS acceleration (requires BLAS_INCLUDE_DIRS env var)
openmp	OpenMP threading
coreml	Apple CoreML
intel-sycl	Intel SYCL
raw-api	Re-export whisper-rs-sys types publicly
log_backend	Route C++ logs to the log crate
tracing_backend	Route C++ logs to the tracing crate

Nix Development Environment

The flake.nix provides a devshell with all dependencies for Vulkan and ROCm/hipBLAS builds. Use direnv allow or nix develop to enter the environment. Key env vars (LIBCLANG_PATH, BINDGEN_EXTRA_CLANG_ARGS, HIP_PATH, VULKAN_SDK) are set automatically.

PR Conventions

Per .github/PULL_REQUEST_TEMPLATE.md:

• Run cargo fmt and cargo clippy before submitting
• Self-review code for legibility
• No GenAI-generated code in PRs