dejavu：Python 音频指纹识别库

dejavu：Python 音频指纹识别库

一个用 Python 实现的音频指纹识别和识别库，目前获得 6,759 Star。它的用途很明确：先听一遍歌曲生成指纹存入数据库，之后通过麦克风或音频文件就能匹配出正在播放的歌曲。

核心能力

dejavu 的工作流程分两步。第一步是指纹化：读取音频文件，提取频谱特征并生成唯一指纹，批量存入数据库。这个过程支持多进程并行加速，而且允许中断和恢复。已经处理过的文件会被记录，重新启动时不会重复计算，对大量音频文件的处理很友好。

第二步是识别。你可以传入一个音频文件让它匹配，也可以直接调用麦克风实时收音。系统会把输入音频转成指纹，然后在数据库里检索最相近的记录，返回对应的歌曲信息。

项目作者在文档里特别说明，这个工具不适用于语音识别。它的设计目标是识别完整音频信号，在有背景噪音的环境下也能工作。比如你在收音机里听到一首歌想知道名字，这种场景就是它的主战场。

快速上手

项目提供了完整的 Docker 配置，几条命令就能跑起来。如果想在本地部署，需要先安装依赖并配置 MySQL 或 PostgreSQL 作为指纹存储的后端数据库。

配置通过 Python 字典传入：

from dejavu import Dejavu
config = {
    "database": {
        "host": "127.0.0.1",
        "user": "root",
        "password": "xxx",
        "database": "dejavu",
    }
}
djv = Dejavu(config)

指纹化一个目录：

djv.fingerprint_directory("mp3", [".mp3"], 3)

第一个参数是目录路径，第二个是文件扩展名过滤，第三个是并行进程数。

识别可以通过命令行或代码调用，支持文件读取和麦克风收音两种模式。

准确率

作者用 45 首流行歌曲做了系统测试。从磁盘直接读取文件识别，准确率是 100%，这是没有噪音干扰的基线结果。

更有参考价值的是麦克风识别测试。作者播放歌曲让电脑麦克风收音，同时故意加入了聊天声和哼唱声作为日常干扰。不同收音时长的识别结果如下：

1 秒片段：60% 2 秒片段：95.6% 3 秒片段：97.8% 5 秒及以上：100%

5 秒钟的收音就能从 45 首歌里准确找出目标。用 iPhone 播放压缩后的流媒体音乐再做测试，1 到 2 秒就足够识别，说明它对压缩损失有一定容错能力。

存储开销

45 首歌生成了约 540 万条指纹记录，数据库占用 377MB。这些歌的 mp3 文件总共 339MB，wav 无损格式则占 1.8GB。指纹存储的体积和原始音频相当，换来的是快速检索的能力。

原理

技术上，dejavu 基于频谱图的局部敏感哈希。先对音频做短时傅里叶变换得到频谱图，然后找到局部振幅峰值，把这些峰值的时间和频率信息组合成哈希值。每条哈希就是一根指纹，大量的指纹构成了每首歌的特征库。

这个思路和 Shazam 的底层算法属于同一类。项目作者写过一篇博客详细讲解了实现细节。

小结

dejavu 是一个功能完整的音频指纹库，代码结构清晰，文档也比较齐全。如果你需要搭建听歌识曲功能，或者给音频库建立可检索的索引，可以直接基于它二次开发。Python 实现的好处是易读易改，但峰值计算是性能瓶颈。作者提到如果用 C/C++ 或 Java 重写，实时识别应该不会有问题。

这是一个解决具体问题的项目，不是花架子。