Input and Output API

hyperion.io reads and writes waveform audio, keyed feature matrices, and voice-activity metadata. It is the boundary between files on disk and the NumPy/PyTorch workflows documented elsewhere.

CSV-indexed archives are the maintained interchange format. Use a paired Ark or HDF5 archive plus CSV index, for example ark,csv:embeddings.ark,embeddings.csv. Kaldi .scp inputs remain available only through legacy compatibility paths; new package workflows use CSV indexes.

Core contracts

Feature readers and writers use string keys. Writers associate each key with one matrix/vector and optional metadata; readers return data in key order. Keep keys identical across embedding archives, manifests, enrollment maps, and trial tables. Missing or reordered keys are alignment errors.

Use the factories rather than selecting concrete Ark/HDF5 implementations in application code. They parse the archive/index specifier and return the appropriate implementation.

class hyperion.io.DataWriterFactory

Factory that builds feature writers for H5 and Ark outputs.

Usage examples:

Create an H5 writer with CSV index output: >>> w = DataWriterFactory.create(“h5,csv:out/feat.h5,out/feat.csv”) >>> w.close()

Write one record using an H5+CSV writer: >>> import numpy as np >>> w = DataWriterFactory.create( … “h5,csv:out/feat.h5,out/feat.csv”, … metadata_columns=[“speaker”], … ) >>> x = np.random.randn(100, 80).astype(“float32”) >>> w.write(“utt1”, x, metadata={“speaker”: “spk1”}) >>> w.close()

Create an Ark writer with CSV index, compression and metadata columns: >>> w = DataWriterFactory.create( … “ark,csv:out/feat.ark,out/feat.csv”, … compress=True, … compression_method=”auto”, … metadata_columns=[“speaker”, “session”], … ) >>> w.close()

Parse external kwargs before creating a writer: >>> writer_kwargs = DataWriterFactory.filter_args( … compress=True, compression_method=”speech_feat” … ) >>> w = DataWriterFactory.create( … “h5:out/feat.h5”, compress=writer_kwargs[“compress”] … ) >>> w.close()

Create an Ark writer with a CSV sidecar: >>> w = DataWriterFactory.create(“ark,csv:out/feat.ark,out/feat.csv”) >>> w.close()

static create(wspecifier: str | Path | WSpecifier, compress: bool = False, compression_method: str = 'auto', metadata_columns: List[str] | None = None) → H5DataWriter | ArkDataWriter

Create a writer instance from a write specifier.

Parameters:

• wspecifier – Write specifier as string/path or pre-parsed WSpecifier.

• compress – If True, enable Kaldi compression when supported by the writer.

• compression_method – Kaldi compression method name.

• metadata_columns – Optional metadata column names for CSV/TSV script outputs.

Returns:

H5DataWriter or ArkDataWriter depending on the parsed archive type.

Raises:

ValueError – If the specifier is not an archive/both specifier or if the archive type is not supported by this factory.

static filter_args(**kwargs: Any) → Dict[str, Any]

Filter a kwargs dictionary to only writer-factory arguments.

Parameters:

kwargs – Arbitrary keyword arguments from CLI/config.

Returns:

Dictionary with keys accepted by create().

static add_class_args(parser: ArgumentParser, prefix: str | None = None) → None

Register writer-factory arguments in a jsonargparse parser.

Parameters:

• parser – Target parser to augment.

• prefix – Optional group prefix. When provided, arguments are nested under --<prefix> via ActionParser.

class hyperion.io.SequentialDataReaderFactory

Factory that builds sequential readers for H5/Ark sources.

Usage examples:

Create a sequential H5 file reader: >>> r = SequentialDataReaderFactory.create(“h5:data/feat.h5”) >>> keys, data = r.read(10) >>> r.close()

Create a sequential reader from CSV script with path prefix: >>> r = SequentialDataReaderFactory.create( … “csv:data/feat.csv”, … path_prefix=”/mnt/storage”, … part_idx=1, … num_parts=4, … ) >>> r.close()

Parse kwargs from a larger config dictionary: >>> reader_kwargs = SequentialDataReaderFactory.filter_args( … path_prefix=”/mnt/storage”, part_idx=2, num_parts=8 … ) >>> r = SequentialDataReaderFactory.create( … “csv:data/feat.csv”, path_prefix=reader_kwargs[“path_prefix”] … ) >>> r.close()

static create(rspecifier: str | Path | RSpecifier, path_prefix: str | Path | None = None, **kwargs: Any) → SequentialH5FileDataReader | SequentialArkFileDataReader | SequentialH5ScriptDataReader | SequentialArkScriptDataReader

Create a sequential reader from a read specifier.

Parameters:

• rspecifier – Read specifier as string/path or pre-parsed RSpecifier.

• path_prefix – Optional path prefix prepended to script entries.

• kwargs – Extra reader options (for example part_idx and num_parts).

Returns:

One of sequential reader implementations for H5 or Ark.

static filter_args(**kwargs: Any) → Dict[str, Any]

Filter kwargs to arguments accepted by sequential readers.

static add_class_args(parser: ArgumentParser, prefix: str | None = None) → None

Register sequential-reader arguments in a parser.

Parameters:

• parser – Target parser to augment.

• prefix – Optional nested argument prefix.

class hyperion.io.RandomAccessDataReaderFactory

Factory that builds random-access readers for H5/Ark scripts.

Usage examples:

Create random-access reader from an H5 file: >>> r = RandomAccessDataReaderFactory.create(“h5:data/feat.h5”) >>> x = r.read([“utt1”, “utt2”]) >>> r.close()

Create random-access reader from a CSV script with transform: >>> transform = lambda x: x.astype(np.float32) >>> r = RandomAccessDataReaderFactory.create( … “csv:data/feat_h5.csv”, … path_prefix=”/mnt/storage”, … transform=transform, … ) >>> r.close()

Create random-access Ark reader from an scp file: >>> r = RandomAccessDataReaderFactory.create(“csv:data/feat_ark.csv”) >>> r.close()

static create(rspecifier: str | Path | RSpecifier, path_prefix: str | Path | None = None, transform: Callable[[ndarray], ndarray] | None = None) → RandomAccessH5FileDataReader | RandomAccessH5ScriptDataReader | RandomAccessArkDataReader

Create a random-access reader from a read specifier.

Parameters:

• rspecifier – Read specifier as string/path or pre-parsed RSpecifier.

• path_prefix – Optional path prefix prepended to script entries.

• transform – Optional callable applied to each loaded matrix.

Returns:

One of random-access reader implementations for H5 or Ark-script.

Raises:

ValueError – If random access is requested directly on an Ark archive file without an accompanying script.

static filter_args(**kwargs: Any) → Dict[str, Any]

Filter kwargs to arguments accepted by random-access readers.

static add_class_args(parser: ArgumentParser, prefix: str | None = None) → None

Register random-access-reader arguments in a parser.

Parameters:

• parser – Target parser to augment.

• prefix – Optional nested argument prefix.

static add_argparse_args(parser: ArgumentParser, prefix: str | None = None) → None

Register random-access-reader arguments in a parser.

Parameters:

• parser – Target parser to augment.

• prefix – Optional nested argument prefix.

Archive specifications

Common write specifications:

ark,csv:exp/xvectors.ark,exp/xvectors.csv
h5,csv:exp/xvectors.h5,exp/xvectors.csv

Common read specifications:

csv:exp/xvectors.csv
ark:exp/xvectors.ark
h5:exp/xvectors.h5

The CSV index records keys and archive locations and can hold declared metadata columns. It is preferred because it is inspectable, extensible, and consistent with the manifest/table layer.

Feature API

class hyperion.io.data_reader.DataReader(file_path: str | Path, transform: TransformList | str | None = None, permissive: bool = False)

Abstract base class to read feature matrices from Ark/HDF5 backends.

__init__(file_path: str | Path, transform: TransformList | str | None = None, permissive: bool = False) → None

Abstract base class to read Ark or hdf5 feature files.

file_path

h5, ark or scp file to read.

transform

TransformList object, applies a transformation to the features after reading them from disk.

permissive

If True, if the data that we want to read is not in the file it returns an empty matrix, if False it raises an exception.

__enter__() → DataReader

Function required when entering constructions of type

with DataReader(‘file.h5’) as f:

keys, data = f.read()

__exit__(exc_type: Type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None) → None

Function required when exiting from constructions of type

with DataReader(‘file.h5’) as f:

keys, data = f.read()

abstractmethod close() → None

Closes input file.

static _squeeze(data: List[ndarray], permissive: bool = False) → ndarray

Converts list of matrices to 3D numpy array or

list of vectors to 2D numpy array.

Parameters:

• data – List of matrices or vectors.

• permissive – If True, if one of the matrices/vectors in data is empty, it substitutes it by matrix/vector with all zeros. If false, it raises exception.

Returns:

2D or 3D numpy array.

static _combine_ranges(read_range: Tuple[int, int] | None, row_offset: int, num_rows: int) → Tuple[int, int]

Combines two frame ranges.

One is the range in the scp file, e.g, in the scp file

recording1 file1.ark:34[3:40] recording2 file1.ark:100[5:20]

[3:40] and [5:20] are frame ranges.

The user can decide to just read a submatrix of that, e.g., read 10 rows starting in row_offset 1. If we combine that with the range [3:40], the function returns. row_offset=4 (3+1) and num_rows=10.

Parameters:

• read_range – Frame range from scp file. It is a tuple with the first row and number of rows to read.

• row_offset – User defined row_offset.

• num_rows – User defined number of rows to read, it it is 0, we read all the rows defined in the scp read_range.

Returns:

Combined row_offset, first row of the recording to read. Combined number of rows (frames) to read.

static _apply_range_to_shape(shape: Tuple[int, ...], row_offset: int, num_rows: int) → Tuple[int, ...]

Modifies shape given the user defined row_offset and num_rows to read.

If we are reading a matrix of shape (100,4) and row_offset=10, num_rows=20, it returns (20,4). If row_offset=20, num_rows=0, it returns (80,4).

Parameters:

• shape – Original shape of the feature matrix.

• row_offset – User defined row_offset, first frame to read.

• num_rows – User defined num_rows, number of frames to read.

Returns:

2D tuple with modified shape.

class hyperion.io.data_writer.DataWriter(archive_path: str | Path, script_path: str | Path | None = None, flush: bool = False, compress: bool = False, compression_method: str = 'auto', metadata_columns: List[str] | None = None)

Abstract base class to write Ark or hdf5 feature files.

archive_path

output data file path.

script_path

Optional output index file.

flush

If True, it flushes the output after writing each feature matrix.

compress

Whether to use Kaldi compression.

compression_method

Kaldi compression method. Supported values are auto (default), speech_feat, 2byte-auto, 2byte-signed-integer, 1byte-auto, 1byte-unsigned-integer, and 1byte-0-1.

metadata_columns

Optional metadata columns for non-SCP index files.

__init__(archive_path: str | Path, script_path: str | Path | None = None, flush: bool = False, compress: bool = False, compression_method: str = 'auto', metadata_columns: List[str] | None = None) → None

Initialize writer configuration and output files.

__enter__() → DataWriter

Enter a writer context.

Example:

with DataWriter("file.h5") as writer:
    writer.write(key, data)

abstractmethod __exit__(exc_type: Type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None) → None

Exit a writer context.

The concrete writer closes its output files.

abstractmethod close() → None

Close the output files.

abstractmethod flush() → None

Flush buffered output data.

standardize_write_args(keys: str | List[str] | ndarray, data: ndarray | List[ndarray | KaldiMatrix | KaldiCompressedMatrix], metadata: DataFrame | Dict[str, object | List[object] | ndarray] | None = None) → Tuple[List[str], List[ndarray | KaldiMatrix | KaldiCompressedMatrix], List[List[object]] | None]

Normalize write arguments to list form and validate list lengths.

static _escape_script_field(value: object, sep: str | None) → str

Escape a value written to a CSV/TSV-like script row.

abstractmethod write(keys: str | List[str] | ndarray, data: ndarray | List[ndarray | KaldiMatrix | KaldiCompressedMatrix], metadata: DataFrame | Dict[str, object | List[object] | ndarray] | None = None) → None

Writes data to file.

Parameters:

• keys – List of recording names.

• data – List of Feature matrices or vectors. If all the matrices have the same dimension it can be a 3D numpy array. If they are vectors, it can be a 2D numpy array.

• metadata – Dictionary/DataFrame with metadata values.

class hyperion.io.ArkDataWriter(archive_path: str | Path, script_path: str | Path | None = None, binary: bool = True, **kwargs)

Class to write Ark feature files.

archive_path

output data file path.

script_path

Optional output index file.

binary

True if the the Ark file is binary, False if it is text file.

flush

If True, it flushes the output after writing each feature file.

compress

Whether to use Kaldi compression.

compression_method

Kaldi compression method. Supported values are auto (default), speech_feat, 2byte-auto, 2byte-signed-integer, 1byte-auto, 1byte-unsigned-integer, and 1byte-0-1.

__init__(archive_path: str | Path, script_path: str | Path | None = None, binary: bool = True, **kwargs) → None

Initialize writer configuration and output files.

__exit__(exc_type: Type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None) → None

Exit the writer context and close the output file.

Example:

with ArkDataWriter("file.ark") as writer:
    writer.write(key, data)

close() → None

Close output files.

flush() → None

Flush buffered output data.

_convert_data(data: ndarray | KaldiMatrix | KaldiCompressedMatrix) → KaldiMatrix | KaldiCompressedMatrix

Converts the feature matrix from numpy array to KaldiMatrix or KaldiCompressedMatrix.

Compression is only applied to 2D arrays/matrices.

__enter__() → DataWriter

Enter a writer context.

Example:

with DataWriter("file.h5") as writer:
    writer.write(key, data)

static _escape_script_field(value: object, sep: str | None) → str

Escape a value written to a CSV/TSV-like script row.

standardize_write_args(keys: str | List[str] | ndarray, data: ndarray | List[ndarray | KaldiMatrix | KaldiCompressedMatrix], metadata: DataFrame | Dict[str, object | List[object] | ndarray] | None = None) → Tuple[List[str], List[ndarray | KaldiMatrix | KaldiCompressedMatrix], List[List[object]] | None]

Normalize write arguments to list form and validate list lengths.

write(keys: str | List[str] | ndarray, data: ndarray | List[ndarray | KaldiMatrix | KaldiCompressedMatrix] | KaldiMatrix | KaldiCompressedMatrix, metadata: DataFrame | Dict[str, object | List[object] | ndarray] | None = None) → None

Writes data to file.

Parameters:

• keys – List of recording names.

• data – List of Feature matrices or vectors. If all the matrices have the same dimension it can be a 3D numpy array. If they are vectors, it can be a 2D numpy array. It also accepts KaldiMatrix/KaldiCompressedMatrix objects.

• metadata – Dictionary/DataFrame with metadata values.

class hyperion.io.H5DataWriter(archive_path: str | Path, script_path: str | Path | None = None, **kwargs)

Class to write hdf5 feature files.

archive_path

output data file path.

script_path

Optional output index file.

flush

If True, it flushes the output after writing each feature file.

compress

Whether to use Kaldi compression.

compression_method

Kaldi compression method. Supported values are auto (default), speech_feat, 2byte-auto, 2byte-signed-integer, 1byte-auto, 1byte-unsigned-integer, and 1byte-0-1.

__init__(archive_path: str | Path, script_path: str | Path | None = None, **kwargs) → None

Initialize an HDF5 data writer.

__exit__(exc_type: Type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None) → None

Exit the writer context and close the output file.

Example:

with H5DataWriter("file.h5") as writer:
    writer.write(key, data)

close() → None

Close output files.

flush() → None

Flush buffered output data.

_convert_data(data: ndarray) → Tuple[ndarray, Dict[str, object] | None]

Converts data to the format for saving. Compresses the data if needed. Compression is only applied to 2D arrays. :param data: Numpy array feature matrix/vector.

Returns:

Numpy array to save in h5 file. Attributes for the hdf5 dataset with information about the compression.

write(keys: str | List[str] | ndarray, data: ndarray | List[ndarray | KaldiMatrix | KaldiCompressedMatrix], metadata: DataFrame | Dict[str, object | List[object] | ndarray] | None = None) → None

Writes data to file.

Parameters:

• keys – List of recording names.

• data – List of Feature matrices or vectors. If all the matrices have the same dimension it can be a 3D numpy array. If they are vectors, it can be a 2D numpy array. Non-numpy inputs are rejected at runtime.

• metadata – Dictionary/DataFrame with metadata values.

__enter__() → DataWriter

Enter a writer context.

Example:

with DataWriter("file.h5") as writer:
    writer.write(key, data)

static _escape_script_field(value: object, sep: str | None) → str

Escape a value written to a CSV/TSV-like script row.

standardize_write_args(keys: str | List[str] | ndarray, data: ndarray | List[ndarray | KaldiMatrix | KaldiCompressedMatrix], metadata: DataFrame | Dict[str, object | List[object] | ndarray] | None = None) → Tuple[List[str], List[ndarray | KaldiMatrix | KaldiCompressedMatrix], List[List[object]] | None]

Normalize write arguments to list form and validate list lengths.

For random lookup of embeddings by segment id, use RandomAccessDataReaderFactory. For sequential bulk processing, use SequentialDataReaderFactory. The scoring commands use random access because enrollment and trial tables select vectors by id.

Audio API

class hyperion.io.AudioReader(dataset: HyperDataset | str | Path | None = None, recordings: RecordingSet | str | Path | None = None, segments: SegmentSet | str | Path | None = None, wav_scale: float = 1.0, target_sample_freq: int | None = None, channels_first: bool = True, always_2d: bool = False, return_all_channels: bool = False)

Read audio waveforms from wav, flac, pipe commands, and related formats.

This class receives either a HyperDataset or standalone RecordingSet (with an optional SegmentSet). When providing only a recordings table, the reader can use the accompanying segment table to extract specific time spans from each recording.

Parameters:

• dataset (Union[HyperDataset, PathLike, None]) – Dataset instance or path to a dataset file containing recordings and, optionally, segments.

• recordings (Union[RecordingSet, PathLike, None]) – Recording table or path to a recordings file when dataset is None.

• segments (Union[SegmentSet, PathLike, None]) – Segment table or path to a segments file. Must be None when dataset is provided.

• wav_scale (float) – Multiplicative factor applied to every waveform.

• target_sample_freq (Optional[int]) – Target sampling frequency used for optional resampling.

• channels_first (bool) – If True returns waveforms using the (channels, num_samples) ordering; otherwise uses (num_samples, channels).

• always_2d (bool) – If True keeps a trailing channel dimension even for mono audio.

• return_all_channels (bool) – If True returns every channel from multi-channel recordings instead of selecting a single channel.

recordings

Table describing the recordings to load.

Type:

RecordingSet

segments

Table with segment definitions when the reader operates in segment mode.

Type:

Optional[SegmentSet]

with_segments

Whether the reader was configured with segment metadata.

Type:

bool

wav_scale

Multiplicative factor applied to each waveform.

Type:

float

target_sample_freq

Requested resampling target. None disables resampling.

Type:

Optional[int]

channels_first

Shape convention for returned waveforms.

Type:

bool

always_2d

Whether mono audio retains a channel axis.

Type:

bool

return_all_channels

Whether to return every channel for multi-channel audio.

Type:

bool

resampler

Resampler used when a target sampling rate is requested.

Type:

Optional[Any2AnyFreqResampler]

__init__(dataset: HyperDataset | str | Path | None = None, recordings: RecordingSet | str | Path | None = None, segments: SegmentSet | str | Path | None = None, wav_scale: float = 1.0, target_sample_freq: int | None = None, channels_first: bool = True, always_2d: bool = False, return_all_channels: bool = False)

property keys: ndarray[Any, dtype[Any]]

__enter__() → AudioReader

Enter the context manager.

Returns:

The current reader instance for chained usage.

Return type:

AudioReader

Example

>>> with AudioReader(dataset="file.h5") as reader:
...     keys, data, fs = reader.read()

__exit__(exc_type: Type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None) → None

Exit the context manager.

Parameters:

• exc_type – Exception type raised inside the context (if any).

• exc_value – Exception value raised inside the context (if any).

• traceback – Traceback information for the exception (if any).

The reader does not allocate external resources, so no explicit cleanup is required.

static channel_name_to_idx(channel: int | str, num_channels: int) → int

Convert a human-readable channel descriptor to a zero-based index.

Parameters:

• channel (Union[int, str]) – Channel index (1-based) or mnemonic such as "left"/"right"/"center".

• num_channels (int) – Number of channels available in the recording.

Returns:

Zero-based channel index.

Return type:

int

Raises:

Exception – If channel is unknown or not available in the recording.

static read_wavspecifier(wavspecifier: str | Path, scale: float = 1.0, time_offset: float = 0.0, time_dur: float = 0.0, channels_first: bool = True, always_2d: bool = False) → Tuple[ndarray, int]

Read audio from a file path or shell pipe specification.

Supports pipes as well as every format handled by libsndfile (wav, flac, ogg, etc.) together with the extensions listed in valid_ext.

Parameters:

• wavspecifier (PathLike) – Pipe command or audio file path (wav, flac, ogg, etc.).

• scale (float) – Multiplicative factor applied to the waveform.

• time_offset (float) – Start time in seconds relative to the beginning of the utterance.

• time_dur (float) – Duration in seconds to read. 0 reads the audio until the end of the utterance.

• channels_first (bool) – If True returns waveforms as (channels, num_samples).

• always_2d (bool) – Forces single-channel audio to retain a channel dimension.

Returns:

Waveform and sampling rate.

Return type:

Tuple[np.ndarray, int]

Raises:

Exception – If the specifier points to an unsupported format.

static read_pipe(wavspecifier: str | Path, scale: float = 1.0, time_offset: float = 0, time_dur: float = 0, channels_first: bool = True, always_2d: bool = False) → Tuple[ndarray, int]

Read audio produced by a shell pipe command.

Parameters:

• wavspecifier (PathLike) – Shell command whose stdout returns the encoded waveform.

• scale (float) – Multiplicative factor applied to the waveform.

• time_offset (float) – Start time in seconds relative to the pipe output.

• time_dur (float) – Duration in seconds to read. 0 reads until the end of the available samples.

• channels_first (bool) – If True returns waveforms as (channels, num_samples).

• always_2d (bool) – Forces single-channel audio to retain a channel dimension.

Returns:

Waveform and sampling rate.

Return type:

Tuple[np.ndarray, int]

Raises:

Exception – If the pipe command returns a non-zero exit status.

static read_file_sf(wavspecifier: str | Path, scale: float = 1.0, time_offset: float = 0, time_dur: float = 0, channels_first: bool = True, always_2d: bool = False) → Tuple[ndarray, int]

Read audio from disk using soundfile.

Parameters:

• wavspecifier (PathLike) – Audio file path readable by libsndfile.

• scale (float) – Multiplicative factor applied to the waveform.

• time_offset (float) – Start time in seconds relative to the beginning of the recording.

• time_dur (float) – Duration in seconds to read. 0 reads until the end of the recording.

• channels_first (bool) – If True returns waveforms as (channels, num_samples).

• always_2d (bool) – Forces single-channel audio to retain a channel dimension.

Returns:

Waveform and sampling rate.

Return type:

Tuple[np.ndarray, int]

static read_file_torchaudio(wavspecifier: str | Path, scale: float = 1.0, time_offset: float = 0, time_dur: float = 0, channels_first: bool = True, always_2d: bool = False) → Tuple[ndarray, int]

Read audio from disk using torchaudio.

Parameters:

• wavspecifier (PathLike) – Audio file path readable by torchaudio.

• scale (float) – Multiplicative factor applied to the waveform.

• time_offset (float) – Start time in seconds relative to the beginning of the recording.

• time_dur (float) – Duration in seconds to read. 0 reads until the end of the recording.

• channels_first (bool) – If True returns waveforms as (channels, num_samples).

• always_2d (bool) – Forces single-channel audio to retain a channel dimension.

Returns:

Waveform and sampling rate.

Return type:

Tuple[np.ndarray, int]

static read_file(wavspecifier: str | Path, scale: float = 1.0, time_offset: float = 0, time_dur: float = 0, channels_first: bool = True, always_2d: bool = False) → Tuple[ndarray, int]

Read audio from disk, retrying with progressively broader fallbacks.

Parameters:

• wavspecifier (PathLike) – Audio file path.

• scale (float) – Multiplicative factor applied to the waveform.

• time_offset (float) – Start time in seconds relative to the beginning of the recording.

• time_dur (float) – Duration in seconds to read. 0 reads until the end of the recording.

• channels_first (bool) – If True returns waveforms as (channels, num_samples).

• always_2d (bool) – Forces single-channel audio to retain a channel dimension.

Returns:

Waveform and sampling rate.

Return type:

Tuple[np.ndarray, int]

Raises:

RuntimeError – If the audio cannot be read by any backend.

Notes

Attempts to read with soundfile first (except for .mp3, which uses torchaudio first), including a relaxed slicing strategy to recover from libsndfile fseek issues, and finally falls back to torchaudio when required.

_read_recording(recording: Series, time_offset: float = 0, time_dur: float = 0, channels_first: bool = True, always_2d: bool = False, return_all_channels: bool = False) → Tuple[ndarray, int] | Tuple[ndarray, int, int]

Load a recording defined in the recordings table.

Parameters:

• recording (pd.Series) – Row from the recordings table (requires a storage_path field and optional channel).

• time_offset (float) – Start time in seconds relative to the beginning of the recording.

• time_dur (float) – Duration in seconds to read.

• channels_first (bool) – If True returns waveforms as (channels, num_samples).

• always_2d (bool) – Forces single-channel audio to retain a channel dimension.

• return_all_channels (bool) – If True returns every channel available.

Returns:

Waveform and sampling rate when a single channel is returned.

Tuple[np.ndarray, int, int]: Waveform, sampling rate, and selected channel index when return_all_channels is True.

Return type:

Tuple[np.ndarray, int]

_read_segment(segment: Series, time_offset: float = 0, time_dur: float = 0, channels_first: bool = True, always_2d: bool = False, return_all_channels: bool = False) → Tuple[ndarray, int] | Tuple[ndarray, int, int]

Load a segment defined in the segments table.

Parameters:

• segment (pd.Series) – Row from the segments table (expects recording, start, and duration fields).

• time_offset (float) – Additional start offset in seconds relative to the segment start.

• time_dur (float) – Duration in seconds to read. 0 reads the full segment after applying time_offset.

• channels_first (bool) – If True returns waveforms as (channels, num_samples).

• always_2d (bool) – Forces single-channel audio to retain a channel dimension.

• return_all_channels (bool) – If True returns every channel available.

Returns:

Waveform and sampling rate when a single channel is returned.

Tuple[np.ndarray, int, int]: Waveform, sampling rate, and selected channel index when return_all_channels is True.

Return type:

Tuple[np.ndarray, int]

read(*args: Any, **kwargs: Any) → Any

class hyperion.io.SequentialAudioReader(dataset: HyperDataset | str | Path | None = None, recordings: RecordingSet | str | Path | None = None, segments: SegmentSet | str | Path | None = None, wav_scale: float = 1.0, part_idx: int = 1, num_parts: int = 1, target_sample_freq: int | None = None, channels_first: bool = True, always_2d: bool = False, return_all_channels: bool = False)

Iterate through recordings or segments sequentially.

Parameters:

• dataset (Union[HyperDataset, PathLike, None]) – Dataset instance or path to a dataset file.

• recordings (Union[RecordingSet, PathLike, None]) – Recording table or path to a recordings file when dataset is None.

• segments (Union[SegmentSet, PathLike, None]) – Segment table or path to a segments file. Must be None when dataset is provided.

• wav_scale (float) – Multiplicative factor applied to every waveform.

• part_idx (int) – Index of the partition to process when splitting the dataset.

• num_parts (int) – Number of partitions used to split the dataset.

• target_sample_freq (Optional[int]) – Target sampling frequency used for optional resampling.

• channels_first (bool) – If True returns waveforms as (channels, num_samples).

• always_2d (bool) – Forces single-channel audio to retain a channel dimension.

• return_all_channels (bool) – If True returns every channel available.

dataset

Dataset reference used to initialize the reader, when applicable.

Type:

Optional[Union[HyperDataset, PathLike]]

recordings

Table describing the recordings to load.

Type:

RecordingSet

segments

Table with segment definitions when the reader operates in segment mode.

Type:

Optional[SegmentSet]

wav_scale

Multiplicative factor applied to each waveform.

Type:

float

part_idx

Partition index being processed by this reader.

Type:

int

num_parts

Total number of partitions across which the dataset is split.

Type:

int

target_sample_freq

Target sampling frequency used for optional resampling.

Type:

Optional[int]

channels_first

Shape convention for returned waveforms.

Type:

bool

always_2d

Whether mono audio retains a channel axis.

Type:

bool

return_all_channels

Whether to return every channel for multi-channel audio.

Type:

bool

cur_item

Index of the next item to read.

Type:

int

Examples

>>> with SequentialAudioReader(recordings="recordings.csv") as reader:
...     keys, wavs, fs = reader.read(num_records=2)
>>> for key, wav, fs in SequentialAudioReader(recordings="recordings.csv"):
...     process(key, wav, fs)
>>> reader = SequentialAudioReader(
...     recordings="recordings.csv",
...     return_all_channels=True,
...     always_2d=True,
... )
>>> keys, wavs, fs, channels = reader.read(num_records=1)
>>> seg_reader = SequentialAudioReader(
...     recordings="recordings.csv",
...     segments="segments.csv",
...     target_sample_freq=16000,
... )
>>> keys, wavs, fs = seg_reader.read(num_records=4, time_offset=0.0, time_durs=1.5)

__init__(dataset: HyperDataset | str | Path | None = None, recordings: RecordingSet | str | Path | None = None, segments: SegmentSet | str | Path | None = None, wav_scale: float = 1.0, part_idx: int = 1, num_parts: int = 1, target_sample_freq: int | None = None, channels_first: bool = True, always_2d: bool = False, return_all_channels: bool = False)

__iter__() → SequentialAudioReader

Return the iterator so the reader can be used in loops.

Example

>>> for key, wav, fs in SequentialAudioReader(recordings=rs):
...     process(key, wav, fs)

__next__() → Tuple[str, ndarray, int] | Tuple[str, ndarray, int, int]

Return the next sequential item.

Returns:

Key, waveform, and sampling rate when a single channel is returned.

Tuple[str, np.ndarray, int, int]: Key, waveform, sampling rate, and channel index when return_all_channels is True.

Return type:

Tuple[str, np.ndarray, int]

Raises:

StopIteration – When the reader is exhausted.

next() → Tuple[str, ndarray, int] | Tuple[str, ndarray, int, int]

Python 2 compatibility alias for __next__().

reset() → None

Reset the internal pointer to the beginning of the dataset.

eof() → bool

Check whether all recordings or segments have been consumed.

Returns:

True when the reader has produced every item.

Return type:

bool

read(num_records: int = 0, time_offset: float | List[float] | ndarray = 0, time_durs: float | List[float] | ndarray = 0) → Tuple[List[str], List[ndarray], List[int]] | Tuple[List[str], List[ndarray], List[int], List[int]]

Read the next group of recordings or segments.

Parameters:

• num_records (int) – Number of items to read (0 reads the remainder of the dataset).

• time_offset (float) – Scalar or per-item offsets in seconds to apply before reading each item.

• time_durs (float) – Scalar or per-item durations in seconds. 0 reads until the end of each item.

Returns:

Keys, waveforms, and sampling rates when returning a single channel per item.

Tuple[List[str], List[np.ndarray], List[int], List[int]]: Keys, waveforms, sampling rates, and channel indices when return_all_channels is True.

Return type:

Tuple[List[str], List[np.ndarray], List[int]]

static filter_args(**kwargs: Any) → Dict[str, Any]

Select keyword arguments relevant to the sequential reader.

Parameters:

**kwargs – Arbitrary keyword arguments.

Returns:

Subset containing only recognized reader arguments.

Return type:

Dict[str, Any]

static add_class_args(parser: ArgumentParser, prefix: str | None = None) → None

Register command-line arguments for SequentialAudioReader.

Parameters:

• parser (ArgumentParser) – Parser where arguments are to be added.

• prefix (Optional[str]) – Optional prefix to nest arguments under a group.

static add_argparse_args(parser: ArgumentParser, prefix: str | None = None) → None

Register command-line arguments for SequentialAudioReader.

Parameters:

• parser (ArgumentParser) – Parser where arguments are to be added.

• prefix (Optional[str]) – Optional prefix to nest arguments under a group.

__enter__() → AudioReader

Enter the context manager.

Returns:

The current reader instance for chained usage.

Return type:

AudioReader

Example

>>> with AudioReader(dataset="file.h5") as reader:
...     keys, data, fs = reader.read()

__exit__(exc_type: Type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None) → None

Exit the context manager.

Parameters:

• exc_type – Exception type raised inside the context (if any).

• exc_value – Exception value raised inside the context (if any).

• traceback – Traceback information for the exception (if any).

The reader does not allocate external resources, so no explicit cleanup is required.

_read_recording(recording: Series, time_offset: float = 0, time_dur: float = 0, channels_first: bool = True, always_2d: bool = False, return_all_channels: bool = False) → Tuple[ndarray, int] | Tuple[ndarray, int, int]

Load a recording defined in the recordings table.

Parameters:

• recording (pd.Series) – Row from the recordings table (requires a storage_path field and optional channel).

• time_offset (float) – Start time in seconds relative to the beginning of the recording.

• time_dur (float) – Duration in seconds to read.

• channels_first (bool) – If True returns waveforms as (channels, num_samples).

• always_2d (bool) – Forces single-channel audio to retain a channel dimension.

• return_all_channels (bool) – If True returns every channel available.

Returns:

Waveform and sampling rate when a single channel is returned.

Tuple[np.ndarray, int, int]: Waveform, sampling rate, and selected channel index when return_all_channels is True.

Return type:

Tuple[np.ndarray, int]

_read_segment(segment: Series, time_offset: float = 0, time_dur: float = 0, channels_first: bool = True, always_2d: bool = False, return_all_channels: bool = False) → Tuple[ndarray, int] | Tuple[ndarray, int, int]

Load a segment defined in the segments table.

Parameters:

• segment (pd.Series) – Row from the segments table (expects recording, start, and duration fields).

• time_offset (float) – Additional start offset in seconds relative to the segment start.

• time_dur (float) – Duration in seconds to read. 0 reads the full segment after applying time_offset.

• channels_first (bool) – If True returns waveforms as (channels, num_samples).

• always_2d (bool) – Forces single-channel audio to retain a channel dimension.

• return_all_channels (bool) – If True returns every channel available.

Returns:

Waveform and sampling rate when a single channel is returned.

Tuple[np.ndarray, int, int]: Waveform, sampling rate, and selected channel index when return_all_channels is True.

Return type:

Tuple[np.ndarray, int]

static channel_name_to_idx(channel: int | str, num_channels: int) → int

Convert a human-readable channel descriptor to a zero-based index.

Parameters:

• channel (Union[int, str]) – Channel index (1-based) or mnemonic such as "left"/"right"/"center".

• num_channels (int) – Number of channels available in the recording.

Returns:

Zero-based channel index.

Return type:

int

Raises:

Exception – If channel is unknown or not available in the recording.

property keys: ndarray[Any, dtype[Any]]

static read_file(wavspecifier: str | Path, scale: float = 1.0, time_offset: float = 0, time_dur: float = 0, channels_first: bool = True, always_2d: bool = False) → Tuple[ndarray, int]

Read audio from disk, retrying with progressively broader fallbacks.

Parameters:

• wavspecifier (PathLike) – Audio file path.

• scale (float) – Multiplicative factor applied to the waveform.

• time_offset (float) – Start time in seconds relative to the beginning of the recording.

• time_dur (float) – Duration in seconds to read. 0 reads until the end of the recording.

• channels_first (bool) – If True returns waveforms as (channels, num_samples).

• always_2d (bool) – Forces single-channel audio to retain a channel dimension.

Returns:

Waveform and sampling rate.

Return type:

Tuple[np.ndarray, int]

Raises:

RuntimeError – If the audio cannot be read by any backend.

Notes

Attempts to read with soundfile first (except for .mp3, which uses torchaudio first), including a relaxed slicing strategy to recover from libsndfile fseek issues, and finally falls back to torchaudio when required.

static read_file_sf(wavspecifier: str | Path, scale: float = 1.0, time_offset: float = 0, time_dur: float = 0, channels_first: bool = True, always_2d: bool = False) → Tuple[ndarray, int]

Read audio from disk using soundfile.

Parameters:

• wavspecifier (PathLike) – Audio file path readable by libsndfile.

• scale (float) – Multiplicative factor applied to the waveform.

• time_offset (float) – Start time in seconds relative to the beginning of the recording.

• time_dur (float) – Duration in seconds to read. 0 reads until the end of the recording.

• channels_first (bool) – If True returns waveforms as (channels, num_samples).

• always_2d (bool) – Forces single-channel audio to retain a channel dimension.

Returns:

Waveform and sampling rate.

Return type:

Tuple[np.ndarray, int]

static read_file_torchaudio(wavspecifier: str | Path, scale: float = 1.0, time_offset: float = 0, time_dur: float = 0, channels_first: bool = True, always_2d: bool = False) → Tuple[ndarray, int]

Read audio from disk using torchaudio.

Parameters:

• wavspecifier (PathLike) – Audio file path readable by torchaudio.

• scale (float) – Multiplicative factor applied to the waveform.

• time_offset (float) – Start time in seconds relative to the beginning of the recording.

• time_dur (float) – Duration in seconds to read. 0 reads until the end of the recording.

• channels_first (bool) – If True returns waveforms as (channels, num_samples).

• always_2d (bool) – Forces single-channel audio to retain a channel dimension.

Returns:

Waveform and sampling rate.

Return type:

Tuple[np.ndarray, int]

static read_pipe(wavspecifier: str | Path, scale: float = 1.0, time_offset: float = 0, time_dur: float = 0, channels_first: bool = True, always_2d: bool = False) → Tuple[ndarray, int]

Read audio produced by a shell pipe command.

Parameters:

• wavspecifier (PathLike) – Shell command whose stdout returns the encoded waveform.

• scale (float) – Multiplicative factor applied to the waveform.

• time_offset (float) – Start time in seconds relative to the pipe output.

• time_dur (float) – Duration in seconds to read. 0 reads until the end of the available samples.

• channels_first (bool) – If True returns waveforms as (channels, num_samples).

• always_2d (bool) – Forces single-channel audio to retain a channel dimension.

Returns:

Waveform and sampling rate.

Return type:

Tuple[np.ndarray, int]

Raises:

Exception – If the pipe command returns a non-zero exit status.

static read_wavspecifier(wavspecifier: str | Path, scale: float = 1.0, time_offset: float = 0.0, time_dur: float = 0.0, channels_first: bool = True, always_2d: bool = False) → Tuple[ndarray, int]

Read audio from a file path or shell pipe specification.

Supports pipes as well as every format handled by libsndfile (wav, flac, ogg, etc.) together with the extensions listed in valid_ext.

Parameters:

• wavspecifier (PathLike) – Pipe command or audio file path (wav, flac, ogg, etc.).

• scale (float) – Multiplicative factor applied to the waveform.

• time_offset (float) – Start time in seconds relative to the beginning of the utterance.

• time_dur (float) – Duration in seconds to read. 0 reads the audio until the end of the utterance.

• channels_first (bool) – If True returns waveforms as (channels, num_samples).

• always_2d (bool) – Forces single-channel audio to retain a channel dimension.

Returns:

Waveform and sampling rate.

Return type:

Tuple[np.ndarray, int]

Raises:

Exception – If the specifier points to an unsupported format.

class hyperion.io.RandomAccessAudioReader(dataset: HyperDataset | str | Path | None = None, recordings: RecordingSet | str | Path | None = None, segments: SegmentSet | str | Path | None = None, wav_scale: float = 1.0, target_sample_freq: int | None = None, channels_first: bool = True, always_2d: bool = False, return_all_channels: bool = False)

Provide random access to recordings or segments on demand.

Parameters:

• dataset (Union[HyperDataset, PathLike, None]) – Dataset instance or path to a dataset file.

• recordings (Union[RecordingSet, PathLike, None]) – Recording table or path to a recordings file when dataset is None.

• segments (Union[SegmentSet, PathLike, None]) – Segment table or path to a segments file. Must be None when dataset is provided.

• wav_scale (float) – Multiplicative factor applied to every waveform.

• target_sample_freq (Optional[int]) – Target sampling frequency used for optional resampling.

• channels_first (bool) – If True returns waveforms as (channels, num_samples).

• always_2d (bool) – Forces single-channel audio to retain a channel dimension.

• return_all_channels (bool) – If True returns every channel available.

dataset

Dataset reference used to initialize the reader, when applicable.

Type:

Optional[Union[HyperDataset, PathLike]]

recordings

Table describing the recordings to load.

Type:

RecordingSet

segments

Table with segment definitions when the reader operates in segment mode.

Type:

Optional[SegmentSet]

wav_scale

Multiplicative factor applied to each waveform.

Type:

float

target_sample_freq

Target sampling frequency used for optional resampling.

Type:

Optional[int]

channels_first

Shape convention for returned waveforms.

Type:

bool

always_2d

Whether mono audio retains a channel axis.

Type:

bool

return_all_channels

Whether queries return every channel rather than a single mixdown.

Type:

bool

Examples

>>> reader = RandomAccessAudioReader(recordings="recordings.csv")
>>> wavs, fs = reader.read(["utt1", "utt2"], time_offset=[0.0, 0.5], time_durs=1.0)
>>> wav, fs = reader.read("utt1")
>>> seg_reader = RandomAccessAudioReader(
...     recordings="recordings.csv",
...     segments="segments.csv",
... )
>>> wavs, fs = seg_reader.read(["seg1", "seg2"], time_durs=[0.8, 1.2])
>>> ch_reader = RandomAccessAudioReader(
...     recordings="recordings.csv",
...     return_all_channels=True,
...     always_2d=True,
... )
>>> wavs, fs, channels = ch_reader.read("utt1")

__init__(dataset: HyperDataset | str | Path | None = None, recordings: RecordingSet | str | Path | None = None, segments: SegmentSet | str | Path | None = None, wav_scale: float = 1.0, target_sample_freq: int | None = None, channels_first: bool = True, always_2d: bool = False, return_all_channels: bool = False)

read(keys: str | List[str], time_offset: float | List[float] | ndarray = 0, time_durs: float | List[float] | ndarray = 0) → Tuple[List[ndarray], List[int]] | Tuple[List[ndarray], List[int], List[int]]

Fetch the waveforms for the requested keys.

Parameters:

• keys (Union[str, List[str]]) – Recording or segment identifiers.

• time_offset (float) – Scalar or per-item offsets in seconds.

• time_durs (float) – Scalar or per-item durations in seconds. 0 reads until the end of each item.

Returns:

Waveforms and sampling rates when returning a single channel per item.

Tuple[List[np.ndarray], List[int], List[int]]: Waveforms, sampling rates, and channel indices when return_all_channels is True.

Return type:

Tuple[List[np.ndarray], List[int]]

Raises:

Exception – If a requested key is not found.

static filter_args(**kwargs: Any) → Dict[str, Any]

Select keyword arguments relevant to the random-access reader.

Parameters:

**kwargs – Arbitrary keyword arguments.

Returns:

Subset containing only recognized reader arguments.

Return type:

Dict[str, Any]

static add_class_args(parser: ArgumentParser, prefix: str | None = None) → None

Register command-line arguments for RandomAccessAudioReader.

Parameters:

• parser (ArgumentParser) – Parser where arguments are to be added.

• prefix (Optional[str]) – Optional prefix to nest arguments under a group.

__enter__() → AudioReader

Enter the context manager.

Returns:

The current reader instance for chained usage.

Return type:

AudioReader

Example

>>> with AudioReader(dataset="file.h5") as reader:
...     keys, data, fs = reader.read()

__exit__(exc_type: Type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None) → None

Exit the context manager.

Parameters:

• exc_type – Exception type raised inside the context (if any).

• exc_value – Exception value raised inside the context (if any).

• traceback – Traceback information for the exception (if any).

The reader does not allocate external resources, so no explicit cleanup is required.

_read_recording(recording: Series, time_offset: float = 0, time_dur: float = 0, channels_first: bool = True, always_2d: bool = False, return_all_channels: bool = False) → Tuple[ndarray, int] | Tuple[ndarray, int, int]

Load a recording defined in the recordings table.

Parameters:

• recording (pd.Series) – Row from the recordings table (requires a storage_path field and optional channel).

• time_offset (float) – Start time in seconds relative to the beginning of the recording.

• time_dur (float) – Duration in seconds to read.

• channels_first (bool) – If True returns waveforms as (channels, num_samples).

• always_2d (bool) – Forces single-channel audio to retain a channel dimension.

• return_all_channels (bool) – If True returns every channel available.

Returns:

Waveform and sampling rate when a single channel is returned.

Tuple[np.ndarray, int, int]: Waveform, sampling rate, and selected channel index when return_all_channels is True.

Return type:

Tuple[np.ndarray, int]

_read_segment(segment: Series, time_offset: float = 0, time_dur: float = 0, channels_first: bool = True, always_2d: bool = False, return_all_channels: bool = False) → Tuple[ndarray, int] | Tuple[ndarray, int, int]

Load a segment defined in the segments table.

Parameters:

• segment (pd.Series) – Row from the segments table (expects recording, start, and duration fields).

• time_offset (float) – Additional start offset in seconds relative to the segment start.

• time_dur (float) – Duration in seconds to read. 0 reads the full segment after applying time_offset.

• channels_first (bool) – If True returns waveforms as (channels, num_samples).

• always_2d (bool) – Forces single-channel audio to retain a channel dimension.

• return_all_channels (bool) – If True returns every channel available.

Returns:

Waveform and sampling rate when a single channel is returned.

Tuple[np.ndarray, int, int]: Waveform, sampling rate, and selected channel index when return_all_channels is True.

Return type:

Tuple[np.ndarray, int]

static add_argparse_args(parser: ArgumentParser, prefix: str | None = None) → None

Register command-line arguments for RandomAccessAudioReader.

Parameters:

• parser (ArgumentParser) – Parser where arguments are to be added.

• prefix (Optional[str]) – Optional prefix to nest arguments under a group.

static channel_name_to_idx(channel: int | str, num_channels: int) → int

Convert a human-readable channel descriptor to a zero-based index.

Parameters:

• channel (Union[int, str]) – Channel index (1-based) or mnemonic such as "left"/"right"/"center".

• num_channels (int) – Number of channels available in the recording.

Returns:

Zero-based channel index.

Return type:

int

Raises:

Exception – If channel is unknown or not available in the recording.

property keys: ndarray[Any, dtype[Any]]

static read_file(wavspecifier: str | Path, scale: float = 1.0, time_offset: float = 0, time_dur: float = 0, channels_first: bool = True, always_2d: bool = False) → Tuple[ndarray, int]

Read audio from disk, retrying with progressively broader fallbacks.

Parameters:

• wavspecifier (PathLike) – Audio file path.

• scale (float) – Multiplicative factor applied to the waveform.

• time_offset (float) – Start time in seconds relative to the beginning of the recording.

• time_dur (float) – Duration in seconds to read. 0 reads until the end of the recording.

• channels_first (bool) – If True returns waveforms as (channels, num_samples).

• always_2d (bool) – Forces single-channel audio to retain a channel dimension.

Returns:

Waveform and sampling rate.

Return type:

Tuple[np.ndarray, int]

Raises:

RuntimeError – If the audio cannot be read by any backend.

Notes

Attempts to read with soundfile first (except for .mp3, which uses torchaudio first), including a relaxed slicing strategy to recover from libsndfile fseek issues, and finally falls back to torchaudio when required.

static read_file_sf(wavspecifier: str | Path, scale: float = 1.0, time_offset: float = 0, time_dur: float = 0, channels_first: bool = True, always_2d: bool = False) → Tuple[ndarray, int]

Read audio from disk using soundfile.

Parameters:

• wavspecifier (PathLike) – Audio file path readable by libsndfile.

• scale (float) – Multiplicative factor applied to the waveform.

• time_offset (float) – Start time in seconds relative to the beginning of the recording.

• time_dur (float) – Duration in seconds to read. 0 reads until the end of the recording.

• channels_first (bool) – If True returns waveforms as (channels, num_samples).

• always_2d (bool) – Forces single-channel audio to retain a channel dimension.

Returns:

Waveform and sampling rate.

Return type:

Tuple[np.ndarray, int]

static read_file_torchaudio(wavspecifier: str | Path, scale: float = 1.0, time_offset: float = 0, time_dur: float = 0, channels_first: bool = True, always_2d: bool = False) → Tuple[ndarray, int]

Read audio from disk using torchaudio.

Parameters:

• wavspecifier (PathLike) – Audio file path readable by torchaudio.

• scale (float) – Multiplicative factor applied to the waveform.

• time_offset (float) – Start time in seconds relative to the beginning of the recording.

• time_dur (float) – Duration in seconds to read. 0 reads until the end of the recording.

• channels_first (bool) – If True returns waveforms as (channels, num_samples).

• always_2d (bool) – Forces single-channel audio to retain a channel dimension.

Returns:

Waveform and sampling rate.

Return type:

Tuple[np.ndarray, int]

static read_pipe(wavspecifier: str | Path, scale: float = 1.0, time_offset: float = 0, time_dur: float = 0, channels_first: bool = True, always_2d: bool = False) → Tuple[ndarray, int]

Read audio produced by a shell pipe command.

Parameters:

• wavspecifier (PathLike) – Shell command whose stdout returns the encoded waveform.

• scale (float) – Multiplicative factor applied to the waveform.

• time_offset (float) – Start time in seconds relative to the pipe output.

• time_dur (float) – Duration in seconds to read. 0 reads until the end of the available samples.

• channels_first (bool) – If True returns waveforms as (channels, num_samples).

• always_2d (bool) – Forces single-channel audio to retain a channel dimension.

Returns:

Waveform and sampling rate.

Return type:

Tuple[np.ndarray, int]

Raises:

Exception – If the pipe command returns a non-zero exit status.

static read_wavspecifier(wavspecifier: str | Path, scale: float = 1.0, time_offset: float = 0.0, time_dur: float = 0.0, channels_first: bool = True, always_2d: bool = False) → Tuple[ndarray, int]

Read audio from a file path or shell pipe specification.

Supports pipes as well as every format handled by libsndfile (wav, flac, ogg, etc.) together with the extensions listed in valid_ext.

Parameters:

• wavspecifier (PathLike) – Pipe command or audio file path (wav, flac, ogg, etc.).

• scale (float) – Multiplicative factor applied to the waveform.

• time_offset (float) – Start time in seconds relative to the beginning of the utterance.

• time_dur (float) – Duration in seconds to read. 0 reads the audio until the end of the utterance.

• channels_first (bool) – If True returns waveforms as (channels, num_samples).

• always_2d (bool) – Forces single-channel audio to retain a channel dimension.

Returns:

Waveform and sampling rate.

Return type:

Tuple[np.ndarray, int]

Raises:

Exception – If the specifier points to an unsupported format.

class hyperion.io.AudioWriter(output_path: str | Path, script_path: str | Path | None = None, audio_format: str = 'wav', audio_subtype: str | None = None, wav_scale: float = 1.0, channels_first: bool = True, always_2d: bool = False)

Write audio arrays to disk and optionally create an output manifest.

output_path

Directory where audio files are saved.

script_path

Optional output Kaldi .scp or table file (.csv/.tsv).

audio_format

Output audio container format.

audio_subtype

Audio encoding subtype (e.g., PCM_16, FLOAT).

wav_scale

Scale of the input waveform.

channels_first

If True, interprets 2-D inputs as (channels, num_samples).

always_2d

If True, always writes 2-channel output audio.

Example

>>> import numpy as np
>>> with AudioWriter(
...     "./audio_out",
...     script_path="./audio_out/recordings.csv",
...     audio_format="wav",
...     audio_subtype="pcm_16",
...     channels_first=True,
... ) as w:
...     x = np.random.randn(1, 16000).astype("float32")  # (channels, samples)
...     files = w.write("utt1", x, 16000)
>>> files[0]
'./audio_out/utt1.wav'

__init__(output_path: str | Path, script_path: str | Path | None = None, audio_format: str = 'wav', audio_subtype: str | None = None, wav_scale: float = 1.0, channels_first: bool = True, always_2d: bool = False)

__enter__()

Function required when entering constructions of type

with AudioWriter(‘./path’) as f:

f.write(key, data, fs)

__exit__(exc_type, exc_value, traceback)

Function required when exiting from constructions of type

with AudioWriter(‘./path’) as f:

f.write(key, data, fs)

close()

Closes the script file if open

write(keys: str | List[str] | array, data: array | List[array], fs: int | float | List[int] | List[float] | array)

Write one or more waveforms to audio files.

Parameters:

• keys – Recording key or list of recording keys.

• data – Single waveform array or list of waveform arrays.

• fs – Sample rate scalar or list of sample rates aligned with keys.

Returns:

List with the output file paths written for each key.

Raises:

ValueError – If key/data/fs lengths are inconsistent.

_prepare_audio(x: array) → array

Convert input waveform to soundfile layout.

Returns audio as either (num_samples,) or (num_samples, channels), honoring channels_first and always_2d.

static filter_args(**kwargs)

static add_class_args(parser, prefix=None)

static add_argparse_args(parser, prefix=None)

Audio readers can consume a HyperDataset manifest or recording/segment inputs. Waveform extractors resample to the loaded model’s expected sample frequency; see Train an X-Vector Directly from Waveforms.

VAD API

class hyperion.io.VADReaderFactory

Factory that builds VAD readers from Kaldi-style read specifiers.

Examples

Create a table-based VAD reader from a CSV index: >>> r = VADReaderFactory.create(“csv:data/vad.csv”) >>> marks = r.read_time_marks([“utt1”, “utt2”]) >>> r.close()

Create a table-based VAD reader: >>> r = VADReaderFactory.create(“csv:data/vad_index.csv”) >>> marks = r.read_time_marks([“utt1”]) >>> r.close()

Parse only factory-relevant arguments from a larger config: >>> vad_kwargs = VADReaderFactory.filter_args( … path_prefix=”/mnt/vad”, frame_shift=10.0, foo=1 … ) >>> r = VADReaderFactory.create( … “csv:data/vad.csv”, path_prefix=vad_kwargs[“path_prefix”] … ) >>> r.close()

static create(rspecifier: str | Path | RSpecifier, path_prefix: str | Path | None = None, frame_length: float = 25, frame_shift: float = 10, snip_edges: bool = False) → BinVADReader | TableVADReader

Create a VAD reader.

Parameters:

• rspecifier – Read specifier string/path or pre-parsed RSpecifier.

• path_prefix – Optional prefix added to script paths.

• frame_length – Frame length in milliseconds used for binary VAD conversion.

• frame_shift – Frame shift in milliseconds used for binary VAD conversion.

• snip_edges – Snip-edges setting used for binary VAD conversion.

Returns:

A BinVADReader for H5/ARK inputs, or a TableVADReader for table inputs.

Raises:

ValueError – If specifier type or archive type is unsupported.

static filter_args(**kwargs: Any) → Dict[str, Any]

Filter kwargs to those accepted by create().

static add_class_args(parser: ArgumentParser, prefix: str | None = None) → None

Register VAD reader arguments in a jsonargparse parser.

Parameters:

• parser – Target parser to augment.

• prefix – Optional nested argument prefix.

static add_argparse_args(parser: ArgumentParser, prefix: str | None = None) → None

Register VAD reader arguments in a jsonargparse parser.

Parameters:

• parser – Target parser to augment.

• prefix – Optional nested argument prefix.

class hyperion.io.BinVADReader(rspecifier: str | Path | RSpecifier, path_prefix: str | Path | None = None, frame_length: float = 25, frame_shift: float = 10, snip_edges: bool = False)

Read binary VAD vectors from Ark/HDF5 inputs.

r

Underlying random-access feature reader that returns binary VAD vectors.

frame_shift

Frame shift in milliseconds used for timestamp conversion.

frame_length

Frame length in milliseconds used for timestamp conversion.

snip_edges

Whether the source VAD was computed with snip-edges.

Examples

>>> from hyperion.io.bin_vad_reader import BinVADReader
>>> with BinVADReader("csv:data/vad.csv", frame_length=25, frame_shift=10) as r:
...     vad = r.read_binary(["utt1", "utt2"])
...     t_start, t_end = r.read_time_marks(["utt1", "utt2"])

__init__(rspecifier: str | Path | RSpecifier, path_prefix: str | Path | None = None, frame_length: float = 25, frame_shift: float = 10, snip_edges: bool = False) → None

Initialize binary VAD reader.

Parameters:

• rspecifier – Kaldi-style read specifier or parsed RSpecifier.

• path_prefix – Optional path prefix for script-based readers.

• frame_length – Frame length in milliseconds.

• frame_shift – Frame shift in milliseconds.

• snip_edges – Whether frame extraction used snip-edges.

close() → None

Close underlying random-access reader resources.

read_num_frames(keys: str | List[str] | ndarray) → ndarray

Read VAD vector lengths (in frames) for requested keys.

property keys: ndarray

Available recording keys.

property ids: ndarray

Alias for keys.

read(keys: str | List[str] | ndarray, squeeze: bool = False, offset: int | List[int] | ndarray = 0, num_frames: int | List[int] | ndarray | None = 0, frame_length: float = 25.0, frame_shift: float = 10.0, snip_edges: bool = False, duration: float | List[float] | ndarray | None = None) → List[ndarray] | ndarray

Read binary VAD vectors.

Parameters:

• keys – Recording key or list/array of keys.

• squeeze – If True, stack outputs when shapes are compatible.

• offset – Starting frame offset(s).

• num_frames – Number of frames to return (0 means full length).

• frame_length – Frame length in milliseconds (must match reader config).

• frame_shift – Frame shift in milliseconds (must match reader config).

• snip_edges – Snip-edges flag (must match reader config).

• duration – Optional duration(s) in seconds used to derive num_frames.

Returns:

List of binary VAD vectors, or a stacked numpy array when squeeze=True.

read_binary(keys: str | List[str] | ndarray, squeeze: bool = False, offset: int | List[int] | ndarray = 0, num_frames: int | List[int] | ndarray | None = 0, frame_length: float = 25.0, frame_shift: float = 10.0, snip_edges: bool = False, duration: float | List[float] | ndarray | None = None) → List[ndarray] | ndarray

Alias for read() with identical arguments.

read_time_marks(keys: str | List[str] | ndarray, merge_tol: float = 0.001) → Tuple[List[ndarray], List[ndarray]]

Convert binary VAD into start/end timestamp arrays.

Parameters:

• keys – Recording key or list/array of keys.

• merge_tol – Timestamp merge tolerance in seconds.

Returns:

Tuple (t_start, t_end) where each element is a list of numpy arrays.

__enter__() → VADReader

Enter context manager.

Returns:

Self, so the reader can be used in with blocks.

__exit__(exc_type: Type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None) → None

Exit context manager and close underlying resources.

static _assert_offsets_num_frames(keys: List[str] | ndarray, offset: int | List[int] | ndarray | float | List[float] | None, num_frames: int | List[int] | ndarray | None | float | List[float]) → Tuple[bool, bool]

Check whether offset/length arguments are per-key sequences.

Parameters:

• keys – Key list used in the read operation.

• offset – Scalar or per-key offsets.

• num_frames – Scalar or per-key lengths.

Returns:

Tuple (offset_is_list, num_frames_is_list).

static _duration_to_num_frames(duration: float | List[float] | ndarray, frame_length: float, frame_shift: float, snip_edges: bool) → int | ndarray

Convert duration(s) in seconds into frame counts.

Parameters:

• duration – Duration value(s) in seconds.

• frame_length – Frame length in milliseconds.

• frame_shift – Frame shift in milliseconds.

• snip_edges – Whether frame extraction uses snip-edges behavior.

Returns:

Integer frame count for scalar duration input, or a numpy array of integer frame counts for vectorized duration input.

static _get_bin_vad_slice(vad: ndarray, offset: int, num_frames: int) → ndarray

Apply frame offset and frame count cropping/padding to a binary VAD.

class hyperion.io.TableVADReader(file_path: str | Path, path_prefix: str | Path | None = None)

Read VAD timestamps from table/script files.

The input file_path points to a VAD table (for example CSV/TSV or an equivalent script managed by VADSet). Each key maps to a timestamps file containing start/end columns.

Examples

>>> from hyperion.io.table_vad_reader import TableVADReader
>>> with TableVADReader("data/vad_index.csv") as r:
...     marks = r.read_time_marks(["utt1"])
...     vad = r.read_binary(["utt1", "utt2"], frame_length=25, frame_shift=10)

__init__(file_path: str | Path, path_prefix: str | Path | None = None) → None

Initialize table-based VAD reader.

Parameters:

• file_path – VADSet table path.

• path_prefix – Optional prefix prepended to each storage_path entry.

property keys: ndarray

Array of available recording keys.

property ids: ndarray

Alias for keys.

close() → None

No-op close method (reader keeps no open file handles).

read_num_frames(keys: str | List[str] | ndarray) → ndarray

Read VAD lengths in frames for each key.

read_binary(keys: str | List[str] | ndarray, squeeze: bool = False, t_start: float | List[float] | ndarray = 0, duration: float | List[float] | ndarray | None = None, offset_frames: int | List[int] | ndarray = 0, num_frames: int | List[int] | ndarray | None = None, frame_length: float = 25, frame_shift: float = 10, snip_edges: bool = False) → List[ndarray] | ndarray

Read binary VAD vectors from timestamp marks.

Parameters:

• keys – Recording key or list/array of keys.

• squeeze – If True, stack outputs when shapes are compatible.

• t_start – Time offset(s) in seconds used to crop marks.

• duration – Duration(s) in seconds used to limit marks.

• offset_frames – Frame offset(s). Only 0 is currently supported.

• num_frames – Optional maximum number of output frames.

• frame_length – Frame length in milliseconds.

• frame_shift – Frame shift in milliseconds.

• snip_edges – Snip-edges flag used for time-to-frame conversion.

Returns:

List of binary VAD vectors, or stacked numpy array when squeeze=True.

read_time_marks(keys: str | List[str] | ndarray, t_start: float | List[float] | ndarray = 0, duration: float | List[float] | ndarray | None = None, merge_tol: float = 0.001) → List[DataFrame]

Read timestamp marks for keys and optionally crop by time window.

Parameters:

• keys – Recording key or list/array of keys.

• t_start – Start time(s) in seconds.

• duration – Duration(s) in seconds. If provided and > 0, marks are cropped to [t_start, t_start + duration).

• merge_tol – Reserved for API compatibility.

Returns:

List of data frames with start and end columns.

__enter__() → VADReader

Enter context manager.

Returns:

Self, so the reader can be used in with blocks.

__exit__(exc_type: Type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None) → None

Exit context manager and close underlying resources.

static _assert_offsets_num_frames(keys: List[str] | ndarray, offset: int | List[int] | ndarray | float | List[float] | None, num_frames: int | List[int] | ndarray | None | float | List[float]) → Tuple[bool, bool]

Check whether offset/length arguments are per-key sequences.

Parameters:

• keys – Key list used in the read operation.

• offset – Scalar or per-key offsets.

• num_frames – Scalar or per-key lengths.

Returns:

Tuple (offset_is_list, num_frames_is_list).

static _duration_to_num_frames(duration: float | List[float] | ndarray, frame_length: float, frame_shift: float, snip_edges: bool) → int | ndarray

Convert duration(s) in seconds into frame counts.

Parameters:

• duration – Duration value(s) in seconds.

• frame_length – Frame length in milliseconds.

• frame_shift – Frame shift in milliseconds.

• snip_edges – Whether frame extraction uses snip-edges behavior.

Returns:

Integer frame count for scalar duration input, or a numpy array of integer frame counts for vectorized duration input.

static _get_bin_vad_slice(vad: ndarray, offset: int, num_frames: int) → ndarray

Apply frame offset and frame count cropping/padding to a binary VAD.

Binary VAD needs its frame length, frame shift, and snip_edges convention to be interpreted correctly. Table VAD represents time marks. See Prepare Dataset Metadata and VAD for conversion and validation guidance.

Compatibility interfaces

HypDataReader and HypDataWriter remain available for legacy callers, but new code should use the factory-based data reader/writer interfaces above.

class hyperion.io.HypDataReader(file_path)

Class to read data from hdf5 files.

Deprecated:

This class is deprecated and will be removed in a future release.

__init__(file_path)

get_datasets()

read(keys, field='', return_tensor=False)

get_num_rows(keys, field='')

read_slice(key, index, num_samples, field='')

read_random_slice(key, num_samples, rng, field='')

read_random_samples(key, num_samples, rng, field='', replace=True)

class hyperion.io.HypDataWriter(file_path)

Class to write data to hdf5 files (deprecated).

__init__(file_path)

write(keys, field, x)

See also

• Extract, Score, and Evaluate X-Vectors

• Utility Layer

• Hyperion Data Model