lhotse

library1.33.0pypypi✓ verified 22d ago

Lhotse is a Python library for data preparation in speech and audio processing. It provides a flexible, declarative API for representing audio collections as manifests (e.g., Recordings, Supervisions, Cuts) and tools for data manipulation, augmentation, and feature extraction. It's currently at version 1.32.2 and maintains an active development and release cadence.

ai-ml data

pip install lhotse

package ↗

INSTALL

IMPORT

SIG · LHOTSE

lhotse

ai-mlpythonv1.33.0

Install

—

Import

—

Disk

—

Pass rate

0/ 10

Env Coverage0 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.33.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✕ build_error

1/2 runs

py 3.11

✕ build_error

1/2 runs

py 3.12

✕ build_error

1/2 runs

py 3.13

✕ build_error

1/2 runs

py 3.9

✕ build_error

✕ timeout

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CutSet

✓ from lhotse import CutSet

✗ from lhotse import CutSet

This quickstart demonstrates how to create a basic `MonoCut` representing an audio segment's metadata and encapsulate it within a `CutSet`. It shows how to access basic properties like ID and duration. Lhotse operates primarily on `CutSet` objects, which are collections of `Cut`s (e.g., `MonoCut`, `MixedCut`).

from lhotse import MonoCut, CutSet # Create a simple mono cut representing metadata for an audio segment cut = MonoCut( id="example-cut-001", start=0.0, duration=5.0, # 5 seconds channel=0, recording_id="example-rec-001", supervisions=[], # An empty list of supervisions features=None, # Features can be attached later sampling_rate=16000, num_samples=int(5.0 * 16000) ) # Create a CutSet from a list of cuts cuts = CutSet([cut]) # Perform a simple operation, e.g., print its duration print(f"CutSet created with {len(cuts)} cut(s).") first_cut = cuts[0] print(f"First cut ID: {first_cut.id}") print(f"First cut duration: {first_cut.duration} seconds") # In a real scenario, you'd save and load manifests: # cuts.to_json("my_cuts.jsonl.gz") # loaded_cuts = CutSet.from_json("my_cuts.jsonl.gz") # print(f"Loaded {len(loaded_cuts)} cuts from file.")

Debug

Known issues

breakingLhotse 1.0 introduced `lhotse.utils.Duration` and `lhotse.utils.Timestamp` objects to represent time quantities, replacing direct floats. While they mostly behave like floats, direct float comparisons, arithmetic operations, or type hints in older code might break.

fix

Review code that directly compares or performs arithmetic with time-related attributes (e.g., `cut.duration`, `cut.start`). In most cases, implicit conversion works, but explicit conversion to `float` (e.g., `float(cut.duration)`) might be needed for strict comparisons or external libraries expecting floats.

affects: <1.0 to 1.0+

gotchaLhotse heavily relies on lazy evaluation for performance. Materializing large `CutSet` objects (e.g., `list(cuts.map(...))`, `list(cuts)`) or repeatedly calling `Cut.load_audio()` on many cuts without proper batching can lead to Out-Of-Memory (OOM) errors.

fix

Leverage Lhotse's dataset and data loader utilities (e.g., `lhotse.dataset.K2SpeechRecognitionDataset`, `torch.utils.data.DataLoader`) which handle batching and resource management efficiently. Avoid `list()` on large `CutSet`s after transformations unless absolutely necessary, and prefer iterator-based processing.

affects: All versions

gotchaMany common functionalities (e.g., Kaldi-style feature extraction, Torchaudio-based audio I/O, specific training integrations) require optional dependencies. Failing to install these will result in runtime `ImportError` or other errors when attempting to use the functionality.

fix

Install Lhotse with the necessary optional dependencies using the extra syntax, e.g., `pip install lhotse[kaldi,torchaudio,train]` for a common set, or `pip install lhotse[all]` for most extras. Refer to the official documentation for a complete list of extras.

affects: All versions

gotchaFeatures in Lhotse are often stored with `lilcom` compression by default for efficiency. Directly accessing `Cut.load_features()` outside of a `lhotse.dataset` iterator will return compressed arrays. If you need to work with uncompressed features, you must explicitly decompress them.

fix

When manually loading features, use `lhotse.features.io.read_lilcom_array` or `lilcom.decompress` to uncompress the data. When using Lhotse's datasets, features are typically decompressed automatically as part of the data loading pipeline.

affects: All versions

Upgrade

Version history

1.33.0latest on PyPI · released Apr 20, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

Resources

packagehttps://pypi.org/project/lhotse/ ↗