Metadata-Version: 2.4
Name: hyperion-ml
Version: 0.4.1a0
Summary: Toolkit for speaker recognition
Author-email: Jesus Villalba <jesus.antonio.villalba@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/hyperion-ml/hyperion
Keywords: speaker recognition,adversarial attacks,NIST SRE,x-vectors
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch<=2.9.1,>=2.4.1
Requires-Dist: torchaudio<=2.9.1,>=2.4.1
Requires-Dist: torchvision<=0.24.1,>=0.19.1
Requires-Dist: numpy<2.0,>=1.26
Requires-Dist: pandas<2.3,>=2.1
Requires-Dist: scipy<1.13,>=1.11
Requires-Dist: scikit-learn<1.6,>=1.4
Requires-Dist: matplotlib<3.11,>=3.7.0
Requires-Dist: h5py<4.0,>=3.11.0
Requires-Dist: soundfile<0.14,>=0.13.1
Requires-Dist: transformers<5,>=4.40
Requires-Dist: datasets<4.0,>=3.0.0
Requires-Dist: tensorboard<2.21,>=2.12
Requires-Dist: librosa<0.11,>=0.10.1
Requires-Dist: lhotse<2.0,>=1.30
Requires-Dist: sentencepiece<0.3,>=0.2.0
Requires-Dist: kaldialign<1.0,>=0.9.1
Requires-Dist: sphinx_rtd_theme>=0.4.3
Requires-Dist: pympler
Requires-Dist: memory_profiler
Requires-Dist: gdown
Requires-Dist: jsonargparse>=3.5.0
Requires-Dist: wandb>=0.10.30
Requires-Dist: isort
Requires-Dist: black
Requires-Dist: twine
Requires-Dist: wheel
Requires-Dist: loralib
Requires-Dist: pytest
Requires-Dist: toml
Requires-Dist: hyperion-utmosv2==1.3.1
Requires-Dist: pycountry<25.0,>=24.0
Requires-Dist: langcodes<4.0,>=3.3
Requires-Dist: nvidia-ml-py<14.0.0,>=11.0.0
Requires-Dist: onnxruntime<1.19,>=1.16.3
Requires-Dist: intervaltree>=3.1.0
Requires-Dist: sortedcontainers<3.0,>=2.4
Requires-Dist: pesq<0.1,>=0.0.4
Requires-Dist: pystoi<0.5,>=0.4.1
Provides-Extra: torch24
Requires-Dist: torch==2.4.1; extra == "torch24"
Requires-Dist: torchaudio==2.4.1; extra == "torch24"
Requires-Dist: torchvision==0.19.1; extra == "torch24"
Provides-Extra: torch25
Requires-Dist: torch<2.6,>=2.5.1; extra == "torch25"
Requires-Dist: torchaudio<2.6,>=2.5.1; extra == "torch25"
Requires-Dist: torchvision<0.21,>=0.20.1; extra == "torch25"
Provides-Extra: torch26
Requires-Dist: torch<2.7,>=2.6; extra == "torch26"
Requires-Dist: torchaudio<2.7,>=2.6; extra == "torch26"
Requires-Dist: torchvision<0.22,>=0.21; extra == "torch26"
Provides-Extra: torch27
Requires-Dist: torch<2.8,>=2.7.1; extra == "torch27"
Requires-Dist: torchaudio<2.8,>=2.7.1; extra == "torch27"
Requires-Dist: torchvision<0.23,>=0.22.1; extra == "torch27"
Provides-Extra: torch28
Requires-Dist: torch<2.9,>=2.8; extra == "torch28"
Requires-Dist: torchaudio<2.9,>=2.8; extra == "torch28"
Requires-Dist: torchvision<0.24,>=0.23; extra == "torch28"
Provides-Extra: torch29
Requires-Dist: torch==2.9.1; extra == "torch29"
Requires-Dist: torchaudio==2.9.1; extra == "torch29"
Requires-Dist: torchvision==0.24.1; extra == "torch29"
Provides-Extra: gcc217
Requires-Dist: h5py==3.11.0; extra == "gcc217"
Requires-Dist: onnxruntime==1.16.3; extra == "gcc217"
Requires-Dist: numpy<2.0,>=1.26; extra == "gcc217"
Provides-Extra: onnx-cpu-modern
Requires-Dist: onnxruntime<1.19,>=1.18; extra == "onnx-cpu-modern"
Provides-Extra: voxprofile
Requires-Dist: hyperion-voxprofile==0.1.0; extra == "voxprofile"
Provides-Extra: voxlect
Requires-Dist: hyperion-voxlect==0.1.1; extra == "voxlect"
Provides-Extra: art
Requires-Dist: adversarial-robustness-toolbox>=1.17; extra == "art"
Dynamic: license-file

# HYPERION

<div align="center">

[![PyPI version](https://badge.fury.io/py/hyperion-ml.svg)](https://badge.fury.io/py/hyperion-ml)
[![License](https://img.shields.io/github/license/hyperion-ml/hyperion.svg)](https://www.apache.org/licenses/LICENSE-2.0)
[![Python Versions](https://img.shields.io/pypi/pyversions/hyperion-ml.svg)](https://pypi.org/project/hyperion-ml/)
[![Downloads](https://pepy.tech/badge/hyperion-ml)](https://pepy.tech/project/hyperion-ml)
[![Documentation Status](https://readthedocs.org/projects/hyperion-ml/badge/?version=latest)](https://hyperion-ml.readthedocs.io/en/latest/?badge=latest)
[![Black](https://github.com/hyperion-ml/hyperion/actions/workflows/black.yml/badge.svg?branch=master)](https://github.com/hyperion-ml/hyperion/actions/workflows/black.yml)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

</div>

Hyperion is a Speaker Recognition Toolkit based on PyTorch and numpy. It provides:
 - x-Vector architectures: ResNet, Res2Net, Spine2Net, ECAPA-TDNN, EfficientNet, Transformers and others.
 - Embedding preprocessing tools: PCA, LDA, NAP, Centering/Whitening, Length Normalization, CORAL
 - Several flavours of PLDA back-ends: Full-rank PLDA, Simplified PLDA, PLDA
 - Calibration and Fusion tools
 - Recipes for popular datasets: VoxCeleb, NIST-SRE, VOiCES

The full API is described in the documentation page [https://hyperion-ml.readthedocs.io](https://hyperion-ml.readthedocs.io)

## Building the documentation

Install the documentation dependencies and run the repository build script:

```bash
python3 -m pip install -r docs/requirements.txt
./docs/build.sh
```

The generated site is at `docs/_build/html/index.html`. The script treats
documentation warnings as errors. See the
[documentation build guide](docs/building-documentation.rst) for link checking,
doctests, and cleanup commands.

## Installation Instructions

### Prerequisites

    We use anaconda or miniconda, though you should be able to make it work in other python distributions
    To start, you should create a new enviroment:
```
conda create --name ${your_env} python=3.11
conda activate ${your_env}
```

### Installing Hyperion

- First, clone the repo:
```bash
git clone https://github.com/hyperion-ml/hyperion.git
```

- Then install hyperion in the environment, these are some valid commands depending pytorch and cuda versions:
```bash
cd hyperion
pip install --extra-index-url https://download.pytorch.org/whl/cu130 -e .[torch29]
pip install --extra-index-url https://download.pytorch.org/whl/cu128 -e .[torch29]
pip install --extra-index-url https://download.pytorch.org/whl/cu126 -e .[torch29]
pip install --extra-index-url https://download.pytorch.org/whl/cu129 -e .[torch28]
pip install --extra-index-url https://download.pytorch.org/whl/cu128 -e .[torch28]
pip install --extra-index-url https://download.pytorch.org/whl/cu126 -e .[torch28]
pip install --extra-index-url https://download.pytorch.org/whl/cu128 -e .[torch27]
pip install --extra-index-url https://download.pytorch.org/whl/cu126 -e .[torch27]
pip install --extra-index-url https://download.pytorch.org/whl/cu124 -e .[torch26]
pip install --extra-index-url https://download.pytorch.org/whl/cu121 -e .[torch25]
pip install --extra-index-url https://download.pytorch.org/whl/cu121 -e .[torch24]
```

Known issues:

For older linux systems with GLIB <=2.17, try something like
```
pip install --extra-index-url https://download.pytorch.org/whl/cu121 -e .[torch25,gcc217] --only-binary=:all: --no-binary=intervaltree,fairscale
```

If you get this error when training:
```
Error: mkl-service + Intel(R) MKL: MKL_THREADING_LAYER=INTEL is incompatible with libgomp.so.1 library.
        Try to import numpy first or set the threading layer accordingly. Set MKL_SERVICE_FORCE_INTEL to force it.
```
Unistall and reinstall numpy:
```
pip unistall numpy
pip install numpy=={same-version-you-uninstalled}
```

## Recipes

There are recipes for several tasks in the `./egs` directory.

### Prerequistes to run the recipes

These recipes require some extra tools (e.g. sph2pipe), which need to be installed first:
```bash
./install_egs_requirements.sh 
```

Most recipes do not require Kaldi, only the older ones using Kaldi x-vectors,
so we do not install it by default. If you are going to need it install it 
yourself. Then make a link in `./tools` to your kaldi installation
```bash
cd tools
ln -s ${your_kaldi_path} kaldi
cd -
```

Finally configure the python and environment name that you intend to use to run the recipes.
For that run
```bash
./prepare_egs_paths.sh
```
This script will ask for the path to your anaconda installation and enviromentment name.
It will also detect if hyperion is already installed in the environment,
otherwise it will add hyperion to your python path.
This will create the file
```
tools/path.sh
```
which sets all the enviroment variables required to run the recipes.
This has been tested only on JHU computer grids, so you may need to 
modify this file manually to adapt it to your grid.

## Recipes structure

The recipe layout is inspired by Kaldi: each dataset is prepared in a
directory under `data/`, and the numbered `run_*.sh` scripts operate on those
prepared datasets. However, the maintained recipes generally use Hyperion's
`HyperDataset` format rather than a collection of Kaldi mapping files. A
typical prepared dataset contains a manifest describing the available tables:
```
dataset.yaml
segments.csv       # segment IDs, recordings, speakers, timing, and metadata
recordings.csv     # recording IDs and audio storage paths
speaker.csv        # optional class/speaker information
trials.csv         # optional enrollment/test trial definitions
```

Some older recipes still use Kaldi-style data directories, with files such as
`wav.scp`, `utt2spk`, and `spk2utt`. Those layouts remain supported where the
recipe expects them, but they are not the standard output of the current
dataset-preparation classes.

### Running the recipes

Contrary to other toolkits, the recipes do not contain a single `run.sh` script 
to run all the steps of the recipe.
Since some recipes have many steps and most times you don't want to run all of then
from the beginning, we have split the recipe in several run scripts.
The scripts have a number indicating the order in the sequence.
For example,
```bash
run_001_prepare_data.sh
run_002_compute_vad.sh
run_010_prepare_audios_to_train_xvector.sh
run_011_train_xvector.sh
run_030_extract_xvectors.sh
run_040_evaluate_plda_backend.sh
```
will evaluate the recipe with the default configuration.
The default configuration is in the file `default_config.sh`

We also include extra configurations, which may change 
the hyperparamters of the recipe. For example:
 - Acoustic features
 - Type of the x-vector neural netwok
 - Hyper-parameters of the models
 - etc.

Extra configs are in the `global_conf` directory of the recipe.
Then you can run the recipe with the alternate config as:
```bash
run_001_prepare_data.sh --config-file global_conf/alternative_conf.sh
run_002_compute_vad.sh --config-file global_conf/alternative_conf.sh
run_010_prepare_audios_to_train_xvector.sh --config-file global_conf/alternative_conf.sh
run_011_train_xvector.sh --config-file global_conf/alternative_conf.sh
run_030_extract_xvectors.sh --config-file global_conf/alternative_conf.sh
run_040_evaluate_plda_backend.sh --config-file global_conf/alternative_conf.sh
```
Note that many alternative configus share hyperparameters with the default configs.
That means that you may not need to rerun all the steps to evaluate a new configuration.
It mast cases you just need to re-run the steps from the neural network training to the end.


## Citing

Each recipe README.md file contains the bibtex to the works that should be cited if you 
use that recipe in your research
     
## Directory structure:
 - The directory structure of the repo looks like this:
```bash
hyperion
hyperion/egs
hyperion/hyperion
hyperion/resources
hyperion/tests
hyperion/tools
```
 - Directories:
    - hyperion: python classes with utilities for speaker and language recognition
    - egs: recipes for sevaral tasks: VoxCeleb, SRE18/19/20, voices, ...
    - tools: contains external repos and tools like kaldi, python, cudnn, etc.
    - tests: unit tests for the classes in hyperion
    - resources: data files required by unittest or recipes
