Lhotse

1.32.2 · active · verified Mon Apr 13

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.

Warnings

breaking Lhotse 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.
gotcha Lhotse 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.
gotcha Many 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.
gotcha Features 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.

Install

pip install lhotse Basic installation
pip install lhotse[kaldi,torchaudio,train] Full installation with common optional dependencies

Imports

CutSet
```
from lhotse import CutSet
```
MonoCut
```
from lhotse import MonoCut
```
Recording
```
from lhotse import Recording
```
Supervision
```
from lhotse import Supervision
```
LilcomChunkyWriter
```
from lhotse.features.io import LilcomChunkyWriter
```
Feature writers were moved to `lhotse.features.io` in Lhotse 1.0.

Quickstart

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.")

view raw JSON →