feat: rebuild AudioManager around downloadable moods
CI / chart (push) Successful in 3s
CI / test (push) Successful in 2m2s
CI / chart-push (push) Successful in 4s
CI / image (push) Successful in 3m20s

- V8 wipe migration and the shared song store keyed by YouTube video id
- media store, indexer, downloader, recommendation top-up and refcounted GC
- mood songs plus the recommendation lifecycle and mixed radio pools
- new search, song and recommendation API; remove library/longform/seed routes
- chart PVC/media env, docs, Nix, README and an end-to-end smoke test
This commit is contained in:
TapTap committed 2026-11-15 21:37:39 +00:00
1 parent 50d8b6c580
commit 824eb36dd2
59 files changed
+3838 -5276

No files matched your search

@@ -6,10 +6,7 @@ import java.util.UUID
import kotlin.math.max
import kotlin.random.Random
import org.slf4j.LoggerFactory
import win.taptap.musicmanager.api.musicFolderIds
import win.taptap.musicmanager.config.LibraryConfig
import win.taptap.musicmanager.config.UserAccount
import win.taptap.musicmanager.db.LibraryRepository
import win.taptap.musicmanager.db.MoodRecord
import win.taptap.musicmanager.db.MoodRepository
import win.taptap.musicmanager.db.PlaybackSessionRecord
@@ -24,11 +21,11 @@ data class StartedSession(
/**
* Server-driven mood radio.
*
* A batch is a weighted sample of the mood's world: seeds are guaranteed
* candidates, related genres/artists and free-text matches shape the pool, and
* per-user completions/skips nudge the ranking. Tracks already queued in the
* session are never repeated. The client asks for more whenever its buffer is
* low, so the queue is always generated with the latest signals.
* A batch mixes the mood's permanent collection with its ready recommendation
* songs. Every slot rolls `collectionPercent` independently, so a 70% mood gets
* roughly seven collection tracks in ten. Per-user completions/skips nudge the
* ranking. Tracks already queued in the session are never repeated until the
* pool is exhausted; then the least-recently-heard tracks replay.
*/
class RadioService(
private val random: Random = Random.Default,
@@ -36,14 +33,9 @@ class RadioService(
private val log = LoggerFactory.getLogger(RadioService::class.java)
fun start(
mood: MoodRecord,
user: UserAccount,
library: LibraryConfig,
limit: Int,
): StartedSession {
fun start(mood: MoodRecord, user: UserAccount, limit: Int): StartedSession {
val session = RadioRepository.createSession(user.name, mood.id, UUID.randomUUID().toString())
val songs = generate(mood, user, library, session.id, emptySet(), limit, persist = true)
val songs = generate(mood, user, session.id, emptySet(), limit, persist = true)
log.info("Radio session {} started for mood {} with {} tracks", session.id, mood.name, songs.size)
return StartedSession(session, songs)
}
@@ -51,34 +43,31 @@ class RadioService(
fun next(
mood: MoodRecord,
user: UserAccount,
library: LibraryConfig,
sessionId: String,
excluded: Set<String>,
limit: Int,
): List<SongRecord> =
generate(mood, user, library, sessionId, excluded, limit, persist = true)
): List<SongRecord> = generate(mood, user, sessionId, excluded, limit, persist = true)
/** Queue preview for the mood screen; nothing is persisted. */
fun preview(
mood: MoodRecord,
user: UserAccount,
library: LibraryConfig,
limit: Int,
): List<SongRecord> =
generate(mood, user, library, sessionId = null, excluded = emptySet(), limit, persist = false)
fun preview(mood: MoodRecord, user: UserAccount, limit: Int): List<SongRecord> =
generate(mood, user, sessionId = null, excluded = emptySet(), limit, persist = false)
private fun generate(
mood: MoodRecord,
user: UserAccount,
library: LibraryConfig,
sessionId: String?,
excluded: Set<String>,
requestedLimit: Int,
persist: Boolean,
): List<SongRecord> {
val limit = requestedLimit.coerceIn(1, 50)
val folders = user.musicFolderIds(library)
if (folders.isEmpty()) return emptyList()
val collection = MoodRepository.songRecords(mood.id)
// A mood can only play once it has at least one permanent song.
if (collection.isEmpty()) return emptyList()
val collectionIds = collection.map { it.id }.toSet()
val recommendations = MoodRepository.readySongs(mood.id)
.filterNot { it.id in collectionIds }
val sessionSongs = if (sessionId != null && persist) {
RadioRepository.queuedSongIds(sessionId)
@@ -86,180 +75,111 @@ class RadioService(
emptySet()
}
val skip = sessionSongs + excluded
val seeds = LibraryRepository.songsByIds(
MoodRepository.seedSongIds(mood.id),
folders,
user.name,
)
val seedIds = seeds.map { it.id }.toSet()
val seedGenres = (seeds.flatMap { it.genres } + mood.genres)
.map { it.trim() }
.filter { it.isNotEmpty() }
.distinctBy { it.lowercase() }
val seedArtistIds = seeds.mapNotNull { it.artistId }.distinct()
val query = mood.query?.trim()?.takeIf { it.isNotEmpty() }
val candidates = LinkedHashMap<String, SongRecord>()
seeds.forEach { candidates[it.id] = it }
if (seedGenres.isNotEmpty()) {
LibraryRepository.songsByGenres(seedGenres, POOL_LIMIT, folders, user.name)
.forEach { candidates[it.id] = it }
}
if (seedArtistIds.isNotEmpty()) {
LibraryRepository.songsByArtists(seedArtistIds, POOL_LIMIT, folders, user.name)
.forEach { candidates[it.id] = it }
}
if (query != null) {
LibraryRepository.searchSongs(query, POOL_LIMIT, 0, folders, user.name)
.forEach { candidates[it.id] = it }
}
// A mood with no seeds and no filters still needs a starting point.
LibraryRepository.randomSongs(
size = POOL_LIMIT,
genre = null,
fromYear = null,
toYear = null,
folderIds = folders,
userName = user.name,
).forEach { candidates[it.id] = it }
candidates.keys.removeAll(skip)
// Small libraries can exhaust the mood. Replay tracks the session already
// heard instead of returning silence, but never repeat the current batch.
if (candidates.size < limit) {
refill(candidates, folders, user.name, excluded, sessionSongs, emptySet(), limit)
}
val recent = RadioRepository.recentSongIds(
user.name,
Instant.now().minus(RECENT_DAYS, ChronoUnit.DAYS),
)
// In a normal-sized library, skip songs from the last week entirely.
// Small libraries keep them as low-scored fallbacks instead of going silent.
if (candidates.size > limit * 3) {
candidates.keys.removeAll(recent - seedIds)
}
// Pruning can empty the pool even though the library has songs. Prefer
// non-recent tracks, then fall back to replay if the library is tiny.
if (candidates.size < limit) {
refill(candidates, folders, user.name, excluded, sessionSongs, recent, limit)
if (candidates.size < limit) {
refill(candidates, folders, user.name, excluded, emptySet(), emptySet(), limit)
}
}
val affinity = RadioRepository.affinity(
user.name,
(collection.map { it.id } + recommendations.map { it.id }).toSet(),
)
val affinity = RadioRepository.affinity(user.name, candidates.keys)
val scored = candidates.values.map { song ->
song to scoreCandidate(
song = song,
seedIds = seedIds,
seedGenres = seedGenres,
seedArtistIds = seedArtistIds,
query = query,
affinity = affinity[song.id]?.score ?: 0.0,
recent = recent,
jitter = random.nextDouble(0.0, 2.0),
val freshCollection = collection.filterNot { it.id in skip }
val freshRecommendations = recommendations.filterNot { it.id in skip }
val picks = pickMixed(
collectionScored = score(freshCollection, affinity, recent, heard = false),
recommendationScored = score(freshRecommendations, affinity, recent, heard = false),
limit = limit,
collectionPercent = mood.collectionPercent,
).toMutableList()
// Small moods exhaust their pool quickly. Replay the least-recently
// queued tracks instead of returning silence, but never duplicate
// within one batch.
if (picks.size < limit) {
val pickedIds = picks.map { it.id }.toSet()
val heardCollection = collection.filter { it.id in skip && it.id !in pickedIds }
val heardRecommendations = recommendations.filter { it.id in skip && it.id !in pickedIds }
picks += pickMixed(
collectionScored = score(heardCollection, affinity, recent, heard = true),
recommendationScored = score(heardRecommendations, affinity, recent, heard = true),
limit = limit - picks.size,
collectionPercent = mood.collectionPercent,
)
}
val seedScored = scored.filter { (song, _) -> song.id in seedIds }
val recommendationScored = scored.filter { (song, _) -> song.id !in seedIds }
val picks = pickMixed(
seedScored = seedScored,
recommendationScored = recommendationScored,
limit = limit,
seedPercent = mood.seedPercent,
)
if (persist && sessionId != null && picks.isNotEmpty()) {
RadioRepository.append(sessionId, picks.map { it.id })
}
return picks
}
private fun refill(
candidates: LinkedHashMap<String, SongRecord>,
folders: Set<Int>,
userName: String,
excluded: Set<String>,
avoidSession: Set<String>,
avoidRecent: Set<String>,
limit: Int,
) {
LibraryRepository.randomSongs(
size = max(limit * 10, 200),
genre = null,
fromYear = null,
toYear = null,
folderIds = folders,
userName = userName,
).forEach { song ->
if (song.id !in excluded && song.id !in avoidSession && song.id !in avoidRecent) {
candidates.putIfAbsent(song.id, song)
}
}
private fun score(
songs: List<SongRecord>,
affinity: Map<String, win.taptap.musicmanager.db.AffinityRecord>,
recent: Set<String>,
heard: Boolean,
): List<Pair<SongRecord, Double>> = songs.map { song ->
song to scoreCandidate(
song = song,
affinity = affinity[song.id]?.score ?: 0.0,
recent = song.id in recent,
jitter = random.nextDouble(0.0, 2.0),
heard = heard,
)
}
internal fun scoreCandidate(
song: SongRecord,
seedIds: Set<String>,
seedGenres: List<String>,
seedArtistIds: List<String>,
query: String?,
affinity: Double,
recent: Set<String> = emptySet(),
recent: Boolean = false,
jitter: Double = 0.0,
heard: Boolean = false,
): Double {
var score = jitter
if (song.id in seedIds) score += 10.0
if (song.artistId != null && song.artistId in seedArtistIds) score += 3.0
score += song.genres.count { candidate ->
seedGenres.any { it.equals(candidate, ignoreCase = true) }
} * 1.5
if (query != null && song.title.contains(query, ignoreCase = true)) score += 2.0
score += affinity.coerceIn(-8.0, 8.0)
if (song.id in recent) score -= RECENT_PENALTY
var score = jitter + affinity.coerceIn(-8.0, 8.0)
if (recent) score -= RECENT_PENALTY
if (heard) score -= HEARD_PENALTY
return score
}
/**
* Picks a batch with the mood's requested seed share. Each slot rolls the
* percentage independently, so a 70% mood gets roughly seven seed tracks in
* ten. An exhausted pool falls back to the other one instead of stalling.
* Picks a batch with the mood's requested collection share. Each slot rolls
* the percentage independently. An exhausted pool falls back to the other
* one instead of stalling.
*/
internal fun pickMixed(
seedScored: List<Pair<SongRecord, Double>>,
collectionScored: List<Pair<SongRecord, Double>>,
recommendationScored: List<Pair<SongRecord, Double>>,
limit: Int,
seedPercent: Int,
collectionPercent: Int,
artistSpacing: Int = 2,
albumSpacing: Int = 3,
): List<SongRecord> {
val seeds = seedScored
val collection = collectionScored
.sortedByDescending { it.second }
.toMutableList()
val recommendations = recommendationScored
.sortedByDescending { it.second }
.toMutableList()
val percent = seedPercent.coerceIn(0, 100)
val percent = collectionPercent.coerceIn(0, 100)
val picked = ArrayList<SongRecord>(limit)
val artists = ArrayDeque<String>()
val albums = ArrayDeque<String>()
while (picked.size < limit && (seeds.isNotEmpty() || recommendations.isNotEmpty())) {
val preferSeed = when {
seeds.isEmpty() -> false
while (picked.size < limit && (collection.isNotEmpty() || recommendations.isNotEmpty())) {
val preferCollection = when {
collection.isEmpty() -> false
recommendations.isEmpty() -> true
else -> random.nextInt(100) < percent
}
val pool = if (preferSeed) seeds else recommendations
val pool = if (preferCollection) collection else recommendations
val song = pool.removeAt(diverseIndex(pool, artists, albums)).first
picked += song
artists.addLast(song.displayArtist)
artists.addLast(song.artist)
if (artists.size > artistSpacing) artists.removeFirst()
albums.addLast(song.albumId)
albums.addLast(albumKey(song))
if (albums.size > albumSpacing) albums.removeFirst()
}
return picked
@@ -271,53 +191,17 @@ class RadioService(
albums: ArrayDeque<String>,
): Int {
var index = pool.indexOfFirst { (song, _) ->
song.displayArtist !in artists && song.albumId !in albums
song.artist !in artists && albumKey(song) !in albums
}
if (index < 0) index = pool.indexOfFirst { (song, _) -> song.displayArtist !in artists }
if (index < 0) index = pool.indexOfFirst { (song, _) -> song.artist !in artists }
return if (index < 0) 0 else index
}
/**
* Picks the best remaining candidate while keeping artists and albums apart.
* An artist may return after [artistSpacing] other tracks, an album after
* [albumSpacing]. Fallbacks relax the constraints rather than stalling.
*/
internal fun pickDiverse(
scored: List<Pair<SongRecord, Double>>,
limit: Int,
artistSpacing: Int = 2,
albumSpacing: Int = 3,
): List<SongRecord> {
val remaining = scored
.sortedWith(compareByDescending<Pair<SongRecord, Double>> { it.second })
.toMutableList()
val picked = ArrayList<SongRecord>(limit)
val artists = ArrayDeque<String>()
val albums = ArrayDeque<String>()
while (picked.size < limit && remaining.isNotEmpty()) {
var index = remaining.indexOfFirst { (song, _) ->
song.displayArtist !in artists && song.albumId !in albums
}
if (index < 0) {
index = remaining.indexOfFirst { (song, _) -> song.displayArtist !in artists }
}
if (index < 0) index = 0
val song = remaining.removeAt(index).first
picked += song
artists.addLast(song.displayArtist)
if (artists.size > artistSpacing) artists.removeFirst()
albums.addLast(song.albumId)
if (albums.size > albumSpacing) albums.removeFirst()
}
return picked
}
private fun albumKey(song: SongRecord): String = song.album?.takeIf { it.isNotBlank() } ?: song.id
private companion object {
const val POOL_LIMIT = 400
const val RECENT_DAYS = 7L
const val RECENT_PENALTY = 6.0
const val HEARD_PENALTY = 20.0
}
}