Hyperion Documentation

Hyperion is a speech processing toolkit with NumPy and PyTorch stacks for speaker recognition, anonymization/voice conversion, neural codecs, and evaluation tooling.

This documentation reflects the current implementation in this repository, including:

• hyperion.np: NumPy models and utilities.

• hyperion.torch: layers, neural architectures, models, trainers, and TPM wrappers.

• hyperion.io: audio/feature readers and writers.

• hyperion.utils: dataset manifests, trial tables, and Kaldi-style helpers.

• hyperion.data_prep: dataset preparation classes.

• hyperion.text_norm: text normalization utilities.

• hyperion.metrics: high-level evaluators.

• hyperion.bin: CLI entry points generated from scripts.

Getting started

• Getting Started
  • Requirements
  • Install
  • Known issues
  • Packaging and entry points
  • Quick sanity checks
  • See Also
• Speaker Verification Quickstart
  • Requirements
  • Create embeddings and trials
  • Score and evaluate
  • What the tables mean
  • Next steps
• Optional Dependencies, External Assets, and TPM
  • Requirement levels
  • Offline and reproducible operation
  • TPM wrappers
  • Command behavior
  • See also

Concepts

• Repository Architecture
  • Top-level layout
  • NumPy stack
  • PyTorch stack
  • Training and data
  • Third-party wrappers (TPM)
  • Metrics layering
  • CLI generation
• Hyperion Data Model
  • The three levels of data
  • Typical flow
  • Detailed guides
• Glossary

How-to guides

• Train an X-Vector Directly from Waveforms
  • Choose a model family
  • Prepare the manifests
  • Configuration layout
  • Train the native model
  • Use a Wav2Vec2 x-vector model
  • Extract embeddings
  • Validate the result
  • Common problems
  • See also
• Extract, Score, and Evaluate X-Vectors
  • Prepare evaluation metadata
  • Extract embeddings
  • Score with cosine similarity
  • Train and score a PLDA backend
  • Evaluate EER and minDCF
  • Calibrate scores only with development data
  • Common problems
  • See also
• Prepare Dataset Metadata and VAD
  • Discover a dataset preparer
  • Compute energy VAD
  • Convert VAD formats when needed
  • See also
• Submitting recipe jobs
  • Command line
  • Array jobs and task substitution
  • Execution and failure semantics
  • Slurm execution model
  • Runtime environment
  • YAML configuration
  • Initial non-goals
• Run Resumable, Mixed-Precision, and Distributed Training
  • Experiment artifacts and resume
  • Enable AMP
  • Launch single-node DDP
  • Batch sizing and memory
  • Troubleshooting
  • See also
• Train a Pretrained Wav2Vec2 X-Vector
  • Choose an architecture
  • Configure the pretrained encoder
  • Fine-tuning policy
  • Train and extract
  • Memory and performance
  • See also
• Use Configuration Files
  • Pass a configuration file
  • Nested configuration mirrors parser groups
  • Use one canonical experiment configuration
  • Override sparingly
  • Common configuration failures
  • See also
• Save and Load Models and Backends
  • Load a PyTorch x-vector model
  • Load NumPy preprocessing and PLDA
  • Deployment manifest
  • Compatibility and safety
  • See also

Documentation and maintenance

• Building the Documentation
  • Install documentation dependencies
  • Build HTML
  • Check public API coverage
  • Check public namespace coverage
  • Check tutorial quality coverage
  • Check release notes
  • Continuous-integration quality gates
  • Check CLI coverage and generated index drift
  • Run documentation CI locally before a pull request
  • Regenerate the CLI option reference
  • Offline and online builds
  • Additional checks
  • External-link retry policy
  • Contributing documentation
• Documentation Policy
  • Scope
  • Support levels
  • Documentation requirements
  • Quality gates
  • See also
• Contributor Extension Guide
  • Choose the extension point
  • Architectural boundaries
  • Contributor responsibilities
  • See also
• Model Extension Contracts
  • Choose the correct base class
  • HyperNPModel contract
  • HyperTorchModel contract
  • Registry discovery and imports
  • Compatibility rules
  • Validation before a pull request
  • See also
• PyTorch Extension Workflows
  • Choose the lowest appropriate layer
  • Adding a primitive layer
  • Adding a layer block
  • Adding a NetArch
  • Adding a task model
  • Adding datasets and samplers
  • Adding or extending a trainer
  • Adding optimizers, schedules, and losses
  • Completion checklist
  • See also
• Data-Preparation and CLI Extension Workflows
  • Adding a data-preparation class
  • Prepared-data artifact contract
  • Implementation sequence
  • Adding a maintained command
  • Register and document the command
  • CLI validation checklist
  • See also
• Contributor Validation and Documentation Requirements
  • Start from the observable contract
  • Required validation by change type
  • Targeted tests
  • PyTorch-specific evidence
  • Data and compatibility evidence
  • Documentation changes required for a PR
  • Before submitting
  • See also
• Deprecation and Compatibility Policy
  • Support boundary
  • What needs a compatibility decision
  • Deprecation lifecycle
  • Implementation patterns
  • Removal checklist
  • Documenting a deprecation
  • See also
• Release Notes
  • Entry rules
  • Unreleased
  • Released versions
• Tutorial Quality Inventory
  • See also
• Public Surface Inventory
  • Stable package areas
  • Experimental package areas
  • Out of scope
  • Inventory maintenance
  • See also
• API Contract Coverage
  • Stable contracts
  • Experimental or intentionally excluded surfaces
  • Review rule

Package reference

• PyTorch Stack
  • Overview
  • Core model abstractions
  • Layering model
  • Layer and block namespaces
  • Neural architectures
  • Top-level models
  • Data pipeline and samplers
  • Learning rate and weight decay schedulers
  • Training stack
  • Torch metrics
  • Third-party model wrappers (TPM)
• PyTorch API Overview
  • Model contract
  • Data and sampling
  • Training
  • Architecture layers
  • Experimental model families
  • Third-party integrations and adversarial robustness
  • See also
• PyTorch API Contracts
  • Model serialization and modes
  • Waveform embedding models
  • NetArch and forward contracts
  • Data and samplers
  • Trainer and checkpoint contracts
  • Factories and configuration
  • Focused inference example
  • See also
• PyTorch Extension Points
  • Layering and ownership
  • Neural architectures
  • Task models and waveform wrappers
  • Datasets and samplers
  • Training and optimization
  • Stable and experimental families
  • See also
• PyTorch Layers and Architecture Catalog
  • Input representation
  • Frontends, normalization, and pooling
  • Reusable blocks
  • Neural architecture families
  • Factories and selection
  • Experimental architecture families
  • See also
• PyTorch Training Support
  • Classification output layers
  • Metrics and loggers
  • Schedulers and checkpoints
  • See also
• PyTorch Integrations and Robustness
  • Third-party model wrappers
  • Adversarial attacks
  • Defenses
  • See also
• Experimental Components
  • Neural codecs (DAC)
  • VITS anonymization and voice conversion
  • Transducers
  • Q-vectors
  • Adoption checklist
  • See also
• NumPy Backend API
  • Model serialization
  • Transforms and preprocessing
  • PLDA and scoring backends
  • Calibration and score normalization
  • Other stable areas
  • See also
• NumPy Backend Extension Points
  • Score backend pipeline
  • PLDA and transforms
  • Calibration
  • Score normalization
  • Clustering and diarization
  • Speech augmentation
  • See also
• Metrics and Evaluation API
  • Verification metrics
  • Other evaluator families
  • Torch metrics
  • See also
• Input and Output API
  • Core contracts
  • Archive specifications
  • Feature API
  • Audio API
  • VAD API
  • Compatibility interfaces
  • See also
• Utility Layer
  • Overview
  • Alignment rules
  • Dataset and table abstractions
  • Trial/key/score structures
  • Enrollment and class metadata
  • Compatibility helper structures
  • Miscellaneous utilities
• Foundation API Contracts
  • I/O contracts
  • Table and trial contracts
  • Focused example
• Statistical, Evaluation, and Preparation API Contracts
  • Metrics and evaluators
  • Data preparation
  • NumPy model and backend contracts
  • Text normalization
  • See also
• Working With Info Tables
  • Overview
  • Representative Example Tables
  • Core InfoTable Behavior
  • SegmentSet
  • RecordingSet
  • EnrollmentMap
  • ClassInfo
  • Putting The Tables Together
  • Other InfoTable Children
  • Practical Guidelines
  • See Also
• Working With HyperDataset
  • Overview
  • What HyperDataset Adds On Top Of InfoTable
  • Core Alignment Rules
  • Minimal End-To-End Example
  • Building A Dataset
  • Lazy Loading And Access Patterns
  • Saving And Loading Dataset Bundles
  • Registering, Replacing, And Removing Tables
  • Working With Classes
  • Keeping The Dataset Consistent
  • Common Filtering And Curation Operations
  • Splitting Datasets
  • Working With Enrollments And Trials
  • Transforming A Dataset
  • Best Practices
  • Related Tutorials
• Working With Trial Tables
  • Overview
  • Core Concepts
  • Dense vs Sparse
  • File Formats
  • Loading and Saving
  • Basic Manipulation
  • Converting Between TrialKey and TrialNdx
  • Working With Scores and Keys
  • Quality Measures
  • Sparse Workflows
  • Advanced Utilities
  • Practical Recommendations
  • End-to-End Example
• Data Preparation API
  • Base extension point
  • Use a registered preparer
  • Add a new preparer
  • See also
• Text Normalization API
  • Core normalizers
  • Numbers and spelling
  • See also
• Command-Line Interface
  • Entry point model
  • Naming convention
  • Task-oriented command index
  • Family guides
  • Generated command and option reference
  • Scope notes
  • Optional dependencies and TPM commands
  • Discover commands

Indices and tables

• Index

• Module Index

• Search Page