spafe 0.1.1

Rust port of the spafe audio feature extraction library and jenellefeather/chcochleagram
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

# Spafe

Native Rust implementation of the core
[`spafe`](https://pypi.org/project/spafe/) audio feature extraction APIs and
[`jenellefeather/chcochleagram`](https://github.com/jenellefeather/chcochleagram)
cochleagram routines.

The crate provides filter banks, spectrograms, cepstral features, spectral
descriptors, frequency estimators, cochleagram generation, preprocessing helpers,
and deterministic SVG visualization helpers.

## Build

```bash
cargo build
```

The crate also has an opt-in portable SIMD path for hot numeric kernels. Because
`std::simd` is still unstable, this feature currently requires nightly Rust:

```bash
cargo +nightly build --features portable-simd
```

## Python Bindings

The crate exposes a PyO3 extension module through maturin. The Python package is
published as `spafe-rs` and imports as `spafe`. Python functions use plain
Python lists for one-dimensional signals and nested lists for matrices.

Install locally in a virtual environment:

```bash
python -m pip install maturin
maturin develop
```

Build a wheel:

```bash
python -m pip install build
python -m build --wheel
```

Basic Python usage:

```python
import math
import spafe

fs = 16_000
sig = [math.sin(2.0 * math.pi * 440.0 * n / fs) for n in range(fs)]
opts = spafe.FeatureOptions(fs=fs, nfft=256, nfilts=24)

ceps = spafe.mfcc(sig, opts)
fbanks, centers = spafe.mel_filter_banks(spafe.FilterBankOptions(nfft=256))

print(len(ceps), len(ceps[0]))
print(len(fbanks), len(centers))
```

## Test

```bash
cargo test --all-targets
cargo clippy --all-targets -- -D warnings
RUSTDOCFLAGS="-D warnings -D missing_docs" cargo doc --no-deps
```

## Examples

Generate a filter-bank SVG:

```bash
cargo run --example fbanks
open target/fbanks.svg
```

Generate a cochleagram SVG:

```bash
cargo run --example cochleagram
open target/cochleagram.svg
```

Python examples live in `examples/python`, use matplotlib, and write outputs to
`target/python-examples`:

```bash
python -m pip install matplotlib
python examples/python/features.py
python examples/python/fbanks.py
python examples/python/pitch.py
python examples/python/cochleagram.py
```

Interactive notebooks live in `notebooks`:

```bash
python -m pip install notebook matplotlib numpy
jupyter notebook notebooks
```

They cover feature extraction, filter banks, pitch tracking, cochleagrams,
spectrogram variants, conversion helpers, parameter sensitivity, option tuning,
performance, and visualization/export/classification recipes.
The real-audio notebook uses `notebooks/sample_uk.opus` and requires `ffmpeg`.

## Basic Usage

```rust
use spafe::prelude::*;

fn main() -> spafe::Result<()> {
    let fs = 16_000;
    let signal = vec![0.0; fs];
    let opts = FeatureOptions {
        fs,
        ..Default::default()
    };

    let coeffs = mfcc(&signal, &opts)?;
    println!("frames={}, coeffs={}", coeffs.nrows(), coeffs.ncols());

    let coch = cochleagram(&signal, &CochleagramOptions {
        signal_size: signal.len(),
        sr: fs,
        env_sr: 400,
        ..Default::default()
    })?;
    println!("filters={}, samples={}", coch.cochleagram.nrows(), coch.cochleagram.ncols());
    Ok(())
}
```