API 参考

该页面由 mkdocstrings 从源码 docstring 自动生成。

Core

音频加载与元信息读取。

提供统一的音频读取接口以及基础元数据提取能力，解码依赖 librosa， 无损格式元信息优先使用 soundfile。

get_audio_info(file_path)

获取音频文件的基础元数据。

参数：

名称	类型	描述	默认
file_path	str	音频文件路径。	必需

返回：

类型	描述
dict	元信息字典，包含 sr、channels、duration、samples、 bit_depth 与 format。

引发：

类型	描述
Exception	获取失败时抛出异常。

Notes

• WAV/FLAC/OGG/AIFF 等无损格式使用 soundfile 读取。
• MP3 等格式通过解码后的样本估算时长与通道数。

load_audio(file_path, sr=None, mono=True, offset=0.0, duration=None)

加载音频文件。

参数：

名称	类型	描述	默认
file_path	str	音频文件路径。	必需
sr	int or None	目标采样率。为 None 时保持原采样率。	None
mono	bool	是否转换为单声道。	True
offset	float	起始读取时间（秒）。	0.0
duration	float or None	读取时长（秒）。为 None 时读取全部。	None

返回：

类型	描述
tuple	(audio, sample_rate)。mono=True 时 audio 为一维 ndarray， mono=False 时形状为 (channels, samples)，dtype 为 float32。

引发：

类型	描述
Exception	读取失败时抛出异常。

Notes

• MP3 等有损格式的解码依赖系统后端（如 ffmpeg）。
• 大文件建议使用 offset 与 duration 控制内存占用。

示例：

>>> from audiofeatures.core import load_audio
>>> audio, sr = load_audio("example.wav", sr=16000)
>>> audio.shape, sr
((16000,), 16000)

信号分帧与窗函数处理。

apply_window(frames, window_type='hann')

对分帧信号应用窗函数。

参数：

名称	类型	描述	默认
frames	ndarray	二维分帧数组，形状 (n_frames, frame_length)。	必需
window_type	str	窗函数类型，支持 hann、hamming、blackman、 bartlett、kaiser、rectangular。	'hann'

返回：

类型	描述
ndarray	加窗后的帧，形状与输入一致。

引发：

类型	描述
ValueError	输入维度或窗函数类型非法时抛出。

Notes

加窗会改变幅值分布，必要时可做能量补偿。

frame_signal(signal, frame_length, hop_length, center=True)

将一维信号切分为重叠帧。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
frame_length	int	帧长度（样本数）。	必需
hop_length	int	帧移（样本数）。	必需
center	bool	是否居中对齐。为 True 时在两端补零。	True

返回：

类型	描述
ndarray	分帧结果，形状为 (n_frames, frame_length)。

引发：

类型	描述
ValueError	输入非一维或参数非法时抛出。

Notes

当 center=False 且信号长度不足一个帧时返回空数组；center=True 会在两端补零并至少返回一帧。

Preprocessing

音频信号滤波工具。

band_pass_filter(signal, sr, low_cutoff, high_cutoff, order=4)

应用巴特沃斯带通滤波。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
sr	int	采样率（Hz）。	必需
low_cutoff	float	低截止频率（Hz）。	必需
high_cutoff	float	高截止频率（Hz）。	必需
order	int	滤波器阶数。	4

返回：

类型	描述
ndarray	带通滤波后的信号。

引发：

类型	描述
ValueError	参数非法或超过奈奎斯特频率时抛出。

high_pass_filter(signal, sr, cutoff_freq, order=4)

应用巴特沃斯高通滤波。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
sr	int	采样率（Hz）。	必需
cutoff_freq	float	截止频率（Hz）。	必需
order	int	滤波器阶数。	4

返回：

类型	描述
ndarray	高通滤波后的信号。

引发：

类型	描述
ValueError	参数非法或超过奈奎斯特频率时抛出。

low_pass_filter(signal, sr, cutoff_freq, order=4)

应用巴特沃斯低通滤波。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
sr	int	采样率（Hz）。	必需
cutoff_freq	float	截止频率（Hz）。	必需
order	int	滤波器阶数。	4

返回：

类型	描述
ndarray	低通滤波后的信号。

引发：

类型	描述
ValueError	参数非法或超过奈奎斯特频率时抛出。

median_filter(signal, kernel_size=3)

应用中值滤波以去除脉冲噪声。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
kernel_size	int	滤波核大小（必须为奇数）。	3

返回：

类型	描述
ndarray	中值滤波后的信号。

引发：

类型	描述
ValueError	kernel_size 非正奇数时抛出。

音频信号归一化工具。

min_max_normalize(signal, min_val=0.0, max_val=1.0)

将信号线性缩放到指定区间。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
min_val	float	目标最小值。	0.0
max_val	float	目标最大值。	1.0

返回：

类型	描述
ndarray	缩放后的信号。

引发：

类型	描述
ValueError	输入非一维或 min_val >= max_val 时抛出。

警告：

类型	描述
UserWarning	当信号取值近似常数时返回常数数组。

normalize_amplitude(signal, target_dBFS=-20.0)

将信号归一化到目标 dBFS。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
target_dBFS	float	目标 dBFS 值。	-20.0

返回：

类型	描述
ndarray	归一化后的信号。

引发：

类型	描述
ValueError	输入非一维时抛出。

警告：

类型	描述
UserWarning	当 RMS 接近 0 时返回原信号。

peak_normalize(signal, target_peak=0.95)

按峰值幅度进行归一化。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
target_peak	float	目标峰值幅度。	0.95

返回：

类型	描述
ndarray	归一化后的信号。

引发：

类型	描述
ValueError	输入非一维时抛出。

警告：

类型	描述
UserWarning	当峰值接近 0 时返回原信号。

z_normalize(signal)

执行 Z-score 标准化（零均值、单位方差）。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需

返回：

类型	描述
ndarray	标准化后的信号。

引发：

类型	描述
ValueError	输入非一维时抛出。

警告：

类型	描述
UserWarning	当标准差接近 0 时返回原信号。

音频分段工具。

segment_by_energy(signal, sr, threshold=0.05, min_length=0.1)

基于能量阈值进行分段。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号（建议已归一化到 [-1, 1]）。	必需
sr	int	采样率（Hz）。	必需
threshold	float	能量阈值，范围 [0, 1]。	0.05
min_length	float	片段最小时长（秒）。	0.1

返回：

类型	描述
list of tuple	片段列表，每个元素为 (start_idx, end_idx)。

引发：

类型	描述
ValueError	输入非法或参数越界时抛出。

警告：

类型	描述
UserWarning	当信号能量接近 0 时返回空列表。

segment_by_zcr(signal, sr, threshold=0.2, min_length=0.1, frame_length=0.025, hop_length=0.01)

基于过零率（ZCR）进行分段。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号（建议已归一化到 [-1, 1]）。	必需
sr	int	采样率（Hz）。	必需
threshold	float	ZCR 阈值，范围 [0, 1]。	0.2
min_length	float	片段最小时长（秒）。	0.1
frame_length	float	分析帧长度（秒）。	0.025
hop_length	float	帧移（秒）。	0.01

返回：

类型	描述
list of tuple	片段列表，每个元素为 (start_idx, end_idx)。

引发：

类型	描述
ValueError	输入非法或参数越界时抛出。

警告：

类型	描述
UserWarning	当信号长度不足一帧时返回空列表。

Features

时域特征提取函数。

energy(signal, frame_length=2048, hop_length=512)

计算短时能量。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
frame_length	int	帧长度（样本数）。	2048
hop_length	int	帧移（样本数）。	512

返回：

类型	描述
ndarray	每帧能量，形状为 (n_frames, 1)。

引发：

类型	描述
ValueError	输入维度或参数非法时抛出。

log_energy(signal, frame_length=2048, hop_length=512, eps=1e-10)

计算对数短时能量。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
frame_length	int	帧长度（样本数）。	2048
hop_length	int	帧移（样本数）。	512
eps	float	防止 log(0) 的小常数。	1e-10

返回：

类型	描述
ndarray	每帧对数能量，形状为 (n_frames, 1)。

pitch(signal, sr, frame_length=2048, hop_length=512, method='autocorr')

估计基频（音高）。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
sr	int	采样率（Hz）。	必需
frame_length	int	帧长度（样本数）。	2048
hop_length	int	帧移（样本数）。	512
method	(autocorr, improved_autocorr)	基于自相关的两种估计方式。	'autocorr'

返回：

类型	描述
ndarray	每帧基频（Hz），形状为 (n_frames, 1)。

引发：

类型	描述
ValueError	输入非法或方法不支持时抛出。

Notes

自相关法在噪声或多音情况下可能不稳定。

zero_crossing_rate(signal, frame_length=2048, hop_length=512)

计算过零率（ZCR）。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
frame_length	int	帧长度（样本数）。	2048
hop_length	int	帧移（样本数）。	512

返回：

类型	描述
ndarray	每帧过零率，形状为 (n_frames, 1)。

引发：

类型	描述
ValueError	输入维度或参数非法时抛出。

Notes

过零率对噪声较敏感，建议配合降噪或预处理。

频域特征提取函数。

magnitude_spectrum(signal, n_fft=2048, hop_length=512, win_length=None, window='hann', center=True, pad_mode='constant')

计算幅度谱。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
n_fft	int	FFT 点数。	2048
hop_length	int	帧移（样本数）。	512
win_length	int or None	窗长度（样本数），默认等于 n_fft。	None
window	str	窗函数类型，传入 librosa.stft。	'hann'
center	bool	是否在帧中心对齐。	True
pad_mode	str	边界填充模式，透传给 librosa.stft。	'constant'

返回：

类型	描述
ndarray	幅度谱，形状为 (n_frames, 1 + n_fft // 2)。

引发：

类型	描述
ValueError	输入维度或参数非法时抛出。

power_spectrum(signal, n_fft=2048, hop_length=512, win_length=None, window='hann', center=True, pad_mode='constant')

计算功率谱。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
n_fft	int	FFT 点数。	2048
hop_length	int	帧移（样本数）。	512
win_length	int or None	窗长度（样本数），默认等于 n_fft。	None
window	str	窗函数类型。	'hann'
center	bool	是否在帧中心对齐。	True
pad_mode	str	边界填充模式。	'constant'

返回：

类型	描述
ndarray	功率谱，形状为 (n_frames, 1 + n_fft // 2)。

spectral_bandwidth(signal, sr, n_fft=2048, hop_length=512, win_length=None, window='hann', p=2, center=True, pad_mode='constant')

计算谱带宽。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
sr	int	采样率（Hz）。	必需
n_fft	int	FFT 点数。	2048
hop_length	int	帧移（样本数）。	512
win_length	int or None	窗长度（样本数），默认等于 n_fft。	None
window	str	窗函数类型。	'hann'
p	float	带宽计算的幂次。	2
center	bool	是否在帧中心对齐。	True
pad_mode	str	边界填充模式。	'constant'

返回：

类型	描述
ndarray	谱带宽序列（Hz），形状为 (n_frames, 1)。

引发：

类型	描述
ValueError	输入维度或参数非法时抛出。

spectral_centroid(signal, sr, n_fft=2048, hop_length=512, win_length=None, window='hann', center=True, pad_mode='constant')

计算谱质心。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
sr	int	采样率（Hz）。	必需
n_fft	int	FFT 点数。	2048
hop_length	int	帧移（样本数）。	512
win_length	int or None	窗长度（样本数），默认等于 n_fft。	None
window	str	窗函数类型。	'hann'
center	bool	是否在帧中心对齐。	True
pad_mode	str	边界填充模式。	'constant'

返回：

类型	描述
ndarray	谱质心序列（Hz），形状为 (n_frames, 1)。

引发：

类型	描述
ValueError	输入维度或参数非法时抛出。

spectral_rolloff(signal, sr, n_fft=2048, hop_length=512, win_length=None, window='hann', roll_percent=0.85, center=True, pad_mode='constant')

计算谱滚降点。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
sr	int	采样率（Hz）。	必需
n_fft	int	FFT 点数。	2048
hop_length	int	帧移（样本数）。	512
win_length	int or None	窗长度（样本数），默认等于 n_fft。	None
window	str	窗函数类型。	'hann'
roll_percent	float	能量累积分位，默认 0.85。	0.85
center	bool	是否在帧中心对齐。	True
pad_mode	str	边界填充模式。	'constant'

返回：

类型	描述
ndarray	谱滚降点序列（Hz），形状为 (n_frames, 1)。

引发：

类型	描述
ValueError	输入维度或参数非法时抛出。

谱特征提取函数。

delta_mfcc(mfcc_features, order=1, width=9)

计算 MFCC 的差分特征。

参数：

名称	类型	描述	默认
mfcc_features	ndarray	MFCC 特征，形状为 (n_frames, n_mfcc)。	必需
order	int	差分阶数：1 为一阶，2 为二阶。	1
width	int	差分窗口宽度（奇数）。	9

返回：

类型	描述
ndarray	差分后的 MFCC，形状与输入一致。

引发：

类型	描述
ValueError	输入维度或参数非法时抛出。

formant_frequencies(signal, sr, order=12, n_formants=4)

估计共振峰频率（LPC）。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
sr	int	采样率（Hz）。	必需
order	int	LPC 阶数。	12
n_formants	int	估计的共振峰数量。	4

返回：

类型	描述
ndarray	共振峰频率数组，形状为 (n_frames, n_formants)。

引发：

类型	描述
ValueError	输入维度或参数非法时抛出。

Notes

LPC 共振峰估计对噪声敏感，结果仅供近似分析。

mel_spectrogram(signal, sr, n_fft=2048, hop_length=512, n_mels=128, fmin=0.0, fmax=None, center=True, pad_mode='constant')

计算 Mel 频谱。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
sr	int	采样率（Hz）。	必需
n_fft	int	FFT 点数。	2048
hop_length	int	帧移（样本数）。	512
n_mels	int	Mel 滤波器组数量。	128
fmin	float	最低频率（Hz）。	0.0
fmax	float or None	最高频率（Hz），默认 sr / 2。	None
center	bool	是否在帧中心对齐。	True
pad_mode	str	边界填充模式。	'constant'

返回：

类型	描述
ndarray	Mel 频谱，形状为 (n_frames, n_mels)。

引发：

类型	描述
ValueError	输入维度或参数非法时抛出。

mfcc(signal, sr, n_mfcc=13, n_fft=2048, hop_length=512, n_mels=128, fmin=0.0, fmax=None, center=True, pad_mode='constant')

计算 MFCC（梅尔频率倒谱系数）。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
sr	int	采样率（Hz）。	必需
n_mfcc	int	MFCC 系数数量。	13
n_fft	int	FFT 点数。	2048
hop_length	int	帧移（样本数）。	512
n_mels	int	Mel 滤波器组数量。	128
fmin	float	最低频率（Hz）。	0.0
fmax	float or None	最高频率（Hz），默认 sr / 2。	None
center	bool	是否在帧中心对齐。	True
pad_mode	str	边界填充模式。	'constant'

返回：

类型	描述
ndarray	MFCC 特征，形状为 (n_frames, n_mfcc)。

引发：

类型	描述
ValueError	输入维度或参数非法时抛出。

Notes

MFCC 常用于语音识别、说话人识别等任务。

统计特征提取函数。

harmonic_percussive_ratio(signal, sr, margin=3.0, kernel_size=31)

估计谐波-打击乐能量比。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
sr	int	采样率（Hz）。	必需
margin	float	HPSS 分离的裕度参数。	3.0
kernel_size	int	中值滤波器核大小。	31

返回：

类型	描述
float	谐波能量占比，范围 [0, 1]。

引发：

类型	描述
ValueError	输入维度或参数非法时抛出。

signal_statistics(signal, frame_length=2048, hop_length=512)

计算信号的帧级统计量。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
frame_length	int	帧长度（样本数）。	2048
hop_length	int	帧移（样本数）。	512

返回：

类型	描述
dict	统计量字典，包含 mean、std、skewness、kurtosis、 median、min、max、range、rms，每项形状为 (n_frames, 1)。

引发：

类型	描述
ValueError	输入维度或参数非法时抛出。

spectral_statistics(spectrogram, sr, n_fft=2048)

计算频谱的统计特征。

参数：

名称	类型	描述	默认
spectrogram	ndarray	频谱矩阵，形状为 (n_frames, 1 + n_fft // 2)。	必需
sr	int	采样率（Hz）。	必需
n_fft	int	计算频谱时使用的 FFT 点数。	2048

返回：

类型	描述
dict	频谱统计量字典，包含 centroid、bandwidth、flatness、 rolloff、flux、contrast，每项形状为 (n_frames, 1)。

引发：

类型	描述
ValueError	输入维度或参数非法时抛出。

Augmentation

时域数据增强函数。

add_noise(signal, noise_level=0.005, rng=None, seed=None)

向信号添加高斯白噪声。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
noise_level	float	噪声标准差。	0.005
rng	Generator or None	随机数生成器。	None
seed	int or None	随机种子，设置后结果可复现。	None

返回：

类型	描述
ndarray	加噪后的信号。

引发：

类型	描述
ValueError	输入非法时抛出。

pitch_shift(signal, sr, n_steps=4)

对信号进行变调（不改变时长）。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
sr	int	采样率（Hz）。	必需
n_steps	float	变化的半音数，正值升高、负值降低。	4

返回：

类型	描述
ndarray	变调后的信号。

引发：

类型	描述
ValueError	输入非法时抛出。

time_mask(signal, mask_fraction=0.1, rng=None, seed=None)

对信号随机时间片段进行掩码。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
mask_fraction	float	掩码比例，范围 [0, 1]。	0.1
rng	Generator or None	随机数生成器。	None
seed	int or None	随机种子，设置后结果可复现。	None

返回：

类型	描述
ndarray	掩码后的信号。

引发：

类型	描述
ValueError	输入非法时抛出。

time_stretch(signal, sr, rate=1.2)

对信号进行时间拉伸（不改变音高）。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
sr	int	采样率（Hz）。	必需
rate	float	拉伸倍率，>1 加速，<1 放慢。	1.2

返回：

类型	描述
ndarray	拉伸后的信号。

引发：

类型	描述
ValueError	输入非法时抛出。

频域数据增强函数。

frequency_mask(signal, sr, mask_start, mask_width, n_fft=2048, hop_length=512)

对频谱的指定频带进行掩码。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
sr	int	采样率（Hz）。	必需
mask_start	float	掩码起始频率（Hz）。	必需
mask_width	float	掩码频带宽度（Hz）。	必需
n_fft	int	FFT 点数。	2048
hop_length	int	帧移（样本数）。	512

返回：

类型	描述
ndarray	频带掩码后的信号。

引发：

类型	描述
ValueError	输入非法时抛出。

harmonic_enhancement(signal, sr, enhancement_factor=2.0)

增强谐波成分。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
sr	int	采样率（Hz）。	必需
enhancement_factor	float	谐波增强倍数。	2.0

返回：

类型	描述
ndarray	增强后的信号。

引发：

类型	描述
ValueError	输入非法时抛出。

spectral_contrast(signal, sr, enhancement_factor=5.0, n_fft=2048, hop_length=512)

增强谱对比度。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
sr	int	采样率（Hz）。	必需
enhancement_factor	float	增强系数，数值越大对比越强。	5.0
n_fft	int	FFT 点数。	2048
hop_length	int	帧移（样本数）。	512

返回：

类型	描述
ndarray	增强后的信号。

引发：

类型	描述
ValueError	输入非法时抛出。

spectral_inversion(signal)

对信号进行极性反转。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需

返回：

类型	描述
ndarray	反相后的信号。

引发：

类型	描述
ValueError	输入非法时抛出。

Pipeline

特征提取流水线。

FeatureExtractor

统一配置的特征提取器。

参数：

名称	类型	描述	默认
sr	int	目标采样率（Hz）。	22050
n_fft	int	FFT 点数。	2048
hop_length	int	帧移（样本数）。	512
n_mels	int	Mel 滤波器组数量。	128
n_mfcc	int	MFCC 系数数量。	13

属性：

名称	类型	描述
sr	int	采样率（Hz）。
n_fft	int	FFT 点数。
hop_length	int	帧移（样本数）。
n_mels	int	Mel 滤波器组数量。
n_mfcc	int	MFCC 系数数量。

__init__(sr=22050, n_fft=2048, hop_length=512, n_mels=128, n_mfcc=13)

初始化特征提取器。

extract_all_features(signal)

提取全部支持的特征类型。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号，采样率应与 self.sr 一致。	必需

返回：

类型	描述
dict	特征字典，值为 (n_frames, n_features)。

extract_features(signal, feature_types)

从信号中提取指定特征。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号，采样率应与 self.sr 一致。	必需
feature_types	list or tuple	特征名称列表，支持 mfcc、spectral_centroid、 spectral_bandwidth、spectral_rolloff、zcr、rms、 chroma、tonnetz、tempogram。	必需

返回：

类型	描述
dict	特征字典，键为特征名称，值为特征数组，形状为 (n_frames, n_features)，dtype 为 float32。

引发：

类型	描述
ValueError	输入非法或特征名称不支持时抛出。

extract_from_file(file_path, feature_types)

从音频文件中提取指定特征。

参数：

名称	类型	描述	默认
file_path	str	音频文件路径。	必需
feature_types	list or tuple	特征名称列表。	必需

返回：

类型	描述
dict	特征字典。

特征聚合工具。

FeatureAggregator

将帧级特征聚合为片段级统计特征。

aggregate_features(features, aggregation_methods)

按指定统计方法聚合特征。

参数：

名称	类型	描述	默认
features	dict	特征字典，键为特征名称，值为特征数组，形状为 (n_frames, n_features)。	必需
aggregation_methods	list or tuple	聚合方法列表，支持 mean、std、min、max、median、 skewness、kurtosis、range、quantile_25、quantile_75。	必需

返回：

类型	描述
dict	聚合后的特征字典，聚合结果按特征维度返回。

引发：

类型	描述
ValueError	输入非法或聚合方法不支持时抛出。

aggregate_statistics(features)

计算常用统计量并按特征归类。

参数：

名称	类型	描述	默认
features	dict	特征字典，键为特征名称，值为特征数组，形状为 (n_frames, n_features)。	必需

返回：

类型	描述
dict	嵌套字典：{feature_name: {stat_name: value}}。

Visualization

时域可视化工具。

plot_energy(signal, sr, frame_length=2048, hop_length=512, title='Signal Energy', figsize=(10, 4), ax=None)

绘制短时能量曲线。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
sr	int	采样率（Hz）。	必需
frame_length	int	帧长度（样本数）。	2048
hop_length	int	帧移（样本数）。	512
title	str	图表标题。	'Signal Energy'
figsize	tuple	图表大小（英寸）。	(10, 4)
ax	Axes or None	可选的坐标轴对象。	None

返回：

类型	描述
Figure	绘制后的图对象。

引发：

类型	描述
ValueError	输入非法时抛出。

plot_waveform(signal, sr, title='Waveform', figsize=(10, 4), ax=None)

绘制波形图。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
sr	int	采样率（Hz）。	必需
title	str	图表标题。	'Waveform'
figsize	tuple	图表大小（英寸）。	(10, 4)
ax	Axes or None	可选的坐标轴对象。	None

返回：

类型	描述
Figure	绘制后的图对象。

引发：

类型	描述
ValueError	输入非法时抛出。

plot_zero_crossing_rate(signal, sr, frame_length=2048, hop_length=512, title='Zero Crossing Rate', figsize=(10, 4), ax=None)

绘制过零率曲线。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
sr	int	采样率（Hz）。	必需
frame_length	int	帧长度（样本数）。	2048
hop_length	int	帧移（样本数）。	512
title	str	图表标题。	'Zero Crossing Rate'
figsize	tuple	图表大小（英寸）。	(10, 4)
ax	Axes or None	可选的坐标轴对象。	None

返回：

类型	描述
Figure	绘制后的图对象。

引发：

类型	描述
ValueError	输入非法时抛出。

频域可视化工具。

plot_chromagram(signal, sr, title='Chromagram', figsize=(10, 6), ax=None)

绘制色度图。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
sr	int	采样率（Hz）。	必需
title	str	图表标题。	'Chromagram'
figsize	tuple	图表大小（英寸）。	(10, 6)
ax	Axes or None	可选的坐标轴对象。	None

返回：

类型	描述
Figure	绘制后的图对象。

引发：

类型	描述
ValueError	输入非法时抛出。

plot_mel_spectrogram(signal, sr, n_fft=2048, hop_length=512, n_mels=128, title='Mel Spectrogram', figsize=(10, 6), ax=None)

绘制 Mel 频谱图。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
sr	int	采样率（Hz）。	必需
n_fft	int	FFT 点数。	2048
hop_length	int	帧移（样本数）。	512
n_mels	int	Mel 滤波器组数量。	128
title	str	图表标题。	'Mel Spectrogram'
figsize	tuple	图表大小（英寸）。	(10, 6)
ax	Axes or None	可选的坐标轴对象。	None

返回：

类型	描述
Figure	绘制后的图对象。

引发：

类型	描述
ValueError	输入非法时抛出。

plot_mfcc(signal, sr, n_mfcc=13, title='MFCC', figsize=(10, 6), ax=None)

绘制 MFCC 特征图。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
sr	int	采样率（Hz）。	必需
n_mfcc	int	MFCC 系数数量。	13
title	str	图表标题。	'MFCC'
figsize	tuple	图表大小（英寸）。	(10, 6)
ax	Axes or None	可选的坐标轴对象。	None

返回：

类型	描述
Figure	绘制后的图对象。

引发：

类型	描述
ValueError	输入非法时抛出。

plot_spectrogram(signal, sr, n_fft=2048, hop_length=512, title='Spectrogram', figsize=(10, 6), ax=None)

绘制线性频率谱图。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
sr	int	采样率（Hz）。	必需
n_fft	int	FFT 点数。	2048
hop_length	int	帧移（样本数）。	512
title	str	图表标题。	'Spectrogram'
figsize	tuple	图表大小（英寸）。	(10, 6)
ax	Axes or None	可选的坐标轴对象。	None

返回：

类型	描述
Figure	绘制后的图对象。

引发：

类型	描述
ValueError	输入非法时抛出。

Utils

音频与特征文件 I/O 工具。

load_audio(file_path, sr=None, mono=True)

读取音频文件。

参数：

名称	类型	描述	默认
file_path	str	音频文件路径。	必需
sr	int or None	目标采样率，为 None 时保持原采样率。	None
mono	bool	是否转换为单声道。	True

返回：

类型	描述
tuple	(signal, sr)。mono=True 时 signal 为一维数组， mono=False 时形状为 (channels, samples)，dtype 为 float32。

Notes

实际读取由 audiofeatures.core.audio_loader.load_audio 完成。

load_features(file_path)

从 .npz 文件读取特征。

参数：

名称	类型	描述	默认
file_path	str	特征文件路径。	必需

返回：

类型	描述
dict	特征字典。

save_audio(signal, sr, file_path)

保存音频到文件。

参数：

名称	类型	描述	默认
signal	ndarray	一维输入信号。	必需
sr	int	采样率（Hz）。	必需
file_path	str	输出文件路径。	必需

引发：

类型	描述
ValueError	输入非法时抛出。

save_features(features, file_path)

将特征字典保存为 .npz 文件。

参数：

名称	类型	描述	默认
features	dict	特征字典，键为名称、值为数组。	必需
file_path	str	输出路径（建议以 .npz 结尾）。	必需

引发：

类型	描述
ValueError	features 不是字典时抛出。

音频相关单位换算工具。

hz_to_mel(frequencies)

将 Hz 频率转换为 Mel 频率。

参数：

名称	类型	描述	默认
frequencies	float or ndarray	输入频率（Hz）。	必需

返回：

类型	描述
float or ndarray	Mel 频率。

hz_to_note(frequency)

将频率转换为音符名称。

参数：

名称	类型	描述	默认
frequency	float	频率（Hz）。	必需

返回：

类型	描述
str	音符名称，例如 "A4"。

引发：

类型	描述
ValueError	频率非正时抛出。

mel_to_hz(mels)

将 Mel 频率转换为 Hz 频率。

参数：

名称	类型	描述	默认
mels	float or ndarray	Mel 频率。	必需

返回：

类型	描述
float or ndarray	Hz 频率。

note_to_hz(note)

将音符名称转换为频率（Hz）。

参数：

名称	类型	描述	默认
note	str	音符名称，例如 "A4"、"C#3"。	必需

返回：

类型	描述
float	对应频率（Hz）。

引发：

类型	描述
ValueError	音符格式非法时抛出。

samples_to_seconds(samples, sr)

将样本数转换为秒数。

参数：

名称	类型	描述	默认
samples	int	样本数。	必需
sr	int	采样率（Hz）。	必需

返回：

类型	描述
float	时间（秒）。

引发：

类型	描述
ValueError	输入非法时抛出。

seconds_to_samples(seconds, sr)

将秒数转换为样本数。

参数：

名称	类型	描述	默认
seconds	float	时间（秒）。	必需
sr	int	采样率（Hz）。	必需

返回：

类型	描述
int	样本数。

引发：

类型	描述
ValueError	输入非法时抛出。

特征契约与数组规范化工具。

ensure_float32(signal, clip=False)

确保输入转换为 float32。

参数：

名称	类型	描述	默认
signal	array - like	输入信号。	必需
clip	bool	是否裁剪到 [-1, 1]。	False

返回：

类型	描述
ndarray	float32 数组。

to_feature_matrix(values, frame_axis=0)

将特征转换为 (n_frames, n_features)。

参数：

名称	类型	描述	默认
values	array - like	输入特征。	必需
frame_axis	int	输入中的帧轴位置。0 表示输入已是 (n_frames, n_features)， 1 表示输入为 (n_features, n_frames)。	0

返回：

类型	描述
ndarray	形状为 (n_frames, n_features) 的 float32 数组。

引发：

类型	描述
ValueError	输入维度非法或 frame_axis 不支持时抛出。