Skip to main content

NeverLib

一个用于音频处理、语音质量评估和数据增广的Python工具库.

功能模块

模块 说明
metrics 语音质量度量 (SNR/PESQ/STOI/KWS/ASR/TTS/可懂度/振幅/THD等60+指标)
vad 语音活动检测 (Energy/Silero/WebRTC/funasr/whisper/vadlib等7种引擎)
audio_aug 音频数据增广 (编解码/混响/变速/变调/限幅/丢包等14种)
filter 滤波和音频处理 (高通/低通/EQ等)
utils 实用工具函数 (路径列表/音频分割/邮件发送等)
data_analyze 数据分析工具 (波形预览/可视化)

安装

基本安装

pip install neverlib

安装特定功能

pip install neverlib[metrics]    # PESQ/STOI/pyloudnorm
pip install neverlib[vad]       # Silero/WebRTC/funasr/whisper等VAD引擎
pip install neverlib[aug]       # PyAV编解码增强
pip install neverlib[analysis]  # numpy/scipy/tqdm等分析依赖
pip install neverlib[io]        # soundfile/pydub读写
pip install neverlib[plot]      # matplotlib可视化

安装所有功能

pip install neverlib[all]

从源码安装(开发版)

git clone https://gitee.com/LXP-Never/neverlib.git
cd neverlib
pip install .

开发环境配置

Pre-commit 代码格式化

本项目使用 pre-commit 在 git commit 时自动格式化 Python 代码.

安装步骤(首次开发时执行一次):

# 1. 安装 pre-commit 工具
pip install pre-commit

# 2. 在仓库中安装 git hooks
cd /path/to/neverlib
pre-commit install

工作方式:

安装后,每次执行 git commit 时会自动执行以下任务:

1. 代码格式化(autopep8)

  • ✅ 自动修复空格问题(a+b → a + b)
  • ✅ 自动修复缩进问题(统一 4 空格)
  • ✅ 自动修复空行问题(函数间 2 个空行)
  • ✅ 删除行尾空格
  • ✅ 长行自动换行(最大 150 字符)

2. 自动生成 __init__.py 文件

  • ✅ 当 neverlib/ 目录下的 .py 文件有变化时自动触发
  • ✅ 扫描所有子包,提取模块导出项(包括全大写常量,如 EPS)
  • ✅ 生成懒加载版本的 __init__.py(支持 IDE 补全)
  • ✅ 智能跳过:只在内容真的改变时才写入文件

正确的提交工作流:

# 1. 添加修改的文件
git add your_files

# 2. 第一次提交(可能失败,这是正常的)
git commit -m "your message"

# 3. 如果 pre-commit 提示 "files were modified by this hook"
#    说明文件被自动格式化了,需要重新添加
git add -u  # 添加所有已跟踪文件的修改

# 4. 再次提交(通常会成功)
git commit -m "your message"

说明:

  • git add -u 只添加已跟踪文件的修改,不会误添加新文件(如 .env、密钥等)
  • 如果第二次提交仍然失败,检查是否有语法错误或其他问题
  • pre-commit 修改文件是为了确保代码风格一致,这是正常行为

手动检查所有文件(可选):

pre-commit run --all-files

配置文件位于 .pre-commit-config.yaml.

使用示例

import neverlib

# 语音质量度量
from neverlib.metrics import get_snr, pesq, stoi

# VAD语音活动检测
from neverlib import vad

# 音频数据增广
from neverlib.audio_aug import volume_norm

# 滤波
from neverlib.filter import HPFilter

# 发送邮件
from neverlib.message import send_QQEmail

发布到 PyPI

1. 配置 PyPI 认证(首次发布)

创建 ~/.pypirc 文件(用户 home 目录下):

[distutils]
index-servers =
    pypi
    testpypi

[pypi]
repository = https://upload.pypi.org/legacy/
username = __token__
password = pypi-AgEI...你的token...

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = pypi-AgEI...你的token...

设置文件权限:

chmod 600 ~/.pypirc

获取 PyPI Token:

  1. 登录 PyPI 或 TestPyPI
  2. 进入 Account settings → API tokens
  3. 创建新 token,复制到 ~/.pypirc

2. 更新版本号

编辑 pyproject.toml,更新 version 字段:

[project]
name = "neverlib"
version = "x.y.z"  # 修改这里

版本号规范:

  • 补丁版本(Bug 修复):0.3.1 → 0.3.2
  • 次版本(新功能):0.3.2 → 0.4.0
  • 主版本(重大变更):0.4.0 → 1.0.0

3. 构建发布包

# 安装构建工具(首次需要)
pip install build twine

# 清理旧的构建文件
rm -rf dist/ build/ *.egg-info

# 构建源码包和wheel包
python -m build

4. 上传到 PyPI

先上传到 TestPyPI 测试(推荐):

python -m twine upload --repository testpypi dist/*

测试安装:

pip install --index-url https://test.pypi.org/simple/ neverlib

确认无误后,上传到正式 PyPI:

python -m twine upload dist/*

5. 验证发布

# 等待几分钟后
pip install --upgrade neverlib

# 验证版本
python -c "import neverlib; print(neverlib.__version__)"

常见问题

Q: 提示 "File already exists" A: 该版本号已存在,需要更新 pyproject.toml 中的版本号

Q: 提示 "Invalid or non-existent authentication" A: 检查 ~/.pypirc 中的 token 是否正确

Q: 上传时需要输入密码 A: 确认 ~/.pypirc 在用户 home 目录(~/.pypirc),而不是项目目录

TODO List

  • 客观指标添加 DNSMOSPro
  • 添加单元测试覆盖 (metrics模块优先)

许可证

本项目采用MIT许可证. 详情请参阅LICENSE文件.

作者

凌逆战 | Never

博客:https://www.cnblogs.com/LXP-Never

Metadata

Release files for neverlib 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for neverlib 0.4.0
File Size Uploaded Provenance Actions
neverlib-0.4.0.tar.gz 10.3 MB Without provenance Details for neverlib-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for neverlib 0.4.0
File Interpreter ABI Platform Actions
neverlib-0.4.0-py3-none-any.whl Python 3 none any Details for neverlib-0.4.0-py3-none-any.whl

Total release size: 20.6 MB

Release files / neverlib-0.4.0.tar.gz

Download URL neverlib-0.4.0.tar.gz
Size 10.3 MB
Tags Source
SHA-256 checksum
How to use checksums
038cb9f039faf4d970851aafffb142bb8bbf0225850bebdfc76c237047631b0e
BLAKE2b-256 checksum
How to use checksums
af5bf1b81c7fa67d59b90c0058f9b91a150475a669efd28a7d92050575f43837
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.11

Release files / neverlib-0.4.0-py3-none-any.whl

Download URL neverlib-0.4.0-py3-none-any.whl
Size 10.3 MB
Tags Python 3
SHA-256 checksum
How to use checksums
a1d237274b9f9dd69c98acd5f8c3085a752e99c4e4af8bf47117719f8292d372
BLAKE2b-256 checksum
How to use checksums
a8ad62250cdb80afb6b7c1e60e6ffeea31131f55efe244a0bbe5a2aa583a8417
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.11

Security for neverlib 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page