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
This commit is contained in:
1 parent
6763a83b03
commit
91312faa1c
15 files changed
+387
-9
No files matched your search
@@ -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 |
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -144,6 +144,11 @@ cases (auth, ownership, streaming, transcription, permissions).
|
||||
ids) or `"dz:<trackId>"` 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
|
||||
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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;
|
||||
@@ -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) },
|
||||
)
|
||||
|
||||
@@ -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"))
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user