refactor(whisper): modularize crate into folder-based modules

Refactor keyless-whisper crate to follow modern Rust module organization:

- Split lib.rs into focused modules: config, device, transcriber, whisper
- Modularize decode.rs into decode/ folder with submodules: constants, fallback, helpers, language, result, temperature
- Modularize model.rs into model/ folder with submodules: files, loader, mel_filters, types
- Modularize whisper.rs into whisper/ folder with submodules: construct, inference_thread, worker_thread, trait_impl, types
- Move mel filter generation from preprocessing.rs to model/mel_filters.rs (model-specific logic)
- Update README.md to document new module structure

Author: hate

keyless-whisper/README.md

@@ -190,11 +190,30 @@ Unit tests cover preprocessing and token filtering. Full model inference is exer
 
 ### Module structure
 
-- `src/lib.rs`: threading, public API, event channels, rubato resampling
-- `src/model.rs`: model/tokenizer download and load
-- `src/preprocessing.rs`: mel filter generation and PCM→mel
-- `src/decode.rs`: token generation/decoding
-- `src/inference.rs`: end‑to‑end inference pipeline
+- `src/lib.rs`: Public API re-exports and module declarations
+- `src/config.rs`: Configuration types (`WhisperConfig`, `WhisperLoadPhase`, `PhaseState`)
+- `src/device.rs`: Device selection and caching (Metal > CUDA > CPU)
+- `src/transcriber.rs`: `RealtimeTranscriber` trait definition
+- `src/whisper.rs`: Main `Whisper` transcriber implementation
+  - `whisper/construct.rs`: Construction and initialization
+  - `whisper/inference_thread.rs`: Inference thread (runs Whisper model)
+  - `whisper/worker_thread.rs`: Worker thread (resampling, accumulation, partial previews)
+  - `whisper/trait_impl.rs`: Trait implementations (`RealtimeTranscriber`, `Drop`)
+  - `whisper/types.rs`: Type definitions (`Whisper`, `WhisperCmd`, `InferReq`)
+- `src/model.rs`: Model loading and management
+  - `model/loader.rs`: Model loading with progress callbacks
+  - `model/mel_filters.rs`: Mel filter bank generation
+  - `model/files.rs`: File detection and location helpers
+  - `model/types.rs`: Model type definitions (`Model`, `WhisperModel`, `WhisperTokens`)
+- `src/decode.rs`: Token generation and text decoding
+  - `decode/fallback.rs`: Temperature fallback decoding
+  - `decode/language.rs`: Language detection from audio features
+  - `decode/temperature.rs`: Single-temperature decoding
+  - `decode/helpers.rs`: Helper functions (token decoding, repetition detection)
+  - `decode/constants.rs`: Decoding constants (thresholds, temperatures)
+  - `decode/result.rs`: Decoding result type with quality metrics
+- `src/preprocessing.rs`: PCM→mel spectrogram conversion (uses pre-generated mel filters)
+- `src/inference.rs`: End‑to‑end inference pipeline
 
 ### Platform support (macOS, Windows, Linux)
 

keyless-whisper/src/config.rs

@@ -0,0 +1,82 @@
+use std::path::PathBuf;
+
+/// Loading phase identifiers for Whisper model initialization.
+#[derive(Clone, Copy, Debug)]
+pub enum WhisperLoadPhase {
+    /// Resolving model source (local cache path or remote HF ID).
+    ModelSource,
+    /// Detecting model format (safetensors vs. gguf quantized).
+    DetectFormat,
+    /// Reading model configuration (config.json).
+    ReadConfig,
+    /// Parsing model configuration JSON.
+    ParseConfig,
+    /// Mapping model weights into memory (mmap or gguf loader).
+    MapWeights,
+    /// Constructing model layers/graph.
+    ConstructModel,
+    /// Loading tokenizer JSON.
+    LoadTokenizer,
+    /// Resolving special token IDs (SOT/EOT/etc.).
+    ResolveTokens,
+    /// Building mel filter bank.
+    BuildMelFilters,
+}
+
+impl WhisperLoadPhase {
+    /// Return a user-facing label for this phase.
+    pub fn as_label(&self) -> &'static str {
+        match self {
+            WhisperLoadPhase::ModelSource => "locating model",
+            WhisperLoadPhase::DetectFormat => "detecting model format",
+            WhisperLoadPhase::ReadConfig => "reading config",
+            WhisperLoadPhase::ParseConfig => "parsing config",
+            WhisperLoadPhase::MapWeights => "mapping weights",
+            WhisperLoadPhase::ConstructModel => "constructing model",
+            WhisperLoadPhase::LoadTokenizer => "loading tokenizer",
+            WhisperLoadPhase::ResolveTokens => "resolving tokens",
+            WhisperLoadPhase::BuildMelFilters => "building mel filters",
+        }
+    }
+}
+
+/// Loading phase state (begin/end).
+#[derive(Clone, Copy, Debug)]
+pub enum PhaseState {
+    /// Phase begins.
+    Begin,
+    /// Phase ends successfully.
+    End,
+}
+
+/// Configuration for the Whisper transcriber.
+///
+/// Specifies the model source, language hint, and source audio sample rate.
+/// The transcriber will handle model downloading and resampling automatically.
+#[derive(Clone, Debug)]
+pub struct WhisperConfig {
+    /// Model source: either a Hugging Face model ID or a local directory path.
+    ///
+    /// **Hugging Face model IDs** (auto-downloads if not cached):
+    /// - "openai/whisper-tiny" (~75 MB, fastest, multilingual, supports auto-detection)
+    /// - "openai/whisper-base" (~142 MB, balanced, multilingual, supports auto-detection)
+    /// - "openai/whisper-small" (~466 MB, good accuracy, multilingual)
+    /// - "openai/whisper-tiny.en" (~75 MB, fastest, English-only)
+    /// - "openai/whisper-base.en" (~142 MB, balanced, English-only)
+    /// - ...
+    ///
+    /// **Local directory paths** (must contain config.json, model.safetensors, tokenizer.json):
+    /// - Example: "/Users/name/.cache/keyless/models/whisper-tiny"
+    ///
+    /// If not specified or if the path doesn't exist, defaults to "openai/whisper-tiny".
+    pub model_path: PathBuf,
+
+    /// Language code for transcription (ISO 639-1, e.g., "en", "es", "fr").
+    /// Providing a hint significantly improves accuracy vs. auto-detection.
+    /// `None` = let Whisper auto-detect (slower and less accurate).
+    pub language: Option<String>,
+
+    /// Sample rate of the incoming audio (e.g., 48000, 44100, 16000).
+    /// The transcriber will resample to 16 kHz mono if necessary.
+    pub source_sample_hz: u32,
+}