Rustpotter

https://docs.rs/rustpotter/latest/rustpotter/
Admin
Rustpotter is an open-source wakeword spotter library written in Rust for detecting custom wakewords...
Tokens:5,133
Snippets:59
Trust Score:9.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Initialize and Use Rustpotter

Source: https://docs.rs/rustpotter/latest/rustpotter/struct.Rustpotter.html

Example showing how to configure the detector, load a wakeword, and process audio samples in a loop.

```rust
use rustpotter::{Rustpotter, RustpotterConfig};
// assuming the audio input format match the rustpotter defaults
let mut rustpotter_config = RustpotterConfig::default();
// Configure the rustpotter
// ...
let mut rustpotter = Rustpotter::new(&rustpotter_config).unwrap();
// load and enable a wakeword
rustpotter.add_wakeword_from_file("wakeword_key", "./tests/resources/oye_casa_g.rpw").unwrap();
// You need a buffer of size rustpotter.get_samples_per_frame() when using samples or rustpotter.get_bytes_per_frame() when using bytes.  
let mut sample_buffer: Vec<i16> = vec![0; rustpotter.get_samples_per_frame()];
// while true { Iterate forever
    // fill the buffer with the required samples/bytes...
   let detection = rustpotter.process_samples(sample_buffer);
    if let Some(detection) = detection {
        println!("{:?}", detection);
    }
// }
```

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

### Rustpotter::new

Source: https://docs.rs/rustpotter/latest/rustpotter/struct.Rustpotter.html

Creates a new instance of the Rustpotter detector using the provided configuration.

```APIDOC
### pub fn new(config: &RustpotterConfig) -> Result<Rustpotter, String>

Creates a new Rustpotter instance configured with the provided settings.
```

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

### new_from_sample_files

Source: https://docs.rs/rustpotter/latest/rustpotter/trait.WakewordRefBuildFromFiles.html

Constructs a new WakewordRef from a list of sample files with specified thresholds and MFCC size.

```APIDOC
## fn new_from_sample_files(name: String, threshold: Option<f32>, avg_threshold: Option<f32>, samples: Vec<String>, mfcc_size: u16) -> Result<WakewordRef, String>

### Description
Creates a new WakewordRef instance by processing the provided sample files. This method allows configuring detection thresholds and the MFCC size for the wakeword.

### Parameters
- **name** (String) - The name of the wakeword.
- **threshold** (Option<f32>) - Optional detection threshold.
- **avg_threshold** (Option<f32>) - Optional average detection threshold.
- **samples** (Vec<String>) - A list of file paths to the sample audio files.
- **mfcc_size** (u16) - The size of the MFCC features to be used.

### Returns
- **Result<WakewordRef, String>** - Returns the constructed WakewordRef on success, or an error message string on failure.
```

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

### WakewordModelTrainOptions::new

Source: https://docs.rs/rustpotter/latest/rustpotter/struct.WakewordModelTrainOptions.html

Creates a new instance of WakewordModelTrainOptions with the specified training parameters.

```APIDOC
## fn new(m_type: ModelType, learning_rate: f64, epochs: usize, test_epochs: usize, mfcc_size: u16) -> Self

### Description
Creates a new instance of `WakewordModelTrainOptions` to configure the training process for a wakeword model.

### Parameters
- **m_type** (ModelType) - The type of model to train.
- **learning_rate** (f64) - The learning rate for the training process.
- **epochs** (usize) - The number of training epochs.
- **test_epochs** (usize) - The number of epochs used for testing.
- **mfcc_size** (u16) - The size of the MFCC features.
```

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

### Rustpotter::process_samples

Source: https://docs.rs/rustpotter/latest/rustpotter/struct.Rustpotter.html

Processes a buffer of audio samples to detect a wakeword.

```APIDOC
### pub fn process_samples<T: Sample>(&mut self, audio_samples: Vec<T>) -> Option<RustpotterDetection>

Processes a vector of audio samples. The number of samples must match the value returned by get_samples_per_frame(). Returns a RustpotterDetection if a match is found.
```

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

### new_from_sample_buffers

Source: https://docs.rs/rustpotter/latest/rustpotter/trait.WakewordRefBuildFromBuffers.html

Constructs a new WakewordRef from a collection of sample buffers. This method allows specifying the wakeword name, detection thresholds, and audio processing parameters.

```APIDOC
## fn new_from_sample_buffers

### Description
Creates a new `WakewordRef` instance by processing provided sample buffers. This is the primary method for initializing a wakeword reference from raw data.

### Signature
`fn new_from_sample_buffers(name: String, threshold: Option<f32>, avg_threshold: Option<f32>, samples: HashMap<String, Vec<u8>>, mfcc_size: u16) -> Result<WakewordRef, String>`

### Parameters
- **name** (String) - The identifier for the wakeword.
- **threshold** (Option<f32>) - Optional detection threshold.
- **avg_threshold** (Option<f32>) - Optional average detection threshold.
- **samples** (HashMap<String, Vec<u8>>) - A map of sample identifiers to their corresponding byte buffers.
- **mfcc_size** (u16) - The size of the MFCC feature vector.

### Returns
- **Result<WakewordRef, String>** - Returns the initialized `WakewordRef` on success, or an error message string on failure.
```

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

### Rustpotter::get_samples_per_frame

Source: https://docs.rs/rustpotter/latest/rustpotter/struct.Rustpotter.html

Retrieves the required number of samples per audio frame.

```APIDOC
### pub fn get_samples_per_frame(&self) -> usize

Returns the number of audio samples required for each processing frame.
```

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

### Rustpotter::add_wakeword_from_file

Source: https://docs.rs/rustpotter/latest/rustpotter/struct.Rustpotter.html

Loads and enables a wakeword from a file path.

```APIDOC
### pub fn add_wakeword_from_file(&mut self, key: &str, path: &str) -> Result<(), String>

Adds a wakeword to the detector from the specified file path, associated with the given key.
```

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

### Define the Sample trait

Source: https://docs.rs/rustpotter/latest/rustpotter/trait.Sample.html

The core trait definition requiring Sized, Copy, PartialOrd, 'static, and Send bounds.

```rust
pub trait Sample:
    Sized
    + Copy
    + PartialOrd
    + 'static
    + Send {
    const S_TYPE: SampleFormat;

    // Required methods
    fn get_byte_size() -> usize;
    fn get_format() -> SampleFormat;
    fn get_zero() -> Self;
    fn from_le_bytes(bytes: &[u8]) -> Self;
    fn from_be_bytes(bytes: &[u8]) -> Self;
    fn from_ne_bytes(bytes: &[u8]) -> Self;
    fn into_f32(self) -> f32;
}
```

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

### train_from_dirs

Source: https://docs.rs/rustpotter/latest/rustpotter/trait.WakewordModelTrain.html

Trains a wakeword model using audio samples located in specified directories.

```APIDOC
## fn train_from_dirs

### Description
Trains a new or existing wakeword model using audio samples loaded from specified file system directories.

### Parameters
- **options** (WakewordModelTrainOptions) - Training configuration options.
- **train_dir** (String) - Path to the directory containing training audio samples.
- **test_dir** (String) - Path to the directory containing testing audio samples.
- **wakeword_model** (Option<WakewordModel>) - Optional existing model to continue training from.

### Returns
- **Result<WakewordModel, Error>** - The trained model or an error if training fails.
```

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

### SampleFormat Methods

Source: https://docs.rs/rustpotter/latest/rustpotter/enum.SampleFormat.html

Methods available on the SampleFormat enum to retrieve format metadata or create instances based on bit size.

```APIDOC
## pub fn get_bits_per_sample(&self) -> u16

### Description
Returns the number of bits per sample for the current format.

## pub fn get_bytes_per_sample(&self) -> u16

### Description
Returns the number of bytes per sample for the current format.

## pub fn int_of_size(bit_size: u16) -> Option<Self>

### Description
Returns the integer SampleFormat variant corresponding to the provided bit size, if valid.

## pub fn float_of_size(bit_size: u16) -> Option<Self>

### Description
Returns the float SampleFormat variant corresponding to the provided bit size, if valid.
```

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

### load_from_buffer

Source: https://docs.rs/rustpotter/latest/rustpotter/trait.WakewordLoad.html

Loads a wakeword model from a byte buffer.

```APIDOC
## fn load_from_buffer(buffer: &[u8]) -> Result<Self, String>

### Description
Loads the wakeword model from the provided byte buffer.

### Parameters
- **buffer** (&[u8]) - Required - The byte slice containing the model data.

### Returns
- **Result<Self, String>** - Returns the loaded model instance on success, or an error message string on failure.
```

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

### train_from_buffers

Source: https://docs.rs/rustpotter/latest/rustpotter/trait.WakewordModelTrain.html

Trains a wakeword model using audio samples provided as memory buffers.

```APIDOC
## fn train_from_buffers

### Description
Trains a new or existing wakeword model using audio samples provided in memory buffers.

### Parameters
- **options** (WakewordModelTrainOptions) - Training configuration options.
- **samples** (HashMap<String, Vec<u8>>) - Map of label to audio buffer data for training.
- **test_samples** (HashMap<String, Vec<u8>>) - Map of label to audio buffer data for testing.
- **wakeword_model** (Option<WakewordModel>) - Optional existing model to continue training from.

### Returns
- **Result<WakewordModel, Error>** - The trained model or an error if training fails.
```

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

### load_from_file

Source: https://docs.rs/rustpotter/latest/rustpotter/trait.WakewordLoad.html

Loads a wakeword model from a specified file path.

```APIDOC
## fn load_from_file(path: &str) -> Result<Self, String>

### Description
Loads the wakeword model from the file located at the provided path.

### Parameters
- **path** (&str) - Required - The filesystem path to the wakeword model file.

### Returns
- **Result<Self, String>** - Returns the loaded model instance on success, or an error message string on failure.
```

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

### RustpotterConfig Struct Definition

Source: https://docs.rs/rustpotter/latest/rustpotter/struct.RustpotterConfig.html

The structure definition for RustpotterConfig, containing fields for audio format, detector settings, and filter configurations.

```rust
pub struct RustpotterConfig {
    pub fmt: AudioFmt,
    pub detector: DetectorConfig,
    pub filters: FiltersConfig,
}
```

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

### fn save_to_file(&self, path: &str) -> Result<(), String>

Source: https://docs.rs/rustpotter/latest/rustpotter/trait.WakewordSave.html

Saves the wakeword model to the specified file path.

```APIDOC
## fn save_to_file(&self, path: &str) -> Result<(), String>

### Description
Saves the current wakeword model instance to a file at the provided path.

### Parameters
- **path** (&str) - Required - The file system path where the model should be saved.

### Returns
- **Result<(), String>** - Returns Ok(()) on success, or an Err containing a string description of the error if the operation fails.
```

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

### WakewordRef::load_from_file

Source: https://docs.rs/rustpotter/latest/rustpotter/struct.WakewordRef.html

Loads a WakewordRef instance from a specified file path.

```APIDOC
## fn load_from_file(path: &str) -> Result<Self, String>

### Description
Loads a wakeword configuration from a file at the provided path.

### Parameters
- **path** (&str) - Required - The file system path to the wakeword file.
```

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

### Define AudioFmt struct

Source: https://docs.rs/rustpotter/latest/rustpotter/struct.AudioFmt.html

The structure used to represent the audio format configuration.

```rust
pub struct AudioFmt {
    pub sample_rate: usize,
    pub sample_format: SampleFormat,
    pub channels: u16,
    pub endianness: Endianness,
}
```

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

### WakewordRef::load_from_buffer

Source: https://docs.rs/rustpotter/latest/rustpotter/struct.WakewordRef.html

Loads a WakewordRef instance from a byte buffer.

```APIDOC
## fn load_from_buffer(buffer: &[u8]) -> Result<Self, String>

### Description
Loads a wakeword configuration from a byte buffer.

### Parameters
- **buffer** (&[u8]) - Required - The byte slice containing the wakeword data.
```

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

### SampleFormat Enum Definition

Source: https://docs.rs/rustpotter/latest/rustpotter/enum.SampleFormat.html

Defines the supported audio sample formats including integer and floating-point types.

```rust
pub enum SampleFormat {
    I8,
    I16,
    I32,
    F32,
}
```

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

### fn save_to_buffer(&self) -> Result<Vec<u8>, String>

Source: https://docs.rs/rustpotter/latest/rustpotter/trait.WakewordSave.html

Serializes the wakeword model into a byte buffer.

```APIDOC
## fn save_to_buffer(&self) -> Result<Vec<u8>, String>

### Description
Serializes the current wakeword model instance into a vector of bytes.

### Returns
- **Result<Vec<u8>, String>** - Returns Ok(Vec<u8>) containing the serialized model data on success, or an Err containing a string description of the error if the operation fails.
```

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

### Define FiltersConfig struct

Source: https://docs.rs/rustpotter/latest/rustpotter/struct.FiltersConfig.html

The structure definition for configuring audio filters in Rustpotter.

```rust
pub struct FiltersConfig {
    pub gain_normalizer: GainNormalizationConfig,
    pub band_pass: BandPassConfig,
}
```

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

### Define BandPassConfig struct

Source: https://docs.rs/rustpotter/latest/rustpotter/struct.BandPassConfig.html

The structure definition for configuring the band-pass audio filter.

```rust
pub struct BandPassConfig {
    pub enabled: bool,
    pub low_cutoff: f32,
    pub high_cutoff: f32,
}
```

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

### Define WakewordRefBuildFromFiles trait

Source: https://docs.rs/rustpotter/latest/rustpotter/trait.WakewordRefBuildFromFiles.html

The trait definition includes the new_from_sample_files method for creating a wakeword reference.

```rust
pub trait WakewordRefBuildFromFiles {
    // Provided method
    fn new_from_sample_files(
        name: String,
        threshold: Option<f32>,
        avg_threshold: Option<f32>,
        samples: Vec<String>,
        mfcc_size: u16,
    ) -> Result<WakewordRef, String> { ... }
}
```

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

### Rustpotter Struct Definition

Source: https://docs.rs/rustpotter/latest/rustpotter/struct.Rustpotter.html

The primary structure used for wakeword spotting.

```rust
pub struct Rustpotter { /* private fields */ }
```

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

### View Aliased Type Structure

Source: https://docs.rs/rustpotter/latest/rustpotter/type.ModelWeights.html

Shows the internal structure of the ModelWeights type.

```rust
struct ModelWeights { /* private fields */ }
```

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

### GainNormalizationConfig Struct Definition

Source: https://docs.rs/rustpotter/latest/rustpotter/struct.GainNormalizationConfig.html

The primary configuration structure for the gain-normalizer audio filter.

```rust
pub struct GainNormalizationConfig {
    pub enabled: bool,
    pub gain_ref: Option<f32>,
    pub min_gain: f32,
    pub max_gain: f32,
}
```

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

### WakewordRef::save_to_file

Source: https://docs.rs/rustpotter/latest/rustpotter/struct.WakewordRef.html

Saves the current WakewordRef instance to a file.

```APIDOC
## fn save_to_file(&self, path: &str) -> Result<(), String>

### Description
Serializes and saves the wakeword configuration to the specified file path.

### Parameters
- **path** (&str) - Required - The destination file path.
```

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

### RustpotterDetection Struct Definition

Source: https://docs.rs/rustpotter/latest/rustpotter/struct.RustpotterDetection.html

Defines the structure used to store detection results, including individual template scores and overall metrics.

```rust
pub struct RustpotterDetection {
    pub name: String,
    pub avg_score: f32,
    pub score: f32,
    pub scores: HashMap<String, f32>,
    pub counter: usize,
    pub gain: f32,
}
```

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

### WakewordLoad Trait Definition

Source: https://docs.rs/rustpotter/latest/rustpotter/trait.WakewordLoad.html

The trait definition requiring DeserializeOwned and Sized, providing default implementations for loading from files and buffers.

```rust
pub trait WakewordLoad: DeserializeOwned + Sized {
    // Provided methods
    fn load_from_file(path: &str) -> Result<Self, String> { ... }
    fn load_from_buffer(buffer: &[u8]) -> Result<Self, String> { ... }
}
```

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

### WakewordRef::save_to_buffer

Source: https://docs.rs/rustpotter/latest/rustpotter/struct.WakewordRef.html

Serializes the WakewordRef instance into a byte buffer.

```APIDOC
## fn save_to_buffer(&self) -> Result<Vec<u8>, String>

### Description
Serializes the wakeword configuration into a byte vector.
```

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

### DetectorConfig Struct Definition

Source: https://docs.rs/rustpotter/latest/rustpotter/struct.DetectorConfig.html

The primary structure used to configure the detector's scoring behavior.

```rust
pub struct DetectorConfig {
    pub avg_threshold: f32,
    pub threshold: f32,
    pub min_scores: usize,
    pub eager: bool,
    pub score_ref: f32,
    pub band_size: u16,
    pub score_mode: ScoreMode,
    pub vad_mode: Option<VADMode>,
}
```

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

### WakewordSave::save_to_file

Source: https://docs.rs/rustpotter/latest/rustpotter/struct.WakewordModel.html

Saves the current WakewordModel instance to a file.

```APIDOC
## fn save_to_file(&self, path: &str) -> Result<(), String>

### Description
Serializes and saves the current model instance to the specified file path.

### Parameters
- **path** (&str) - Required - The destination file path.

### Returns
- **Result<(), String>** - Returns Ok(()) on success, or an error message string on failure.
```

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

### WakewordRefBuildFromBuffers Trait Definition

Source: https://docs.rs/rustpotter/latest/rustpotter/trait.WakewordRefBuildFromBuffers.html

Defines the interface for building a WakewordRef from raw sample buffers.

```rust
pub trait WakewordRefBuildFromBuffers {
    // Provided method
    fn new_from_sample_buffers(
        name: String,
        threshold: Option<f32>,
        avg_threshold: Option<f32>,
        samples: HashMap<String, Vec<u8>>,
        mfcc_size: u16,
    ) -> Result<WakewordRef, String> { ... }
}
```

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

### WakewordModelTrain Trait Definition

Source: https://docs.rs/rustpotter/latest/rustpotter/trait.WakewordModelTrain.html

Defines the interface for training models using either buffers or directories. Implementations must handle the provided options and optional existing model state.

```rust
pub trait WakewordModelTrain {
    // Provided methods
    fn train_from_buffers(
        options: WakewordModelTrainOptions,
        samples: HashMap<String, Vec<u8>>,
        test_samples: HashMap<String, Vec<u8>>,
        wakeword_model: Option<WakewordModel>,
    ) -> Result<WakewordModel, Error> { ... }
    fn train_from_dirs(
        options: WakewordModelTrainOptions,
        train_dir: String,
        test_dir: String,
        wakeword_model: Option<WakewordModel>,
    ) -> Result<WakewordModel, Error> { ... }
}
```

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

### WakewordModel Struct Definition

Source: https://docs.rs/rustpotter/latest/rustpotter/struct.WakewordModel.html

The primary data structure representing a wakeword model.

```rust
pub struct WakewordModel {
    pub labels: Vec<String>,
    pub train_size: usize,
    pub mfcc_size: u16,
    pub m_type: ModelType,
    pub weights: ModelWeights,
    pub rms_level: f32,
}
```

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

### WakewordRef Struct Definition

Source: https://docs.rs/rustpotter/latest/rustpotter/struct.WakewordRef.html

The primary data structure representing a wakeword's internal state and configuration.

```rust
pub struct WakewordRef {
    pub name: String,
    pub avg_features: Option<Vec<Vec<f32>>>,
    pub samples_features: HashMap<String, Vec<Vec<f32>>>,
    pub threshold: Option<f32>,
    pub avg_threshold: Option<f32>,
    pub rms_level: f32,
    pub mfcc_size: u16,
}
```

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

### WakewordSave::save_to_buffer

Source: https://docs.rs/rustpotter/latest/rustpotter/struct.WakewordModel.html

Serializes the current WakewordModel instance into a byte buffer.

```APIDOC
## fn save_to_buffer(&self) -> Result<Vec<u8>, String>

### Description
Serializes the model instance into a byte vector.

### Returns
- **Result<Vec<u8>, String>** - Returns the serialized model as a byte vector on success, or an error message string on failure.
```

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

### Define TensorData struct

Source: https://docs.rs/rustpotter/latest/rustpotter/struct.TensorData.html

The core structure definition for TensorData, containing the raw byte buffer, dimension array, and data type string.

```rust
pub struct TensorData {
    pub bytes: Vec<u8>,
    pub dims: Vec<usize>,
    pub d_type: String,
}
```

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

### VADMode Enum Definition

Source: https://docs.rs/rustpotter/latest/rustpotter/enum.VADMode.html

Defines the available sensitivity levels for the VAD detector.

```rust
pub enum VADMode {
    Easy,
    Medium,
    Hard,
}
```

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

### Define ModelWeights Type Alias

Source: https://docs.rs/rustpotter/latest/rustpotter/type.ModelWeights.html

Represents the underlying structure of the ModelWeights type alias.

```rust
pub type ModelWeights = HashMap<String, TensorData>;
```

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

### WakewordSave Trait Definition

Source: https://docs.rs/rustpotter/latest/rustpotter/trait.WakewordSave.html

The trait requires the Serialize trait and provides methods for saving data to a file or a byte buffer.

```rust
pub trait WakewordSave: Serialize {
    // Provided methods
    fn save_to_file(&self, path: &str) -> Result<(), String> { ... }
    fn save_to_buffer(&self) -> Result<Vec<u8>, String> { ... }
}
```

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

### Define Endianness enum

Source: https://docs.rs/rustpotter/latest/rustpotter/enum.Endianness.html

The Endianness enum specifies the byte order used in audio data processing.

```rust
pub enum Endianness {
    Big,
    Little,
    Native,
}
```

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

### Define ModelType Enum

Source: https://docs.rs/rustpotter/latest/rustpotter/enum.ModelType.html

The ModelType enum defines the supported model sizes with explicit integer discriminants.

```rust
pub enum ModelType {
    Tiny = 0,
    Small = 1,
    Medium = 2,
    Large = 3,
}
```

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

### Define ScoreMode Enum

Source: https://docs.rs/rustpotter/latest/rustpotter/enum.ScoreMode.html

The ScoreMode enum defines the available strategies for calculating the final score.

```rust
pub enum ScoreMode {
    Average,
    Max,
    Median,
    P25,
    P50,
    P75,
    P80,
    P90,
    P95,
}
```
Tokens:
Raw