neverlib 0.2.8__py3-none-any.whl → 0.3.0__py3-none-any.whl

neverlib/QA/ImpactNoiseRejection.py

@@ -0,0 +1,119 @@
+"""VPU 冲击声检测 + 可视化(轻量版). """
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List, Tuple
+
+import matplotlib.pyplot as plt
+import numpy as np
+import soundfile as sf
+
+# 基本参数, 可按需修改
+AUDIO_PATH = Path(__file__).resolve().parent / "out.wav"
+CHANNEL_INDEX = 4
+DC_WINDOW_MS = 40.0
+SHORT_MS = 6.0
+LONG_MS = 60.0
+RATIO_THRESHOLD = 3.0
+MIN_DURATION_MS = 8.0
+MIN_GAP_MS = 35.0
+
+
+def moving_average(x: np.ndarray, window: int) -> np.ndarray:
+    if window <= 1:
+        return x
+    kernel = np.ones(window, dtype=np.float64) / window
+    return np.convolve(x, kernel, mode="same")
+
+
+def preprocess(signal: np.ndarray, sr: int) -> np.ndarray:
+    dc_window = max(int(sr * DC_WINDOW_MS / 1000.0), 1)
+    return signal - moving_average(signal, dc_window)
+
+
+def ratio_score(signal: np.ndarray, sr: int) -> np.ndarray:
+    short = max(int(sr * SHORT_MS / 1000.0), 1)
+    long = max(int(sr * LONG_MS / 1000.0), 1)
+    short_env = moving_average(np.abs(signal), short)
+    long_env = moving_average(np.abs(signal), long)
+    return short_env / np.maximum(long_env, 1e-6)
+
+
+def detect_events(mask: np.ndarray, sr: int) -> List[Tuple[float, float]]:
+    min_samples = max(int(sr * MIN_DURATION_MS / 1000.0), 1)
+    gap_samples = max(int(sr * MIN_GAP_MS / 1000.0), 1)
+
+    events: List[Tuple[int, int]] = []
+    start = -1
+    for idx, active in enumerate(mask):
+        if active and start < 0:
+            start = idx
+        elif not active and start >= 0:
+            if idx - start >= min_samples:
+                events = _append_or_merge(events, start, idx, gap_samples)
+            start = -1
+
+    if start >= 0 and len(mask) - start >= min_samples:
+        events = _append_or_merge(events, start, len(mask), gap_samples)
+
+    return [(s / sr, e / sr) for s, e in events]
+
+
+def _append_or_merge(events: List[Tuple[int, int]], start: int, end: int, gap: int) -> List[Tuple[int, int]]:
+    if events and start - events[-1][1] <= gap:
+        previous_start, _ = events[-1]
+        events[-1] = (previous_start, end)
+    else:
+        events.append((start, end))
+    return events
+
+
+def plot_detection(time: np.ndarray, signal: np.ndarray, score: np.ndarray, events: List[Tuple[float, float]]) -> None:
+    fig, axes = plt.subplots(2, 1, figsize=(12, 6), sharex=True)
+
+    axes[0].plot(time, signal, color="steelblue", linewidth=0.8)
+    axes[0].set_ylabel("Amplitude")
+    axes[0].set_title("VPU 信号与冲击事件")
+
+    axes[1].plot(time, score, color="crimson", linewidth=0.8)
+    axes[1].axhline(RATIO_THRESHOLD, color="gray", linestyle="--", linewidth=0.8, label="阈值")
+    axes[1].set_ylabel("短/长包络比")
+    axes[1].set_xlabel("时间 (s)")
+    axes[1].legend(loc="upper right")
+
+    for axis in axes:
+        for start, end in events:
+            axis.axvspan(start, end, color="lime", alpha=0.25)
+        axis.grid(alpha=0.2)
+
+    fig.tight_layout()
+    plt.savefig('./impact_noise_rejection.png')
+
+
+def main() -> None:
+    if not AUDIO_PATH.exists():
+        raise FileNotFoundError(f"找不到音频文件: {AUDIO_PATH}")
+
+    data, sr = sf.read(AUDIO_PATH, always_2d=True)
+    if CHANNEL_INDEX >= data.shape[1]:
+        raise ValueError(f"音频仅有 {data.shape[1]} 通道, 无法访问 VPU 通道 {CHANNEL_INDEX}")
+
+    signal = data[:, CHANNEL_INDEX].astype(np.float64)
+    signal = preprocess(signal, sr)
+    score = ratio_score(signal, sr)
+    events = detect_events(score > RATIO_THRESHOLD, sr)
+
+    if events:
+        print("检测到的冲击事件：")
+        for start, end in events:
+            print(f"  起始 {start:.3f}s  结束 {end:.3f}s  持续 {(end-start)*1000:.1f}ms")
+    else:
+        print("未检测到明显的冲击事件. ")
+
+    time_axis = np.arange(len(signal)) / sr
+    plot_detection(time_axis, signal, score, events)
+
+
+if __name__ == "__main__":
+    main()

neverlib/QA/gen_init.py

@@ -1,4 +1,4 @@
-# 自动生成指定包目录下的 __init__.py（懒加载格式：lazy_loader.attach）
+# 自动生成指定包目录下的 __init__.py(懒加载格式：lazy_loader.attach)
 # 并且支持IDE友好的 __init__.py 版本
 
 import ast
@@ -8,7 +8,7 @@ from typing import Dict, List, Set
 
 def _extract_exports_from_module(py_file: Path) -> List[str]:
     """
-    优先读取模块内显式定义的 __all__，否则收集顶层的类与函数名（排除以下划线开头的）。
+    优先读取模块内显式定义的 __all__, 否则收集顶层的类与函数名(排除以下划线开头的)
     """
     try:
         source = py_file.read_text(encoding='utf-8')
@@ -46,8 +46,8 @@ def _extract_exports_from_module(py_file: Path) -> List[str]:
 
 def generate_init_for_directory(package_dir: Path, ide_friendly: bool = False) -> Path:
     """
-    为指定目录生成懒加载版 __init__.py（覆盖写入）。
-    - 仅扫描一级子模块（同级 .py 文件），忽略以下划线开头的模块与 __init__.py 本身。
+    为指定目录生成懒加载版 __init__.py(覆盖写入). 
+    - 仅扫描一级子模块(同级 .py 文件), 忽略以下划线开头的模块与 __init__.py 本身. 
     - 生成结构：
         from lazy_loader import attach
 
@@ -59,7 +59,7 @@ def generate_init_for_directory(package_dir: Path, ide_friendly: bool = False) -
 
     Args:
         package_dir: 包目录路径
-        ide_friendly: 是否生成IDE友好版本（使用TYPE_CHECKING）
+        ide_friendly: 是否生成IDE友好版本(使用TYPE_CHECKING)
     """
     package_dir = package_dir.resolve()
     if not package_dir.is_dir():
@@ -87,7 +87,7 @@ def generate_init_for_directory(package_dir: Path, ide_friendly: bool = False) -
         lines.append('from typing import TYPE_CHECKING, Any')
         lines.append('')
         lines.append('if TYPE_CHECKING:')
-        lines.append('    # 仅在类型检查时导入，提供IDE补全支持')
+        lines.append('    # 仅在类型检查时导入, 提供IDE补全支持')
 
         # 生成 TYPE_CHECKING 导入
         for module_name in sorted(module_to_exports.keys()):
@@ -158,7 +158,7 @@ def generate_all_packages(root_dir: Path, ide_friendly: bool = False) -> List[Pa
         if package_dir == root_dir or package_dir in processed_dirs:
             continue
 
-        # 检查是否包含其他Python文件（不是只有__init__.py）
+        # 检查是否包含其他Python文件(不是只有__init__.py)
         has_other_py_files = any(
             f.name != '__init__.py' and f.suffix == '.py'
             for f in package_dir.iterdir()
@@ -181,13 +181,10 @@ def main():
 
     parser = argparse.ArgumentParser(description='为指定包目录自动生成 __init__.py')
     parser.add_argument('-p', '--package-dir', dest='package_dir',
-                        help='包目录路径，比如 /path/to/pkg 或 ./neverlib/utils')
-    parser.add_argument('--all', action='store_true',
-                        help='为所有子包生成 __init__.py')
-    parser.add_argument('--ide-friendly', action='store_true',
-                        help='生成IDE友好版本（使用TYPE_CHECKING）')
-    parser.add_argument('--backup', action='store_true',
-                        help='备份原始文件')
+                        help='包目录路径, 比如 /path/to/pkg 或 ./neverlib/utils')
+    parser.add_argument('--all', default=True, help='为所有子包生成 __init__.py')
+    parser.add_argument('--ide-friendly', default=True, help='生成IDE友好版本(使用TYPE_CHECKING)')
+    parser.add_argument('--backup', default=False, help='备份原始文件')
     args = parser.parse_args()
 
     if args.all:
@@ -209,9 +206,9 @@ def main():
         init_path = generate_init_for_directory(target_dir, ide_friendly=args.ide_friendly)
         print(f'已生成: {init_path}')
         if args.ide_friendly:
-            print('✅ 已生成IDE友好版本（支持代码补全和类型检查）')
+            print('✅ 已生成IDE友好版本(支持代码补全和类型检查)')
         else:
-            print('ℹ️  生成标准懒加载版本，如需IDE支持请使用 --ide-friendly 参数')
+            print('ℹ️  生成标准懒加载版本, 如需IDE支持请使用 --ide-friendly 参数')
 
 
 if __name__ == '__main__':

neverlib/__init__.py

@@ -3,8 +3,8 @@ Author: 凌逆战 | Never
 Date: 2025-09-07
 Description: neverlib - 音频处理和VAD工具集
 
-这是一个提供音频处理、增强、分析和语音活动检测(VAD)功能的Python库。
-该库使用懒加载机制，可以根据需要导入模块，提高启动速度并减少内存占用。
+这是一个提供音频处理、增强、分析和语音活动检测(VAD)功能的Python库. 
+该库使用懒加载机制, 可以根据需要导入模块, 提高启动速度并减少内存占用. 
 
 主要功能模块:
 - utils: 实用工具函数
@@ -14,7 +14,7 @@ Description: neverlib - 音频处理和VAD工具集
 - data_analyze: 数据分析工具
 - metrics: 音频质量评估指标
 
-注意: 所有功能需要通过具体子模块导入，例如:
+注意: 所有功能需要通过具体子模块导入, 例如:
   from neverlib.audio_aug import limiter
   from neverlib.vad import EnergyVad_C
   from neverlib.filter import HPFilter
@@ -45,13 +45,13 @@ if TYPE_CHECKING:
     from .filter import HPFilter
     from .audio_aug import volume_norm
 
-# 懒加载子包，减少初始导入开销
+# 懒加载子包, 减少初始导入开销
 from lazy_loader import attach
 
 __getattr__, __dir__, __all__ = attach(
     __name__,
     submodules=["audio_aug", "data_analyze", "filter", "metrics", "utils", "vad", ],
-    # 只导出子模块，不直接导出函数
+    # 只导出子模块, 不直接导出函数
     submod_attrs={
         "utils": ["get_path_list"],
         "filter": ["HPFilter"],

neverlib/audio_aug/HarmonicDistortion.py

@@ -9,22 +9,22 @@ import soundfile as sf
 
 def apply_harmonic_distortion(wav, drive=1.0, mix=1.0):
     """
-    使用 tanh 函数模拟简单的谐波失真（饱和效果）。
+    使用 tanh 函数模拟简单的谐波失真(饱和效果). 
 
     参数:
-    wav (np.ndarray): 输入的音频波形。
-    drive (float): 驱动/输入增益。建议范围 [1.0, 10.0]。值越大失真越严重。
-    mix (float): 干/湿信号混合比例。范围 [0.0, 1.0]。
-                 0.0 表示纯净原声, 1.0 表示完全失真的声音。
+    wav (np.ndarray): 输入的音频波形. 
+    drive (float): 驱动/输入增益. 建议范围 [1.0, 10.0]. 值越大失真越严重. 
+    mix (float): 干/湿信号混合比例. 范围 [0.0, 1.0]. 
+                 0.0 表示纯净原声, 1.0 表示完全失真的声音. 
 
     返回:
-    np.ndarray: 经过谐波失真的音频波形。
+    np.ndarray: 经过谐波失真的音频波形. 
     """
     # 确保 drive 和 mix 在合理范围
     drive = max(1.0, drive)
     mix = np.clip(mix, 0.0, 1.0)
 
-    # 1. 归一化（可选但推荐）, 以获得更可控的效果
+    # 1. 归一化(可选但推荐), 以获得更可控的效果
     peak = np.max(np.abs(wav))
     if peak == 0:
         return wav
@@ -45,12 +45,12 @@ def apply_harmonic_distortion(wav, drive=1.0, mix=1.0):
 
 def apply_pedalboard_distortion(wav, sr, drive_db=15.0):
     """
-    使用 pedalboard 库模拟高质量的谐波失真。
+    使用 pedalboard 库模拟高质量的谐波失真. 
 
     参数:
-    wav (np.ndarray): 输入的音频波形。
-    sr (int): 采样率。
-    drive_db (float): 驱动增益, 单位是分贝(dB)。值越大失真越严重。
+    wav (np.ndarray): 输入的音频波形. 
+    sr (int): 采样率. 
+    drive_db (float): 驱动增益, 单位是分贝(dB). 值越大失真越严重. 
     """
     try:
         import pedalboard as pdb

neverlib/audio_aug/README.md

@@ -0,0 +1,3 @@
+https://github.com/iver56/audiomentations
+https://github.com/gfdb/wav2aug
+https://github.com/documentation-ai/DocumentationAI-Docs

neverlib/audio_aug/__init__.py

@@ -4,7 +4,7 @@
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
-    # 仅在类型检查时导入，提供IDE补全支持
+    # 仅在类型检查时导入, 提供IDE补全支持
     from .HarmonicDistortion import apply_harmonic_distortion, apply_pedalboard_distortion
     from .TFMask import FreqMask, TimeMask
     from .audio_aug import add_reverb, get_snr_use_vad, limiter, measure_loudness, snr_aug_Interpolation, snr_aug_changeClean, snr_aug_changeNoise, snr_aug_vad_Interpolation, snr_diff_changeClean, snr_diff_changeNoise, volume_aug, volume_aug_dbrms, volume_aug_linmax, volume_aug_lufs, volume_convert, volume_norm
@@ -79,4 +79,4 @@ if TYPE_CHECKING:
         'simulate_packet_loss_vectorized',
         'apply_mulaw_quantization',
         'apply_uniform_quantization',
-    ]
+    ]

neverlib/audio_aug/audio_aug.py

@@ -66,7 +66,7 @@ def snr_aug_changeNoise(clean, noise, target_snr, hpf=False, sr=16000, order=4,
 
 def snr_aug_changeClean(clean, noise, target_snr, clip_check=True, hpf=False, sr=16000, order=4, cutoff=100):
     """ 
-    保持噪声不变，改变纯净语音的幅度以达到目标信噪比
+    保持噪声不变, 改变纯净语音的幅度以达到目标信噪比
     snr = 10 * log10(k*signal_power/ noise_power)
     """
     assert clean.shape == noise.shape, "clean and noise must have the same shape"
@@ -258,7 +258,7 @@ def volume_aug(wav, range, rate, method="linmax"):
 def volume_aug_dbrms(wav, target_level, hpf=False, sr=16000, order=4, cutoff=100):
     """
     音量增强, 使用dbrms方法
-    为了避免有冲击响应影响了最大值，所以使用dBRMS方法, 一定要选好范围，不然容易削波
+    为了避免有冲击响应影响了最大值, 所以使用dBRMS方法, 一定要选好范围, 不然容易削波
     Args:
         wav: 音频
         target_level: 目标音量, 单位dB
@@ -303,12 +303,12 @@ def volume_aug_linmax(wav, target_level, hpf=False, sr=16000, order=4, cutoff=10
 def volume_aug_lufs(wav, target_lufs, hpf=False, sr=16000, order=4, cutoff=100):
     """
     音量增强, 使用lufs方法, 
-    LUFS是“感知响度” → 跟人耳听感对齐，而且符合国际响度标准。
+    LUFS是“感知响度” → 跟人耳听感对齐, 而且符合国际响度标准. 
 
-    LUFS 使用 感知加权（K-weighting）
-    - 高频增强（模拟人耳在 3~6kHz 的敏感）
-    - 低频衰减（降低 <100Hz 对响度的影响）。
-    使用 短时块（400ms）能量 + 响度门限（-70 LUFS） 过滤极静音段。
+    LUFS 使用 感知加权(K-weighting)
+    - 高频增强(模拟人耳在 3~6kHz 的敏感)
+    - 低频衰减(降低 <100Hz 对响度的影响). 
+    使用 短时块(400ms)能量 + 响度门限(-70 LUFS) 过滤极静音段. 
 
     Args:
         wav: 音频
@@ -319,7 +319,7 @@ def volume_aug_lufs(wav, target_lufs, hpf=False, sr=16000, order=4, cutoff=100):
         cutoff: 截止频率
 
     补充信息: 
-    ## 推荐的 target_lufs 值（行业参考）
+    ## 推荐的 target_lufs 值(行业参考)
     平台	推荐目标 LUFS
     YouTube / Spotify	-14
     Apple Music	-16
@@ -336,7 +336,7 @@ def volume_aug_lufs(wav, target_lufs, hpf=False, sr=16000, order=4, cutoff=100):
     if hpf:
         wav_tmp = HPFilter(wav_tmp, sr=sr, order=4, cutoff=1000)
 
-    # Step2: 创建 LUFS 测量器（ITU-R BS.1770）
+    # Step2: 创建 LUFS 测量器(ITU-R BS.1770)
     meter = pyln.Meter(sr, block_size=0.400)  # block_size=400ms
 
     # Step3: 测量当前 LUFS
@@ -353,18 +353,18 @@ def volume_aug_lufs(wav, target_lufs, hpf=False, sr=16000, order=4, cutoff=100):
 
 def measure_loudness(wav, sr):
     """
-    测量音频的 Peak / RMS / LUFS，以及峰均比（Crest Factor）
+    测量音频的 Peak / RMS / LUFS, 以及峰均比(Crest Factor)
 
     参数:
-        wav: np.ndarray, 音频波形（范围 [-1, 1]）
+        wav: np.ndarray, 音频波形(范围 [-1, 1])
         sr: int, 采样率
 
     返回:
         dict:
             - peak_dbfs: 峰值(dBFS)
             - rms_dbfs: 均方根电平(dBFS)
-            - lufs: 感知响度（LUFS，ITU-R BS.1770-4标准）
-            - crest_factor_db: 峰均比(dB)，峰值与RMS的差值
+            - lufs: 感知响度(LUFS, ITU-R BS.1770-4标准)
+            - crest_factor_db: 峰均比(dB), 峰值与RMS的差值
     """
     EPS = 1e-9
 
@@ -399,23 +399,23 @@ def volume_convert(value,
 
     参数:
         value: float
-            输入值（可能是线性幅度、dBFS、LUFS）
+            输入值(可能是线性幅度、dBFS、LUFS)
         from_unit: str
             输入单位: "linear", "dBFS", "RMS_dBFS", "LUFS"
         to_unit: str
             输出单位: "linear", "dBFS", "RMS_dBFS", "LUFS"
         crest_factor_db: float | None
-            峰均比（用于 Peak <-> RMS 的转换）
+            峰均比(用于 Peak <-> RMS 的转换)
         lufs_offset: float | None
-            LUFS 与 RMS 的差值（用于 RMS <-> LUFS 转换）
-            例如, 对人声，LUFS ≈ RMS_dBFS - 1.5
+            LUFS 与 RMS 的差值(用于 RMS <-> LUFS 转换)
+            例如, 对人声, LUFS ≈ RMS_dBFS - 1.5
 
     返回:
         float
     """
     EPS = 1e-9
 
-    # Step 1: 统一转换成线性幅度（以满刻度 1.0 为基准）
+    # Step 1: 统一转换成线性幅度(以满刻度 1.0 为基准)
     if from_unit == "linear":
         lin_val = value
     elif from_unit in ("dBFS", "Peak_dBFS"):

neverlib/audio_aug/coder_aug.py

@@ -6,19 +6,19 @@ Description:
 """
 语音编码器数据增强
 MP3 (MPEG-1 Audio Layer III)	
-- 主要用途：音乐分发、播客。互联网音频的“元老”和事实标准。	
-- 压缩特性：在中低码率下, 高频部分可能会有“嗖嗖”声或模糊感 (swishing artifacts)。	
-- 数据增强目的：模拟通用网络音频压缩。	
+- 主要用途：音乐分发、播客. 互联网音频的“元老”和事实标准. 	
+- 压缩特性：在中低码率下, 高频部分可能会有“嗖嗖”声或模糊感 (swishing artifacts). 	
+- 数据增强目的：模拟通用网络音频压缩. 	
 
 AAC (Advanced Audio Coding)	
-- 主要用途：流媒体、视频文件、现代设备。被认为是 MP3 的继任者。	
-- 压缩特性：在同等码率下, 通常比 MP3 保留更多高频细节, 音质更好。	
-- 数据增强目的：模拟现代流媒体和移动设备上的音频压缩。	
+- 主要用途：流媒体、视频文件、现代设备. 被认为是 MP3 的继任者. 	
+- 压缩特性：在同等码率下, 通常比 MP3 保留更多高频细节, 音质更好. 	
+- 数据增强目的：模拟现代流媒体和移动设备上的音频压缩. 	
 
 AMR (Adaptive Multi-Rate)
-- 主要用途：语音通话、移动通信。专为语音优化。
-- 压缩特性：严格为语音设计, 会滤除大部分非语音频率（如音乐）, 导致音乐听起来“电话音”效果。
-- 数据增强目的：固定采样率：AMR-NB (窄带) 为 8kHz, AMR-WB (宽带) 为 16kHz。这一点至关重要！
+- 主要用途：语音通话、移动通信. 专为语音优化. 
+- 压缩特性：严格为语音设计, 会滤除大部分非语音频率(如音乐), 导致音乐听起来“电话音”效果. 
+- 数据增强目的：固定采样率：AMR-NB (窄带) 为 8kHz, AMR-WB (宽带) 为 16kHz. 这一点至关重要！
 """
 import random
 import numpy as np
@@ -48,8 +48,8 @@ def flac_aug(wav, sr):
 
 def opus_aug_save(wav: np.ndarray, sr: int, output_filepath: str):
     """
-    对音频进行 Opus 压缩, 并直接保存到文件。
-    使用 PyAV 实现, 比特率是随机的。
+    对音频进行 Opus 压缩, 并直接保存到文件. 
+    使用 PyAV 实现, 比特率是随机的. 
     """
     try:
         import av
@@ -91,8 +91,8 @@ def opus_aug_save(wav: np.ndarray, sr: int, output_filepath: str):
 
 def aac_aug_save(wav: np.ndarray, sr: int, output_filepath: str):
     """
-    对音频进行 AAC 压缩, 并直接保存到文件。
-    使用 PyAV 实现, 比特率是随机的。
+    对音频进行 AAC 压缩, 并直接保存到文件. 
+    使用 PyAV 实现, 比特率是随机的. 
     """
     try:
         import av
@@ -139,23 +139,23 @@ def flac_encode_save(wav: np.ndarray,
                      compression_level: int = 5,
                      bits_per_sample=None):
     """
-    使用 pyFLAC 将 NumPy 音频数组编码为 FLAC 文件并保存。
+    使用 pyFLAC 将 NumPy 音频数组编码为 FLAC 文件并保存. 
 
     参数:
-    wav (np.ndarray): 输入的音频数据。可以是 float 类型 (范围 -1.0 到 1.0)
-                        或 int16/int32 类型。
-    sr (int): 音频的采样率。
-    output_filepath (str): 输出的 .flac 文件路径。
-    compression_level (int, optional): FLAC 压缩级别, 范围 0 (最快) 到 8 (最高压缩, 最慢)。
-                                       默认为 5, 是一个很好的平衡点。
-    bits_per_sample (int, optional): 每个样本的位数。通常是 16 或 24。
-                                     如果为 None, 函数会根据输入 wav 的 dtype 自动推断。
-                                     默认为 None。
+    wav (np.ndarray): 输入的音频数据. 可以是 float 类型 (范围 -1.0 到 1.0)
+                        或 int16/int32 类型. 
+    sr (int): 音频的采样率. 
+    output_filepath (str): 输出的 .flac 文件路径. 
+    compression_level (int, optional): FLAC 压缩级别, 范围 0 (最快) 到 8 (最高压缩, 最慢). 
+                                       默认为 5, 是一个很好的平衡点. 
+    bits_per_sample (int, optional): 每个样本的位数. 通常是 16 或 24. 
+                                     如果为 None, 函数会根据输入 wav 的 dtype 自动推断. 
+                                     默认为 None. 
     """
 
     # --- 1. 数据类型和位深处理 ---
-    # pyFLAC 的 Encoder 需要 int16 或 int32 格式的 NumPy 数组。
-    # 我们需要根据输入数据进行转换。
+    # pyFLAC 的 Encoder 需要 int16 或 int32 格式的 NumPy 数组. 
+    # 我们需要根据输入数据进行转换. 
 
     if bits_per_sample is None:
         # 自动推断位深

neverlib/audio_aug/coder_aug2.py

@@ -22,17 +22,17 @@ def check_codec_available(codec):
 
 def apply_codec_distortion(wav, sr, codec='libopus', bitrate='24k'):
     """
-    使用 FFmpeg 对音频应用指定的编解码器和码率, 以模拟有损压缩失真。
+    使用 FFmpeg 对音频应用指定的编解码器和码率, 以模拟有损压缩失真. 
 
     参数:
-    wav (np.ndarray): 输入的音频波形。
-    sr (int): 采样率。
-    codec (str): FFmpeg 支持的编码器名称。
-                 例如: 'aac', 'libopus', 'amr_nb', 'amr_wb', 'mp3'。
-    bitrate (str): 目标码率, FFmpeg 格式。例如: '64k', '24k', '12.2k'。
+    wav (np.ndarray): 输入的音频波形. 
+    sr (int): 采样率. 
+    codec (str): FFmpeg 支持的编码器名称. 
+                 例如: 'aac', 'libopus', 'amr_nb', 'amr_wb', 'mp3'. 
+    bitrate (str): 目标码率, FFmpeg 格式. 例如: '64k', '24k', '12.2k'. 
 
     返回:
-    np.ndarray: 经过编解码器失真的音频波形。
+    np.ndarray: 经过编解码器失真的音频波形. 
     """
     # 检查编解码器是否可用
     if not check_codec_available(codec):
@@ -108,17 +108,17 @@ if __name__ == "__main__":
     wav_path = "/data/never/Desktop/kws_train/QA/wav_data/TIMIT.wav"
     wav, wav_sr = sf.read(wav_path, always_2d=True)
 
-    # 1. 模拟 Opus 编解码器（常用于VoIP, WebRTC）
+    # 1. 模拟 Opus 编解码器(常用于VoIP, WebRTC)
     print("应用 Opus 编解码器失真...")
     opus_wav = apply_codec_distortion(wav, wav_sr, codec='libopus', bitrate='24k')
     sf.write('augmented_opus.wav', opus_wav, wav_sr)
 
-    # 2. 模拟 AAC 编解码器（常用于流媒体, Apple设备）
+    # 2. 模拟 AAC 编解码器(常用于流媒体, Apple设备)
     print("应用 AAC 编解码器失真...")
     aac_wav = apply_codec_distortion(wav, wav_sr, codec='aac', bitrate='64k')
     sf.write('augmented_aac.wav', aac_wav, wav_sr)
 
-    # 3. 模拟 AMR-NB 编解码器（常用于传统移动通信）
+    # 3. 模拟 AMR-NB 编解码器(常用于传统移动通信)
     # AMR-NB 的码率是固定的几个值之一
     amr_bitrates = [
         '4.75k', '5.15k', '5.9k', '6.7k', '7.4k', '7.95k', '10.2k', '12.2k'

neverlib/audio_aug/loss_packet_aug.py

@@ -3,19 +3,19 @@ Author: 凌逆战 | Never
 Date: 2025-07-29 16:28:23
 Description: 丢包数据增强
 “置零” vs “缺失”：两种不同的模拟思路
-结论：对于音质修复, 强烈推荐使用“置零”法, 而不是“删除”法。
+结论：对于音质修复, 强烈推荐使用“置零”法, 而不是“删除”法. 
 
 理由如下：
 
-- 保持时序对齐 (Temporal Alignment): 在音质修复任务中, 模型需要一个一一对应的关系。输入 damaged_audio 的第 t 秒, 应该对应输出 repaired_audio 的第 t 秒, 也对应原始 original_audio 的第 t 秒。
-   如果使用“删除”法, 输入音频变短, 这种对齐关系就被破坏了, 模型无法学习 (损坏的t时刻) -> (修复的t时刻) 的映射。
-- 简化模型训练: 输入和输出的长度保持一致, 意味着你可以直接使用标准的模型架构（如 U-Net）, 而不需要处理复杂的可变长度序列问题。
-- 更贴近修复任务的本质: 音质修复, 特别是丢包补偿 (Packet Loss Concealment, PLC), 其任务本质是**“根据上下文, 猜测并填充一段丢失的音频”**。
+- 保持时序对齐 (Temporal Alignment): 在音质修复任务中, 模型需要一个一一对应的关系. 输入 damaged_audio 的第 t 秒, 应该对应输出 repaired_audio 的第 t 秒, 也对应原始 original_audio 的第 t 秒. 
+   如果使用“删除”法, 输入音频变短, 这种对齐关系就被破坏了, 模型无法学习 (损坏的t时刻) -> (修复的t时刻) 的映射. 
+- 简化模型训练: 输入和输出的长度保持一致, 意味着你可以直接使用标准的模型架构(如 U-Net), 而不需要处理复杂的可变长度序列问题. 
+- 更贴近修复任务的本质: 音质修复, 特别是丢包补偿 (Packet Loss Concealment, PLC), 其任务本质是**“根据上下文, 猜测并填充一段丢失的音频”**. 
 
-“置零”法完美地创造了这样一个场景：模型看到了上下文, 也看到了一个明确的“空白”（零区域）, 它的任务就是把这个空白填上。
-“删除”法则改变了问题的性质, 变成了“检测不连续点并试图将其平滑化”, 这与 PLC 的目标不完全一致。
+“置零”法完美地创造了这样一个场景：模型看到了上下文, 也看到了一个明确的“空白”(零区域), 它的任务就是把这个空白填上. 
+“删除”法则改变了问题的性质, 变成了“检测不连续点并试图将其平滑化”, 这与 PLC 的目标不完全一致. 
 
-“置零”是在深度学习框架下对“真正丢弃”问题的一种高效、可解的数学建模。 我们牺牲了一点点物理上的真实性, 换来了模型训练的可行性和高效性。
+“置零”是在深度学习框架下对“真正丢弃”问题的一种高效、可解的数学建模.  我们牺牲了一点点物理上的真实性, 换来了模型训练的可行性和高效性. 
 '''
 import numpy as np
 import soundfile as sf
@@ -29,20 +29,20 @@ def simulate_packet_loss_vectorized(
     burst_prob: float = 0.2
 ) -> np.ndarray:
     """
-    模拟带有突发性的网络丢包（向量化版本）。
-    使用 NumPy 的向量化操作以获得极高的性能, 避免在 Python 中使用 for 循环。
+    模拟带有突发性的网络丢包(向量化版本). 
+    使用 NumPy 的向量化操作以获得极高的性能, 避免在 Python 中使用 for 循环. 
 
     参数:
-    - wav: 原始音频波形 (NumPy 数组)。
-    - sample_rate: 采样率。
-    - packet_duration_ms: 每个数据包的时长（毫秒）。
+    - wav: 原始音频波形 (NumPy 数组). 
+    - sample_rate: 采样率. 
+    - packet_duration_ms: 每个数据包的时长(毫秒). 
         packet_duration_ms_list= np.arange(10, 60, 5)   # 包时长一般为10-60ms, 5ms间隔
         packet_duration_ms = random.choice(packet_duration_ms_list)
-    - loss_rate: 基础丢包率。
-    - burst_prob: 突发丢包概率。
+    - loss_rate: 基础丢包率. 
+    - burst_prob: 突发丢包概率. 
 
     返回:
-    - 损坏后的音频波形（与原始长度相同）。
+    - 损坏后的音频波形(与原始长度相同). 
     """
     # 0. 复制数组, 避免修改原始输入
     damaged_wav = wav.copy()

neverlib/audio_aug/quant_aug.py

@@ -9,14 +9,14 @@ import soundfile as sf
 
 def apply_uniform_quantization(wav, bit_depth=8):
     """
-    对音频应用均匀量化, 模拟较低位深度的效果。
+    对音频应用均匀量化, 模拟较低位深度的效果. 
 
     参数:
-    wav (np.ndarray): 输入的音频波形, 值应在 [-1.0, 1.0] 范围内。
-    bit_depth (int): 目标模拟的位深度。
+    wav (np.ndarray): 输入的音频波形, 值应在 [-1.0, 1.0] 范围内. 
+    bit_depth (int): 目标模拟的位深度. 
 
     返回:
-    np.ndarray: 量化后的音频波形。
+    np.ndarray: 量化后的音频波形. 
     """
     # 计算量化级别数
     num_levels = 2 ** bit_depth
@@ -36,11 +36,11 @@ def apply_uniform_quantization(wav, bit_depth=8):
 
 def apply_mulaw_quantization(wav, bit_depth=8):
     """
-    【最终正确版】使用 mu_compress 和 mu_expand 模拟 μ-law 量化失真。
+    【最终正确版】使用 mu_compress 和 mu_expand 模拟 μ-law 量化失真. 
 
     参数:
-    wav (np.ndarray): 输入音频。
-    bit_depth (int): 目标模拟的位深度。
+    wav (np.ndarray): 输入音频. 
+    bit_depth (int): 目标模拟的位深度. 
     """
     try:
         import librosa

neverlib/data_analyze/README.md

@@ -1,6 +1,6 @@
 # 音频数据分析模块 (Audio Data Analysis Module)
 
-这个模块提供了完整的音频数据分析功能, 包括特征提取、质量评估、统计分析和可视化等。
+这个模块提供了完整的音频数据分析功能, 包括特征提取、质量评估、统计分析和可视化等. 
 
 ## 模块结构