Command-Line Interface

Entry point model

Hyperion CLI commands are generated from scripts in hyperion.bin (hyperion/bin on disk).

Generation flow:

  1. proto_pyproject.toml defines static package metadata template.

  2. generate_pyproject.py scans hyperion/bin/*.py.

  3. Each script is mapped to hyperion-<script-name> in pyproject.toml.

  4. Dependencies are loaded from requirements.txt.

The machine-readable classification source is docs/cli_inventory.json. It contains one record for every maintained executable module in hyperion/bin: the installed command name, task family, stable/experimental status, planned guide page, and optional runtime requirements. Later CLI reference pages and CI checks are generated from or validated against this inventory.

Regenerate entry points with:

python generate_pyproject.py

Naming convention

A script file like hyperion/bin/train_qvector.py becomes command:

hyperion-train-qvector

Task-oriented command index

The following complete index is generated from docs/cli_inventory.json. Stable commands are supported public interfaces. Experimental commands are visible for evaluation, but their configuration and checkpoint compatibility are not guaranteed across minor releases. Family guides with full workflows are linked below.

Training

Model and backend training commands.

Read the training guide.

Stable commands:

  • hyperion-make-wav2xvector Conditional runtime requirements: PyTorch.

  • hyperion-train-dino-wav2xvector Conditional runtime requirements: PyTorch.

  • hyperion-train-lgbe

  • hyperion-train-plda

  • hyperion-train-qmf

  • hyperion-train-verification-calibration

  • hyperion-train-verification-greedy-fusion

  • hyperion-train-wav2vec2xvector Conditional runtime requirements: PyTorch, transformers.

  • hyperion-train-wav2xvector Conditional runtime requirements: PyTorch.

  • hyperion-train-xvector-from-wav Conditional runtime requirements: PyTorch.

Experimental commands:

  • hyperion-train-dac Conditional runtime requirements: PyTorch, codec training data.

  • hyperion-train-freevc Conditional runtime requirements: PyTorch, VITS/FreeVC assets.

  • hyperion-train-qvector Conditional runtime requirements: PyTorch.

  • hyperion-train-tokenizer Conditional runtime requirements: PyTorch, codec training data.

  • hyperion-train-vi-anonymizer Conditional runtime requirements: PyTorch, VITS assets.

  • hyperion-train-vi-emo-normalizer Conditional runtime requirements: PyTorch, VITS assets.

  • hyperion-train-wav2rnn-transducer Conditional runtime requirements: k2, PyTorch, transducer training data.

  • hyperion-train-wav2vec2rnn-transducer Conditional runtime requirements: k2, PyTorch, transformers, transducer training data.

  • hyperion-train-wav2vec2transducer Conditional runtime requirements: k2, PyTorch, transformers, transducer training data.

Fine-tuning and adaptation

Checkpoint adaptation and fine-tuning commands.

Read the fine-tuning and adaptation guide.

Stable commands:

  • hyperion-adv-finetune-xvector-from-wav Conditional runtime requirements: PyTorch.

  • hyperion-finetune-wav2vec2xvector Conditional runtime requirements: PyTorch, transformers.

  • hyperion-finetune-wav2xvector Conditional runtime requirements: PyTorch.

  • hyperion-finetune-xvector-dfr-from-wav Conditional runtime requirements: PyTorch.

  • hyperion-finetune-xvector-from-wav Conditional runtime requirements: PyTorch.

Experimental commands:

  • hyperion-finetune-dac Conditional runtime requirements: PyTorch, codec checkpoint.

  • hyperion-finetune-qvector Conditional runtime requirements: PyTorch, Q-vector checkpoint.

  • hyperion-finetune-vi-anonymizer Conditional runtime requirements: PyTorch, VITS checkpoint.

  • hyperion-finetune-wav2vec2transducer Conditional runtime requirements: k2, PyTorch, transformers, transducer checkpoint.

Extraction and inference

Embedding extraction, model inference, and decoding commands.

Read the extraction and inference guide.

Stable commands:

  • hyperion-eval-wav2vec2xvector-logits Conditional runtime requirements: PyTorch, transformers.

  • hyperion-eval-wav2xvector-logits Conditional runtime requirements: PyTorch.

  • hyperion-eval-xvec-logits-from-wav Conditional runtime requirements: PyTorch.

  • hyperion-extract-wav2vec2xvectors Conditional runtime requirements: PyTorch, transformers.

  • hyperion-extract-wav2xvectors Conditional runtime requirements: PyTorch.

  • hyperion-extract-xvectors-from-wav Conditional runtime requirements: PyTorch.

  • hyperion-extract-xvectors-slidwin-from-wav Conditional runtime requirements: PyTorch.

Experimental commands:

  • hyperion-infer-qvectors Conditional runtime requirements: PyTorch, Q-vector checkpoint.

Backends, scoring, and evaluation

Backend fitting, scoring, calibration, fusion, and evaluation commands.

Read the backends, scoring, and evaluation guide.

Stable commands:

  • hyperion-accum-speech-quality-metrics Conditional runtime requirements: ONNX Runtime, speech-quality metric dependencies.

  • hyperion-accum-voxprofile-metrics Conditional runtime requirements: voxprofile extra.

  • hyperion-cluster-embeddings

  • hyperion-eval-cosine-scoring-backend

  • hyperion-eval-cosine-scoring-backend-with-qmf

  • hyperion-eval-lgbe

  • hyperion-eval-plda-backend

  • hyperion-eval-speech-quality-metrics Conditional runtime requirements: ONNX Runtime, TPM model packages, optional quality model assets.

  • hyperion-eval-verification-anonymization-metrics

  • hyperion-eval-verification-calibration

  • hyperion-eval-verification-greedy-fusion

  • hyperion-eval-verification-metrics

  • hyperion-eval-voxprofile-metrics Conditional runtime requirements: voxprofile extra, VoxProfile model assets.

  • hyperion-eval-xvec-cosine-scoring-from-adv-test-wav Conditional runtime requirements: PyTorch.

  • hyperion-eval-xvec-cosine-scoring-from-adv-test-wav-wavegan Conditional runtime requirements: PyTorch.

  • hyperion-eval-xvec-cosine-scoring-from-art-test-wav Conditional runtime requirements: ART, PyTorch.

  • hyperion-eval-xvec-cosine-scoring-from-test-wav Conditional runtime requirements: PyTorch.

  • hyperion-eval-xvec-cosine-scoring-from-transfer-adv-test-wav Conditional runtime requirements: PyTorch.

  • hyperion-eval-xvec-cosine-scoring-from-transfer-art-test-wav Conditional runtime requirements: ART, PyTorch.

  • hyperion-generate-adv-attacks-xvector-classif Conditional runtime requirements: PyTorch.

  • hyperion-generate-adv-attacks-xvector-verif Conditional runtime requirements: PyTorch.

Data preparation and manifest operations

Corpus preparation, dataset/table management, and metadata generation commands.

Read the data preparation and manifest operations guide.

Stable commands:

  • hyperion-dataset

  • hyperion-prepare-data Conditional runtime requirements: dataset-specific corpus files.

  • hyperion-split-dataset-into-trials-and-cohort

  • hyperion-tables

Audio, feature, and VAD conversion

Audio, feature, VAD, and score/trial conversion commands.

Read the audio, feature, and vad conversion guide.

Stable commands:

  • hyperion-apply-mvn-select-frames

  • hyperion-audio-to-duration Conditional runtime requirements: audio backend.

  • hyperion-compute-energy-vad Conditional runtime requirements: audio backend.

  • hyperion-compute-mfcc-feats Conditional runtime requirements: audio backend.

  • hyperion-convert-vad-format

  • hyperion-copy-feats

  • hyperion-make-babble-noise-audio-files Conditional runtime requirements: audio backend.

  • hyperion-pack-wav-rirs Conditional runtime requirements: audio backend.

  • hyperion-preprocess-audio-files Conditional runtime requirements: audio backend.

Visualization and utilities

Analysis, plotting, merging, and other standalone utilities.

Read the visualization and utilities guide.

Stable commands:

  • hyperion-merge-scores

  • hyperion-merge-trials

  • hyperion-plot-embedding-tsne Conditional runtime requirements: matplotlib, scikit-learn.

  • hyperion-plot-embedding-tsne-per-class Conditional runtime requirements: matplotlib, scikit-learn.

  • hyperion-submit Conditional runtime requirements: Slurm (slurm backend only).

Family guides

Generated command and option reference

The complete parser-derived option reference is generated from command --help output. It is included separately because it is intentionally an exact parser snapshot rather than a task guide:

Scope notes

  • hyperion/bin_deprec and hyperion/bin_deprec2 are deprecated and not part of the documented CLI surface.

  • Experimental transducer decoders are listed in Experimental Components.

Optional dependencies and TPM commands

The generated index labels conditional runtime requirements: dependencies, extras, model assets, or network retrieval needed for that command, but not for every Hyperion workflow. This does not promise that an asset is installed, licensed, available offline, or compatible with an arbitrary device.

The policy for package extras, local assets, first-run downloads, offline execution, and stable TPM wrappers is defined in Optional Dependencies, External Assets, and TPM. For reproducible work, provide local assets and pin model revisions rather than depending on a mutable remote default or a personal cache.

Discover commands

After installation:

python -m pip show hyperion-ml
hyperion-train-qvector --help
hyperion-eval-verification-metrics --help