Implementation:Speechbrain Speechbrain Load Hyperpyyaml

Field	Value
Implementation Name	Load_Hyperpyyaml
API Signature	load_hyperpyyaml(yaml_stream, overrides=None, overrides_must_match=False)
Source File	External package hyperpyyaml (not vendored in SpeechBrain). Usage site: recipes/CommonVoice/ASR/CTC/train_with_wav2vec.py:L28
Import	from hyperpyyaml import load_hyperpyyaml
Type	Wrapper Doc
External Reference	https://github.com/speechbrain/HyperPyYAML
Related Principle	Principle:Speechbrain_Speechbrain_HyperPyYAML_Configuration

Description

load_hyperpyyaml is the entry point for SpeechBrain's declarative configuration system. It reads a YAML file stream containing special HyperPyYAML tags (!new:, !ref, !name:, !apply:) and returns a Python dictionary where all tagged entries have been resolved: classes have been instantiated, references have been dereferenced, and functions have been called. This transforms a static configuration file into a fully populated runtime environment containing live Python objects.

Inputs

Parameter	Type	Default	Description
yaml_stream	TextIO	(required)	An open file handle or text stream containing the HyperPyYAML configuration. Typically obtained by opening a .yaml file with open(hparams_file, encoding="utf-8").
overrides	str	None	A string of YAML-formatted key-value pairs that override values in the main YAML file. Typically generated from command-line arguments by speechbrain.parse_arguments().
overrides_must_match	bool	False	If True, raises an error if any override key does not correspond to an existing key in the YAML file. If False, unmatched overrides are silently added.

Outputs

Returns a Python dict where:

• Simple YAML values (strings, numbers, booleans, lists) are returned as their Python equivalents
• !new: tagged entries are fully instantiated Python objects (e.g., torch.nn.Module instances, scheduler objects, checkpointer objects)
• !name: tagged entries are callables (class constructors or function references) with pre-bound keyword arguments
• !ref values are resolved to their referenced targets
• !apply: entries contain the return value of the called function

Tag Resolution

!new:fully.qualified.ClassName

Imports the specified class and instantiates it with the nested YAML keys as constructor keyword arguments.

# In YAML:
enc: !new:speechbrain.nnet.containers.Sequential
    input_shape: [null, null, 1024]
    linear1: !name:speechbrain.nnet.linear.Linear
        n_neurons: 1024

# Result in hparams dict:
hparams["enc"]  # -> Sequential instance with specified architecture

!ref <key>

References another value in the YAML tree. Supports string interpolation and nested references.

# In YAML:
seed: 1234
output_folder: !ref results/experiment/<seed>
save_folder: !ref <output_folder>/save

# Result:
hparams["output_folder"]  # -> "results/experiment/1234"
hparams["save_folder"]    # -> "results/experiment/1234/save"

!name:fully.qualified.Name

Returns a callable (partial function or class) with pre-bound arguments, but does not call it.

# In YAML:
model_opt_class: !name:torch.optim.Adadelta
    lr: 1.0
    rho: 0.95
    eps: 1.e-8

# Result:
hparams["model_opt_class"]  # -> functools.partial(Adadelta, lr=1.0, rho=0.95, eps=1e-8)
# Called later with: hparams["model_opt_class"](model.parameters())

!apply:function_name

Calls the function immediately during YAML loading and stores the result.

# In YAML:
__set_seed: !apply:speechbrain.utils.seed_everything [!ref <seed>]

Usage Example

Basic Usage

from hyperpyyaml import load_hyperpyyaml

# Load configuration from a YAML file
with open("hparams/train_en_with_wav2vec.yaml", encoding="utf-8") as fin:
    hparams = load_hyperpyyaml(fin)

# Access instantiated objects directly
encoder = hparams["enc"]           # Sequential module instance
wav2vec = hparams["wav2vec2"]      # Wav2Vec2 model instance
optimizer_cls = hparams["model_opt_class"]  # Optimizer constructor

With Command-Line Overrides

import speechbrain as sb
from hyperpyyaml import load_hyperpyyaml

# Parse command-line arguments
hparams_file, run_opts, overrides = sb.parse_arguments(sys.argv[1:])

# Load YAML with overrides applied
with open(hparams_file, encoding="utf-8") as fin:
    hparams = load_hyperpyyaml(fin, overrides)

# overrides might be: "number_of_epochs: 50\nlr: 0.001"
# These values replace the defaults in the YAML file

Full CTC Training Integration

import sys
import speechbrain as sb
from hyperpyyaml import load_hyperpyyaml

hparams_file, run_opts, overrides = sb.parse_arguments(sys.argv[1:])
with open(hparams_file, encoding="utf-8") as fin:
    hparams = load_hyperpyyaml(fin, overrides)

# hparams now contains all instantiated objects:
# hparams["modules"]       -> dict of nn.Module instances
# hparams["checkpointer"]  -> Checkpointer instance
# hparams["epoch_counter"]  -> EpochCounter instance
# hparams["ctc_cost"]      -> CTC loss function
# hparams["log_softmax"]   -> Softmax module
# hparams["lr_annealing_model"] -> NewBobScheduler instance

Objects Instantiated for CTC ASR

The following key objects are created from the CTC ASR YAML configuration:

YAML Key	Class	Purpose
enc	speechbrain.nnet.containers.Sequential	Encoder DNN (3 linear layers with batch norm, activation, dropout)
wav2vec2	speechbrain.lobes.models.huggingface_transformers.wav2vec2.Wav2Vec2	Pretrained wav2vec2/WavLM feature extractor
ctc_lin	speechbrain.nnet.linear.Linear	CTC output linear layer
log_softmax	speechbrain.nnet.activations.Softmax	Log-softmax activation
ctc_cost	speechbrain.nnet.losses.ctc_loss (partial)	CTC loss function with blank_index pre-bound
model_opt_class	torch.optim.Adadelta (partial)	Model optimizer constructor
wav2vec_opt_class	torch.optim.AdamW (partial)	Wav2vec2 optimizer constructor
lr_annealing_model	speechbrain.nnet.schedulers.NewBobScheduler	Model learning rate scheduler
lr_annealing_wav2vec	speechbrain.nnet.schedulers.NewBobScheduler	Wav2vec2 learning rate scheduler
checkpointer	speechbrain.utils.checkpoints.Checkpointer	Checkpoint manager
epoch_counter	speechbrain.utils.epoch_loop.EpochCounter	Epoch counter/iterator
error_rate_computer	speechbrain.utils.metric_stats.ErrorRateStats (partial)	WER metric computer
cer_computer	speechbrain.utils.metric_stats.ErrorRateStats (partial)	CER metric computer (with split_tokens=True)

Dependencies

• hyperpyyaml package -- external dependency, installable via pip
• speechbrain.parse_arguments() -- for parsing command-line overrides into the format expected by load_hyperpyyaml