Whisper Stream RS

https://docs.rs/whisper-stream-rs/latest/
Admin
A Rust library for performing real-time transcription using Whisper ASR models with audio capture,...
Tokens:54,869
Snippets:461
Trust Score:9.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### Starting WhisperStream

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/whisper_stream.rs.html?search=

Placeholder function to start the WhisperStream. The actual background thread will be initiated in a subsequent phase.

```rust
pub fn start(&mut self) -> Result<(), crate::error::WhisperStreamError> {
        // Will start the background thread in next phase
        Ok(())
    }
```

--------------------------------

### start_capture_16k

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/audio.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Starts audio capture, returning a `Receiver` for 16kHz mono f32 audio chunks. This is the primary method to get audio for Whisper ASR. `step_duration_ms` determines chunk size. In a spawned thread, it initializes the cpal input stream, sets up a resampler if needed, and continuously collects, converts, downmixes, resamples, and sends audio chunks.

```APIDOC
## start_capture_16k

### Description
Starts audio capture, returning a `Receiver` for 16kHz mono f32 audio chunks. This is the primary method to get audio for Whisper ASR. `step_duration_ms` determines chunk size. In a spawned thread, it initializes the cpal input stream, sets up a resampler if needed, and continuously collects, converts, downmixes, resamples, and sends audio chunks.

### Method
`pub fn start_capture_16k(&self) -> Receiver<Result<Vec<f32>, WhisperStreamError>>`

### Parameters
None

### Returns
A `Receiver` that yields `Result<Vec<f32>, WhisperStreamError>`.
- `Ok(Vec<f32>)`: A chunk of 16kHz mono f32 audio data.
- `Err(WhisperStreamError)`: An error encountered during audio capture or processing.
```

--------------------------------

### WhisperStream::start()

Source: https://docs.rs/whisper-stream-rs/latest/whisper_stream_rs/struct.WhisperStream.html?search=

Starts the Whisper transcription stream.

```APIDOC
## WhisperStream::start()

### Description
Begins the audio capture and transcription process for the configured stream.

### Method
`pub fn start(&mut self) -> Result<(), WhisperStreamError>`

### Parameters
None

### Returns
A `Result` indicating success or a `WhisperStreamError` if the stream fails to start.
```

--------------------------------

### Example Search Queries

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/whisper_stream.rs.html?search=

Illustrates common search query patterns used within the project, such as searching for standard library types, type conversions, and functional transformations on Option types.

```text
Example searches:
  * std::vec
  * u32 -> bool
  * Option<T>, (T -> U) -> Option<U>
```

--------------------------------

### Verify Device Access and Permissions

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/audio.rs.html?search=u32+-%3E+bool

Attempts to get the default input configuration again to verify that the device is accessible and permissions are correctly set. Returns an error if access fails.

```rust
if let Err(e) = device.default_input_config() {
            error!("[Audio] Failed to access device configuration: {}", e);
            return Err(WhisperStreamError::AudioDevice(
                format!("Failed to access device '{}'. Please check microphone permissions: {}", device_name, e)
            ));
        }
```

--------------------------------

### Start WhisperStream

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/whisper_stream.rs.html

Initiates the WhisperStream process. The actual background thread startup is handled in a subsequent phase.

```rust
pub fn start(&mut self) -> Result<(), crate::error::WhisperStreamError> {
            // Will start the background thread in next phase
            Ok(())
        }
```

--------------------------------

### Starting WhisperStream in Rust

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/whisper_stream.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

This method is intended to start the background thread for the WhisperStream. The actual thread startup is deferred to a later phase.

```rust
347    pub fn start(&mut self) -> Result<(), crate::error::WhisperStreamError> {
348        // Will start the background thread in next phase
349        Ok(())
350    }
```

--------------------------------

### WhisperStream::start

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/whisper_stream.rs.html

Starts the WhisperStream background processing thread.

```APIDOC
## WhisperStream::start

### Description
Initiates the background thread responsible for processing audio and performing speech-to-text transcription. This method should be called after configuring the `WhisperStream`.

### Method
`start()`

### Returns
A `Result` indicating success (`Ok(())`) or a `WhisperStreamError` if the stream fails to start.
```

--------------------------------

### Start WhisperStream

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/whisper_stream.rs.html?search=std%3A%3Avec

Initiates the WhisperStream process, typically starting background threads for audio processing and transcription.

```APIDOC
## WhisperStream::start()

### Description
Starts the WhisperStream. This method is expected to initiate any necessary background threads for audio processing and transcription.

### Method
`start()`

### Returns
- `Result<(), crate::error::WhisperStreamError>`: A `Result` indicating success or failure. An error may occur if the stream cannot be started due to configuration issues or resource unavailability.
```

--------------------------------

### WhisperStream::start

Source: https://docs.rs/whisper-stream-rs/latest/whisper_stream_rs/struct.WhisperStream.html?search=std%3A%3Avec

Starts the Whisper transcription stream.

```APIDOC
## WhisperStream::start

### Description
Begins the audio capture and transcription process using the configured WhisperStream.

### Method
`pub fn start(&mut self) -> Result<(), WhisperStreamError>`

### Returns
A `Result` indicating success or a `WhisperStreamError` if the stream fails to start.
```

--------------------------------

### Basic Rust Functionality Example

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/whisper_stream.rs.html?search=

Demonstrates a simple Rust function that returns Ok(()) to indicate success. This is often used as a placeholder or for functions that don't need to return specific data.

```rust
fn main() {
    // Will stop the background thread in next phase
    Ok(())
}

```

--------------------------------

### WhisperStream::start

Source: https://docs.rs/whisper-stream-rs/latest/whisper_stream_rs/struct.WhisperStream.html

Starts the Whisper transcription stream.

```APIDOC
## WhisperStream::start

### Description
Begins the audio capture and transcription process using the configured Whisper stream.

### Method
`pub fn start(&mut self) -> Result<(), WhisperStreamError>`

### Parameters
- `&mut self`: A mutable reference to the `WhisperStream` instance.

### Returns
A `Result` indicating success (`Ok(())`) or failure (`Err(WhisperStreamError)`) if the stream could not be started.
```

--------------------------------

### WhisperStream::start

Source: https://docs.rs/whisper-stream-rs/latest/whisper_stream_rs/struct.WhisperStream.html?search=u32+-%3E+bool

Starts the Whisper transcription stream.

```APIDOC
## WhisperStream::start

### Description
Begins the audio transcription process using the configured WhisperStream. This method should be called after the stream has been built and configured.

### Method
`start(&mut self)`

### Returns
`Result<(), WhisperStreamError>` - Ok(()) on success, or a WhisperStreamError if the stream fails to start.
```

--------------------------------

### Get Model Download URL

Source: https://docs.rs/whisper-stream-rs/latest/whisper_stream_rs/enum.Model.html?search=u32+-%3E+bool

Provides the direct download URL for the model. Use this to fetch model files.

```rust
pub fn url(&self) -> &'static str
```

--------------------------------

### Get Default Input Config and Check Supported Configurations

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/audio.rs.html

Retrieves the default input audio configuration for a device and iterates through supported configurations, logging their details. This is useful for understanding device capabilities before setting up the audio stream.

```rust
        let mut config = device
            .default_input_config()
            .map_err(WhisperStreamError::from)?;

        // Try to get supported configs for this device specifically
        info!("[Audio] Checking supported configurations for device: {}", device_name);
        if let Ok(supported_configs) = device.supported_input_configs() {
            for supported_config in supported_configs {
                info!("[Audio] - Supported: Rate {:?}, Channels {}, Format {{:?}}",
                    supported_config.min_sample_rate()..=supported_config.max_sample_rate(),
                    supported_config.channels(),
                    supported_config.sample_format()
                );
            }
        }

        let sample_rate = config.sample_rate().0;
        let channels = config.channels();

        info!("[Audio] Attempting to use device: {}", device_name);
        info!("[Audio] Selected config: SampleRate({}), Channels({}), Format({{}}){{",
            sample_rate, channels, config.sample_format());

        // Try to verify device access
        info!("[Audio] Verifying device access...");
        if let Err(e) = device.default_input_config() {
            error!("[Audio] Failed to access device configuration: {{}}", e);
            return Err(WhisperStreamError::AudioDevice(
                format!("Failed to access device '{}'. Please check microphone permissions: {{}}", device_name, e)
            ));
        }
        info!("[Audio] Successfully verified device access");

        if channels != 1 {
            warn!("[Audio][Warning] Source input device '{}' has {} channels. It will be downmixed to mono.", device_name, channels);
        }

        Ok(Self {
            device_name,
            sample_rate,
            channels,
            step_duration_ms: step_ms,
        })
```

--------------------------------

### Verify Audio Device Access

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/audio.rs.html?search=

Attempts to get the default input configuration to verify that the audio device is accessible and can be configured. Returns an error if access fails.

```rust
if let Err(e) = device.default_input_config() {
            error!("[Audio] Failed to access device configuration: {{}}", e);
            return Err(WhisperStreamError::AudioDevice(
                format!("Failed to access device '{}'. Please check microphone permissions: {{}}", device_name, e)
            ));
        }
```

--------------------------------

### WhisperStream::start

Source: https://docs.rs/whisper-stream-rs/latest/whisper_stream_rs/struct.WhisperStream.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Starts the Whisper transcription stream. This method should be called after the stream has been configured and built.

```APIDOC
## WhisperStream::start

### Description
Begins the audio processing and transcription for the configured stream.

### Method
`start(&mut self)`

### Returns
- `Result<(), WhisperStreamError>`: An empty Result on success, or a `WhisperStreamError` if the stream fails to start.
```

--------------------------------

### Starting and Monitoring Audio Stream Playback

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/audio.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Attempts to play the created audio stream and enters a loop to monitor a stop signal. The stream is automatically stopped when it goes out of scope.

```rust
match stream_result {
    Ok(stream) => {
        info!("[Audio] Successfully created audio stream, attempting to start capture...");
        if let Err(e) = stream.play() {
            error!("[Audio] Failed to play stream for device: {} ({})", device_name_clone, e);
            let _ = tx.send(Err(WhisperStreamError::AudioDevice(format!("Failed to play stream: {}", e))));
            return;
        }
        info!("[Audio] Audio capture started successfully!");
        // Stream is playing; cpal callbacks handle audio processing.
        // This thread keeps alive to monitor stop_processing_signal.
        loop {
            if stop_processing_signal.load(Ordering::Relaxed) {
                debug!("[Audio] Stop signal received in main capture thread for device '{}'. Stream will be dropped.", device_name_clone);
                break;
            }
            std::thread::sleep(std::time::Duration::from_millis(100));
        }
        // Dropping `stream` here stops cpal callbacks.
    }
    Err(e) => {
        error!("[Audio] Failed to build input stream for device '{}': {}", device_name_clone, e);
        let _ = tx.send(Err(e));
        return;
    }
}

```

--------------------------------

### Get Default Input Audio Config

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/audio.rs.html?search=

Retrieves the default input audio configuration for a given device. This is a prerequisite for setting up an audio stream.

```rust
let config = device
            .default_input_config()
            .map_err(WhisperStreamError::from)?;
```

--------------------------------

### start_capture_16k

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/audio.rs.html

Starts audio capture from the configured audio device. It returns a Receiver that yields 16kHz mono f32 audio chunks. This is the primary method for obtaining audio data for ASR processing. The `step_duration_ms` parameter controls the size of the audio chunks.

```APIDOC
## start_capture_16k

### Description
Starts audio capture, returning a `Receiver` for 16kHz mono f32 audio chunks. This is the primary method to get audio for Whisper ASR. `step_duration_ms` determines chunk size. In a spawned thread, it initializes the cpal input stream, sets up a resampler if needed, and continuously collects, converts, downmixes, resamples, and sends audio chunks.

### Method
`pub fn start_capture_16k(&self) -> Receiver<Result<Vec<f32>, WhisperStreamError>>`

### Parameters
None directly on the method call, but relies on the `WhisperStreamer`'s configuration:
- `device_name`: The name of the audio input device to use.
- `step_duration_ms`: The duration in milliseconds for each audio chunk.
- `channels`: The number of audio channels to capture (will be forced to mono).
- `sample_rate`: The native sample rate of the audio device.

### Returns
A `Receiver` that yields `Result<Vec<f32>, WhisperStreamError>`. Each `Ok` variant contains a `Vec<f32>` representing a chunk of 16kHz mono audio data. Each `Err` variant contains a `WhisperStreamError` if an issue occurred during capture or processing.

### Example
```rust
use whisper_stream_rs::WhisperStreamer;
use std::sync::mpsc::Receiver;
use whisper_stream_rs::WhisperStreamError;

let streamer = WhisperStreamer::new(None, 100, 1, 16000);
let mut audio_receiver: Receiver<Result<Vec<f32>, WhisperStreamError>> = streamer.start_capture_16k();

// In another thread or async task:
// loop {
//     match audio_receiver.recv() {
//         Ok(Ok(audio_chunk)) => {
//             // Process audio_chunk (Vec<f32>)
//             println!("Received audio chunk of size: {}", audio_chunk.len());
//         }
//         Ok(Err(e)) => {
//             eprintln!("Audio capture error: {:?}", e);
//             break; // Or handle error appropriately
//         }
//         Err(e) => {
//             eprintln!("Channel receive error: {:?}", e);
//             break; // Channel closed
//         }
//     }
// }
```
```

--------------------------------

### WhisperStream Methods

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/whisper_stream.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Provides essential methods for interacting with the WhisperStream, including listing devices, models, starting, and stopping the stream.

```APIDOC
## WhisperStream

### Methods

- `builder() -> WhisperStreamBuilder`
  Initializes and returns a `WhisperStreamBuilder` to configure and create a new `WhisperStream` instance.

- `list_devices() -> Result<Vec<String>, WhisperStreamError>`
  Returns a list of available audio input devices on the system.

- `list_models() -> Vec<Model>`
  Returns a list of available transcription models.

- `start(&mut self) -> Result<(), WhisperStreamError>`
  Starts the background thread for audio processing and transcription. This method is a placeholder and the actual start will occur in a subsequent phase.

- `stop(&mut self) -> Result<(), WhisperStreamError>`
  Stops the WhisperStream processing. The implementation details for stopping the stream are not fully provided in this snippet.
```

--------------------------------

### Audio Stream Playback and Monitoring

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/audio.rs.html?search=std%3A%3Avec

Starts playback of the created audio stream and enters a loop to monitor a stop signal. Handles errors during stream playback.

```Rust
match stream_result {
    Ok(stream) => {
        info!("[Audio] Successfully created audio stream, attempting to start capture...");
        if let Err(e) = stream.play() {
            error!("[Audio] Failed to play stream for device: {} ({})", device_name_clone, e);
            let _ = tx.send(Err(WhisperStreamError::AudioDevice(format!("Failed to play stream: {}", e))));
            return;
        }
        info!("[Audio] Audio capture started successfully!");
        // Stream is playing; cpal callbacks handle audio processing.
        // This thread keeps alive to monitor stop_processing_signal.
        loop {
            if stop_processing_signal.load(Ordering::Relaxed) {
                debug!("[Audio] Stop signal received in main capture thread for device '{}'. Stream will be dropped.", device_name_clone);
                break;
            }
            std::thread::sleep(std::time::Duration::from_millis(100));
        }
        // Dropping `stream` here stops cpal callbacks.
    }
    Err(e) => {
        error!("[Audio] Failed to build input stream for device '{}': {}", device_name_clone, e);
        let _ = tx.send(Err(e));
        return;
    }
}
```

--------------------------------

### Start and Monitor Audio Stream

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/audio.rs.html?search=

Attempts to play the created audio stream and enters a loop to monitor a stop signal. The loop keeps the capture thread alive while the stream is active and breaks when the stop signal is received.

```Rust
            match stream_result {
                Ok(stream) => {
                    info!("[Audio] Successfully created audio stream, attempting to start capture...");
                    if let Err(e) = stream.play() {
                        error!("[Audio] Failed to play stream for device: {} ({})", device_name_clone, e);
                        let _ = tx.send(Err(WhisperStreamError::AudioDevice(format!("Failed to play stream: {}", e))));
                        return;
                    }
                    info!("[Audio] Audio capture started successfully!");
                    // Stream is playing; cpal callbacks handle audio processing.
                    // This thread keeps alive to monitor stop_processing_signal.
                    loop {
                        if stop_processing_signal.load(Ordering::Relaxed) {
                            debug!("[Audio] Stop signal received in main capture thread for device '{}'. Stream will be dropped.", device_name_clone);
                            break;
                        }
                        std::thread::sleep(std::time::Duration::from_millis(100));
                    }
                    // Dropping `stream` here stops cpal callbacks.
                }
                Err(e) => {
                    error!("[Audio] Failed to build input stream for device '{}': {}", device_name_clone, e);
                    let _ = tx.send(Err(e));
                    return;
                }
            }
```

--------------------------------

### Start 16kHz Audio Capture

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/audio.rs.html?search=

Initiates audio capture from a specified device, returning a receiver for 16kHz mono f32 audio chunks. Handles device selection, resampling, and error reporting.

```Rust
pub fn start_capture_16k(&self) -> Receiver<Result<Vec<f32>, WhisperStreamError>> {
        let (tx, rx) = mpsc::channel();
        let device_name_clone = self.device_name.clone();
        let step_duration_ms_clone = self.step_duration_ms;

        #[cfg(target_os = "macos")]
        {
            // Double-check permissions before starting capture
            let host = cpal::default_host();
            if let Err(e) = host.input_devices() {
                error!("[Audio] No microphone access. Please check System Settings > Privacy & Security > Microphone: {}", e);
                let _ = tx.send(Err(WhisperStreamError::AudioDevice(
                    "No microphone access. Please check System Settings > Privacy & Security > Microphone".to_string()
                )));
                return rx;
            }
        }

        let stop_processing_signal = Arc::new(AtomicBool::new(false));
        // _thread_stop_signal kept for potential future use or if stream lifetime needs explicit management with it.
        let _thread_stop_signal = stop_processing_signal.clone();

        let tx_for_err_fn = tx.clone();
        let tx_for_data_cb = tx.clone();

        info!("[Audio] Starting capture for device '{}'. Native SR: {}, Target SR: {}, Channels: {}, Chunk ms: {}",
            self.device_name, self.sample_rate, 16000, self.channels, self.step_duration_ms);

        std::thread::spawn(move || {
            let host = cpal::default_host();
            let device_result = host.input_devices().map_err(WhisperStreamError::from)
                .and_then(|mut devices| {
                    devices.find(|d| d.name().is_ok_and(|n| n == device_name_clone))
                        .ok_or_else(|| WhisperStreamError::AudioDevice(format!("Named input device '{}' not found.", device_name_clone)))
                })
                .or_else(|_| { // If named device not found or error in listing, try default
                    host.default_input_device()
                        .ok_or_else(|| WhisperStreamError::AudioDevice(format!("Audio device '{}' not found and no default available.", device_name_clone)))
                });

            let device = match device_result {
                Ok(d) => d,
                Err(e) => {
                    let _ = tx.send(Err(e));
                    return;
                }
            };

                        let default_config = match device.default_input_config().map_err(WhisperStreamError::from) {
                Ok(c) => c,
                Err(e) => {
                    let _ = tx.send(Err(e));
                    return;
                }
            };

            let native_sample_rate = default_config.sample_rate().0;

            // Create a specific config instead of using default
            let config = StreamConfig {
                channels: 1, // Force mono
                sample_rate: cpal::SampleRate(native_sample_rate),
                buffer_size: cpal::BufferSize::Default,
            };
            debug!("[Audio] Using explicit stream config: channels={}, rate={}",
                config.channels, config.sample_rate.0);
            let audio_channels = config.channels as usize;
            let target_sample_rate = 16000;
            // device_samples_per_step is the number of *native* samples for one chunk before any processing.
            let device_samples_per_step = (native_sample_rate as f32 * (step_duration_ms_clone as f32 / 1000.0)) as usize;

                        debug!("[Audio] Device config: Format={:?}, Rate={}, Channels={}",
                default_config.sample_format(), native_sample_rate, audio_channels);

            // Try to get supported configs
            if let Ok(supported_configs) = device.supported_input_configs() {
                debug!("[Audio] Supported input configurations:");
                for conf in supported_configs {
                    debug!("  - Rate: {:?}, Channels: {}, Format: {:?}",
                        conf.min_sample_rate()..=conf.max_sample_rate(),
                        conf.channels(),

```

--------------------------------

### Get User-Facing Model Name

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/model.rs.html?search=std%3A%3Avec

Provides a method to get the human-readable name for each Whisper model. For example, `Model::BaseEn` returns "base.en".

```rust
impl Model {
    /// Returns the user-facing name for this model (e.g., "base.en").
    pub fn name(&self) -> &'static str {
        match self {
            Model::BaseEn => "base.en",
            Model::TinyEn => "tiny.en",
            Model::SmallEn => "small.en",
        }
    }
// ... other methods
```

--------------------------------

### Initialize WavAudioRecorder

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/audio_utils.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new WavAudioRecorder. If a path is provided, it sets up the WAV file writer, creating parent directories if necessary. If no path is given, recording is disabled.

```rust
/// Handles recording audio chunks to a WAV file.
pub struct WavAudioRecorder {
    writer: Option<WavWriter<std::io::BufWriter<std::fs::File>>>,
    path: String,
    is_recording_active: bool,
}

impl WavAudioRecorder {
    /// Creates a new `WavAudioRecorder`.
    ///
    /// # Arguments
    /// * `path_opt`: Optional path to save the WAV file. If `None`, recording is disabled.
    pub fn new(path_opt: Option<&str>) -> Result<Self, WhisperStreamError> {
        match path_opt {
            Some(p) => {
                // Create parent directory if it doesn't exist
                if let Some(parent_dir) = Path::new(p).parent() {
                    if !parent_dir.exists() {
                        fs::create_dir_all(parent_dir).map_err(|e| WhisperStreamError::Io { source: e })?;
                    }
                }

                let spec = WavSpec {
                    channels: 1,        // Whisper processes mono audio
                    sample_rate: 16000, // Whisper processes 16kHz audio
                    bits_per_sample: 16,
                    sample_format: SampleFormat::Int,
                };
                let writer = WavWriter::create(p, spec)
                    .map_err(|e| WhisperStreamError::Hound { source: e })?;
                Ok(Self {
                    writer: Some(writer),
                    path: p.to_string(),
                    is_recording_active: true,
                })
            }
            None => Ok(Self {
                writer: None,
                path: String::new(),
                is_recording_active: false,
            }),
        }
    }

```

--------------------------------

### Initialize WAV Audio Recorder

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/audio_utils.rs.html?search=u32+-%3E+bool

Creates a new `WavAudioRecorder`. If a path is provided, it sets up the WAV file, creating parent directories if necessary. If `None` is provided for the path, recording is disabled.

```rust
pub fn new(path_opt: Option<&str>) -> Result<Self, WhisperStreamError> {
    match path_opt {
        Some(p) => {
            // Create parent directory if it doesn't exist
            if let Some(parent_dir) = Path::new(p).parent() {
                if !parent_dir.exists() {
                    fs::create_dir_all(parent_dir).map_err(|e| WhisperStreamError::Io { source: e })?;
                }
            }

            let spec = WavSpec {
                channels: 1,        // Whisper processes mono audio
                sample_rate: 16000, // Whisper processes 16kHz audio
                bits_per_sample: 16,
                sample_format: SampleFormat::Int,
            };
            let writer = WavWriter::create(p, spec)
                .map_err(|e| WhisperStreamError::Hound { source: e })?;
            Ok(Self {
                writer: Some(writer),
                path: p.to_string(),
                is_recording_active: true,
            })
        }
        None => Ok(Self {
            writer: None,
            path: String::new(),
            is_recording_active: false,
        }),
    }
}
```

--------------------------------

### Get Type ID

Source: https://docs.rs/whisper-stream-rs/latest/whisper_stream_rs/enum.Model.html?search=u32+-%3E+bool

Gets the `TypeId` of the `Model` type. This is part of the blanket `Any` trait implementation.

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### WavAudioRecorder Initialization and Usage

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/whisper_stream.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Illustrates how to initialize a WavAudioRecorder for saving transcribed audio to a file. It also shows how to write audio chunks to the recorder and provides feedback on the recording process.

```rust
let mut wav_audio_recorder = match WavAudioRecorder::new(config.record_to_wav.as_deref()) {
    Ok(recorder) => recorder,
    Err(e) => {
        let _ = tx.send(Event::Error(e));
        match WavAudioRecorder::new(None) {
            Ok(no_op_recorder) => no_op_recorder,
            Err(_) => return,
        }
    }
};

if wav_audio_recorder.is_recording() {
    if let Some(path_str) = config.record_to_wav.as_ref() {
        info!("[Recording] Saving transcribed audio to {}...", path_str);
        let _ = tx.send(Event::SystemMessage(format!("[Recording] Saving transcribed audio to {}...", path_str)));
    }
}

// ... inside the loop ...
if wav_audio_recorder.is_recording() {
    if let Err(e) = wav_audio_recorder.write_audio_chunk(&pcmf32_new) {
        let _ = tx.send(Event::Error(e));
    }
}
```

--------------------------------

### Create and Configure WAV Audio Recorder

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/audio_utils.rs.html?search=

Initializes a WavAudioRecorder. If a path is provided, it creates the parent directory if necessary and sets up the WAV file with specific parameters (1 channel, 16kHz sample rate, 16-bit integer format). If no path is given, recording is disabled.

```rust
/// Handles recording audio chunks to a WAV file.
pub struct WavAudioRecorder {
    writer: Option<WavWriter<std::io::BufWriter<std::fs::File>>>,
    path: String,
    is_recording_active: bool,
}

impl WavAudioRecorder {
    /// Creates a new `WavAudioRecorder`.
    ///
    /// # Arguments
    /// * `path_opt`: Optional path to save the WAV file. If `None`, recording is disabled.
    pub fn new(path_opt: Option<&str>) -> Result<Self, WhisperStreamError> {
        match path_opt {
            Some(p) => {
                // Create parent directory if it doesn't exist
                if let Some(parent_dir) = Path::new(p).parent() {
                    if !parent_dir.exists() {
                        fs::create_dir_all(parent_dir).map_err(|e| WhisperStreamError::Io { source: e })?;
                    }
                }

                let spec = WavSpec {
                    channels: 1,        // Whisper processes mono audio
                    sample_rate: 16000, // Whisper processes 16kHz audio
                    bits_per_sample: 16,
                    sample_format: SampleFormat::Int,
                };
                let writer = WavWriter::create(p, spec)
                    .map_err(|e| WhisperStreamError::Hound { source: e })?;
                Ok(Self {
                    writer: Some(writer),
                    path: p.to_string(),
                    is_recording_active: true,
                })
            }
            None => Ok(Self {
                writer: None,
                path: String::new(),
                is_recording_active: false,
            }),
        }
    }

    /// Writes an audio chunk to the WAV file if recording is active.
    ///
    /// # Arguments
    /// * `audio_chunk`: A slice of `f32` audio samples (expected to be mono, 16kHz).
    ///
    /// Samples should be in the range -1.0 to 1.0.
    pub fn write_audio_chunk(&mut self, audio_chunk: &[f32]) -> Result<(), WhisperStreamError> {
        if let Some(writer) = self.writer.as_mut() {
            let mut min_sample = f32::INFINITY;
            let mut max_sample = f32::NEG_INFINITY;
            let mut non_zero_count = 0;

            for &sample_f32_original in audio_chunk {
                min_sample = min_sample.min(sample_f32_original);
                max_sample = max_sample.max(sample_f32_original);
                if sample_f32_original != 0.0 {
                    non_zero_count += 1;
                }

                let sample_f32 = if sample_f32_original.is_finite() {
                    sample_f32_original
                } else {
                    warn!("Non-finite audio sample detected: {}. Replacing with 0.0.", sample_f32_original);
                    0.0
                };

                // Clamp to [-1.0, 1.0) then scale and cast
                let clamped_sample = sample_f32.clamp(-1.0, 1.0 - f32::EPSILON);
                // Scale to i16 range and round to nearest integer
                let scaled = clamped_sample * i16::MAX as f32;
                let sample_i16 = scaled.round() as i16;
                if let Err(e) = writer.write_sample(sample_i16) {
                    return Err(WhisperStreamError::Hound { source: e });
                }
            }

            debug!("[WAV Writer] Chunk stats: len={}, non_zero={}, range=[{:.6}, {:.6}]",
                audio_chunk.len(), non_zero_count, min_sample, max_sample);
        }
        Ok(())
    }

    /// Finalizes the WAV file. Must be called to complete the recording.
    /// Returns a system message indicating the result.
    pub fn finalize(mut self) -> Result<Option<String>, WhisperStreamError> {

```

--------------------------------

### Initialize WAV Audio Recorder

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/audio_utils.rs.html?search=std%3A%3Avec

Creates a new `WavAudioRecorder` instance. If a path is provided, it sets up the WAV file with specific parameters (16kHz, mono, 16-bit PCM) and creates parent directories if they don't exist. If `None` is provided, recording is disabled.

```rust
use std::borrow::Cow;
use hound::{WavWriter, WavSpec, SampleFormat};
use crate::error::WhisperStreamError;
use std::fs;
use std::path::Path;
use log::{warn, debug};

/// Handles recording audio chunks to a WAV file.
pub struct WavAudioRecorder {
    writer: Option<WavWriter<std::io::BufWriter<std::fs::File>>>, 
    path: String,
    is_recording_active: bool,
}

impl WavAudioRecorder {
    /// Creates a new `WavAudioRecorder`.
    ///
    /// # Arguments
    /// * `path_opt`: Optional path to save the WAV file. If `None`, recording is disabled.
    pub fn new(path_opt: Option<&str>) -> Result<Self, WhisperStreamError> {
        match path_opt {
            Some(p) => {
                // Create parent directory if it doesn't exist
                if let Some(parent_dir) = Path::new(p).parent() {
                    if !parent_dir.exists() {
                        fs::create_dir_all(parent_dir).map_err(|e| WhisperStreamError::Io { source: e })?;
                    }
                }

                let spec = WavSpec {
                    channels: 1,        // Whisper processes mono audio
                    sample_rate: 16000, // Whisper processes 16kHz audio
                    bits_per_sample: 16,
                    sample_format: SampleFormat::Int,
                };
                let writer = WavWriter::create(p, spec)
                    .map_err(|e| WhisperStreamError::Hound { source: e })?;
                Ok(Self {
                    writer: Some(writer),
                    path: p.to_string(),
                    is_recording_active: true,
                })
            }
            None => Ok(Self {
                writer: None,
                path: String::new(),
                is_recording_active: false,
            }),
        }
    }

    /// Writes an audio chunk to the WAV file if recording is active.
    ///
    /// # Arguments
    /// * `audio_chunk`: A slice of `f32` audio samples (expected to be mono, 16kHz).
    ///
    /// Samples should be in the range -1.0 to 1.0.
    pub fn write_audio_chunk(&mut self, audio_chunk: &[f32]) -> Result<(), WhisperStreamError> {
        if let Some(writer) = self.writer.as_mut() {
            let mut min_sample = f32::INFINITY;
            let mut max_sample = f32::NEG_INFINITY;
            let mut non_zero_count = 0;

            for &sample_f32_original in audio_chunk {
                min_sample = min_sample.min(sample_f32_original);
                max_sample = max_sample.max(sample_f32_original);
                if sample_f32_original != 0.0 {
                    non_zero_count += 1;
                }

                let sample_f32 = if sample_f32_original.is_finite() {
                    sample_f32_original
                } else {
                    warn!("Non-finite audio sample detected: {}. Replacing with 0.0.", sample_f32_original);
                    0.0
                };

                // Clamp to [-1.0, 1.0) then scale and cast
                let clamped_sample = sample_f32.clamp(-1.0, 1.0 - f32::EPSILON);
                // Scale to i16 range and round to nearest integer
                let scaled = clamped_sample * i16::MAX as f32;
                let sample_i16 = scaled.round() as i16;
                if let Err(e) = writer.write_sample(sample_i16) {
                    return Err(WhisperStreamError::Hound { source: e });
                }
            }

            debug!("[WAV Writer] Chunk stats: len={}, non_zero={}, range=[{:.6}, {:.6}]",
                audio_chunk.len(), non_zero_count, min_sample, max_sample);
        }
        Ok(())
    }

    /// Finalizes the WAV file. Must be called to complete the recording.
    /// Returns a system message indicating the result.
    pub fn finalize(mut self) -> Result<Option<String>, WhisperStreamError> {

```

--------------------------------

### Initialize WAV Audio Recorder

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/audio_utils.rs.html

Creates a new WavAudioRecorder. If a path is provided, it sets up a WAV writer with specific audio specifications (mono, 16kHz, 16-bit integer). If no path is given, recording is disabled.

```rust
use std::borrow::Cow;
use hound::{WavWriter, WavSpec, SampleFormat};
use crate::error::WhisperStreamError;
use std::fs;
use std::path::Path;
use log::{warn, debug};

/// Handles recording audio chunks to a WAV file.
pub struct WavAudioRecorder {
    writer: Option<WavWriter<std::io::BufWriter<std::fs::File>>>,
    path: String,
    is_recording_active: bool,
}

impl WavAudioRecorder {
    /// Creates a new `WavAudioRecorder`.
    ///
    /// # Arguments
    /// * `path_opt`: Optional path to save the WAV file. If `None`, recording is disabled.
    pub fn new(path_opt: Option<&str>) -> Result<Self, WhisperStreamError> {
        match path_opt {
            Some(p) => {
                // Create parent directory if it doesn't exist
                if let Some(parent_dir) = Path::new(p).parent() {
                    if !parent_dir.exists() {
                        fs::create_dir_all(parent_dir).map_err(|e| WhisperStreamError::Io { source: e })?;
                    }
                }

                let spec = WavSpec {
                    channels: 1,        // Whisper processes mono audio
                    sample_rate: 16000, // Whisper processes 16kHz audio
                    bits_per_sample: 16,
                    sample_format: SampleFormat::Int,
                };
                let writer = WavWriter::create(p, spec)
                    .map_err(|e| WhisperStreamError::Hound { source: e })?;
                Ok(Self {
                    writer: Some(writer),
                    path: p.to_string(),
                    is_recording_active: true,
                })
            }
            None => Ok(Self {
                writer: None,
                path: String::new(),
                is_recording_active: false,
            }),
        }
    }

    /// Writes an audio chunk to the WAV file if recording is active.
    ///
    /// # Arguments
    /// * `audio_chunk`: A slice of `f32` audio samples (expected to be mono, 16kHz).
    ///
    /// Samples should be in the range -1.0 to 1.0.
    pub fn write_audio_chunk(&mut self, audio_chunk: &[f32]) -> Result<(), WhisperStreamError> {
        if let Some(writer) = self.writer.as_mut() {
            let mut min_sample = f32::INFINITY;
            let mut max_sample = f32::NEG_INFINITY;
            let mut non_zero_count = 0;

            for &sample_f32_original in audio_chunk {
                min_sample = min_sample.min(sample_f32_original);
                max_sample = max_sample.max(sample_f32_original);
                if sample_f32_original != 0.0 {
                    non_zero_count += 1;
                }

                let sample_f32 = if sample_f32_original.is_finite() {
                    sample_f32_original
                } else {
                    warn!("Non-finite audio sample detected: {}. Replacing with 0.0.", sample_f32_original);
                    0.0
                };

                // Clamp to [-1.0, 1.0) then scale and cast
                let clamped_sample = sample_f32.clamp(-1.0, 1.0 - f32::EPSILON);
                // Scale to i16 range and round to nearest integer
                let scaled = clamped_sample * i16::MAX as f32;
                let sample_i16 = scaled.round() as i16;
                if let Err(e) = writer.write_sample(sample_i16) {
                    return Err(WhisperStreamError::Hound { source: e });
                }
            }

            debug!("[WAV Writer] Chunk stats: len={}, non_zero={}, range=[{:.6}, {:.6}]",
                audio_chunk.len(), non_zero_count, min_sample, max_sample);
        }
        Ok(())
    }

    /// Finalizes the WAV file. Must be called to complete the recording.
    /// Returns a system message indicating the result.
    pub fn finalize(mut self) -> Result<Option<String>, WhisperStreamError> {

```

--------------------------------

### Create Audio Input Configuration

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/audio.rs.html

Initializes a new `AudioInput` instance. It selects an audio input device, either the specified one or a default/preferred device if none is provided. It also configures the audio processing parameters like sample rate and chunk duration.

```Rust
pub fn new(device_name_opt: Option<&str>, step_ms: u32) -> Result<Self, WhisperStreamError> {
        let host = cpal::default_host();

        // Always list devices first to potentially trigger permission prompt
        info!("[Audio] Available input devices:");
        let mut found_devices = Vec::new();

        // Get the default device name first for comparison
        let default_name = host.default_input_device()
            .and_then(|d| d.name().ok())
            .unwrap_or_else(|| "<unknown default>".to_string());
        info!("[Audio] Default input device is: {}", default_name);

        for device in host.input_devices().map_err(WhisperStreamError::from)? {
            if let Ok(name) = device.name() {
                info!("[Audio] Found device: {} {}",
                    name,
                    if name == default_name { "(default)" } else { "" }
                );
                found_devices.push((name, device));
            }
        }

        if found_devices.is_empty() {
            return Err(WhisperStreamError::AudioDevice("No input devices available".to_string()));
        }

        let (device_name, device) = match device_name_opt {
            Some(name) => {
                // Try to find the exact device
                found_devices.into_iter()
                    .find(|(dev_name, _)| dev_name.eq_ignore_ascii_case(name))
                    .ok_or_else(|| WhisperStreamError::AudioDevice(format!("Input device named '{}' not found (case-insensitive search)", name)))?;
            }
            None => {
                // Try to find a non-default device first (prefer external microphones)
                info!("[Audio] No device specified, looking for best available device...");

                // Find index of preferred device
                let preferred_idx = found_devices.iter()
                    .position(|(name, _)| {
                        name != &default_name && ( 
                            name.contains("MacBook Pro-Mikrofon")
                        )
                    });

                // Remove and return either the preferred device or the first one
                if let Some(idx) = preferred_idx {
                    let (name, device) = found_devices.remove(idx);
                    info!("[Audio] Selected preferred device: {}", name);
                    (name, device)
                } else {
                    let (name, device) = found_devices.remove(0);
                    info!("[Audio] No preferred device found, using: {}", name);
                    (name, device)
                }
            }
        };

        // TODO: Fetch device config and warn if not mono, as mono is the target format.
        // let config = device.default_input_config().map_err(WhisperStreamError::from)?;
        // if config.channels != 1 {
        //     warn!("[Audio] Input device '{}' is not mono ({} channels), downmixing will occur.", device_name, config.channels);
        // }

        Ok(Self { device_name, sample_rate: 16000, channels: 1, step_duration_ms: step_ms })
    }
```

--------------------------------

### Check Supported Input Configurations

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/audio.rs.html?search=u32+-%3E+bool

Iterates through and logs all supported input configurations for a given audio device. Useful for debugging and understanding device capabilities.

```rust
if let Ok(supported_configs) = device.supported_input_configs() {
            for supported_config in supported_configs {
                info!("[Audio] - Supported: Rate {:?}, Channels {}, Format {:?}",
                    supported_config.min_sample_rate()..=supported_config.max_sample_rate(),
                    supported_config.channels(),
                    supported_config.sample_format()
                );
            }
        }
```

--------------------------------

### Initialize Audio Input with Device Selection

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/audio.rs.html?search=

Creates a new `AudioInput` instance, allowing selection of a specific audio device by name or falling back to a default/preferred device. Configures audio chunk duration.

```rust
pub fn new(device_name_opt: Option<&str>, step_ms: u32) -> Result<Self, WhisperStreamError> {
        let host = cpal::default_host();

        // Always list devices first to potentially trigger permission prompt
        info!("[Audio] Available input devices:");
        let mut found_devices = Vec::new();

        // Get the default device name first for comparison
        let default_name = host.default_input_device()
            .and_then(|d| d.name().ok())
            .unwrap_or_else(|| "<unknown default>".to_string());
        info!("[Audio] Default input device is: {}", default_name);

        for device in host.input_devices().map_err(WhisperStreamError::from)? {
            if let Ok(name) = device.name() {
                info!("[Audio] Found device: {} {}",
                    name,
                    if name == default_name { "(default)" } else { "" }
                );
                found_devices.push((name, device));
            }
        }

        if found_devices.is_empty() {
            return Err(WhisperStreamError::AudioDevice("No input devices available".to_string()));
        }

        let (device_name, device) = match device_name_opt {
            Some(name) => {
                // Try to find the exact device
                found_devices.into_iter()
                    .find(|(dev_name, _)| dev_name.eq_ignore_ascii_case(name))
                    .ok_or_else(|| WhisperStreamError::AudioDevice(format!("Input device named '{}' not found (case-insensitive search)", name)))?;
            }
            None => {
                // Try to find a non-default device first (prefer external microphones)
                info!("[Audio] No device specified, looking for best available device...");

                // Find index of preferred device
                let preferred_idx = found_devices.iter()
                    .position(|(name, _)| {
                        name != &default_name && (
                            name.contains("MacBook Pro-Mikrofon")
                        )
                    });

                // Remove and return either the preferred device or the first one
                if let Some(idx) = preferred_idx {
                    let (name, device) = found_devices.remove(idx);
                    info!("[Audio] Selected preferred device: {}", name);
                    (name, device)
                } else {
                    let (name, device) = found_devices.remove(0);
                    info!("[Audio] No preferred device found, using: {}", name);
                    (name, device)
                }
            }
        };

```

--------------------------------

### WavAudioRecorder Initialization Without Path

Source: https://docs.rs/whisper-stream-rs/latest/src/whisper_stream_rs/audio_utils.rs.html

Tests the initialization of `WavAudioRecorder` when no file path is provided. Asserts that the recorder is not in a recording state.

```rust
let recorder = WavAudioRecorder::new(None).expect("Failed to create recorder");
assert!(!recorder.is_recording());
```

--------------------------------

### Get Model Name

Source: https://docs.rs/whisper-stream-rs/latest/whisper_stream_rs/enum.Model.html?search=u32+-%3E+bool

Returns the user-facing name for a given model. Useful for display purposes.

```rust
pub fn name(&self) -> &'static str
```
Tokens:
Raw