Skip to content

feat(播放): Exo 音频平衡(响度 AGC) - #97

Merged
ModerRAS merged 2 commits into
masterfrom
cursor/audio-balance-c1d2
Nov 3, 2026
Merged

ModerRAS merged 2 commits into
masterfrom
cursor/audio-balance-c1d2

Conversation

@ModerRAS

@ModerRAS ModerRAS commented Nov 2, 2026

Copy link
Copy Markdown
Owner

概述

为 MiruPlay 增加可选的 「音频平衡」(响度 AGC),减轻同一集内对白/BGM/音效忽大忽小的问题。实现参考 blbl 类产品思路(RMS 追踪 + 峰值限制),但接入现有 Exo DSP 管线而非独立粘贴。

设计

Exo PCM 处理器顺序

DefaultAudioSink 内顺序(自解码器 toward AudioTrack):

  1. DspAudioProcessor — 现有 PEQ/FIR/下混/LinkedLimiter
  2. AudioBalanceAudioProcessor — 本 PR 新增,包装 audio-dsp-core 的 LoudnessBalanceProcessor
  3. MusicSrcBypassProcessor(仅音乐 SRC=高质软 SRC 时)— Sonic 重采样到本机速率

平衡放在 DSP 之后,避免 EQ/下混前的增益与 AGC 互相打架;放在 SRC 之前,对即将送入混音器的 PCM 做最终响度整理。

算法要点(LoudnessBalanceProcessor)

  • 目标 RMS ≈ −20 dBFS,帧级 RMS 平滑
  • 启动 校准窗口(按档位 1.8–3.5s)再正式追踪
  • 分离 attack / release 系数,抑制抽吸感
  • 噪声门(档位 −48 ~ −54 dBFS)以下不盲目抬增益
  • 联动 峰值天花板 0.98,必要时瞬时压限并回写增益状态
  • 档位变更通过 AudioDspRuntimeConfig revision 热更新,onFlush 重置状态

档位语义

档位 最大抬升 最大衰减 特点
关 — — 直通
低 +6 dB −6 dB 慢 release,适合对话为主
中 +10 dB −8 dB 默认推荐
高 +14 dB −10 dB 更快追踪,复杂混音可能略感压缩

持久化键:player_audio_balance_level(与 blbl 命名一致),默认 关。

引擎支持

引擎 音频平衡
Exo / Media3 ✅ 完整支持
IJK ❌ 未接入(设置/UI 已说明)
MPV ❌ 未接入(设置/UI 已说明)

设置面

  • TV:设置 → 播放 → 「音频平衡」四档芯片(关/低/中/高)
  • WebAPI / WebUI:/api/settings/playback 增加 audioBalanceLevel 字段,保存时同步 AudioDspRuntimeConfig

测试

本地已跑(通过):

  • :audio-dsp-core:test — LoudnessBalanceProcessorTest(静音、quiet boost、峰值限制、档位切换)
  • :data:testDebugUnitTest — PlaybackPreferencesManagerTest(持久化)
  • :player-core:testDebugUnitTest — MusicSrcBypassPipelineTest(含新处理器链路的组合回归)
  • :web-control-core:test — WebControlSettingsRouteTest(playback DTO 字段)

手动验证(HK1 / 真机)

  1. 准备同一集内响度差明显的片源(安静对白 + 大动态 BGM/爆炸)。
  2. 确认默认 Exo 后端,设置 → 播放 → 音频平衡=关,播放 2–3 分钟感受原始动态。
  3. 不切集,改为 中 或 高,继续播放:对白与突发音效之间的落差应变小(可能有轻微压缩感,高档更明显)。
  4. 切到 IJK/MPV 后端:功能不生效,UI 文案已提示;不应崩溃。
  5. (可选)WebUI 修改档位并保存,TV 正在播放时应能热更新。

未做 / 后续

  • IJK/MPV 侧等价 hook(若产品需要再单独立项)
  • 真机 HK1 验收(Cloud Agent 环境无法代测)
Open in Web Open in Cursor 

Integrate AGC-style loudness balance into the Exo PCM processor chain
after DSP and before optional music SRC. Persist level in playback prefs
with TV/WebUI controls and unit tests for core gain math.

Co-authored-by: ModerRAS <adqewsx@gmail.com>
@coderabbitai

coderabbitai Bot commented Nov 2, 2026 •

Copy link
Copy Markdown

Important

  • Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: a8731580-1f31-4936-a695-fb6b57ef3bd4
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

- lint MissingTranslation: values-zh-rTW / values-zh-rHK 补 10 条 audio balance 文案
- SettingsViewModelTokenTest: 严格 mock 补 audioBalanceLevel=OFF
  (构造器新增读取,7 例 MockKException)
- docs/agents/pre-pr-checklist.md: 追加音频平衡 feature log(HK1 真机证据)
@ModerRAS

ModerRAS commented Nov 2, 2026

Copy link
Copy Markdown
Owner Author

真机验证(HK1)+ CI 修灯

CI 红灯已修(已 push)

  • lint MissingTranslation:补 values-zh-rTW / values-zh-rHK 10 条 audio balance 文案;本地 :ui-tv:lintDebug 通过
  • 7 例 SettingsViewModelTokenTest MockKException:构造器新增读取 playbackPreferences.audioBalanceLevel,严格 mock 补 stub returns OFF;本地 :ui-tv:testDebugUnitTest 全过;另跑通 :audio-dsp-core:test、MusicSrcBypassPipelineTest、PlaybackPreferencesManagerTest、:web-control-core:test

HK1 真机(debug APK,Exo 默认)

  • 冷启动无崩溃;test hook 建库(AudioTest 1 文件);播完回详情且标"已看"
  • 设置 → 播放 → 音频平衡四档渲染正常(默认关);切中/高/低即时落盘 player_audio_balance_level,分档文案正确
  • TV↔WebAPI 双向 parity:GET 返回 audioBalanceLevel;PUT 高/低档 TV 侧一致
  • Exo 播放(高/中/低档):position 推进、无 error;播放中 PUT 热更新继续播到 EOF 无 error;全程无 AndroidRuntime:E / Player error / Fatal signal
  • IJK 播同片无崩溃(按设计不生效);MPV 内嵌因盒子 OpenGL 过旧起不来 VO(pre-existing 环境问题),进程存活无崩溃
  • 外挂 ASS 渲染正常,MiruLibass resolved,Skipped malformed ASS=0(截图见附件描述,视频表面字幕可见)

未覆盖(原因已记入 checklist feature log)

  • 长片主观听感(fixture 最长 2 分钟);WebUI 浏览器端点选(本机无浏览器环境,同一 DTO 的 TV/WebAPI 双向已验证)

@ModerRAS
ModerRAS marked this pull request as ready for review November 2, 2026 14:39
@ModerRAS
ModerRAS merged commit 919625f into master Nov 3, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants