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

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/__init__.py

@@ -1,5 +1,20 @@
 # This file is auto-generated. Do NOT edit manually.
 # Generated by neverlib.QA.gen_init
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    # 仅在类型检查时导入, 提供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
+    from .clip_aug import clipping_aug
+    from .coder_aug import aac_aug_save, amr_nb_aug, amr_wb_aug, flac_aug, flac_encode_save, mp3_aug, opus_aug_save, vorbis_aug
+    from .coder_aug2 import apply_codec_distortion, check_codec_available
+    from .loss_packet_aug import simulate_packet_loss_vectorized
+    from .quant_aug import apply_mulaw_quantization, apply_uniform_quantization
+
+# 运行时使用懒加载
 from lazy_loader import attach
 
 __getattr__, __dir__, __all__ = attach(
@@ -26,3 +41,42 @@ __getattr__, __dir__, __all__ = attach(
         "quant_aug": ['apply_mulaw_quantization', 'apply_uniform_quantization'],
     }
 )
+
+# 显式声明 __all__ 以便 IDE 识别
+if TYPE_CHECKING:
+    __all__ = [
+        'apply_harmonic_distortion',
+        'apply_pedalboard_distortion',
+        'FreqMask',
+        'TimeMask',
+        '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',
+        'clipping_aug',
+        'aac_aug_save',
+        'amr_nb_aug',
+        'amr_wb_aug',
+        'flac_aug',
+        'flac_encode_save',
+        'mp3_aug',
+        'opus_aug_save',
+        'vorbis_aug',
+        'apply_codec_distortion',
+        'check_codec_available',
+        '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)
 
-这个模块提供了完整的音频数据分析功能, 包括特征提取、质量评估、统计分析和可视化等。
+这个模块提供了完整的音频数据分析功能, 包括特征提取、质量评估、统计分析和可视化等. 
 
 ## 模块结构
 

neverlib/data_analyze/__init__.py

@@ -1,5 +1,19 @@
 # This file is auto-generated. Do NOT edit manually.
 # Generated by neverlib.QA.gen_init
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    # 仅在类型检查时导入, 提供IDE补全支持
+    from .dataset_analyzer import AudioFileInfo, DatasetAnalyzer, analyze_audio_dataset
+    from .quality_metrics import QualityAnalyzer, audio_health_check, comprehensive_quality_assessment
+    from .rms_distrubution import get_rms_vad
+    from .spectral_analysis import SpectralAnalyzer, compute_spectral_features, frequency_domain_stats
+    from .statistics import AudioStatistics, compare_datasets, quick_audio_stats
+    from .temporal_features import dB, dc_offset, max_rms_amplitude, mean_rms_amplitude, min_rms_amplitude, peak_amplitude, rms_amplitude, short_time_energy, zero_crossing_rate
+    from .visualization import AudioVisualizer, create_analysis_dashboard, plot_dataset_overview
+
+# 运行时使用懒加载
 from lazy_loader import attach
 
 __getattr__, __dir__, __all__ = attach(
@@ -23,3 +37,33 @@ __getattr__, __dir__, __all__ = attach(
         "visualization": ['AudioVisualizer', 'create_analysis_dashboard', 'plot_dataset_overview'],
     }
 )
+
+# 显式声明 __all__ 以便 IDE 识别
+if TYPE_CHECKING:
+    __all__ = [
+        'AudioFileInfo',
+        'DatasetAnalyzer',
+        'analyze_audio_dataset',
+        'QualityAnalyzer',
+        'audio_health_check',
+        'comprehensive_quality_assessment',
+        'get_rms_vad',
+        'SpectralAnalyzer',
+        'compute_spectral_features',
+        'frequency_domain_stats',
+        'AudioStatistics',
+        'compare_datasets',
+        'quick_audio_stats',
+        'dB',
+        'dc_offset',
+        'max_rms_amplitude',
+        'mean_rms_amplitude',
+        'min_rms_amplitude',
+        'peak_amplitude',
+        'rms_amplitude',
+        'short_time_energy',
+        'zero_crossing_rate',
+        'AudioVisualizer',
+        'create_analysis_dashboard',
+        'plot_dataset_overview',
+    ]

neverlib/data_analyze/dataset_analyzer.py

@@ -130,7 +130,7 @@ class DatasetAnalyzer:
             has_clipping = max_amplitude >= 0.99
             is_silent = mean_amplitude < 1e-6
 
-            # SNR估计（基于信号强度和噪声层）
+            # SNR估计(基于信号强度和噪声层)
             snr_estimate = None
             try:
                 if not is_silent:
@@ -548,7 +548,7 @@ def analyze_audio_dataset(directory: str, output_dir: str = None,
 
     Args:
         directory: 音频文件目录
-        output_dir: 输出目录（可选）
+        output_dir: 输出目录(可选)
         extensions: 支持的文件扩展名
         sr: 目标采样率
         n_jobs: 并行作业数