MLT媒体程序框架03：滤镜——loudness

EBU R.128协议

引用链接
EBU的全称为European Broadcasting Union ，既欧洲广播联盟，为欧洲与北非各广播业者（包含广播电台与电视台）的合作组织，成立于1950年2月12日,有五十多个正式加盟国,总部位于瑞士日内瓦,目前中国是EBU的准会员。
EBU R.128实质上是欧洲广播联盟出的一个关于响度控制的建议书,该建议书在ITU-R BS.1770标准的(国际广播联盟规定的音频节目响度及真峰值的测量算法)基础之上，对响度的被测主体、积分窗长等细节作了更加明确的定义。

响度和动态范围的定义与相关的计量单位

• 响度(Loudness)的定义： 在声学中，响度是人对声音压力的主观感受,也是听觉的一种属性，根据这种属性，可以对声音进行排序，如从安静排列到响亮，亦或者从响亮排列至安静。响度虽是声音的物理属性，但其却与听者的生理感受，心理感受息息相关，准确来说这属于心理物理学的范畴了。

• 音量单位dBFS与dB： 首先dBFS与dB都是分贝的意思，而分贝一般指的就是音量大小。 dBFS全称decibels relative to full scale,什么叫full scale呢？既是满刻度，具体来讲是将0作为这种满刻度单位的最大值（也就是说此类值均为负数），凡是带FS后缀的计量单位都可这样理解（如LUFS或LKFS）。dB常用来形容一个音量到目标音量的“距离”，比如需要将一个信号从-4dBFS提升至-1dBFS，那么就需要对-4dBFS做3dB的提升操作。在业界，dBFS常被简称为dB，如-4dB等等。

• 动态范围： 用通俗不严谨的话来说，动态范围指的是最大音量与最小音量之间的“距离”值，这个“距离”值就被称为动态范围，比如一段音频中的最大音量为-2dBFS,最小音量为-8dBFS,那么它的动态范围就是6dB。站在AD转换器的角度来说，动态范围指的是信号可以达到的最大不失真电平与本底噪声的差值。

• EBU响度单位LUFS： LUFS的全称为Loudness units relative to full scale，既相对完整刻度的响度单位。广电行业中，LUFS是有一个目标响度值的，那就是-23LUFS，该值是广播世界的终极响度参考值！LUFS的数值越大，其响度就越大。至于为什么是-23LUFS，笔者暂未做深入研究。另外，LKFS是国际广播联盟用的单位，与LUFS差不多。

• EBU响度单位LU： LU的全称为Loudness units，通常1LU“等同于”1dB（仅仅是理解层面上的“相等”），常用来形容两个LUFS之间的“距离”,如-25LUFS与-18LUFS间差了7LU。综上所述，dBFS与LUFS, dB与LU，虽测量算法不同，但其含义却是相似的。

响度示值，响度范围和真峰值的介绍

• 瞬时响度 Momentary Loudness： 瞬时响度指的是400MS(毫秒)内的响度，并每过100ms进行一次更新，响应相当灵敏。
• 短期响度 Short Term Loudness： 短期响度是提取3秒以内的信号，表达的是3S内的平均响度。
• 综合响度 Integrated Loudness： 综合响度指的是整段音频的平均响度。
• 响度范围 Loudness Range： 响度范围，经常被简称为LRA，其代表的是两个LUFS之间的“距离”，如一段音频的最小响度为-25LUFS，最大响度为-18LUFS，其间差了7LU，既代表该音频的响度范围为7LU。响度范围与动态范围表达的是一个意思，只是测量方法不一样。
• 真峰值 True Peak： 在说真峰值之前，先用通俗的话来说说峰值是什么，峰值就是波形振幅的波峰值（波形有波谷和波峰之分），说白了就是波形瞬态的最大电平值。那为什么要在峰值之前加个“真”字呢？原因是这样的，以前有一种峰值测量方法，只有当峰值的持续时间超过一定的时间时（通常是几毫秒），才会计算出比较准确的峰值，这种测量算法被称为准峰值（QPPM）。而EBU给出了一种新的算法，无论它的持续时间有多短，都能正确的测量出其波形的真实峰值水平，故此，称其为真峰值。那么响度表中的真峰值指示条是用来干嘛的呢？它是用来检测信号有没有过载的，一旦信号过载就会被削波造成信号失真，正因如此，EBU给出建议为真峰值不要超过-1dBTP，目的就是防止信号产生过载削波，其单位为dBTP(dB True Peak真实峰值），对应的值是dBFS值。

双遍滤镜(loudness)

主要用于音频向度的精准标准化，其核心作用是通过两次处理（Double Pass）分析音频特征并应用目标响度参数，确保输出音频符合行业标准（如EBU R128 或 ITU-R BS.1770），同时优化动态范围控制

使用方式

One Pass: 调用滤镜分析得到result

std::string AudioAnalyze::analyzeAudio(const std::string &path,int trimIn,int trimOut) {Producer producer(getGlobalProfile(), nullptr,path.c_str());if(producer.get_length() <= 1 || producer.get_int("audio_index") == -1){std::cout << "analyzeAudio no effect"  << std::endl;return "";}if(trimOut > 0){producer.set_in_and_out(trimIn,trimOut);}Filter filter(getGlobalProfile(),"loudness");filter.set("program",-29);producer.attach(filter);Consumer consumer(getGlobalProfile(), "null");consumer.set("terminate_on_pause",0);consumer.connect(producer);consumer.start();while (!consumer.is_stopped()) {// ignoreif(filter.property_exists("results")){const char *results = filter.get("results");if(results != nullptr) {std::cout << "analyzeAudio results:" << results << std::endl;consumer.stop();return results;} else {std::cout << "analyzeAudio results:" << "error: key is null" << std::endl;return "";}}}return "";
}

Two Pass: 把result写入滤镜参数中，则会自动调整目标响度

std::shared_ptr<Filter> loudnessFilter{nullptr};
if (!results.empty()) {loudnessFilter = std::make_shared<Filter>(getGlobalProfile(), "loudness");loudnessFilter->set("program", configuration.aiDefaultLoudness);loudnessFilter->set("disable", 0);loudnessFilter->set("reload", 1);auto length = results.length() + 1;char *result = (char *) malloc(results.length() + 1);memcpy((void *) result, (const void *) results.c_str(), results.length());result[length - 1] = '\0';loudnessFilter->set("results", result);
}
loudnessFilter->set_in_and_out(trimIn, trimOut);
childClipInfo->producer->attach(*loudnessFilter);

关键源码分析

filter_get_audio

static int filter_get_audio(mlt_frame frame,void **buffer,mlt_audio_format *format,int *frequency,int *channels,int *samples)
{mlt_filter filter = mlt_frame_pop_audio(frame);mlt_properties properties = MLT_FILTER_PROPERTIES(filter);mlt_service_lock(MLT_FILTER_SERVICE(filter));// Get the producer's audio*format = mlt_audio_f32le;mlt_frame_get_audio(frame, buffer, format, frequency, channels, samples);char *results = mlt_properties_get(properties, "results");if (buffer && buffer[0] && results && strcmp(results, "")) {// Two Pass的时候走这个函数apply(filter, frame, buffer, format, frequency, channels, samples);} else {// One Pass的时候走这个函数analyze(filter, frame, buffer, format, frequency, channels, samples);}mlt_service_unlock(MLT_FILTER_SERVICE(filter));return 0;
}

analyze：分析得到原音频信息

static void analyze(mlt_filter filter,mlt_frame frame,void **buffer,mlt_audio_format *format,int *frequency,int *channels,int *samples)
{private_data *private = (private_data *) filter->child;mlt_position pos = mlt_filter_get_position(filter, frame);// If any frames are skipped, analysis data will be incomplete.// 作用：确保音频帧按顺序处理，跳过帧会导致分析中断。// 原因：EBU R128 要求连续分析，缺失帧会导致积分响度计算错误。if (private->analyze && pos != private->last_position + 1) {mlt_log_error(MLT_FILTER_SERVICE(filter), "Analysis Failed: Bad frame sequence\n");destroy_analyze_data(filter);}// Analyze Audioif (!private->analyze && pos == 0) {init_analyze_data(filter, *channels, *frequency);}if (private->analyze) {// 作用：将当前音频帧数据（buffer）输入 EBU R128 分析器，更新内部状态。ebur128_add_frames_float(private->analyze->state, *buffer, *samples);if (pos + 1 == mlt_filter_get_length2(filter, frame)) {mlt_properties properties = MLT_FILTER_PROPERTIES(filter);double loudness = 0.0;double range = 0.0;double tmpPeak = 0.0;double peak = 0.0;int i = 0;char result[MAX_RESULT_SIZE];// 计算整体响度ebur128_loudness_global(private->analyze->state, &loudness);// 计算响度范围ebur128_loudness_range(private->analyze->state, &range);// 获取声道峰值for (i = 0; i < *channels; i++) {ebur128_sample_peak(private->analyze->state, i, &tmpPeak);if (tmpPeak > peak) {peak = tmpPeak;}}// 格式化结果并存储snprintf(result, MAX_RESULT_SIZE, "L: %lf\tR: %lf\tP %lf", loudness, range, peak);result[MAX_RESULT_SIZE - 1] = '\0';mlt_log_info(MLT_FILTER_SERVICE(filter), "Stored results: %s\n", result);mlt_properties_set(properties, "results", result);destroy_analyze_data(filter);}private->last_position = pos;}
}

ebur128_gated_loudness: 计算 综合响度（Integrated Loudness）

这段代码是 EBU R128 综合响度（Integrated Loudness） 的核心计算逻辑，用于在音频处理中通过门限控制（Gating）剔除低能量部分，最终得到符合标准的响度值。

static int
ebur128_gated_loudness(ebur128_state** sts, size_t size, double* out) {struct ebur128_dq_entry* it;double gated_loudness = 0.0;double relative_threshold = 0.0;size_t above_thresh_counter = 0;size_t i, j, start_index;// 检查输入的音频状态结构体数组 sts 是否启用了综合响度模式（EBUR128_MODE_I）。若未启用，返回错误。
// 综合响度模式是 EBU R128 的核心功能，需通过 ebur128_init 初始化时设置模式标志for (i = 0; i < size; i++) {if (sts[i] && (sts[i]->mode & EBUR128_MODE_I) != EBUR128_MODE_I) {return EBUR128_ERROR_INVALID_MODE;}}
// 作用：遍历所有音频状态实例，调用 ebur128_calc_relative_threshold 计算 相对门限
// 相对门限：基于音频块能量分布，动态确定一个阈值，剔除低于该值的部分（如静音段或背景噪声）
// 公式：相对门限 = 平均能量 × 相对门限因子（默认-10 dB，即 relative_gate_factor = 0.1）
// 引用：EBU R128 要求综合响度计算需忽略低于动态门限的音频段，以聚焦主要节目内容for (i = 0; i < size; i++) {if (!sts[i]) {continue;}ebur128_calc_relative_threshold(sts[i], &above_thresh_counter,&relative_threshold);}if (!above_thresh_counter) {*out = -HUGE_VAL;return EBUR128_SUCCESS;}relative_threshold /= (double) above_thresh_counter;relative_threshold *= relative_gate_factor;
// 作用：根据相对门限值，确定直方图中高于门限的起始索引 start_index。
// 直方图优化：若启用直方图模式（use_histogram），直接遍历预计算的能量区间，跳过低能量部分。
// 未启用直方图：则需遍历块链表（block_list），逐个检查能量是否高于门限。
// 引用：直方图加速了能量统计，是 EBU R128 实现高效计算的关键优化 above_thresh_counter = 0;if (relative_threshold < histogram_energy_boundaries[0]) {start_index = 0;} else {start_index = find_histogram_index(relative_threshold);if (relative_threshold > histogram_energies[start_index]) {++start_index;}}
// 作用：统计所有高于门限的音频块能量总和 gated_loudness 及其数量 above_thresh_counter。
// 直方图模式：通过预计算的能量值 histogram_energies 和直方图计数快速累加。
// 块链表模式：遍历链表，筛选符合门限的块并累加能量。
// 引用：EBU R128 要求忽略低于门限的音频段，例如静音或低电平背景声for (i = 0; i < size; i++) {if (!sts[i]) {continue;}if (sts[i]->d->use_histogram) {for (j = start_index; j < 1000; ++j) {gated_loudness +=sts[i]->d->block_energy_histogram[j] * histogram_energies[j];above_thresh_counter += sts[i]->d->block_energy_histogram[j];}} else {STAILQ_FOREACH(it, &sts[i]->d->block_list, entries) {if (it->z >= relative_threshold) {++above_thresh_counter;gated_loudness += it->z;}}}}if (!above_thresh_counter) {*out = -HUGE_VAL;return EBUR128_SUCCESS;}
// 作用：
//  平均能量：将累积的能量总和除以有效块数量，得到平均能量。
// 能量转响度：调用 ebur128_energy_to_loudness 将能量转换为 LUFS（Loudness Units Full Scale）。
// 公式：LUFS = 10 × log₁₀(平均能量) - 绝对偏移值（如-0.691 dB，用于校准滤波器响应）
// 引用：LUFS 是 EBU R128 的标准化响度单位，综合响度目标值为 -23 LUFS（广播领域）gated_loudness /= (double) above_thresh_counter;*out = ebur128_energy_to_loudness(gated_loudness);return EBUR128_SUCCESS;
}

ebur128_loudness_range_multiple：计算响度范围（Loudness Range, LRA）

用于衡量音频节目中响度的动态变化
计算多个音频流的综合响度范围（LRA），即节目中最响的 95% 部分与最安静的 10% 部分之间的响度差（单位：LU）

输入：
sts：多个 ebur128_state 状态对象的数组（支持多路音频流合并计算）。
size：数组长度。
输出：
out：计算得到的 LRA 值。
返回值：错误码（成功为 EBUR128_SUCCESS）。

int ebur128_loudness_range_multiple(ebur128_state** sts,size_t size,double* out) {size_t i, j;struct ebur128_dq_entry* it;double* stl_vector;size_t stl_size;double* stl_relgated;size_t stl_relgated_size;double stl_power, stl_integrated;/* High and low percentile energy */double h_en, l_en;int use_histogram = 0;// 模式校验
// 必须启用 LRA 模式：所有状态对象需通过 EBUR128_MODE_LRA 初始化。
// 直方图模式一致性：所有状态对象需统一启用或禁用直方图（EBUR128_MODE_HISTOGRAM）。for (i = 0; i < size; ++i) {if (sts[i]) {if ((sts[i]->mode & EBUR128_MODE_LRA) != EBUR128_MODE_LRA) {return EBUR128_ERROR_INVALID_MODE;}if (i == 0 && sts[i]->mode & EBUR128_MODE_HISTOGRAM) {use_histogram = 1;} else if (use_histogram != !!(sts[i]->mode & EBUR128_MODE_HISTOGRAM)) {return EBUR128_ERROR_INVALID_MODE;}}}
// 直方图模式计算if (use_histogram) {unsigned long hist[1000] = { 0 };size_t percentile_low, percentile_high;size_t index;stl_size = 0;stl_power = 0.0;for (i = 0; i < size; ++i) {if (!sts[i]) {continue;}for (j = 0; j < 1000; ++j) {// 直方图累加：合并所有音频流的短期能量直方图（3秒窗口）。hist[j] += sts[i]->d->short_term_block_energy_histogram[j];stl_size += sts[i]->d->short_term_block_energy_histogram[j];stl_power += sts[i]->d->short_term_block_energy_histogram[j] *histogram_energies[j];}}if (!stl_size) {*out = 0.0;return EBUR128_SUCCESS;}
//门限处理：排除低于平均能量 -20 dB 的块（minus_twenty_decibels = 0.01）。// 平均能量stl_power /= stl_size;// // 应用-20 dB门限stl_integrated = minus_twenty_decibels * stl_power;if (stl_integrated < histogram_energy_boundaries[0]) {index = 0;} else {// 找到门限对应的直方图索引(直方图优化：跳过低于门限的区间，减少计算量。)index = find_histogram_index(stl_integrated);if (stl_integrated > histogram_energies[index]) {++index;}}stl_size = 0;for (j = index; j < 1000; ++j) {stl_size += hist[j];}if (!stl_size) {*out = 0.0;return EBUR128_SUCCESS;}
// 遍历直方图：累加直方图计数，找到对应百分位的能量值。// 10% 低百分位percentile_low = (size_t) ((stl_size - 1) * 0.1 + 0.5);// 95% 高百分位percentile_high = (size_t) ((stl_size - 1) * 0.95 + 0.5);stl_size = 0;j = index;while (stl_size <= percentile_low) {stl_size += hist[j++];}l_en = histogram_energies[j - 1];while (stl_size <= percentile_high) {stl_size += hist[j++];}h_en = histogram_energies[j - 1];
// 计算 LRA(将能量值转换为响度（LU），计算高低百分位的差值*out = ebur128_energy_to_loudness(h_en) - ebur128_energy_to_loudness(l_en);return EBUR128_SUCCESS;}
// 非直方图模式计算同理stl_size = 0;for (i = 0; i < size; ++i) {if (!sts[i]) {continue;}STAILQ_FOREACH(it, &sts[i]->d->short_term_block_list, entries) {++stl_size;}}if (!stl_size) {*out = 0.0;return EBUR128_SUCCESS;}stl_vector = (double*) malloc(stl_size * sizeof(double));if (!stl_vector) {return EBUR128_ERROR_NOMEM;}j = 0;for (i = 0; i < size; ++i) {if (!sts[i]) {continue;}STAILQ_FOREACH(it, &sts[i]->d->short_term_block_list, entries) {stl_vector[j] = it->z;++j;}}qsort(stl_vector, stl_size, sizeof(double), ebur128_double_cmp);stl_power = 0.0;for (i = 0; i < stl_size; ++i) {stl_power += stl_vector[i];}stl_power /= (double) stl_size;stl_integrated = minus_twenty_decibels * stl_power;stl_relgated = stl_vector;stl_relgated_size = stl_size;while (stl_relgated_size > 0 && *stl_relgated < stl_integrated) {++stl_relgated;--stl_relgated_size;}if (stl_relgated_size) {h_en = stl_relgated[(size_t) ((stl_relgated_size - 1) * 0.95 + 0.5)];l_en = stl_relgated[(size_t) ((stl_relgated_size - 1) * 0.1 + 0.5)];free(stl_vector);*out = ebur128_energy_to_loudness(h_en) - ebur128_energy_to_loudness(l_en);} else {free(stl_vector);*out = 0.0;}return EBUR128_SUCCESS;
}

ebur128_sample_peak：获取指定声道采样峰值（Sample Peak）

作用：获取音频流中指定声道的采样峰值电平（单位：dBFS）。
采样峰值（Sample Peak）：音频信号在数字域中的最大绝对值，未经插值处理，直接来自采样点。
用途：检测音频是否削波（超过 0 dBFS），确保符合广播或流媒体的响度标准。

int ebur128_sample_peak(ebur128_state* st,unsigned int channel_number,double* out) {if ((st->mode & EBUR128_MODE_SAMPLE_PEAK) != EBUR128_MODE_SAMPLE_PEAK) {return EBUR128_ERROR_INVALID_MODE;}if (channel_number >= st->channels) {return EBUR128_ERROR_INVALID_CHANNEL_INDEX;}*out = st->d->sample_peak[channel_number];return EBUR128_SUCCESS;
}

apply

核心目标：将音频的响度调整到用户设定的目标值（如 EBU R128 规定的 -23 LUFS）。
输入依赖：需要预先通过分析阶段获取当前音频的响度（in_loudness）、响度范围（in_range）和峰值（in_peak）。
操作：计算增益系数并应用到音频数据，使其响度匹配目标值。

static void apply(mlt_filter filter,mlt_frame frame,void **buffer,mlt_audio_format *format,int *frequency,int *channels,int *samples)
{mlt_properties properties = MLT_FILTER_PROPERTIES(filter);char *results = mlt_properties_get(properties, "results");double in_loudness;double in_range;double in_peak;int scan_return = sscanf(results, "L: %lf\tR: %lf\tP %lf", &in_loudness, &in_range, &in_peak);if (scan_return != 3) {mlt_log_error(MLT_FILTER_SERVICE(filter), "Unable to load results: %s\n", results);} else {// 计算增益系数// 增益公式是固定的double target_db = mlt_properties_get_double(properties, "program");double delta_db = target_db - in_loudness;double coeff = delta_db > -90.0 ? pow(10.0, delta_db / 20.0) : 0.0;float *p = *buffer;int count = *samples * *channels;// 线性增益：将每个音频样本乘以计算出的增益系数。// 声道处理：遍历所有声道和样本，统一应用增益。for (int i = 0; i < count; i++) {p[i] = p[i] * coeff;}}
}