feat: per-track loudness normalization and server audio info
CI / chart (push) Successful in 3s
CI / test (push) Successful in 2m6s
CI / chart-push (push) Successful in 3s
CI / image (push) Successful in 3m31s

- measure downloads with ffmpeg's EBU R128 filter and store gain/LUFS
- backfill the existing library one file at a time
- expose gain on songs and a /info endpoint for source quality
- chart knobs LOUDNESS_ENABLED and LOUDNESS_TARGET_LUFS
This commit is contained in:
TapTap committed 2026-11-19 16:38:21 +00:00
1 parent 6763a83b03
commit 91312faa1c
15 files changed
+387 -9

No files matched your search

@@ -41,6 +41,7 @@ import win.taptap.musicmanager.config.UsersConfig
import win.taptap.musicmanager.db.ConfigRepository
import win.taptap.musicmanager.db.DatabaseFactory
import win.taptap.musicmanager.db.MoodRepository
import win.taptap.musicmanager.db.SongRepository
import win.taptap.musicmanager.discovery.DeezerSearch
import win.taptap.musicmanager.discovery.DiscoveryService
import win.taptap.musicmanager.discovery.MusicCatalogs
@@ -51,6 +52,7 @@ import win.taptap.musicmanager.download.DownloadService
import win.taptap.musicmanager.download.SourceDownloaders
import win.taptap.musicmanager.download.YtDlpDownloader
import win.taptap.musicmanager.source.MusicSource
import win.taptap.musicmanager.media.LoudnessAnalyzer
import win.taptap.musicmanager.media.MediaGcService
import win.taptap.musicmanager.media.MediaStore
import win.taptap.musicmanager.radio.RadioService
@@ -78,6 +80,14 @@ fun main() {
val mediaStore = MediaStore(config.mediaDir)
val indexer = SongIndexer(mediaStore, coverArtService)
val gc = MediaGcService(mediaStore, coverArtService)
val loudnessAnalyzer = if (config.loudnessEnabled) {
LoudnessAnalyzer(
ffmpegPath = config.ffmpegPath,
targetLufs = config.loudnessTargetLufs,
).takeIf { it.isAvailable() }
} else {
null
}
val transcoder = FfmpegTranscoder(config.ffmpegPath)
val radioService = RadioService()
val catalogs = MusicCatalogs(
@@ -104,6 +114,7 @@ fun main() {
mediaStore = mediaStore,
indexer = indexer,
gc = gc,
loudnessAnalyzer = loudnessAnalyzer,
tempDir = config.downloadDir,
onSongAttached = topUpService::trigger,
)
@@ -140,6 +151,39 @@ fun main() {
}
}
// Normalize the existing library gradually; one file at a time keeps
// download and streaming work responsive.
if (loudnessAnalyzer != null) {
applicationScope.launch(Dispatchers.IO) {
delay(TimeUnit.MINUTES.toMillis(2))
while (isActive) {
val pending = runCatching { SongRepository.pendingLoudness(1) }
.onFailure { log.warn("Loudness backfill query failed", it) }
.getOrDefault(emptyList())
val song = pending.firstOrNull()
if (song == null) {
delay(TimeUnit.MINUTES.toMillis(30))
continue
}
val file = mediaStore.file(song)
if (file == null || !Files.isRegularFile(file)) {
// Keep the row out of the retry loop; a later upsert
// from the scanner will reset it if the file returns.
SongRepository.updateLoudness(song.id, -70.0, 0.0)
} else {
val updated = loudnessAnalyzer.analyzeAndStore(song, file)
if (updated.gainDb == null) {
// Unreadable/corrupt file: record a neutral gain so
// the backfill does not retry it every second.
log.warn("Could not analyze {}; leaving it unnormalized", file)
SongRepository.updateLoudness(song.id, -70.0, 0.0)
}
}
delay(1_000)
}
}
}
// Delete files that no mood, recommendation or open session references.
applicationScope.launch(Dispatchers.IO) {
delay(TimeUnit.MINUTES.toMillis(10))
@@ -224,6 +268,9 @@ fun main() {
mediaStore = mediaStore,
gc = gc,
defaultSource = config.defaultSource,
deezerQuality = config.deezerQuality,
loudnessEnabled = config.loudnessEnabled && loudnessAnalyzer != null,
loudnessTargetLufs = config.loudnessTargetLufs,
startScan = { scanner.start(applicationScope) },
scanStatus = { scanner.status() },
)
@@ -44,6 +44,15 @@ data class DeviceDto(
val current: Boolean,
)
@Serializable
data class ServerInfoDto(
val defaultSource: String,
/** 0 = 128 kbps MP3, 1 = 320 kbps MP3 for Deezer downloads. */
val deezerQuality: Int,
val loudnessEnabled: Boolean,
val loudnessTargetLufs: Double,
)
@Serializable
data class SongDto(
val id: String,
@@ -57,6 +66,10 @@ data class SongDto(
val size: Long,
val suffix: String,
val thumbnail: String? = null,
/** Measured integrated loudness; null when the server has not analyzed it yet. */
val loudnessLufs: Double? = null,
/** Gain in dB the client applies to reach the server's target loudness. */
val gainDb: Double? = null,
)
fun SongRecord.toDto(): SongDto = SongDto(
@@ -71,6 +84,8 @@ fun SongRecord.toDto(): SongDto = SongDto(
size = size,
suffix = suffix,
thumbnail = thumbnail,
loudnessLufs = loudnessLufs,
gainDb = gainDb,
)
@Serializable
@@ -37,6 +37,9 @@ fun Route.apiRoutes(
mediaStore: MediaStore,
gc: MediaGcService,
defaultSource: String,
deezerQuality: Int,
loudnessEnabled: Boolean,
loudnessTargetLufs: Double,
startScan: () -> Boolean,
scanStatus: () -> ScanStatus,
) {
@@ -77,6 +80,19 @@ fun Route.apiRoutes(
call.respond(user.toDto())
}
/** Source and audio settings the client cannot infer from a song. */
get("/info") {
call.requireApiUser(users)
call.respond(
ServerInfoDto(
defaultSource = defaultSource,
deezerQuality = deezerQuality,
loudnessEnabled = loudnessEnabled,
loudnessTargetLufs = loudnessTargetLufs,
),
)
}
post("/auth/logout") {
call.requireApiUser(users)
ApiTokenRepository.revokeRaw(call.bearerToken().orEmpty())
@@ -22,6 +22,10 @@ data class AppConfig(
/** 0 = 128 kbps MP3, 1 = 320 kbps MP3. FLAC is not stored. */
val deezerQuality: Int = 0,
val deezerApiBase: String = "https://api.deezer.com",
/** Analyze downloads and backfill the library to a common loudness. */
val loudnessEnabled: Boolean = true,
/** Integrated loudness target; -16 LUFS is the ReplayGain-style value. */
val loudnessTargetLufs: Double = -16.0,
val mediaDir: Path = dataDir.resolve("media"),
val downloadDir: Path = dataDir.resolve("downloads"),
) {
@@ -50,6 +54,15 @@ data class AppConfig(
"DEEZER_QUALITY must be 0 (128 kbps) or 1 (320 kbps), got: $deezerQuality"
}
val loudnessEnabled = value("LOUDNESS_ENABLED", "true").toBooleanStrictOrNull()
?: throw IllegalArgumentException("LOUDNESS_ENABLED must be true or false")
val rawTarget = value("LOUDNESS_TARGET_LUFS", "-16")
val loudnessTargetLufs = rawTarget.toDoubleOrNull()
?: throw IllegalArgumentException("LOUDNESS_TARGET_LUFS must be a number, got: $rawTarget")
require(loudnessTargetLufs in -30.0..-5.0) {
"LOUDNESS_TARGET_LUFS must be between -30 and -5, got: $loudnessTargetLufs"
}
return AppConfig(
port = port,
dataDir = dataDir,
@@ -61,6 +74,8 @@ data class AppConfig(
deezerArl = env["DEEZER_ARL"]?.takeIf { it.isNotBlank() },
deezerQuality = deezerQuality,
deezerApiBase = value("DEEZER_API_BASE", "https://api.deezer.com"),
loudnessEnabled = loudnessEnabled,
loudnessTargetLufs = loudnessTargetLufs,
mediaDir = Path.of(value("MEDIA_DIR", dataDir.resolve("media").toString())),
downloadDir = Path.of(value("DOWNLOAD_DIR", dataDir.resolve("downloads").toString())),
)
@@ -30,6 +30,10 @@ data class SongRecord(
val thumbnail: String?,
val createdAt: String,
val updatedAt: String,
/** Integrated loudness in LUFS; null until the analyzer has run. */
val loudnessLufs: Double? = null,
/** Gain in dB applied by clients to reach the server's loudness target. */
val gainDb: Double? = null,
)
data class SongUpsert(
@@ -81,6 +85,8 @@ object SongRepository {
it[relativePath] = input.relativePath
it[fileMtime] = input.fileMtime
it[thumbnail] = input.thumbnail
it[loudnessLufs] = null
it[gainDb] = null
it[createdAt] = now
it[updatedAt] = now
}
@@ -105,6 +111,8 @@ object SongRepository {
} else {
val current = existing.toRecord()
val id = current.id
val audioChanged = current.fileMtime != input.fileMtime ||
current.relativePath != input.relativePath
SongsTable.update({ SongsTable.id eq id }) {
it[title] = input.title
it[artist] = input.artist
@@ -117,6 +125,10 @@ object SongRepository {
it[relativePath] = input.relativePath
it[fileMtime] = input.fileMtime
it[thumbnail] = input.thumbnail ?: current.thumbnail
if (audioChanged) {
it[loudnessLufs] = null
it[gainDb] = null
}
it[updatedAt] = now
}
current.copy(
@@ -132,6 +144,8 @@ object SongRepository {
fileMtime = input.fileMtime,
thumbnail = input.thumbnail ?: current.thumbnail,
updatedAt = now,
loudnessLufs = if (audioChanged) null else current.loudnessLufs,
gainDb = if (audioChanged) null else current.gainDb,
)
}
}
@@ -173,6 +187,33 @@ object SongRepository {
fun count(): Long = transaction { SongsTable.selectAll().count() }
/** Files still waiting for loudness analysis, oldest first. */
fun pendingLoudness(limit: Int = 1): List<SongRecord> = transaction {
SongsTable.selectAll()
.where { SongsTable.loudnessLufs.isNull() }
.orderBy(SongsTable.createdAt to SortOrder.ASC)
.limit(limit)
.map { it.toRecord() }
}
fun updateLoudness(id: String, loudnessLufs: Double, gainDb: Double): Boolean = transaction {
SongsTable.update({ SongsTable.id eq id }) {
it[this.loudnessLufs] = loudnessLufs
it[this.gainDb] = gainDb
it[updatedAt] = Instant.now().toString()
} > 0
}
/** Clears the measurement so the backfill analyzes a replaced file again. */
fun clearLoudness(id: String) {
transaction {
SongsTable.update({ SongsTable.id eq id }) {
it[loudnessLufs] = null
it[gainDb] = null
}
}
}
fun delete(id: String): Boolean = transaction {
SongsTable.deleteWhere { SongsTable.id eq id } > 0
}
@@ -194,6 +235,8 @@ object SongRepository {
thumbnail = this[SongsTable.thumbnail],
createdAt = this[SongsTable.createdAt],
updatedAt = this[SongsTable.updatedAt],
loudnessLufs = this[SongsTable.loudnessLufs],
gainDb = this[SongsTable.gainDb],
)
private const val SQL_CHUNK = 500
@@ -35,6 +35,8 @@ object SongsTable : Table("songs") {
val relativePath = text("relative_path")
val fileMtime = long("file_mtime").default(0)
val thumbnail = text("thumbnail").nullable()
val loudnessLufs = double("loudness_lufs").nullable()
val gainDb = double("gain_db").nullable()
val createdAt = varchar("created_at", 40)
val updatedAt = varchar("updated_at", 40)
@@ -13,6 +13,7 @@ import win.taptap.musicmanager.db.MoodRepository
import win.taptap.musicmanager.db.RecommendationCompletion
import win.taptap.musicmanager.db.SongRecord
import win.taptap.musicmanager.db.SongRepository
import win.taptap.musicmanager.media.LoudnessAnalyzer
import win.taptap.musicmanager.media.MediaGcService
import win.taptap.musicmanager.media.MediaStore
import win.taptap.musicmanager.scanner.Mp3TagExtractor
@@ -35,6 +36,8 @@ class DownloadService(
private val indexer: SongIndexer,
private val gc: MediaGcService,
private val tagExtractor: Mp3TagExtractor = Mp3TagExtractor(),
/** Null disables per-track normalization (for example when ffmpeg is absent). */
private val loudnessAnalyzer: LoudnessAnalyzer? = null,
private val tempDir: Path,
private val maxAttempts: Int = 3,
/**
@@ -82,7 +85,16 @@ class DownloadService(
val existing = SongRepository.byExternalId(job.source, job.externalId)
val existingFile = existing?.let { mediaStore.file(it) }
if (existing != null && existingFile != null && Files.isRegularFile(existingFile)) {
finish(job, existing)
// The shared file may predate loudness analysis; measure it before
// finishing so this job's track is normalized too.
val analyzed = loudnessAnalyzer
?.let { analyzer ->
runCatching { analyzer.analyzeAndStore(existing, existingFile) }
.onFailure { log.warn("Loudness analysis failed for {}", existingFile, it) }
.getOrDefault(existing)
}
?: existing
finish(job, analyzed)
return
}
@@ -112,8 +124,17 @@ class DownloadService(
.forEach { runCatching { Files.deleteIfExists(it) } }
}
val song = indexer.index(job.source, job.externalId, target)
val indexed = indexer.index(job.source, job.externalId, target)
?: throw IllegalStateException("Downloaded file could not be indexed")
// Analyze before finishing so the first play already has a gain.
// A failed measurement must never fail the download.
val song = loudnessAnalyzer
?.let { analyzer ->
runCatching { analyzer.analyzeAndStore(indexed, target) }
.onFailure { log.warn("Loudness analysis failed for {}", target, it) }
.getOrDefault(indexed)
}
?: indexed
finish(job, song)
} finally {
runCatching { working.toFile().deleteRecursively() }
@@ -0,0 +1,118 @@
package win.taptap.musicmanager.media
import java.nio.file.Files
import java.nio.file.Path
import java.util.concurrent.TimeUnit
import org.slf4j.LoggerFactory
import win.taptap.musicmanager.db.SongRecord
import win.taptap.musicmanager.db.SongRepository
/**
* Measures a track's integrated loudness with ffmpeg's EBU R128 filter and
* stores the gain clients need to reach a common target.
*
* The analysis is one ffmpeg pass per file. It runs in the download worker for
* new tracks and in a low-priority backfill loop for the existing library, so a
* large collection is normalized gradually instead of blocking playback.
*/
class LoudnessAnalyzer(
private val ffmpegPath: String = "ffmpeg",
private val targetLufs: Double = -16.0,
private val truePeakDb: Double = -1.5,
) {
private val log = LoggerFactory.getLogger(LoudnessAnalyzer::class.java)
@Volatile private var available: Boolean? = null
data class Measurement(val lufs: Double, val truePeakDb: Double)
/** Returns null when the file cannot be analyzed; never throws. */
fun analyze(file: Path): Measurement? {
if (!Files.isRegularFile(file) || !isAvailable()) return null
return runCatching { measure(file) }
.onFailure { log.warn("Loudness analysis failed for {}: {}", file, it.message) }
.getOrNull()
}
/** Measures and persists the result, returning the updated row. */
fun analyzeAndStore(song: SongRecord, file: Path): SongRecord {
val measurement = analyze(file) ?: return song
val gain = gainFor(measurement)
SongRepository.updateLoudness(song.id, measurement.lufs, gain)
return song.copy(loudnessLufs = measurement.lufs, gainDb = gain)
}
fun gainFor(measurement: Measurement): Double {
if (measurement.lufs <= SILENCE_LUFS) return 0.0
val target = targetLufs - measurement.lufs
// Never let a boost push the measured true peak above the ceiling.
val peakLimited = truePeakDb - measurement.truePeakDb
return minOf(target, peakLimited).coerceIn(MIN_GAIN_DB, MAX_GAIN_DB)
.let { kotlin.math.round(it * 10.0) / 10.0 }
}
fun isAvailable(): Boolean {
val cached = available
if (cached != null) return cached
val result = runCatching {
val process = ProcessBuilder(ffmpegPath, "-version")
.redirectErrorStream(true)
.start()
process.inputStream.readBytes()
process.waitFor(VERSION_TIMEOUT_SECONDS, TimeUnit.SECONDS) && process.exitValue() == 0
}.getOrDefault(false)
available = result
if (!result) {
log.warn(
"ffmpeg is not available at '{}': loudness normalization is disabled",
ffmpegPath,
)
}
return result
}
private fun measure(file: Path): Measurement? {
val process = ProcessBuilder(
ffmpegPath,
"-hide_banner",
"-nostdin",
"-i",
file.toString(),
"-af",
"loudnorm=I=$targetLufs:TP=$truePeakDb:LRA=11:print_format=json",
"-f",
"null",
"-",
)
.redirectErrorStream(true)
.start()
val output = process.inputStream.bufferedReader().use { it.readText() }
if (!process.waitFor(ANALYZE_TIMEOUT_SECONDS, TimeUnit.SECONDS)) {
process.destroyForcibly()
return null
}
if (process.exitValue() != 0) return null
return parse(output)
}
companion object {
private const val SILENCE_LUFS = -70.0
private const val MIN_GAIN_DB = -30.0
private const val MAX_GAIN_DB = 12.0
private const val VERSION_TIMEOUT_SECONDS = 5L
private const val ANALYZE_TIMEOUT_SECONDS = 180L
private val INTEGRATED = Regex("\"input_i\"\\s*:\\s*\"([^\"]+)\"")
private val TRUE_PEAK = Regex("\"input_tp\"\\s*:\\s*\"([^\"]+)\"")
/** Parses the JSON block loudnorm appends to ffmpeg's stderr. */
fun parse(output: String): Measurement? {
val lufsText = INTEGRATED.find(output)?.groupValues?.get(1) ?: return null
val peakText = TRUE_PEAK.find(output)?.groupValues?.get(1) ?: return null
val lufs = lufsText.toDoubleOrNull() ?: SILENCE_LUFS
val peak = peakText.toDoubleOrNull() ?: 0.0
return Measurement(lufs = lufs, truePeakDb = peak)
}
}
}