librosa 0.10+ 版本中 `librosa.resample` 已改为仅支持关键字参数（keyword-only），必须显式传入 `orig_sr` 和 `target_sr`，否则会报错“takes 1 positional argument but 3 were given”。本文详解正确调用方式、多通道处理技巧及实用注意事项。
在使用 wav2vec2 等预训练模型进行语音微调时，确保所有音频统一为 16 kHz 采样率 是关键前提。而从 torchaudio.load() 加载的音频往往原始采样率各异（如 44.1 kHz、48 kHz 或 8 kHz），需通过重采样对齐。许多用户在迁移到较新版本的 librosa（≥0.10.0）后，因沿用旧版位置参数写法（如 librosa.resample(y, sr, 16000)）触发如下错误：
TypeError: resample() takes 1 positional argument but 3 were given
这是因为新版 librosa.resample 显式要求所有参数（除音频数组 y 外）必须以命名参数形式传入，其函数签名如下：
def resample(
y: np.ndarray,
*,
orig_sr: float,
target_sr: float,
res_type: str = "soxr_hq",
fix: bool = True,
scale: bool = False,
axis: int = -1,
**kwargs
) -> np.ndarray:其中 * 表示其后所有参数均为 keyword-only —— 这是导致错误的根本原因。
✅ 正确用法（适配 mono 与 stereo）：
import librosa
import numpy as np
# 假设 database['audio'] 是 list of 1D/2D numpy arrays，database['psr'] 是对应原始采样率列表
new_audios = []
new_sr = []
for i, (audio_signal, original_sr) in enumerate(zip(database['audio'], database['psr'])):
audio_signal = np.asarray(audio_signal)
# 处理单通道（mono）
if audio_signal.ndim == 1:
resampled = librosa.resample(
y=audio_signal,
orig_sr=original_sr,
target_sr=16000
)
# 处理多通道（stereo 或更多），逐通道重采样并保持形状
elif audio_signal.ndim == 2:
resampled_channels = []
for ch in audio_signal:
ch_resampled = librosa.resample(
y=ch,
orig_sr=original_sr,
target_sr=16000
)
resampled_channels.append(ch_resampled)
resampled = np.stack(resampled_channels, axis=0)
else:
raise ValueError(f"Unsupported audio dimensionality: {audio_signal.ndim} at index {i}")
new_audios.append(resampled)
new_sr.append(16000)
# 更新数据字典
database['audio'] = new_audios
database['newsr'] = new_sr⚠️ 注意事项与最佳实践：
-
不要混用 torchaudio 与 librosa 的重采样逻辑：torchaudio.transforms.Resample 更高效且原生支持 Tensor，若全程使用 PyTorch 生态，推荐优先采用：
from torchaudio.transforms import Resample resampler = Resample(orig_freq=original_sr, new_freq=16000) resampled_tensor = resampler(speech_array) # speech_array: torch.Tensor, shape [C, T]
避免 librosa.resample 对长音频的内存峰值：该函数内部会将信号上采样至 LCM 频率，对超长语音（>30s）可能引发 OOM。此时建议分段处理或改用 scipy.signal.resample_poly（需手动设计抗混叠滤波器）。
res_type="soxr_hq" 是默认高质量选项，但依赖 soxr 库（需 pip install pysoundfile 或 conda install -c conda-forge soxr）。若环境受限，可降级为 "kaiser_best" 或 "polyphase"，精度略低但无额外依赖。
始终验证重采样结果：检查输出长度是否合理（近似按 len_in * 16000 / orig_sr 缩放），并用 librosa.get_duration(y=resampled, sr=16000) 校验时长一致性。
总结：librosa.resample 的关键字参数强制策略提升了 API 可读性与健壮性。只需将 librosa.resample(y, sr, 16000) 统一替换为 librosa.resample(y, orig_sr=sr, target_sr=16000)，即可彻底解决报错，并为 wav2vec2 微调构建稳定、合规的 16 kHz 音频流水线。
