From 91312faa1cd69b82085d3f0c8d05167c9460fe59 Mon Sep 17 00:00:00 2001 From: TapTap Date: Thu, 19 Nov 2026 16:38:21 +0000 Subject: [PATCH] feat: per-track loudness normalization and server audio info - 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 --- README.md | 5 +- charts/audiomanager/templates/deployment.yaml | 4 + charts/audiomanager/values.yaml | 7 ++ docs/design/mood-first.md | 29 ++++- .../win/taptap/musicmanager/Application.kt | 47 +++++++ .../win/taptap/musicmanager/api/ApiModels.kt | 15 +++ .../win/taptap/musicmanager/api/ApiRoutes.kt | 16 +++ .../taptap/musicmanager/config/AppConfig.kt | 15 +++ .../taptap/musicmanager/db/SongRepository.kt | 43 +++++++ .../win/taptap/musicmanager/db/Tables.kt | 2 + .../musicmanager/download/DownloadService.kt | 25 +++- .../musicmanager/media/LoudnessAnalyzer.kt | 118 ++++++++++++++++++ .../resources/db/migration/V10__loudness.sql | 8 ++ .../taptap/musicmanager/api/ApiRoutesTest.kt | 9 ++ .../media/LoudnessAnalyzerTest.kt | 53 ++++++++ 15 files changed, 387 insertions(+), 9 deletions(-) create mode 100644 src/main/kotlin/win/taptap/musicmanager/media/LoudnessAnalyzer.kt create mode 100644 src/main/resources/db/migration/V10__loudness.sql create mode 100644 src/test/kotlin/win/taptap/musicmanager/media/LoudnessAnalyzerTest.kt diff --git a/README.md b/README.md index ce35d07..71974da 100644 --- a/README.md +++ b/README.md @@ -98,6 +98,8 @@ Everything is environment variables: | `DEEZER_ARL` | empty | Deezer account cookie used for downloads (chart: `deezer.arl` or `deezer.existingSecret`) | | `DEEZER_QUALITY` | `0` | `0` = 128 kbps MP3, `1` = 320 kbps MP3 | | `DEEZER_API_BASE` | `https://api.deezer.com` | Public Deezer API base | +| `LOUDNESS_ENABLED` | `true` | Measure each file and expose a per-track gain | +| `LOUDNESS_TARGET_LUFS` | `-16` | Integrated loudness target (`-30` to `-5`) | ### `users.yaml` @@ -124,6 +126,7 @@ Media URLs may use `?token=` because HTML audio and images cannot send headers. | `POST` | `/auth/login` | `{username,password,deviceName,platform}` → token | | `POST` | `/auth/logout` | Revoke the current token | | `GET` | `/me` | Current user | +| `GET` | `/info` | Default source, Deezer quality and loudness settings | | `GET` | `/auth/devices` | List device tokens | | `DELETE` | `/auth/devices/{id}` | Revoke a device | @@ -133,7 +136,7 @@ Media URLs may use `?token=` because HTML audio and images cannot send headers. |---|---|---| | `GET` | `/moods` | List the user's moods | | `POST` | `/moods` | Create `{name,description,query,genres,source,collectionPercent,recommendationCount,refreshHours}` | -| `GET` | `/moods/{id}` | Mood detail: songs, active recommendations and download status | +| `GET` | `/moods/{id}` | Mood detail: songs, active recommendations, download status | | `PATCH` | `/moods/{id}` | Update options | | `DELETE` | `/moods/{id}` | Delete mood, detach songs and run GC | | `GET` | `/moods/{id}/preview` | Unpersisted radio preview | diff --git a/charts/audiomanager/templates/deployment.yaml b/charts/audiomanager/templates/deployment.yaml index 9a5c95f..a067fa0 100644 --- a/charts/audiomanager/templates/deployment.yaml +++ b/charts/audiomanager/templates/deployment.yaml @@ -61,6 +61,10 @@ spec: value: {{ .Values.deezer.quality | quote }} - name: DEEZER_API_BASE value: {{ .Values.deezer.apiBase | quote }} + - name: LOUDNESS_ENABLED + value: {{ .Values.loudness.enabled | quote }} + - name: LOUDNESS_TARGET_LUFS + value: {{ .Values.loudness.targetLufs | quote }} {{- if .Values.deezer.existingSecret }} - name: DEEZER_ARL valueFrom: diff --git a/charts/audiomanager/values.yaml b/charts/audiomanager/values.yaml index b4467b9..344f6bf 100644 --- a/charts/audiomanager/values.yaml +++ b/charts/audiomanager/values.yaml @@ -40,6 +40,13 @@ deezer: quality: 0 apiBase: https://api.deezer.com +# Per-track loudness normalization. New downloads are analyzed immediately and +# the existing library is backfilled gradually in the background. +loudness: + enabled: true + # -16 LUFS is the ReplayGain-style target; -14 matches most streaming services. + targetLufs: -16 + # The media root, database, cover cache and download temp dir all live here. data: persistence: diff --git a/docs/design/mood-first.md b/docs/design/mood-first.md index 257bb69..3973900 100644 --- a/docs/design/mood-first.md +++ b/docs/design/mood-first.md @@ -144,6 +144,11 @@ cases (auth, ownership, streaming, transcription, permissions). ids) or `"dz:"` for Deezer. - MP3 only (`yt-dlp -x --audio-format mp3 --audio-quality 0`), embedded metadata and thumbnail. +- Loudness: after indexing, ffmpeg measures `input_i`/`input_tp` with + `loudnorm`. `gain_db = min(target - input_i, truePeak - input_tp)` is stored; + clients apply it per track. New downloads are measured inline, the existing + library is backfilled one file at a time. `LOUDNESS_ENABLED` and + `LOUDNESS_TARGET_LUFS` control it. - The scanner walks `MEDIA_DIR`, extracts `(source, externalId)` from the top-level folder, reads tags/cover, and upserts the song. The downloader can call the same indexer for one file to avoid waiting for a full scan. @@ -724,16 +729,28 @@ Phases 1-8 are implemented in both repositories. ### Client -- Models, `ApiClient`, `AppCache` (version 3) and `AppStore` match the new API. -- Screens are `Moods | MoodDetail | Search | Downloads | Settings`. +- Models, `ApiClient`, `AppCache` (version 3 + separate client settings file) and `AppStore` match the new API. +- Screens are `Moods | MoodDetail | MoodSettings | Search | Downloads | Settings | + NowPlaying`. `LibraryScreen`, longform UI, seed management and global shuffle are gone. - Search supports a target-mood picker, a **Deezer / YouTube Music** source selector, downloaded badges and paste-a-URL. - Mood detail shows songs, add music, recommendation states (Add / Not - interested / Retry), next batch and the new options. -- Playback, sleep timer, queue editing, Android media session and device - downloads are unchanged apart from song-keyed covers. -- Tests: 17 client tests; desktop, Android debug and Wasm compile. + interested / Retry). The preview/next-batch section and the inline settings + form are gone: mood settings (including source and the offline switch) live on + a dedicated screen, with Delete at the bottom. +- **0.4.0 playback**: Android's `MediaSessionService` owns a Media3 timeline, + so notification/headset next/back and gapless playback use real media items. + Previous keeps the 2 s restart rule. The app mirrors the index, appends the + next server batch and still reports skipped/completed events. +- **Audio**: server gain is applied by an Android PCM `AudioProcessor` (boost and + attenuation) and by the desktop mixer; the full-screen player shows source and + bitrate. Android has an optional 0–8 s fade between tracks. +- **Offline moods**: a per-mood switch downloads every song and keeps new + additions in sync on unmetered networks, three at a time. +- **Sleep timer** adds "Finish this track"; the full-screen player shows large + artwork, transport, add-to-mood, queue and Up next. +- Tests: 21 client tests; desktop, Android debug and Wasm compile. ### Known follow-ups diff --git a/src/main/kotlin/win/taptap/musicmanager/Application.kt b/src/main/kotlin/win/taptap/musicmanager/Application.kt index a8e1bb9..f730557 100644 --- a/src/main/kotlin/win/taptap/musicmanager/Application.kt +++ b/src/main/kotlin/win/taptap/musicmanager/Application.kt @@ -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() }, ) diff --git a/src/main/kotlin/win/taptap/musicmanager/api/ApiModels.kt b/src/main/kotlin/win/taptap/musicmanager/api/ApiModels.kt index fcddacf..48e17b4 100644 --- a/src/main/kotlin/win/taptap/musicmanager/api/ApiModels.kt +++ b/src/main/kotlin/win/taptap/musicmanager/api/ApiModels.kt @@ -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 diff --git a/src/main/kotlin/win/taptap/musicmanager/api/ApiRoutes.kt b/src/main/kotlin/win/taptap/musicmanager/api/ApiRoutes.kt index e073507..3116744 100644 --- a/src/main/kotlin/win/taptap/musicmanager/api/ApiRoutes.kt +++ b/src/main/kotlin/win/taptap/musicmanager/api/ApiRoutes.kt @@ -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()) diff --git a/src/main/kotlin/win/taptap/musicmanager/config/AppConfig.kt b/src/main/kotlin/win/taptap/musicmanager/config/AppConfig.kt index 27837ec..be6becd 100644 --- a/src/main/kotlin/win/taptap/musicmanager/config/AppConfig.kt +++ b/src/main/kotlin/win/taptap/musicmanager/config/AppConfig.kt @@ -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())), ) diff --git a/src/main/kotlin/win/taptap/musicmanager/db/SongRepository.kt b/src/main/kotlin/win/taptap/musicmanager/db/SongRepository.kt index 82bde41..5a42175 100644 --- a/src/main/kotlin/win/taptap/musicmanager/db/SongRepository.kt +++ b/src/main/kotlin/win/taptap/musicmanager/db/SongRepository.kt @@ -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 = 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 diff --git a/src/main/kotlin/win/taptap/musicmanager/db/Tables.kt b/src/main/kotlin/win/taptap/musicmanager/db/Tables.kt index 594fc05..7ec60ca 100644 --- a/src/main/kotlin/win/taptap/musicmanager/db/Tables.kt +++ b/src/main/kotlin/win/taptap/musicmanager/db/Tables.kt @@ -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) diff --git a/src/main/kotlin/win/taptap/musicmanager/download/DownloadService.kt b/src/main/kotlin/win/taptap/musicmanager/download/DownloadService.kt index 50ddfe2..5b437fc 100644 --- a/src/main/kotlin/win/taptap/musicmanager/download/DownloadService.kt +++ b/src/main/kotlin/win/taptap/musicmanager/download/DownloadService.kt @@ -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() } diff --git a/src/main/kotlin/win/taptap/musicmanager/media/LoudnessAnalyzer.kt b/src/main/kotlin/win/taptap/musicmanager/media/LoudnessAnalyzer.kt new file mode 100644 index 0000000..65db163 --- /dev/null +++ b/src/main/kotlin/win/taptap/musicmanager/media/LoudnessAnalyzer.kt @@ -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) + } + } +} diff --git a/src/main/resources/db/migration/V10__loudness.sql b/src/main/resources/db/migration/V10__loudness.sql new file mode 100644 index 0000000..f48f077 --- /dev/null +++ b/src/main/resources/db/migration/V10__loudness.sql @@ -0,0 +1,8 @@ +-- Per-track loudness, measured once per file with ffmpeg's EBU R128 filter. +-- +-- `loudness_lufs` is the integrated loudness; `gain_db` is the attenuation or +-- boost the clients apply so tracks from Deezer and YouTube sound equally loud. +-- Both stay NULL for files that have not been analyzed yet; the backfill worker +-- picks those up without blocking downloads. +ALTER TABLE songs ADD COLUMN loudness_lufs REAL; +ALTER TABLE songs ADD COLUMN gain_db REAL; diff --git a/src/test/kotlin/win/taptap/musicmanager/api/ApiRoutesTest.kt b/src/test/kotlin/win/taptap/musicmanager/api/ApiRoutesTest.kt index 425bf46..fd553ca 100644 --- a/src/test/kotlin/win/taptap/musicmanager/api/ApiRoutesTest.kt +++ b/src/test/kotlin/win/taptap/musicmanager/api/ApiRoutesTest.kt @@ -89,6 +89,12 @@ class ApiRoutesTest { val me = parse(client.get("/api/v1/me") { bearer(token) }.bodyAsText()) assertEquals("alice", me.string("name")) + val info = parse(client.get("/api/v1/info") { bearer(token) }.bodyAsText()) + assertEquals("deezer", info.string("defaultSource")) + assertEquals(0, info["deezerQuality"]!!.jsonPrimitive.int) + assertTrue(info["loudnessEnabled"]!!.jsonPrimitive.content.toBoolean()) + assertEquals("-16.0", info["loudnessTargetLufs"]!!.jsonPrimitive.content) + val malformed = client.post("/api/v1/moods") { bearer(token) contentType(ContentType.Application.Json) @@ -635,6 +641,9 @@ class ApiRoutesTest { mediaStore = seed.media, gc = seed.gc, defaultSource = defaultSource, + deezerQuality = 0, + loudnessEnabled = true, + loudnessTargetLufs = -16.0, startScan = { false }, scanStatus = { ScanStatus(false, 0) }, ) diff --git a/src/test/kotlin/win/taptap/musicmanager/media/LoudnessAnalyzerTest.kt b/src/test/kotlin/win/taptap/musicmanager/media/LoudnessAnalyzerTest.kt new file mode 100644 index 0000000..eb6eaa1 --- /dev/null +++ b/src/test/kotlin/win/taptap/musicmanager/media/LoudnessAnalyzerTest.kt @@ -0,0 +1,53 @@ +package win.taptap.musicmanager.media + +import kotlin.test.Test +import kotlin.test.assertEquals +import kotlin.test.assertNull + +class LoudnessAnalyzerTest { + + @Test + fun `parses the loudnorm summary`() { + val output = """ + [Parsed_loudnorm_0 @ 0x1] + { + "input_i" : "-9.42", + "input_tp" : "-0.21", + "input_lra" : "6.10", + "output_i" : "-16.00" + } + """.trimIndent() + + val measurement = LoudnessAnalyzer.parse(output) + + assertEquals(-9.42, measurement?.lufs) + assertEquals(-0.21, measurement?.truePeakDb) + } + + @Test + fun `gain targets minus sixteen lufs`() { + val analyzer = LoudnessAnalyzer(targetLufs = -16.0, truePeakDb = -1.5) + + assertEquals(-6.6, analyzer.gainFor(LoudnessAnalyzer.Measurement(-9.4, -3.0))) + } + + @Test + fun `gain is limited by the true peak ceiling`() { + val analyzer = LoudnessAnalyzer(targetLufs = -16.0, truePeakDb = -1.5) + + // The loudness target would need +6 dB, but the peak only allows +1.5. + assertEquals(1.5, analyzer.gainFor(LoudnessAnalyzer.Measurement(-22.0, -3.0))) + } + + @Test + fun `silence is left alone`() { + val analyzer = LoudnessAnalyzer() + + assertEquals(0.0, analyzer.gainFor(LoudnessAnalyzer.Measurement(-70.0, -70.0))) + } + + @Test + fun `missing summary is ignored`() { + assertNull(LoudnessAnalyzer.parse("ffmpeg: no such file")) + } +}