Matchering 2.0 配置参数详解

目标：全面解读 Matchering 2.0.6 的三层配置体系——Python 库的处理参数（Config 与 LimiterConfig）、结果声明参数（Result）与官方 Web 应用的服务端配置，逐项给出默认值、取值约束与实测验证，并给出批处理与公网场景的推荐配置模板。参数默认值以 2.0.6 官方源码为基准，关键项均在《Matchering 2.0 Docker Compose 部署指南》部署的 2.0.6 环境中实测验证。

一、环境信息

本文参数验证环境与取证口径如下：

参数分层说明：Matchering 的配置分三层——处理参数（mg.Config，决定算法行为）、限制器参数（mg.LimiterConfig，嵌在 Config 内）、结果声明（mg.pcm16/mg.pcm24/mg.Result，决定输出文件与后处理方式）。Web 应用另有独立的服务端配置（Django settings）。三层互不重叠，改动互不影响。

二、前置条件

1. 已有一套可运行的 Matchering 2.0.6：Web 应用按《Matchering 2.0 Docker Compose 部署指南》部署，或本地已执行 python3 -m pip install -U matchering（Linux 需先装 libsndfile1 与可选 ffmpeg，见《Matchering 介绍与选型指南》）。
2. 理解一个总原则：官方在源码注释与示例 edited_config.py 中的态度是「Think twice before you change something here」——处理参数改变的是算法内部的工作点，默认值是作者调好的整体平衡，逐项改动前应有可对照的听测样本。

三、参数查看与修改方式

3.1 查看默认值：构造 Config 实例直接打印

Config 的全部参数都带默认值，最直接的查看方式是实例化后逐项打印。在装有 matchering 的 Python 环境执行：

python3 -c "
import matchering as mg
c = mg.Config()
for k, v in sorted(vars(c).items()):
    print(k, '=', v)
"

实测回显（2.0.6 环境，容器内 Python 3.10 实测）：

version: 2.0.6
allow_equality = False
clipping_samples_threshold = 8
fft_size = 4096
internal_sample_rate = 44100
limited_samples_threshold = 128
limiter = <matchering.defaults.LimiterConfig object at 0x756b0fbbf1c0>
lin_log_oversampling = 4
lowess_delta = 0.001
lowess_frac = 0.0375
lowess_it = 0
max_length = 900
max_piece_size = 661500
min_value = 1e-06
preview_analysis_step = 220500
preview_fade_coefficient = 8
preview_fade_size = 44100
preview_size = 1323000
rms_correction_steps = 4
temp_folder = None
threshold = 0.998138427734375

两个观察要点：max_piece_size、preview_size 等在源码里以「秒」为单位传入（如 preview_size=30），但构造函数内部乘以 internal_sample_rate 换算成了样本数（30 × 44100 = 1323000），打印看到的都是样本数口径；threshold 打印值 0.9981384… 对应约 -0.016 dB 的砖墙阈值（20*log10(0.9981384) 实算 = -0.0162 dB）。limiter 字段是 LimiterConfig 实例（打印为对象引用，展开方式见第六节）。

3.2 版本与导入自检

修改配置前先确认环境里实际生效的版本，避免新旧参数名混淆：

python3 -c "import matchering as mg; print('version:', mg.__version__)"

实测回显（Web 应用内置环境）：

version: 2.0.6

3.3 修改方式：构造自定义 Config 传入 process

mg.process() 的 config 参数接受任意自定义的 Config 实例，未显式指定的参数自动落到默认值。官方示例 edited_config.py 给出的标准写法：

import matchering as mg

mg.process(
    target="my_song.wav",
    reference="some_popular_song.wav",
    results=[
        mg.pcm16("my_song_master_16bit.wav"),
        mg.pcm24("my_song_master_24bit.wav"),
    ],
    config=mg.Config(
        max_length=30 * 60,
        internal_sample_rate=96000,
        threshold=0.7079,
        temp_folder="/tmp",
        preview_size=15,
        allow_equality=True
    ),
)

写法要点：每个参数都是关键字传参；max_length=30 * 60 与 preview_size=15 以秒为单位；threshold 是 0 到 1 之间的浮点（官方注释给出换算——0.7079 即 -3 dB）。非法值不会静默生效，构造函数内置了断言，越界直接抛 AssertionError（各参数的断言约束见下文逐项表）。

四、Config 处理参数总览

Config 构造函数的完整参数清单（默认值取自 2.0.6 defaults.py 源码）：

构造函数的约束断言（改值前必读）：max_length 必须大于 fft_size / internal_sample_rate；max_piece_size 必须大于 fft_size / internal_sample_rate 且小于 max_length；threshold 必须落在 (min_value, 1) 开区间；fft_size 必须是 2 的整数次幂；preview_size 必须大于 5；min_value 必须小于 0.1。任何一项越界，实例化阶段即抛 AssertionError，不会带病运行。

五、核心处理参数分类详解

5.1 采样率与时钟：internal_sample_rate

这是影响面最大的单一参数：加载后的目标与参考都被重采样到该速率，匹配运算在此速率上进行，结果文件也以此速率写出。默认 44100 Hz 是流媒体与 CD 的行业标准。源码对偏离默认值显式打警告：

Using an internal sample rate other than 44100 has not been tested properly! Use it at your own risk!

适配场景与代价：

配套约束：max_length 与 max_piece_size 的下限校验都引用该值，把采样率改大后，以秒为单位的时间参数不受影响（构造函数内部自动按新采样率换算）。

5.2 时长与规模：max_length / max_piece_size

max_length 是输入轨的时长上限，默认 900 秒（15 分钟），超限直接报错。批处理长素材（如 DJ 混音带、长播客）时按需放大，例如 max_length=30 * 60（官方示例同款写法）。代价是匹配分析的内存占用与曲目时长成正比——这也是官方要求 4 GB RAM 起步的原因之一。

max_piece_size（默认 15 秒）控制频响匹配的分段粒度：片段越小，频响估计对局部变化越敏感，但统计稳定性下降；默认值是作者平衡后的结果，除特殊实验外不建议单独改它（注意它必须小于 max_length）。

5.3 峰值控制：threshold 与两个采样数阈值

threshold 是限制器与导出环节的砖墙阈值，默认值 (2^15-61)/2^15（实测打印 0.998138427734375）的来源很有讲究——它比满幅 1.0 低了 61/32768（约 -0.016 dB），恰好给 16-bit 输出留出余量，避免 dither 后溢出。改它之前先想清楚：调低（如 -3 dB，官方示例的 threshold=0.7079）会整体压低响度，调高到 1.0 可能让 16-bit 导出削波。

clipping_samples_threshold（默认 8）与 limited_samples_threshold（默认 128）是质量哨兵：处理过程中若发现连续 N 个采样贴着阈值，即判定削波/过度限幅并在日志中给出对应日志码。把这两个阈值调大等于放宽告警灵敏度，一般保持默认。

💡 技术拓展：砖墙限制器（brickwall limiter）不止 Matchering 自研这一种实现思路——

实现路线	原理	代表
前瞻型限制器	预读未来若干毫秒，提前起增益衰减，透明度高	商业插件主流（FabFilter Pro-L 等）
反馈型/自适应释放	按信号统计自适应释放时间	开源 swh-limiter 等
Matchering hyrax	Python 实现的自研方案，attack/hold/release 全可配	本组件（LIMITER_TEST.md 有官方对比数据）

Matchering 选择自研并公开质量对比文档，正是因为 2.0 重写时「不再依赖 MATLAB」后需要一款可控的开源限制器；默认参数即官方推荐值。

5.4 频响拟合：fft_size 与 LOWESS 三参数

fft_size（默认 4096，约 93 ms @ 44.1 kHz）决定频谱分析的频率分辨率：窗口越大频率分辨率越高、时间定位越粗。必须保持 2 的整数次幂（源码断言 math.log2(fft_size).is_integer()）。

LOWESS（局部加权回归散点平滑）三参数控制均衡曲线的平滑程度：lowess_frac（默认 0.0375）是参与每次拟合的窗口占比，越大越平滑；lowess_it（默认 0）是稳健性迭代次数；lowess_delta（默认 0.001）是计算间隔。频响匹配出「过猛」的均衡时，可微调 lowess_frac 加大平滑；这组参数同样属于「默认即作者调优结果」，建议一次只动一个。

5.5 会话与临时文件：allow_equality / temp_folder

allow_equality 默认 False：把同一个文件同时作为目标与参考提交会被拒绝（这是防呆设计——相同文件匹配出的母带没有意义，还浪费算力）。自动化管线里若存在「用上一版输出做参考再磨一遍」的合法场景，设 True 放开。

temp_folder 默认 None：MP3 等需经 FFmpeg 解码的输入会先落盘临时 WAV，None 时自动使用结果文件所在目录。容器化部署时建议显式指到数据卷路径（如 /app/data），避免写入只读层。

5.6 预览输出：preview_* 四参数

Web 界面的试听波形与 FLAC 预览由这组参数控制：preview_size（默认 30 秒）取母带结果的头部片段，preview_analysis_step（5 秒）是分析步进，preview_fade_size（1 秒）与 preview_fade_coefficient（8）共同决定首尾淡入淡出形状。Python 库侧只有当 process() 传入 preview_target/preview_result 时才生成预览，不传则跳过、不产生开销。

六、LimiterConfig 限制器参数

限制器参数是独立子对象 mg.LimiterConfig，经 Config(limiter=mg.LimiterConfig(...)) 嵌入。全部 8 个参数及默认值（2.0.6 defaults.py）：

实测打印限制器子配置。注意：LimiterConfig 未从包顶层导出（mg.LimiterConfig 会报 AttributeError），需从 matchering.defaults 导入：

python3 -c "
from matchering.defaults import LimiterConfig
l = LimiterConfig()
for k, v in sorted(vars(l).items()):
    print(k, '=', v)
"

实测回显（2.0.6）：

attack = 1
attack_filter_coefficient = -2
hold = 1
hold_filter_coefficient = 7
hold_filter_order = 1
release = 3000
release_filter_coefficient = 800
release_filter_order = 1

调参指引：这组参数直接决定母带的「响度抑制音头」听感——attack 越大限制器反应越慢（保留更多瞬态但峰值控制越松），release 越大增益恢复越慢（听感更平顺但连续响段会被持续压低）。源码断言要求 attack > 0、hold > 0、release > 0、两个 filter_order 为正整数。官方在 LIMITER_TEST.md 中用它与其他限制器做过量化对比，默认值即该测试所用配置，建议以此为基准做 A/B 听测再动。

七、Result 结果声明参数

输出不是「一个文件名」而是「一组 Result 对象」，这是 Matchering 设计上容易被忽略的灵活性来源。mg.Result(file, subtype, use_limiter=True, normalize=True) 的四个字段：

内置快捷方式 mg.pcm16(path) 与 mg.pcm24(path) 等价于 Result(path, "PCM_16") / Result(path, "PCM_24")，对应 Web 应用「16-bit 与 24-bit 两档结果」的产品行为。

字段组合的实际语义（源码 core.py 的分支逻辑实测梳理）：

示例——同一次处理同时产出三种版本做对比听测：

import matchering as mg

mg.process(
    target="my_song.wav",
    reference="some_popular_song.wav",
    results=[
        mg.pcm24("master_limited.wav"),
        mg.Result("master_nolim_norm.wav", "PCM_24", use_limiter=False),
        mg.Result("master_raw.wav", "FLAC", use_limiter=False, normalize=False),
    ],
)

合法性由 libsndfile 校验：扩展名必须是本机 soundfile 支持的格式、subtype 必须为该格式合法位深，不合法在构造 Result 时即抛 TypeError（错误文本形如 FLAC format does not have PCM_24 subtype——FLAC 实际支持 PCM_24，此处仅示意错误形态）。

八、Web 应用服务端配置

Web 应用（matchering-web）的可调配置在 Django settings 与应用源码层，容器化部署后经环境变量或源码修改调整。2.0.6 源码 matchering_web/settings.py 的关键项：

实测确认数据目录结构（部署环境，ls 节选）：

db.sqlite3
media

media/ 下平铺存放上传轨与结果文件（结果文件名带随机后缀，如 Matchering_16bit_target_BCvo.wav）；db.sqlite3 记录会话状态。Django 的会话签名密钥在 /app/.secret_key（init.sh 首次启动生成，独立于数据目录）。/app/data 整目录即 Web 应用的全部业务持久化状态——保留 60 分钟后由应用自行清理，备份该目录即备份全部会话数据。

Web 应用侧的完整部署与运维视角（内部组件构成、日志观察、公网加固）见《Matchering 2.0 Docker Compose 部署指南》；对外 HTTP 接口的逐端点实测见《Matchering 2.0 API 使用详解》。

九、生产配置模板

9.1 批处理管线（16 GB 内存服务器，长专辑批量母带）

import matchering as mg

mg.log(print)

mg.process(
    target="album_track_07.wav",
    reference="ref_loudness_leader.wav",
    results=[
        mg.pcm24("album_track_07_master_24bit.wav"),
        mg.pcm16("album_track_07_master_16bit.wav"),
    ],
    config=mg.Config(
        max_length=30 * 60,          # 放开到 30 分钟，覆盖长曲目
        internal_sample_rate=44100,  # 流媒体交付规格，保持默认
        temp_folder="/data/tmp",     # 显式指到数据盘，避免占满系统盘
    ),
)

要点：参考轨建议全专辑固定用同一首（响度领袖曲），整张专辑才有统一的响度目标；max_length 按最长曲目设定而非无脑放大，内存占用随其线性上升。

9.2 Web 应用公网加固模板（对外提供内网服务时）

公网场景在 Compose 基础上必须补三件事，缺一即有隐私/安全风险（官方 Wiki「Keep the Privacy」同口径）：

1. 反向代理加认证：Matchering Web 自身无登录体系，前置 Nginx/Caddy 做 Basic Auth 或 SSO；
2. 收窄 Django 配置：settings.py 中 DEBUG=False、ALLOWED_HOSTS=["your.domain.com"] 后重建；
3. 缩短数据留存：MGW_STORE_DATA_FOR_MINUTES 调小（如 15），降低音轨滞留面。

十、常见问题

Q1：改了 internal_sample_rate=96000，结果文件确实是 96 kHz 吗？ 是。结果采样率跟随该参数写出，但源码明确警告非 44100 未充分测试；发行前务必用 ffprobe/soxi 核对输出，并做完整听测。

Q2：断言错误 AssertionError 怎么定位？ 构造 Config/LimiterConfig 时抛出的断言都对应第四节/第六节表格里的约束列，报错行号即所违反的断言行；常见是 fft_size 不是 2 的幂、threshold 越界、max_piece_size 大于 max_length 三类。

Q3：处理报 4201 之类四位数字码是什么？ 这是日志码体系（LOG_CODES.md 全量收录），Web 界面同样用码反馈错误。码首位是分类，完整码表解读与排障路径见《Matchering 2.0 API 使用详解》。

Q4：Web 界面没有参数可调，能改吗？ 不能从界面调。Web 应用按「极简、开箱即用」定位写死了全部算法参数（默认 Config + pcm16/pcm24 双输出）；需要调参必须走 Python 库（本文第三节写法）。

Q5：同一对音轨每次处理结果一致吗？ 一致。匹配运算与限制器均为确定性数值计算，无随机源；结果差异只可能来自输入文件或配置差异。

十一、参考链接

1. Config/LimiterConfig 源码（2.0.6 defaults.py）：https://github.com/sergree/matchering/blob/master/matchering/defaults.py
2. Result 与导出源码：https://github.com/sergree/matchering/blob/master/matchering/results.py
3. 官方自定义配置示例：https://github.com/sergree/matchering/blob/master/examples/edited_config.py
4. 限制器质量对比：https://github.com/sergree/matchering/blob/master/LIMITER_TEST.md
5. 日志码文档：https://github.com/sergree/matchering/blob/master/LOG_CODES.md
6. Web 应用仓库：https://github.com/sergree/matchering-web
7. 公网托管隐私指引：https://github.com/sergree/matchering/wiki/Keep-the-Privacy