feat: discover YT recommendations and tune the radio
CI / chart (push) Successful in 26s
CI / chart-push (push) Successful in 5s
CI / test (push) Successful in 2m6s
CI / image (push) Failing after 2m54s

yt-dlp now feeds mood discovery. Queries come from the free-text hint, seed
artists and genres; they run in parallel, are filtered to music-length videos,
matched against library songs by normalized title and artist, scored, and
stored as review candidates. Refresh, accept and reject endpoints are added:
accepting a library match adds a seed immediately, while accepted tracks that
are not owned wait for the future downloader. Decisions survive refreshes and
stale undecided candidates are pruned.

A background pass refreshes stale moods every hour, and the image ships a
pinned yt-dlp binary (YTDLP_PATH, also added to the Nix shell and chart).

Radio now avoids tracks played in the last 7 days when the pool is large
enough, spaces artists and albums across a batch, and weighs skips three times
as heavily as completions. The chart moves to 0.2.2.
This commit is contained in:
TapTap committed 2026-11-15 12:44:30 +00:00
1 parent 67eed8d262
commit c5aa000d1a
18 files changed
+1061 -37

No files matched your search

@@ -0,0 +1,220 @@
package win.taptap.musicmanager.discovery
import java.time.Instant
import java.time.temporal.ChronoUnit
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.async
import kotlinx.coroutines.awaitAll
import kotlinx.coroutines.coroutineScope
import org.slf4j.LoggerFactory
import win.taptap.musicmanager.config.FolderType
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.RecommendationUpsert
import win.taptap.musicmanager.util.IdGenerator
data class DiscoveryOutcome(
val stored: Int,
val matched: Int,
val skipped: Boolean = false,
val error: String? = null,
)
/**
* Turns mood seeds, genres and free text into YouTube Music candidates. New
* candidates are stored for review; accepted ones either become seeds (when the
* library already has the track) or wait for the future downloader.
*/
class DiscoveryService(
private val search: YtSearch,
private val clock: () -> Instant = { Instant.now() },
) {
private val log = LoggerFactory.getLogger(DiscoveryService::class.java)
suspend fun refresh(
mood: MoodRecord,
user: UserAccount,
library: LibraryConfig,
force: Boolean = false,
): DiscoveryOutcome {
if (!mood.ytEnabled) return DiscoveryOutcome(0, 0, skipped = true)
val now = clock()
if (!force && isFresh(mood.lastDiscoveryAt, mood.refreshHours, now)) {
return DiscoveryOutcome(0, 0, skipped = true)
}
val folders = library.folders
.asSequence()
.filter { it.type == FolderType.MUSIC && it.id in user.folders }
.map { it.id }
.toSet()
if (folders.isEmpty()) {
MoodRepository.markError(mood.id, "No music folder is visible to this user")
return DiscoveryOutcome(0, 0, error = "No music folder is visible to this user")
}
val seeds = LibraryRepository.songsByIds(MoodRepository.seedSongIds(mood.id), folders, user.name)
val seedIds = seeds.map { it.id }.toSet()
val seedArtists = seeds.map { it.displayArtist }.filter { it.isNotBlank() }
val queries = buildQueries(mood, seedArtists)
if (queries.isEmpty()) {
MoodRepository.markDiscovered(mood.id)
return DiscoveryOutcome(0, 0)
}
// Queries are independent; running them together keeps a refresh within
// the client's request timeout even when yt-dlp is slow.
val results = coroutineScope {
queries.map { query ->
async(Dispatchers.IO) {
runCatching { search.search(query, QUERY_LIMIT) }
}
}.awaitAll()
}
val failures = results.filter { it.isFailure }
if (failures.size == queries.size) {
val message = failures.firstNotNullOfOrNull { it.exceptionOrNull()?.message }
?: "Search failed"
log.warn("YT discovery failed for mood {}: {}", mood.name, message)
MoodRepository.markError(mood.id, message)
return DiscoveryOutcome(0, 0, error = message)
}
val candidates = LinkedHashMap<String, YtCandidate>()
results.mapNotNull { it.getOrNull() }.flatten().forEach { candidate ->
if (isMusicLength(candidate.duration)) {
candidates.putIfAbsent(candidate.videoId, candidate)
}
}
val known = MoodRepository.recommendations(mood.id).associateBy { it.videoId }
val moodText = listOfNotNull(mood.query, mood.description, mood.name)
.joinToString(" ")
val upserts = candidates.values
.mapNotNull { candidate ->
val existing = known[candidate.videoId]
// Accepted or rejected tracks keep their decision and are never
// offered again; only last_seen is refreshed by the upsert.
val matched = existing?.matchedSongId ?: matchSong(candidate, folders, user.name)
if (existing == null && matched != null && matched in seedIds) {
return@mapNotNull null
}
UpsertCandidate(
candidate = candidate,
matchedSongId = matched,
score = scoreCandidate(candidate, seedArtists, moodText, matched != null),
)
}
.sortedWith(compareByDescending<UpsertCandidate> { it.score }.thenBy { it.candidate.title })
.take(mood.targetSize.coerceIn(10, 60))
.map {
RecommendationUpsert(
videoId = it.candidate.videoId,
title = it.candidate.title,
artist = it.candidate.artist,
album = it.candidate.album,
duration = it.candidate.duration,
thumbnail = it.candidate.thumbnail,
matchedSongId = it.matchedSongId,
)
}
val stored = MoodRepository.storeRecommendations(mood.id, upserts, now.toString())
MoodRepository.markDiscovered(mood.id)
log.info("YT discovery for mood {} stored {} recommendations", mood.name, stored)
return DiscoveryOutcome(
stored = stored,
matched = upserts.count { it.matchedSongId != null },
)
}
private fun matchSong(candidate: YtCandidate, folders: Set<Int>, userName: String): String? {
val titleKey = matchKey(candidate.title)
if (titleKey.isEmpty()) return null
return LibraryRepository
.searchSongs(candidate.title, MATCH_LIMIT, 0, folders, userName)
.firstOrNull { song ->
matchKey(song.title) == titleKey && artistMatches(candidate.artist, song.displayArtist)
}
?.id
}
private data class UpsertCandidate(
val candidate: YtCandidate,
val matchedSongId: String?,
val score: Double,
)
private companion object {
const val QUERY_LIMIT = 10
const val MATCH_LIMIT = 25
}
}
internal fun isFresh(lastDiscoveryAt: String?, refreshHours: Int, now: Instant): Boolean {
if (lastDiscoveryAt == null) return false
val at = runCatching { Instant.parse(lastDiscoveryAt) }.getOrNull() ?: return false
return at.plus(refreshHours.toLong().coerceAtLeast(1), ChronoUnit.HOURS).isAfter(now)
}
internal fun isMusicLength(seconds: Int?): Boolean =
seconds == null || seconds in 45..(20 * 60)
internal fun buildQueries(mood: MoodRecord, seedArtists: List<String>): List<String> {
val queries = LinkedHashSet<String>()
mood.query?.trim()?.takeIf { it.isNotEmpty() }?.let(queries::add)
seedArtists.map { it.trim() }.filter { it.isNotEmpty() }.distinct().take(2).forEach {
queries += it
}
mood.genres.map { it.trim() }.filter { it.isNotEmpty() }.take(2).forEach {
queries += "$it mix"
}
if (queries.isEmpty()) queries += mood.name
return queries.distinctBy { it.lowercase() }.take(4)
}
internal fun scoreCandidate(
candidate: YtCandidate,
seedArtists: List<String>,
moodText: String,
matched: Boolean,
): Double {
var score = 0.0
val artist = matchKey(candidate.artist)
val seedKeys = seedArtists.map { matchKey(it) }.filter { it.isNotEmpty() }
when {
artist.isNotEmpty() && artist in seedKeys -> score += 3.0
artist.isNotEmpty() && seedKeys.any { artist.contains(it) || it.contains(artist) } -> score += 1.5
}
val text = matchKey(moodText)
if (text.isNotEmpty() && matchKey(candidate.title).contains(text)) score += 1.0
if (matched) score += 1.5
if ((candidate.duration ?: 0) > 8 * 60) score -= 1.0
return score
}
private val BRACKETS = Regex("\\([^)]*\\)|\\[[^\\]]*\\]")
private val NON_WORD = Regex("[^\\p{L}\\p{N} ]+")
private val SPACES = Regex("\\s+")
private val FEATURING = Regex("\\b(feat|ft|featuring)\\b.*$", RegexOption.IGNORE_CASE)
/** Loose key for comparing YT titles and artist names with library tags. */
internal fun matchKey(value: String): String =
IdGenerator.normalize(value)
.replace(BRACKETS, " ")
.replace(FEATURING, " ")
.replace(NON_WORD, " ")
.replace(SPACES, " ")
.trim()
internal fun artistMatches(a: String, b: String): Boolean {
val left = matchKey(a)
val right = matchKey(b)
if (left.isEmpty() || right.isEmpty()) return false
return left == right || left.contains(right) || right.contains(left)
}