Metadata-Version: 2.4
Name: ser-standardizer
Version: 0.1.1
Summary: A tool for standardizing Speech Emotion Recognition (SER) datasets and extracting acoustic features.
Author-email: Vinicius Suaiden <vinicius.suaiden@usp.br>, Miguel Arjona Ramirez <maramire@usp.br>, Wesley Beccaro <wesleybeccaro@usp.br>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ViniciusSuaiden/ser-standardizer
Project-URL: Repository, https://github.com/ViniciusSuaiden/ser-standardizer
Project-URL: Issues, https://github.com/ViniciusSuaiden/ser-standardizer/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.3.0
Requires-Dist: audb>=1.0.0
Provides-Extra: features
Requires-Dist: numpy<3.0,>=1.21.0; extra == "features"
Requires-Dist: soundfile>=0.12.0; extra == "features"
Requires-Dist: scipy>=1.10.0; extra == "features"
Requires-Dist: ipython>=9.0.0; extra == "features"
Requires-Dist: ipywidgets>=8.1.8; extra == "features"
Requires-Dist: noisereduce>=3.0.3; extra == "features"
Requires-Dist: tqdm>=4.60.0; extra == "features"
Requires-Dist: opensmile>=2.4.0; extra == "features"
Dynamic: license-file

# SER-Standardizer

🇺🇸 English | [🇧🇷 Português](README.pt-br.md)

[![PyPI](https://img.shields.io/pypi/v/ser-standardizer)](https://pypi.org/project/ser-standardizer/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/downloads/)

**A modular infrastructure for dataset standardization and feature extraction in Speech Emotion Recognition (SER).**

**SER-Standardizer** is a Python package built to unify the formatting of multiple speech databases, mitigating metadata heterogeneity. Its main goal is to facilitate *cross-corpus training* and generalization testing of machine learning models.

Beyond the standardization pipeline, the tool provides an extension module for acoustic feature extraction (spectral and prosodic) by integrating the **openSMILE** framework.

## 📋 Currently Supported Datasets

The tool currently supports loading and standardizing the following databases:

* **CREMA-D** | **IEMOCAP** | **EmoUERJ** (PT-BR) | **MSP-IMPROV** | **MSP-PODCAST** | **RAVDESS** | **EmoDB** (DE)

Per-dataset download and directory-layout guides are available under [`docs/en/`](docs/en/).

## 🚀 Installation

### Prerequisites
* Python 3.8 or higher
* Libraries listed in `pyproject.toml` (installed automatically).

The library is published on [PyPI](https://pypi.org/project/ser-standardizer/) and was designed with flexibility in mind, offering two installation modes to optimize the use of computational resources:

#### 1. Base Installation (Lightweight Metadata)
Installs only the essential packages (`pandas`, `audb`) for tabular standardization and filtering.
```bash
pip install ser-standardizer
```
#### 2. Full Installation (With Signal Processing)
Installs the heavy dependencies required for the feature extraction and audio manipulation module (opensmile, noisereduce).
```bash
pip install "ser-standardizer[features]"
```

#### Installation from source
Only needed to modify the code or track the development version:
```bash
git clone https://github.com/ViniciusSuaiden/ser-standardizer.git
cd ser-standardizer
pip install ".[features]"
```
### 💻 How to Use
The workflow is split into three logical steps:

**1. Preprocessing (CLI)**

After installation, the `ser-std` command becomes available in your terminal.
To standardize a specific dataset:
```bash
# Example: crema_d
ser-std --dataset crema_d --input_dir /path/to/crema
```
The standardized `.csv` file is written to the user's home folder, with a specific name for each database.

**2. Data Handling and Filtering (Python)**

After preprocessing, use the library to load, filter and manipulate the audio directly in your code or Jupyter Notebook.
```python
import ser_standardizer as ser

# Loads multiple standardized datasets into a single DataFrame
df = ser.load_datasets(["crema_d", "ravdess", "iemocap"])

# Filters by dataset, emotion and gender
df_target = ser.filters(
    df,
    datasets=['ravdess', 'iemocap'],
    emotions=['anger', 'sad'],
    genders=['female']
)
```
**3. Acoustic Feature Extraction (Requires [features])**

The extraction module automates digital signal processing. It includes the option to apply a Voice Activity Detection (VAD) mask based on RMS energy to extract features strictly from the effective phonation segments.
```python
# Batch extraction via openSMILE
# Supported 'feature_set' values: 'eGeMAPS' or 'ComParE'
features_df = ser.extract_features(
    df_target,
    feature_set='eGeMAPS',
    feature_level='functionals', # 'functionals' (1 vector per utterance) or 'llds' (per frame)
    use_vad=False, # VAD (silence removal) is only allowed with feature_level='llds'
    sr=16000       # Sampling rate
)

# The result preserves the original indices, making concatenation easy
import pandas as pd
final_dataset = pd.concat([df_target, features_df], axis=1)

# Group-wise normalization (z-score) — removes corpus/speaker offsets.
# Pass the grouping column (e.g., 'dataset' or 'speaker_id').
X_corpus  = ser.normalize(features_df, df_target['dataset'])
X_speaker = ser.normalize(features_df, df_target['speaker_id'])

# --- Extra Utilities ---
# Listen to the audio in a Jupyter Notebook
ser.listen(df_target, index=42)

# Load the raw audio as a NumPy array (e.g., to feed neural networks)
audio_array = ser.load_audio(df_target, index=42)

# Load a batch of audio with zero-padding
batch = ser.load_batch(df_target, begin=0, end=32)
```

### ✍️ Authors
Vinicius Suaiden - USP - vinicius.suaiden@usp.br

Miguel Arjona Ramirez - USP - maramire@usp.br

Wesley Beccaro - USP - wesleybeccaro@usp.br
