OpenL3

OpenL3 是一个用于计算深度音频和图像嵌入的开源 Python 库。

请参阅 文档 获取详细说明和示例。

更新： OpenL3 现已支持 TensorFlow 2！

注意： 不幸的是，有人报告了 训练代码 中的一个错误，导致来自同一视频的正样本音频-图像对在时间上并不一定重叠。尽管如此，该嵌入仍然能够捕捉到有用的语义信息。

此处提供的音频和图像嵌入模型作为 [1] 的一部分发布，并基于“看、听与学习”的方法 [2]。有关嵌入模型及其训练方式的详细信息，请参阅：

看、听与学习更多：深度音频嵌入的设计选择
奥罗拉·克雷默、吴浩翔、贾斯汀·萨拉蒙和胡安·巴勃罗·贝洛。
IEEE 国际声学、语音与信号处理会议（ICASSP），第 3852–3856 页，英国布莱顿，2019 年 5 月。

安装 OpenL3

依赖项

libsndfile

OpenL3 依赖于 pysoundfile 模块来加载音频文件，而该模块又依赖于非 Python 库 libsndfile。在 Windows 和 macOS 上，这些库会通过 pip 自动安装，因此您可以跳过此步骤。然而，在 Linux 上，您必须使用平台的包管理器手动安装它。对于基于 Debian 的发行版（如 Ubuntu），只需运行以下命令即可：

apt-get install libsndfile1

或者，如果您使用的是 conda，可以通过以下命令安装 libsndfile：

conda install -c conda-forge libsndfile

有关更详细的信息，请参阅 pysoundfile 安装文档。

TensorFlow

自 openl3>=0.4.0 起，OpenL3 已升级为使用 TensorFlow 2。由于 TensorFlow 2 及更高版本现在包含 GPU 支持，因此 tensorflow>=2.0.0 已被纳入依赖项，不再需要单独安装。

如果您希望使用 TensorFlow 1.x，请通过 pip install 'openl3<=0.3.1' 进行安装。

TensorFlow 1x 与 OpenL3 ≤ v0.3.1

由于 TensorFlow 1.x 有仅 CPU 版本和 GPU 版本之分，我们建议用户根据自己的使用场景选择合适的版本进行安装。

在大多数平台上，以下任一命令均可正确安装 TensorFlow：

pip install "tensorflow<1.14" # 仅 CPU 版本
pip install "tensorflow-gpu<1.14" # GPU 版本

有关更详细的信息，请参阅 TensorFlow 安装文档。

安装 OpenL3

安装 OpenL3 最简单的方式是使用 pip，它也会在必要时自动安装其他所需的依赖项。要使用 pip 安装 OpenL3，只需运行：

pip install openl3

若要从源代码安装最新版本的 OpenL3：

1. 克隆或拉取最新版本，仅获取 main 分支，以避免下载存储模型权重文件的分支（这些文件将在安装过程中自动下载）。

    git clone git@github.com:marl/openl3.git --branch main --single-branch
   

2. 使用 pip 安装以处理 Python 依赖项。安装过程还会下载模型文件，这需要稳定的网络连接。

    cd openl3
    pip install -e .
   

使用 OpenL3

为了帮助您快速上手 OpenL3，请参阅 教程。

致谢 OpenL3

在您的工作中使用 OpenL3 时，请引用以下论文：

[1] 看、听与学习更多：深度音频嵌入的设计选择
奥罗拉·克雷默、吴浩翔、贾斯汀·萨拉蒙和胡安·巴勃罗·贝洛。
IEEE 国际声学、语音与信号处理会议（ICASSP），第 3852–3856 页，英国布莱顿，2019 年 5 月。

[2] 看、听与学习
雷利亚·阿兰杰洛维奇和安德鲁·齐瑟曼
IEEE 国际计算机视觉会议（ICCV），意大利威尼斯，2017 年 10 月。

模型权重许可

模型权重根据 知识共享署名 4.0 国际许可协议 (CC BY 4.0) 提供。

OpenL3 快速上手指南

OpenL3 是一个开源的 Python 库，用于计算深度音频和图像嵌入（Embeddings）。它基于“Look, Listen and Learn”方法，支持 TensorFlow 2。

环境准备

系统要求

• Python: 3.6, 3.7, 或 3.8
• 操作系统: Windows, macOS, Linux

前置依赖

OpenL3 依赖 pysoundfile 加载音频文件，而 pysoundfile 依赖非 Python 库 libsndfile。

Linux 用户需手动安装 libsndfile： 对于 Debian/Ubuntu 系统：

apt-get install libsndfile1

如果使用 Conda：

conda install -c conda-forge libsndfile

注：Windows 和 macOS 用户通过 pip 安装时会自动处理此依赖，无需手动操作。

TensorFlow 版本说明：

• OpenL3 >= 0.4.0：默认使用 TensorFlow 2（包含 GPU 支持），无需单独安装 TF。
• OpenL3 <= 0.3.1：仅支持 TensorFlow 1.x。如需使用旧版，请自行安装 tensorflow<1.14 (CPU) 或 tensorflow-gpu<1.14 (GPU)。

安装步骤

推荐使用 pip 进行安装，这将自动处理 Python 依赖并下载模型权重文件（请确保网络连接稳定）。

方法一：通过 PyPI 安装（推荐）

pip install openl3

方法二：从源码安装

如果需要最新开发版本：

1. 克隆仓库（仅获取 main 分支以避免下载大型权重文件历史）：

git clone git@github.com:marl/openl3.git --branch main --single-branch

2. 进入目录并安装：

cd openl3
pip install -e .

注意：安装过程中会下载模型权重文件，请保持网络畅通。

基本使用

以下是提取音频嵌入的最简示例。更多详细用法请参考官方教程。

import openl3
import soundfile as sf

# 1. 加载音频文件
audio, sr = sf.read('your_audio_file.wav')

# 2. 获取音频嵌入
# input_repr: 输入表示类型 ("mel128", "mel256", "linear")
# content_type: 内容类型 ("music" 或 "env" 环境音)
embedding, timestamps = openl3.get_audio_embedding(audio, sr, input_repr="mel256", content_type="music")

# 3. 查看结果
print(embedding.shape)  # 输出嵌入向量的形状
print(timestamps)       # 输出对应的时间戳

提示：若需处理图像嵌入，可使用 openl3.get_image_embedding() 函数，用法类似。