neurovoc 0.1.1
A biologically plausible vocoder framework for auditory perception modeling and cochlear implant simulation
Requires Python: >=3.7

# 🧠 NeuroVoc: From Spikes to Speech 🔊

[![arXiv](https://img.shields.io/badge/arXiv-Preprint-orange)](https://arxiv.org/abs/2506.03959)  
*A biologically plausible vocoder for auditory perception modeling and cochlear implant simulation.*

---

## 🔍 Overview

**NeuroVoc** is a flexible, biologically inspired vocoder that reconstructs audio signals from simulated auditory nerve activity. It is designed to support both **normal hearing (NH)** and **electrical hearing (EH)** models, allowing for a seamless comparison of auditory perception under different hearing conditions.

![NeuroVoc Diagram](neurovoc.png)

### 🧭 Diagram Explanation

The diagram above illustrates the NeuroVoc processing pipeline:

1. **Sound** — An input waveform (e.g., speech) is passed to an auditory model.
2. **Hearing Model** — This model (e.g., normal hearing or cochlear implant simulation) transforms the sound into a neural representation.
3. **Neurogram** — The output is a time–frequency matrix of spike counts, simulating auditory nerve activity.
4. **Decoder** — The neurogram is then converted back into an acoustic waveform using an inverse short-time Fourier transform (STFT)-based decoder.

This modular flow enables the flexible substitution of different models or model parameters while maintaining a consistent reconstruction backend.

---

## 📁 Repository Structure

```
neurovoc/
├── neurovoc/               # Core vocoder framework (Python package)
├── experiments/            # Scripts for generating the figures from the paper
├── data/                   # Din test data and paper data
├── tests/                  # Unit tests
```

The main package can be found in the neurovoc folder. Experiments holds the notebooks that were used to generate the plots in the paper. The online Digits in Noise test platform, can be found in [this](https://github.com/jacobdenobel/dinweb) repository. 

---

You're absolutely right — numbering those steps suggests a sequence, but in this case, they’re two **alternative** ways to install the package. Here's a better structure:

---

## 🚀 Getting Started

### 📦 Installation Options

#### 🔧 Option 1: Install from Source (Development Version)

If you want to modify or contribute to the codebase:

```bash
git clone https://github.com/jacobdenobel/neurovoc.git
cd neurovoc
pip install .
```

#### 🧪 Option 2: Install from PyPI (Stable Release)

If you just want to use the package:

```bash
pip install neurovoc
```


---

## 💻 Command Line Interface (CLI)

NeuroVoc provides a flexible CLI for simulation and vocoding. Once installed, you can use the `neurovoc` command. If you want to know more about a command, or see which options are available, add the `--help` flag. For example: 

```bash
    neurovoc generate bruce --help
```

### 🔧 Generate a Neurogram
These commands take an audio waveform and convert it into a neurogram (neural spike representation):

```bash
neurovoc generate bruce input.wav output.pkl
neurovoc generate specres input.wav output.pkl
neurovoc generate ace input.wav output.pkl
```

Each model supports its own optional flags, like `--n-fibers-per-bin`, `--n-mels`, or `--version` for ACE. 

### 🎧 Reconstruct Audio from Neurogram
Converts a saved neurogram back into an audio waveform using an inverse STFT-based decoder. Use options like `--n-hop`, `--n-fft`, or `--target-sr` to control reconstruction parameters. 

```bash
neurovoc reconstruct output.pkl reconstructed.wav
```

### 🧪 Full Vocoder Run (Simulate + Reconstruct)
These commands run a full simulation + reconstruction cycle in one go:
```bash
neurovoc vocode bruce input.wav output.wav
neurovoc vocode specres input.wav output.wav
neurovoc vocode ace input.wav output.wav
```

Add `--plot` to visualize original vs reconstructed signal.

---
Certainly! Here's the **“Processing a Custom Neurogram”** section you can directly paste into your README:

---

### 🧩 Processing a Custom Neurogram

If you want to apply the NeuroVoc reconstruction logic to a neurogram generated by a method **not included** in this repository, you can wrap your custom matrix in a `Neurogram` object:

```python
from neurovoc import Neurogram

neurogram = Neurogram(
    dt=...,             # float: time resolution of the neurogram (in seconds)
    frequencies=...,    # np.array (m, 1): frequency bins corresponding to rows
    data=...,           # np.array (m, t): matrix of normalized spike counts or neural activity
    source=...,         # str: label describing the source/method
)
```

📌 **Note:** Currently, only **mel-scale frequency bins** are supported for decoding.

Once constructed, save it to disk with:

```python
neurogram.save("my_custom_ng.pkl")
```

Then reconstruct it using the CLI:

```bash
neurovoc reconstruct my_custom_ng.pkl reconstructed.wav
```

This makes it easy to plug external auditory models into the NeuroVoc decoding pipeline.

---

## 🧠 Citation

If you use NeuroVoc in your work, please cite the following:

```bibtex
@misc{denobel2025spikesspeechneurovoc,
    title={From Spikes to Speech: NeuroVoc -- A Biologically Plausible Vocoder Framework for Auditory Perception and Cochlear Implant Simulation}, 
    author={Jacob de Nobel and Jeroen J. Briaire and Thomas H. W. Baeck and Anna V. Kononova and Johan H. M. Frijns},
    year={2025},
    eprint={2506.03959},
    archivePrefix={arXiv},
    primaryClass={cs.SD},
    url={https://arxiv.org/abs/2506.03959}, 
}
```

---

## 📫 Contact

For questions or feedback, contact [nobeljpde1@liacs.leidenuniv.nl](mailto:nobeljpde1@liacs.leidenuniv.nl)  
Or open an issue in this repository.

---

## 🛠 License

This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.