Lhotse

Lhotse 是一个 Python 库，旨在使多模态（语音、音频、视频、图像、文本）数据的准备更加灵活，并让更广泛的社区能够轻松使用。它与 k2 一起，构成了下一代 Kaldi 语音处理库的一部分。

教程演示和资料

• (Interspeech 2023) 教程笔记本
• (Interspeech 2023) 教程幻灯片
• (Interspeech 2021) 录制讲座 (3小时)

关于

主要目标（更新至 2025 年）

• 扩展到包括音频、文本、图像和视频模态在内的多模态数据流水线。
• 提供最先进的数据加载算法，如数据集混合和高效的按需分桶。
• 处理分布式多节点训练中的数据随机化（或去重）问题。
• 以 以 Python 为中心的设计 吸引更广泛的社区参与多模态处理任务。
• 为常用语料库提供 标准的数据准备配方。
• 通过 音频/视频片段 的概念，实现灵活的模型训练数据准备。
• 支持高效的顺序 I/O 数据格式，例如 Lhotse Shar（类似于 webdataset）。

教程

我们在 examples 目录中提供了以下教程：

• 基本完整的 Lhotse 工作流程
• 使用 Cuts 转换数据
• WebDataset 集成
• 如何合并多个数据集
• Lhotse Shar：针对顺序 I/O 和模块化的存储格式优化
• Lhotse 中的图像和视频支持

使用示例

请查看以下链接，了解 Lhotse 的实际应用：

• Icefall 配方：k2 和 Lhotse 的结合点。
• 最小化 ESPnet+Lhotse 示例：

核心理念

与 Kaldi 类似，Lhotse 提供标准的数据准备配方，但通过特定任务的 Dataset 类实现了与 PyTorch 的无缝集成。数据和元数据以人类可读的文本清单形式呈现，并通过便捷的 Python 类暴露给用户。

Lhotse 引入了音频片段的概念，旨在简化训练数据的构建，通过诸如混合、截断和填充等操作，在运行时完成，从而最大限度地减少所需的存储空间。数据增强和特征提取既支持预计算模式——将特征矩阵存储在磁盘上（可选使用 lilcom 压缩后端以提高存储效率），也支持按需计算变换的实时模式。此外，Lhotse 还引入了特征空间片段混合，以兼顾两者的优点。

安装

Lhotse 支持 Python 3.7 及更高版本。

Pip

Lhotse 已在 PyPI 上发布：

pip install lhotse

若要安装最新的未发布版本，请执行：

pip install git+https://github.com/lhotse-speech/lhotse

开发环境安装

对于开发环境的安装，您可以 fork 或 clone GitHub 仓库，然后使用 pip 安装：

git clone https://github.com/lhotse-speech/lhotse
cd lhotse
pip install -e '.[dev]'
pre-commit install  # 安装带有代码风格检查的 pre-commit 钩子

# 运行单元测试
pytest test

# 运行 linter 检查
pre-commit run

这是一种可编辑的安装方式（-e 选项），这意味着您对源代码所做的更改会在导入 lhotse 时自动生效（无需重新安装）。[dev] 部分表示您正在安装用于运行测试、构建文档或启动 Jupyter 笔记本的额外依赖项。

环境变量

Lhotse 使用多个环境变量来定制其行为。这些变量如下：

• LHOTSE_REQUIRE_TORCHAUDIO - 当该变量被设置且其值不是 1、True、true 或 yes 时，Lhotse 将不会检查是否已安装 torchaudio，并将其从依赖项中移除。这会禁用 Lhotse 的许多功能，但基本功能（包括使用 soundfile 读取音频）仍将保留。

• LHOTSE_AUDIO_DURATION_MISMATCH_TOLERANCE - 当从文件加载音频时，如果实际采样数与 Recording.num_samples 中声明的采样数不一致，此变量将发挥作用。有时这是必要的，因为不同的编解码器（甚至同一编解码器的不同版本）在解码压缩音频时可能会采用不同的填充方式。通常，0.1 秒或甚至 0.3 秒的差异仍属合理范围；超过此范围则表明存在严重问题。

• LHOTSE_AUDIO_BACKEND - 可设置为 CLI 命令 lhotse list-audio-backends 返回的任意值，以覆盖默认的尝试机制，强制使用特定的音频后端。

• LHOTSE_IO_BACKEND - 可设置为 CLI 命令 lhotse list-io-backends 返回的任意值，以覆盖 Lhotse 使用 open_best() 打开路径、URL 和 URI 的方式（例如在读取清单文件或基于 URL 的 AudioSource 时）。同样，Python 中也可通过 lhotse.available_io_backends() 获取该列表。

• LHOTSE_RESAMPLING_BACKEND - 可设置为 CLI 命令 lhotse list-resampling-backends 返回的任意值，以覆盖默认行为。

• LHOTSE_FEATURES_STORAGE_BACKEND - 可设置为任何有效的特征存储后端名称（如 numpy_files、lilcom_chunky），以覆盖默认的特征存储后端（即 numpy_files）。可使用 lhotse.available_storage_backends() 检查当前可用的选项，或使用 lhotse.storage_backend_statuses() 和 CLI 命令 lhotse list-storage-backends 查看完整列表，其中还标注了不可用的后端及其安装提示。如果您已安装 lilcom 并希望获得更小的特征归档文件，建议选择 lilcom_chunky。

• LHOTSE_AUDIO_LOADING_EXCEPTION_VERBOSE - 当设置为 1 时，若所有可用的音频后端均无法加载指定文件，Lhotse 将输出完整的异常堆栈跟踪（可能非常庞大）。

• LHOTSE_DILL_ENABLED - 当设置为 1、True、true 或 yes 时，将在进程间启用基于 dill 的 CutSet 和 Sampler 序列化（即使已安装 dill，默认也为禁用状态）。

• LHOTSE_LEGACY_OPUS_LOADING - （设为 1）将回退到旧版 OPUS 加载机制，该机制会为每个 OPUS 文件启动一个新的 ffmpeg 子进程。

• LHOTSE_PREPARING_RELEASE - 开发者在发布 Lhotse 新版本时内部使用。

• TORCHAUDIO_USE_BACKEND_DISPATCHER - 当设置为 1 且 torchaudio 版本低于 2.1 时，将启用 torchaudio 的实验性 ffmpeg 后端。

• AIS_ENDPOINT 由 AIStore 客户端读取，用于确定 AIStore 端点 URL。这是进行 AIStore 数据加载所必需的。

• AIS_CONNECT_TIMEOUT - 由 AIStore SDK 用于设置 AIStore 客户端请求的连接超时时间（单位：秒）。设置为 0 表示禁用超时（无超时）。若未设置，则使用 SDK 默认值（3 秒）。

• AIS_READ_TIMEOUT - 由 AIStore SDK 用于设置 AIStore 客户端请求的读取超时时间（单位：秒）。设置为 0 表示禁用超时（无超时）。若未设置，则使用 SDK 默认值（20 秒）。

• RANK、WORLD_SIZE、WORKER 和 NUM_WORKERS 在内部用于向 Lhotse Shar 数据加载子进程中传递信息。

• READTHEDOCS 在内部用于文档构建。

• LHOTSE_MSC_OVERRIDE_PROTOCOLS - 当设置时，会在输入数据传递给 MSCIOBackend 之前覆盖协议部分。这在您不想更改现有 URL 格式但仍希望使用 MSCIOBackend 时非常有用。例如，如果您有 s3://s3-bucket/path/to/my/object 和 gs://gs-bucket/path/to/my/object，可以设置 LHOTSE_MSC_OVERRIDE_PROTOCOLS=s3,gs，将 URL 覆盖为 msc://s3-bucket/path/to/my/object 和 msc://gs-bucket/path/to/my/object。

• LHOTSE_MSC_PROFILE - 当设置时，会在输入数据传递给 MSCIOBackend 之前覆盖存储桶名称。这在您的 MSC 配置文件名称与存储桶名称不一致时很有用。例如，如果您有 s3://s3-bucket/path/to/my/object，可以同时设置 LHOTSE_MSC_OVERRIDE_PROTOCOLS=s3 和 LHOTSE_MSC_PROFILE=msc-s3-profile，将 URL 赋值为 msc://msc-s3-profile/path/to/my/object。

• LHOTSE_MSC_BACKEND_FORCED - 当设置为 True 时，将强制 Lhotse 对所有 URL 使用 MSCIOBackend。请谨慎使用，因为如果 MSC 不支持提供的 URL 格式，可能会导致功能失效。

可选依赖项

其他 pip 包。 您可以通过安装相关支持包来利用 Lhotse 的可选功能：

• pip install lhotse[lilcom] 以启用 lilcom 压缩特性和数组存储后端。如果存储效率很重要，在安装此依赖项后，lilcom_chunky 是首选的特性存储后端。
• torchcodec（>= 0.9，需要 torch >= 2.9）在检测到时被支持为音频后端。它是基于 FFmpeg 构建的 PyTorch 原生音频解码器。可通过 pip install torchcodec 安装。安装后，它会在默认后端链中优先于 torchaudio。
• torchaudio 曾经是 Lhotse 的核心依赖项，但现在已成为可选项。请参阅 PyTorch 官方安装文档。
• pip install lhotse[kaldi] 以获得与 Kaldi 兼容的最大化功能集。它包括诸如 kaldi_native_io（kaldi_io 的更高效变体）和 kaldifeat 等库，这些库将部分 Kaldi 功能移植到 Python 中。
• pip install lhotse[orjson] 以实现高达 50% 的 JSONL 清单读取速度提升。
• pip install lhotse[webdataset]。我们支持将您的数据“编译”成 WebDataset tarball 格式，以提高 I/O 效率。您仍然可以像操作普通的惰性 CutSet 一样与数据交互。要了解更多信息，请查看以下教程：
• 如果您希望提取语音特征并将其存储为 HDF5 数组，请安装 pip install h5py。
• pip install dill。当安装了 dill 时，我们将使用它来序列化在 .map 或 .filter 等调用中使用 lambda 函数的 CutSet。这在 PyTorch DataLoader 中且 num_jobs>0 时非常有帮助。如果没有 dill，根据您的环境，您可能会看到异常或脚本挂起。
• pip install aistore 以使用 AIStore 支持的 URL 从 AIStore 读取清单、tar 文件及其他数据（设置 AIS_ENDPOINT 环境变量以激活）。更多详情请参阅 AIStore 文档。
• pip install smart_open 以在 smart_open 支持的任何位置（例如云、http）读取和写入清单及数据。
• pip install opensmile 以使用 OpenSmile 工具包的 Python 封装进行特征提取。
• pip install multi-storage-client 以在不同的存储后端中读取和写入清单及数据。更多详情请参阅 multi-storage-client。

sph2pipe。 对于读取较旧的 LDC SPHERE (.sph) 音频文件，这些文件使用 ffmpeg 和 sox 不支持的编解码器压缩，请运行：

# CLI
lhotse install-sph2pipe

# Python
from lhotse.tools import install_sph2pipe
install_sph2pipe()

它会将其下载到 ~/.lhotse/tools，编译并自动注册到 PATH 中。该程序应能被 Lhotse 自动检测并使用。

示例

我们提供了一些示例脚本，展示如何准备数据并在 Python 中将其加载为 PyTorch Dataset。 这些示例位于 examples 目录中。

以下是一个简短片段，展示 Lhotse 如何使音频数据准备变得快速而简单：

from torch.utils.data import DataLoader
from lhotse import CutSet, Fbank
from lhotse.dataset import VadDataset、SimpleCutSampler
from lhotse.recipes import prepare_switchboard

# 从原始语料分布中准备数据清单。
# RecordingSet 描述了音频录音的元数据；采样率、声道数、时长等。
# SupervisionSet 描述了监督片段的元数据：转录文本、说话人、语言等。
swbd = prepare_switchboard('/export/corpora3/LDC/LDC97S62')

# CutSet 是 Lhotse 的主力工具，允许灵活的数据操作。
# 我们通过以 5 秒为窗口遍历 SWBD 录音来创建 5 秒的切片。
# 在此时，实际并未将音频数据加载到内存或存储到磁盘。
cuts = CutSet.from_manifests(
    recordings=swbd['recordings'],
    supervisions=swbd['supervisions']
).cut_into_windows(duration=5)

# 我们计算 log-Mel 滤波能量并将其存储到磁盘；
# 然后，我们将切片填充至 5 秒，以确保所有切片长度一致，
# 因为每个录音中的最后一个窗口可能持续时间较短。
# 填充将在特征加载到内存后执行。
cuts = cuts.compute_and_store_features(
    extractor=Fbank(),
    storage_path='feats',
    num_jobs=8
).pad(duration=5.0)

# 构建用于语音活动检测任务的 Pytorch Dataset 类：
dataset = VadDataset()
sampler = SimpleCutSampler(cuts, max_duration=300)
dataloader = DataLoader(dataset, sampler=sampler, batch_size=None)
batch = next(iter(dataloader))

VadDataset 将产生包含特征和监督张量对的批次，如下所示——语音大约从第一秒（100 帧）开始：

致谢

本项目的部分贡献得到了美国国家科学基金会 CCRI 资助项目 2120435 的支持。

Lhotse 快速上手指南

Lhotse 是一个专为多模态（语音、音频、视频、图像、文本）数据准备设计的 Python 库。它是下一代 Kaldi 语音处理生态（配合 k2）的核心组件，旨在通过以 Python 为中心的设计，提供灵活的数据加载、增强及标准化食谱。

1. 环境准备

• 操作系统：Linux, macOS, Windows (WSL 推荐)
• Python 版本：3.7 及以上
• 核心依赖：
  • torch (PyTorch)
  • torchaudio (可选，但推荐用于音频处理)
  • soundfile (基础音频读取)
• 可选依赖（根据需求安装）：
  • lilcom：用于高效压缩特征存储。
  • torchcodec：基于 FFmpeg 的 PyTorch 原生音频/视频解码器（需 torch >= 2.9）。

2. 安装步骤

基础安装

通过 PyPI 安装稳定版：

pip install lhotse

国内加速建议：如果遇到下载缓慢，可使用清华或阿里镜像源：

pip install lhotse -i https://pypi.tuna.tsinghua.edu.cn/simple

安装最新开发版

如需体验最新功能（未发布版本）：

pip install git+https://github.com/lhotse-speech/lhotse

开发模式安装

如果您需要修改源码或运行测试：

git clone https://github.com/lhotse-speech/lhotse
cd lhotse
pip install -e '.[dev]'
pre-commit install

启用高级功能（可选）

• 启用高效特征压缩：

  pip install lhotse[lilcom]
  

• 启用高性能音视频解码：

  pip install torchcodec
  

3. 基本使用

Lhotse 的核心概念是 Cut（切片），它允许您在内存中动态组合、截断和填充音频数据，而无需预先修改磁盘上的文件。

以下是最简单的完整工作流示例：

from lhotse import RecordingSet, SupervisionSet, CutSet
from lhotse.audio import AudioSource
from lhotse.cut import MonoCut

# 1. 准备元数据 (通常从标准食谱生成，此处手动构建示例)
# 创建一个录音对象 (指向本地音频文件)
recording = Recording(
    id="rec-1",
    sources=[AudioSource(type="file", channels=[0], source="path/to/audio.wav")],
    sampling_rate=16000,
    num_samples=160000,
    duration=10.0
)

# 创建标注对象
supervision = SupervisionSegment(
    id="seg-1",
    recording_id="rec-1",
    start=0.0,
    duration=5.0,
    text="你好，这是 Lhotse 测试",
    language="Chinese"
)

# 2. 构建 Cut (将录音与标注关联)
cut = MonoCut(
    id="cut-1",
    start=0.0,
    duration=5.0,
    channel=0,
    recording=recording,
    supervision=[supervision]
)

# 3. 放入 CutSet 并进行操作
cuts = CutSet.from_cuts([cut])

# 示例：动态混合噪音 (假设有一个 noise_cut)
# mixed_cuts = cuts.mix(noise_cuts, snr=[10, 20], mix_prob=0.5)

# 示例：截断或填充
# padded_cuts = cuts.pad(num_frames=1000)

# 4. 加载音频数据 (返回 PyTorch Tensor)
audio = cuts.load_audio() 
print(f"音频形状：{audio.shape}")

# 5. 转换为 PyTorch DataLoader
from lhotse.dataset import SingleCutSampler, SimpleCutDataset

sampler = SingleCutSampler(cuts, max_duration=300)
dataset = SimpleCutDataset(cuts)
dataloader = DataLoader(dataset, batch_sampler=sampler)

for batch in dataloader:
    # 训练循环
    pass

关键特性提示

• 惰性加载：load_audio() 仅在调用时读取文件，支持动态混音和增强。
• 多模态支持：除了音频，Lhotse 同样支持 VideoCut 和图像数据的加载与处理。
• 数据存储：推荐使用 Lhotse Shar 格式或 WebDataset 格式进行大规模数据的序列化存储，以提升 I/O 效率。