Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,179 @@
package com.miruplay.tv.audio

import com.miruplay.tv.model.AudioBalanceLevel
import kotlin.math.ln
import kotlin.math.max
import kotlin.math.min
import kotlin.math.sqrt

/**
* Streaming AGC-style loudness balance: chase RMS toward [params.targetRmsLinear] with separate
* attack/release, optional calibration window, noise gate, and a linked peak ceiling.
*/
class LoudnessBalanceProcessor(
level: AudioBalanceLevel,
sampleRateHz: Int,
) {
private var params: LoudnessBalanceParams? = LoudnessBalanceParams.forLevel(level)
private var sampleRate = sampleRateHz.coerceAtLeast(1)

private var currentGain = 1f
private var smoothedRms = 0f
private var calibrationAccum = 0.0
private var calibrationFrames = 0
private var calibrated = false

fun setLevel(level: AudioBalanceLevel, sampleRateHz: Int) {
val next = LoudnessBalanceParams.forLevel(level)
val rateChanged = sampleRateHz.coerceAtLeast(1) != sampleRate
sampleRate = sampleRateHz.coerceAtLeast(1)
if (next == params && !rateChanged) return
params = next
resetState()
}

fun resetState() {
currentGain = 1f
smoothedRms = 0f
calibrationAccum = 0.0
calibrationFrames = 0
calibrated = false
}

fun processInPlace(interleaved: FloatArray, channels: Int) {
val active = params ?: return
require(channels > 0) { "channels must be positive" }
if (interleaved.isEmpty()) return
val frames = interleaved.size / channels
val attackCoeff = timeCoefficient(active.attackMs)
val releaseCoeff = timeCoefficient(active.releaseMs)
val rmsSmoothCoeff = timeCoefficient(active.rmsSmoothMs)
val calibrateFrames = (active.calibrateMs * 0.001f * sampleRate).toInt().coerceAtLeast(1)
val gateLinear = dbToLinear(active.gateDb)
val targetLinear = active.targetRmsLinear
val minGain = dbToLinear(-active.maxCutDb)
val maxGain = dbToLinear(active.maxBoostDb)
val peakCeiling = active.peakCeiling

for (frame in 0 until frames) {
val offset = frame * channels
var sumSquares = 0.0
for (channel in 0 until channels) {
val sample = interleaved[offset + channel].toDouble()
sumSquares += sample * sample
}
val frameRms = sqrt(sumSquares / channels).toFloat()

if (!calibrated) {
calibrationAccum += frameRms.toDouble()
calibrationFrames += 1
if (calibrationFrames >= calibrateFrames) {
smoothedRms = (calibrationAccum / calibrationFrames).toFloat().coerceAtLeast(gateLinear)
calibrated = true
} else {
applyGain(interleaved, offset, channels, currentGain, peakCeiling)
continue
}
}

smoothedRms += (frameRms - smoothedRms) * rmsSmoothCoeff
val measured = max(smoothedRms, gateLinear)
var desiredGain = if (measured <= gateLinear) {
min(currentGain, 1f)
} else {
(targetLinear / measured).coerceIn(minGain, maxGain)
}

val coeff = if (desiredGain < currentGain) attackCoeff else releaseCoeff
currentGain += (desiredGain - currentGain) * coeff
applyGain(interleaved, offset, channels, currentGain, peakCeiling)
}
}

private fun applyGain(
interleaved: FloatArray,
offset: Int,
channels: Int,
gain: Float,
peakCeiling: Float,
) {
var peak = 0f
for (channel in 0 until channels) {
val index = offset + channel
val scaled = interleaved[index] * gain
interleaved[index] = scaled
peak = max(peak, kotlin.math.abs(scaled))
}
if (peak <= peakCeiling || peak <= 0f) return
val limit = peakCeiling / peak
for (channel in 0 until channels) {
val index = offset + channel
interleaved[index] *= limit
}
currentGain *= limit
}

private fun timeCoefficient(timeMs: Float): Float {
val ms = timeMs.coerceAtLeast(1f)
return (1f - kotlin.math.exp(-1f / (ms * 0.001f * sampleRate))).coerceIn(0f, 1f)
}

private data class LoudnessBalanceParams(
val maxBoostDb: Float,
val maxCutDb: Float,
val attackMs: Float,
val releaseMs: Float,
val rmsSmoothMs: Float,
val gateDb: Float,
val calibrateMs: Float,
val targetRmsLinear: Float,
val peakCeiling: Float,
) {
companion object {
private const val TARGET_RMS_DBFS = -20f
private const val PEAK_CEILING = 0.98f

fun forLevel(level: AudioBalanceLevel): LoudnessBalanceParams? = when (level) {
AudioBalanceLevel.OFF -> null
AudioBalanceLevel.LOW -> LoudnessBalanceParams(
maxBoostDb = 6f,
maxCutDb = 6f,
attackMs = 120f,
releaseMs = 1800f,
rmsSmoothMs = 250f,
gateDb = -54f,
calibrateMs = 3500f,
targetRmsLinear = dbToLinear(TARGET_RMS_DBFS),
peakCeiling = PEAK_CEILING,
)
AudioBalanceLevel.MEDIUM -> LoudnessBalanceParams(
maxBoostDb = 10f,
maxCutDb = 8f,
attackMs = 80f,
releaseMs = 1400f,
rmsSmoothMs = 180f,
gateDb = -50f,
calibrateMs = 2500f,
targetRmsLinear = dbToLinear(TARGET_RMS_DBFS),
peakCeiling = PEAK_CEILING,
)
AudioBalanceLevel.HIGH -> LoudnessBalanceParams(
maxBoostDb = 14f,
maxCutDb = 10f,
attackMs = 50f,
releaseMs = 900f,
rmsSmoothMs = 120f,
gateDb = -48f,
calibrateMs = 1800f,
targetRmsLinear = dbToLinear(TARGET_RMS_DBFS),
peakCeiling = PEAK_CEILING,
)
}
}
}
}

internal fun dbToLinear(db: Float): Float {
if (db <= -120f) return 0f
return kotlin.math.exp((db * ln(10.0) / 20.0).toFloat())
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
package com.miruplay.tv.audio

import com.miruplay.tv.model.AudioBalanceLevel
import org.junit.Assert.assertTrue
import org.junit.Test
import kotlin.math.abs

class LoudnessBalanceProcessorTest {
private val sampleRate = 48_000

@Test
fun `off level is a no-op`() {
val processor = LoudnessBalanceProcessor(AudioBalanceLevel.OFF, sampleRate)
val input = floatArrayOf(0.5f, 0.5f, -0.2f, -0.2f)
processor.processInPlace(input, channels = 2)
assertTrue(input.contentEquals(floatArrayOf(0.5f, 0.5f, -0.2f, -0.2f)))
}

@Test
fun `silence stays silent after calibration`() {
val processor = LoudnessBalanceProcessor(AudioBalanceLevel.MEDIUM, sampleRate)
val silence = FloatArray(sampleRate / 10 * 2) { 0f }
repeat(40) { processor.processInPlace(silence, channels = 2) }
assertTrue(silence.all { abs(it) < 1e-4f })
}

@Test
fun `quiet segment is boosted toward target after calibration`() {
val processor = LoudnessBalanceProcessor(AudioBalanceLevel.HIGH, sampleRate)
val quiet = FloatArray(sampleRate * 3 * 2) { index ->
if (index % 2 == 0) 0.01f else 0.01f
}
processor.processInPlace(quiet, channels = 2)
val tailStart = quiet.size - sampleRate * 2
val tailRms = rms(quiet, tailStart, quiet.size, channels = 2)
assertTrue("tailRms=$tailRms", tailRms > 0.03f)
}

@Test
fun `peak is limited below ceiling`() {
val processor = LoudnessBalanceProcessor(AudioBalanceLevel.HIGH, sampleRate)
val warm = FloatArray(sampleRate * 2 * 2) { 0.12f }
processor.processInPlace(warm, channels = 2)
val peakBlock = floatArrayOf(1f, 1f, 1f, 1f)
processor.processInPlace(peakBlock, channels = 2)
assertTrue(peakBlock.maxOf { abs(it) } <= 0.985f)
}

@Test
fun `level change resets calibration state`() {
val processor = LoudnessBalanceProcessor(AudioBalanceLevel.LOW, sampleRate)
val warm = FloatArray(sampleRate * 2 * 2) { 0.08f }
processor.processInPlace(warm, channels = 2)
processor.setLevel(AudioBalanceLevel.HIGH, sampleRate)
val after = FloatArray(4) { 0.08f }
processor.processInPlace(after, channels = 2)
assertTrue(after.all { it.isFinite() })
}

private fun rms(samples: FloatArray, start: Int, end: Int, channels: Int): Float {
var sum = 0.0
var count = 0
for (index in start until end) {
sum += samples[index] * samples[index]
count += 1
}
return kotlin.math.sqrt(sum / count.coerceAtLeast(1)).toFloat()
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
package com.miruplay.tv.model

import kotlinx.serialization.Serializable

/** Exo/Media3 PCM loudness balance strength; IJK and MPV do not apply this today. */
@Serializable
enum class AudioBalanceLevel(val storageValue: String) {
OFF("off"),
LOW("low"),
MEDIUM("medium"),
HIGH("high");

val isEnabled: Boolean
get() = this != OFF

companion object {
fun fromStorageValue(value: String?): AudioBalanceLevel =
entries.firstOrNull { it.storageValue.equals(value?.trim()?.lowercase(), ignoreCase = true) }
?: OFF
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import com.miruplay.tv.model.FormatAwareToneMappingPreferences
import com.miruplay.tv.model.PlaybackEndAction
import com.miruplay.tv.model.PlaybackRenderBackend
import com.miruplay.tv.model.SubtitleLanguagePreference
import com.miruplay.tv.model.AudioBalanceLevel
import com.miruplay.tv.model.AudioDspConfig
import com.miruplay.tv.model.MusicSrcBypassMode
import com.miruplay.tv.repository.MicCalibrationSettings
Expand Down Expand Up @@ -99,6 +100,12 @@ class PlaybackPreferencesManager @Inject constructor(
prefs.edit().putString(KEY_MUSIC_SRC_BYPASS_MODE, value.storageValue).apply()
}

var audioBalanceLevel: AudioBalanceLevel
get() = AudioBalanceLevel.fromStorageValue(prefs.getString(KEY_AUDIO_BALANCE_LEVEL, null))
set(value) {
prefs.edit().putString(KEY_AUDIO_BALANCE_LEVEL, value.storageValue).apply()
}

/** User-picked sweep-measurement microphone (AudioDeviceInfo.id), or null for the default. */
var audioMeasureMicId: Int?
get() = prefs.getInt(KEY_AUDIO_MEASURE_MIC_ID, Int.MIN_VALUE).takeIf { it != Int.MIN_VALUE }
Expand Down Expand Up @@ -178,6 +185,12 @@ class PlaybackPreferencesManager @Inject constructor(
musicSrcBypassMode = mode
}

override suspend fun getAudioBalanceLevel(): AudioBalanceLevel = audioBalanceLevel

override suspend fun setAudioBalanceLevel(level: AudioBalanceLevel) {
audioBalanceLevel = level
}

companion object {
private const val KEY_END_ACTION = "end_action"
private const val KEY_EPISODE_VERSION_SELECTION_POLICY = "episode_version_selection_policy"
Expand All @@ -189,6 +202,7 @@ class PlaybackPreferencesManager @Inject constructor(
private const val KEY_AUDIO_MEASURE_CALIBRATIONS = "audio_measure_calibrations"
private const val KEY_AUDIO_MEASURE_CALIBRATION_ACTIVE = "audio_measure_calibration_active"
private const val KEY_MUSIC_SRC_BYPASS_MODE = "music_src_bypass_mode"
private const val KEY_AUDIO_BALANCE_LEVEL = "player_audio_balance_level"
private const val KEY_AUDIO_MEASURE_MIC_ID = "audio_measure_mic_id"
}
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ import com.miruplay.tv.model.SubtitleLanguagePreference
import com.miruplay.tv.model.ToneMappingCurvePreset
import com.miruplay.tv.model.ToneMappingRuleSet
import com.miruplay.tv.model.VideoRenderRuleKey
import com.miruplay.tv.model.AudioBalanceLevel
import com.miruplay.tv.model.AudioDspConfig
import com.miruplay.tv.model.AudioDspPreset
import kotlinx.coroutines.runBlocking
Expand Down Expand Up @@ -89,6 +90,16 @@ class PlaybackPreferencesManagerTest {
assertEquals(true, manager.perfMonitorEnabled)
}

@Test
fun `manager persists audio balance level default off`() = runBlocking {
assertEquals(AudioBalanceLevel.OFF, manager.getAudioBalanceLevel())

manager.setAudioBalanceLevel(AudioBalanceLevel.MEDIUM)

assertEquals(AudioBalanceLevel.MEDIUM, manager.getAudioBalanceLevel())
assertEquals(AudioBalanceLevel.MEDIUM, manager.audioBalanceLevel)
}

@Test
fun `manager persists normalized audio dsp config`() = runBlocking {
assertEquals(false, manager.getAudioDspConfig().enabled)
Expand Down
23 changes: 23 additions & 0 deletions docs/agents/pre-pr-checklist.md
Original file line number Diff line number Diff line change
Expand Up @@ -288,3 +288,26 @@ Cross-checks:
New failure class (section 1 candidate):

- **Offline-index-at-query-time** —— 离线 archive/索引文件在每次查询时全量解析 + 全排序,单测里几行 fixture 毫秒级全过,真机上 1GB 文件把 50MB 堆的 TV 盒子拖进 10 分钟 GC 泥潭。检查:任何“加载本地大文件再查询”的路径,必须验证真实量级文件在目标设备上的单次耗时;查询必须是流式 + 有界内存 + 可取消;耗时型预处理只做一次(构建期/下载期),绝不在查询热路径上

### Exo 音频平衡(响度 AGC)

Own checks(HK1 真机证据 + 单测):

- [真机] 冷启动无崩溃;test_local_path + test_scan_after_add 建库(AudioTest 1 文件);详情页播完回详情且标“已看”(进度记录正常)
- [真机] 设置 → 播放 → 音频平衡四档(关/低/中/高)渲染正常,默认关;切中/高档即时落盘 `player_audio_balance_level`,分档文案正确
- [真机] TV→WebAPI:`GET /api/settings/playback` 返回 `audioBalanceLevel=medium`;WebAPI→TV:`PUT` 高/低档后 prefs 与 TV 面板一致
- [真机] Exo 播放 AudioTest(balance=高/中/低):position 正常推进,无 error;播放中 `PUT low` 热更新后继续播到 EOF,无 error;全程 logcat 无 `AndroidRuntime:E` / `Player error` / `Fatal signal`
- [真机] IJK 后端播同片无崩溃(功能按设计不生效);MPV 内嵌在该盒子因 OpenGL 版本过旧起不来 VO(pre-existing 环境问题,与本 PR 无关),进程存活无崩溃
- [真机] 外挂 ASS 字幕渲染正常(`EXTERNAL ASS TRACK 1` 可见),`MiruLibass: Resolved libass API from packaged libmpv.so`,`Skipped malformed ASS` = 0
- 单测:`LoudnessBalanceProcessorTest`(静音/quiet boost/峰值限制/档位切换)、`PlaybackPreferencesManagerTest`、`MusicSrcBypassPipelineTest`(新处理器链路组合回归)、`WebControlSettingsRouteTest` 全过
- CI 修灯:补 `values-zh-rTW` / `values-zh-rHK` 10 条翻译(lint MissingTranslation),`SettingsViewModelTokenTest` 补 `audioBalanceLevel` mock stub(构造器新增读取导致严格 mock 抛 MockKException)

Cross-checks:

- 字幕/libass 单 `libc++_shared.so` 路径未动(`MiruLibass` 日志确认);DSP/音乐 SRC/进度/媒体会话等既有行为无改动(本 PR 只在 `DspRenderersFactory` 追加一个 Exo PCM 处理器 + 设置面字段)
- IJK/MPV 不接入平衡(设置文案已说明);WebUI 播放表单新增档位选择,浏览器侧未实测(本机无浏览器环境),TV 与 WebAPI 双向已验证

Not device-verified:

- 长片(>10 分钟)连续播放下的响度曲线主观听感 —— 手头 fixture 最长 2 分钟;算法分支由单测覆盖,真机只验证链路不断、无崩溃、无可闻爆音
- WebUI 浏览器端点选(无浏览器环境;TV/WebAPI 双向 parity 已覆盖同一 DTO)
Loading
Loading