【audioop/audioop-lts详细用法】

audioop‑lts 是 Python 已移除的标准库模块 audioop 的"长期支持（LTS）移植版"，用于在 Python ≥3.13 环境下继续使用原 audioop 的全部原生音频处理功能。它本质上提供对原始 PCM 音频数据（8/16/24/32 位有符号整数）进行算术、格式转换、编解码（a‑Law/u‑Law/ADPCM）、统计与匹配、采样率转换、声道处理等 API。

参考：https://docs.python.org/3.12/library/audioop.html

---

它支持的"大类"功能

• 算术与增益：加法、乘法、加偏置
• 格式/字节序转换：位深转换（1/2/3/4 字节）、字节序交换
• 压缩/解压编解码：a‑Law、u‑Law、Intel/DVI ADPCM
• 统计与能量：均值、RMS、峰值、峰峰值、过零点、极值
• 模板匹配与能量峰值查找：findfactor、findfit、findmax
• 采样率转换：ratecv（带简单的数字滤波器）
• 声道处理：转单声道、转立体声
• 其它：取样本、反转、异常对象
  下面按类别列出并简单说明用途（API 名与原 audioop 完全一致）。

一、算术与增益

• add(fragment1, fragment2, width)------两段音频相加（样本逐点加）；两段长度需相同；溢出时截断。
• mul(fragment, width, factor)------所有样本乘以一个浮点因子（音量缩放）；溢出时截断。
• bias(fragment, width, bias)------每个样本加上一个偏置值（直流偏移）；溢出时循环/截断。

二、格式与字节序转换

• lin2lin(fragment, width, newwidth)------在不同位深之间转换（1/2/3/4 字节）。注意从/到 8‑bit 的常见带符号/无符号问题（需要配合 bias ±128 使用）。
• byteswap(fragment, width)------字节序交换（大端↔小端）；适合在不同平台/音频格式间迁移数据。

三、编解码（压缩）相关

• lin2alaw(fragment, width)------线性 PCM 转 a‑Law 编码（8 bit，约 13 bits 动态范围）。
• alaw2lin(fragment, width)------a‑Law 转回线性 PCM。
• lin2ulaw(fragment, width)------线性 PCM 转 u‑Law 编码（8 bit，约 14 bits 动态范围）。
• ulaw2lin(fragment, width)------u‑Law 转回线性 PCM。
• lin2adpcm(fragment, width, state)------线性 PCM 转 Intel/DVI IMA ADPCM（每样本 4 bit）；返回 (adpcmfrag, newstate)，状态需要传入下一次调用。
• adpcm2lin(adpcmfragment, width, state)------ADPCM 转回线性 PCM；返回 (sample, newstate)。

四、统计与能量/电平分析

• avg(fragment, width)------所有样本的平均值。
• avgpp(fragment, width)------"平均峰峰值"（无滤波；实用性有限）。
• rms(fragment, width)------均方根能量值（用于音量/功率测度）。
• max(fragment, width)------样本绝对值的最大值。
• maxpp(fragment, width)------片段内的最大峰峰值。
• minmax(fragment, width)------(最小值, 最大值)。
• cross(fragment, width)------过零次数（零交叉数量）。

五、模板匹配与能量峰值查找（多用于对齐、检测）

• findfactor(fragment, reference)------寻找一个因子 F，使 rms(add(fragment, mul(reference, -F))) 最小；即用最佳缩放让 reference 与 fragment 匹配（两者需为 2‑字节样本）。
• findfit(fragment, reference)------在 fragment 里找到与 reference 最佳匹配的偏移与缩放因子，返回 (offset, factor)（两者需为 2‑字节样本）。
• findmax(fragment, length)------在 fragment 中按给定样本长度（单位样本数）搜索能量最大的片段位置（返回起始索引 i；两者需为 2‑字节样本）。

六、采样率转换

• ratecv(fragment, width, nchannels, inrate, outrate, state, weightA\[, weightB])------将音频片段从 inrate 转换到 outrate，返回 (newfragment, newstate)，需在多次调用间传递状态；支持简单数字滤波（weightA/weightB）。

七、声道处理

• tomono(fragment, width, lfactor, rfactor)------将立体声转为单声道；左、右通道分别按 lfactor/rfactor 加权后相加。
• tostereo(fragment, width, lfactor, rfactor)------由单声道生成立体声；左右样本分别按 lfactor/rfactor 缩放后组成左右对。

八、其它工具与元信息

• getsample(fragment, width, index)------按索引返回单个样本的值。
• reverse(fragment, width)------将样本顺序反转（例如倒放效果）。
• error------本模块抛出的异常类型；用于参数错误、不支持的字宽等情况。

九、使用要点

• 适用 Python 版本：该移植明确标注仅在 Python ≥3.13 中使用（因为 3.13 移除了内置的 audioop）。
• 数据形态：对"字节串/类字节对象"里的原始 PCM 操作；支持 8/16/24/32 位有符号整数样本；多声道情况下只是把所有样本平等看待（需要时自己先分再合）。
• 兼容性：API 与原 audioop 模块一致，旧代码只需在 ≥3.13 时安装 audioop‑lts 并导入同名模块即可继续使用。

十、快速用法示例

• 安装（仅 Python ≥3.13）：pip install "audioop-lts; python_version >= '3.13'"
• 基本计算（RMS、增益、反转）：

import audioop
rms_val = audioop rms(fragment, 2)          # 16‑位样本的 RMS
louder = audioop.mul(fragment, 2, 1.5)      # 1.5 倍增益
reversed_frag = audioop.reverse(fragment, 2)  # 倒放片段

• 转码与采样率：

alaw_data = audioop.lin2alaw(fragment, 2)   # 转为 a‑Law
new_frag, new_state = audioop.ratecv(fragment, 2, 1, 48000, 44100, None)  # 48k→44.1k

参考：audioop‑lts GitHub README（说明它是对 audioop 的 LTS 移植，链接到原 audioop 文档），以及 Python 3.12 audioop 官方文档（完整 API 列表与说明）。