Files
AudioManager/src/main/kotlin/win/taptap/musicmanager/discovery/DeezerSearch.kt
T
TapTap 26c41cc7d9
CI / chart (push) Successful in 2s
CI / test (push) Successful in 1m57s
CI / chart-push (push) Successful in 5s
CI / image (push) Successful in 3m39s
feat: recommend from Deezer and YouTube Music radios
- Deezer: /artist/{id}/radio for collection artists, affinity 2.0
- YouTube Music: RDAMVM watch playlist via yt-dlp, affinity 2.0
- seed radios from the 2 newest songs of the mood's own catalog
- dedupe candidates by recording, not only by external id
- clean raw YouTube titles and Topic suffixes when indexing
- tests, smoke marker for the RDAMVM path, docs
2026-11-17 15:22:05 +00:00

400 lines
15 KiB
Kotlin

package win.taptap.musicmanager.discovery
import java.net.URI
import java.net.URLEncoder
import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse
import java.time.Duration
import java.util.concurrent.ConcurrentHashMap
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.contentOrNull
import kotlinx.serialization.json.jsonObject
import kotlinx.serialization.json.jsonPrimitive
import win.taptap.musicmanager.source.MusicSource
/**
* Deezer's public catalog API. No user token is needed for search, track
* metadata or the similarity graph; the ARL is only used by the downloader.
*
* Deezer returns canonical tracks with a square album cover, which is also what
* the indexer embeds into the downloaded MP3.
*/
class DeezerSearch(
private val apiBase: String = "https://api.deezer.com",
private val timeoutSeconds: Long = 20,
) : MusicCatalog {
override val source: String = MusicSource.DEEZER
private val json = Json {
ignoreUnknownKeys = true
explicitNulls = false
}
private val http = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(10))
.followRedirects(HttpClient.Redirect.NORMAL)
.build()
/** Artist and album lookups are stable for a release, so cache them. */
private val artistIds = ConcurrentHashMap<String, Lookup<Long>>()
private val albumRefs = ConcurrentHashMap<String, Lookup<DeezerAlbumRefDto>>()
override fun search(query: String, limit: Int): List<TrackCandidate> {
val count = limit.coerceIn(1, MAX_RESULTS)
val url = "$apiBase/search/track?q=${encode(query)}&limit=$count&output=json"
return parseDeezerSearch(get(url))
}
override fun resolve(url: String): TrackCandidate? {
val trimmed = url.trim()
if (trimmed.isEmpty()) return null
val trackId = trackIdFrom(trimmed) ?: followShortLink(trimmed)?.let(::trackIdFrom)
?: return null
return parseDeezerTrack(get("$apiBase/track/$trackId"))
}
/**
* Walks Deezer's own graph from the entire collection:
*
* 1. the most represented artists → their top tracks;
* 2. those artists' related artists → their top tracks;
* 3. the collection's albums → their deep cuts.
*
* A mood with 40 songs by 6 artists therefore still yields fresh material
* even after the obvious artist hits are already in the mood. Every request
* is best-effort; a blocked endpoint does not fail the pass.
*/
override fun discover(seeds: DiscoverySeeds, limit: Int): List<TrackCandidate> {
if (seeds.isEmpty()) return emptyList()
val found = LinkedHashMap<String, TrackCandidate>()
val seedArtists = seeds.artists
.take(MAX_SEED_ARTISTS)
.mapNotNull { seed -> artistId(seed.name)?.let { seed to it } }
seedArtists.forEach { (_, id) ->
artistTopTracks(id, SEED_TOP_LIMIT).forEach {
add(found, it, SEED_TOP_AFFINITY)
}
// Deezer's own radio is the recommendation engine at its strongest:
// a Daft Punk radio mixes Daft Punk with MGMT, Caribou, Jamiroquai.
artistRadio(id, SEED_RADIO_LIMIT).forEach {
add(found, it, RADIO_AFFINITY)
}
}
val related = LinkedHashSet<Long>()
seedArtists.take(MAX_RELATED_SEEDS).forEach { (_, id) ->
related += relatedArtists(id, MAX_RELATED_PER_SEED)
}
val seedIds = seedArtists.map { it.second }.toSet()
related.asSequence()
.filterNot { it in seedIds }
.take(MAX_RELATED_ARTISTS)
.forEach { id ->
artistTopTracks(id, RELATED_TOP_LIMIT).forEach {
add(found, it, RELATED_AFFINITY)
}
}
seeds.albums
.take(MAX_SEED_ALBUMS)
.mapNotNull(::albumRef)
.forEach { album ->
albumTracks(album, ALBUM_TRACK_LIMIT).forEach {
add(found, it, ALBUM_AFFINITY)
}
}
return found.values.take(limit.coerceAtLeast(1))
}
/** Keeps the highest weight when the same track comes from two edges. */
private fun add(
into: MutableMap<String, TrackCandidate>,
candidate: TrackCandidate,
affinity: Double,
) {
if (candidate.externalId.isEmpty()) return
val existing = into[candidate.externalId]
if (existing == null || existing.affinity < affinity) {
into[candidate.externalId] = candidate.copy(affinity = affinity)
}
}
private fun artistId(name: String): Long? = lookup(
cache = artistIds,
key = matchKey(name),
request = "$apiBase/search/artist?q=${encode(name)}&limit=$ARTIST_LOOKUP_LIMIT&output=json",
) { body ->
val parsed = json.decodeFromString<DeezerArtistListResponse>(body)
parsed.data.firstOrNull { artistMatches(it.name, name) && it.id > 0 }?.id
?: parsed.data.firstOrNull { it.id > 0 }?.id
}
private fun albumRef(seed: SeedAlbum): DeezerAlbumRefDto? {
val titleKey = matchKey(seed.title)
if (titleKey.isEmpty()) return null
val artistKey = matchKey(seed.artist)
return lookup(
cache = albumRefs,
key = "$titleKey|$artistKey",
request = "$apiBase/search/album?q=${encode("${seed.title} ${seed.artist}")}" +
"&limit=$ALBUM_LOOKUP_LIMIT&output=json",
) { body ->
val parsed = json.decodeFromString<DeezerAlbumListResponse>(body)
parsed.data.firstOrNull { album ->
album.id > 0 &&
matchKey(album.title) == titleKey &&
(album.artist == null || artistMatches(album.artist.name, seed.artist))
}
}
}
/**
* Resolves a name to an id once. Misses are cached too, so a mood full of
* obscure artists does not re-search them on every refresh.
*/
private inline fun <T : Any> lookup(
cache: MutableMap<String, Lookup<T>>,
key: String,
request: String,
crossinline parse: (String) -> T?,
): T? {
if (key.isEmpty()) return null
cache[key]?.let { return it.value }
val value = runCatching { parse(get(request)) }.getOrNull()
cache[key] = Lookup(value)
return value
}
private fun relatedArtists(id: Long, limit: Int): List<Long> = runCatching {
val body = get("$apiBase/artist/$id/related?limit=$limit&output=json")
json.decodeFromString<DeezerArtistListResponse>(body)
.data
.map { it.id }
.filter { it > 0 }
}.getOrDefault(emptyList())
private fun artistRadio(id: Long, limit: Int): List<TrackCandidate> = runCatching {
val body = get("$apiBase/artist/$id/radio?limit=$limit&output=json")
json.decodeFromString<DeezerTracksResponse>(body).data.mapNotNull { it.toCandidate() }
}.getOrDefault(emptyList())
private fun artistTopTracks(id: Long, limit: Int): List<TrackCandidate> = runCatching {
val body = get("$apiBase/artist/$id/top?limit=$limit&output=json")
json.decodeFromString<DeezerTracksResponse>(body).data.mapNotNull { it.toCandidate() }
}.getOrDefault(emptyList())
/**
* `/album/{id}/tracks` omits the album object, so inject the album the
* collection already gave us to keep the cover and the album name.
*/
private fun albumTracks(
album: DeezerAlbumRefDto,
limit: Int,
): List<TrackCandidate> = runCatching {
val body = get("$apiBase/album/${album.id}/tracks?limit=$limit&output=json")
json.decodeFromString<DeezerTracksResponse>(body).data
.mapNotNull { it.toCandidate() }
.map { candidate ->
candidate.copy(
album = candidate.album ?: album.title.takeIf { it.isNotBlank() },
thumbnail = candidate.thumbnail ?: album.cover(),
)
}
}.getOrDefault(emptyList())
private fun get(url: String): String {
throttle()
val request = HttpRequest.newBuilder(URI.create(url))
.timeout(Duration.ofSeconds(timeoutSeconds))
.header("Accept", "application/json")
.header("User-Agent", "AudioManager/0.1")
.GET()
.build()
val response = try {
http.send(request, HttpResponse.BodyHandlers.ofString())
} catch (e: Exception) {
throw IllegalStateException("Deezer request failed: ${e.message ?: e::class.simpleName}", e)
}
if (response.statusCode() != 200) {
throw IllegalStateException("Deezer API returned HTTP ${response.statusCode()}")
}
val body = response.body()
if (body.isBlank()) throw IllegalStateException("Deezer API returned an empty response")
throwIfError(body)
return body
}
/** `deezer.page.link` redirects to a normal deezer.com URL. */
private fun followShortLink(url: String): String? {
if (!url.contains("deezer.page.link", ignoreCase = true)) return null
return runCatching {
throttle()
val request = HttpRequest.newBuilder(URI.create(url))
.timeout(Duration.ofSeconds(timeoutSeconds))
.header("User-Agent", "AudioManager/0.1")
.GET()
.build()
http.send(request, HttpResponse.BodyHandlers.discarding()).uri().toString()
}.getOrNull()
}
private fun throwIfError(body: String) {
val root = runCatching { json.parseToJsonElement(body).jsonObject }.getOrNull() ?: return
val error = root["error"] as? JsonObject ?: return
val message = error["message"]?.jsonPrimitive?.contentOrNull
?: error["type"]?.jsonPrimitive?.contentOrNull
?: "Deezer request failed"
throw IllegalStateException(message)
}
/** Keeps us well below Deezer's 50 requests per 5 seconds limit. */
private fun throttle() {
synchronized(throttleLock) {
val now = System.nanoTime()
val wait = MIN_REQUEST_INTERVAL_NANOS - (now - lastRequestNanos)
if (wait > 0) {
Thread.sleep(wait / 1_000_000, (wait % 1_000_000).toInt())
}
lastRequestNanos = System.nanoTime()
}
}
/** `value == null` is a cached miss. */
private data class Lookup<T>(val value: T?)
private companion object {
const val MAX_RESULTS = 25
/** Bounds one discovery pass to roughly twenty throttled requests. */
const val MAX_SEED_ARTISTS = 5
const val MAX_RELATED_SEEDS = 2
const val MAX_RELATED_PER_SEED = 8
const val MAX_RELATED_ARTISTS = 6
const val MAX_SEED_ALBUMS = 2
const val SEED_TOP_LIMIT = 25
const val SEED_RADIO_LIMIT = 40
const val RELATED_TOP_LIMIT = 10
const val ALBUM_TRACK_LIMIT = 40
const val ARTIST_LOOKUP_LIMIT = 5
const val ALBUM_LOOKUP_LIMIT = 5
/** A hit by an artist already in the mood; the scorer adds the rest. */
const val SEED_TOP_AFFINITY = 0.5
/** A track Deezer itself puts in that artist's radio. */
const val RADIO_AFFINITY = 2.0
/** A hit by an artist Deezer considers similar to the collection. */
const val RELATED_AFFINITY = 1.5
/** Another track from an album already in the mood. */
const val ALBUM_AFFINITY = 1.0
const val MIN_REQUEST_INTERVAL_NANOS = 120_000_000L
val THROTTLE_LOCK = Any()
fun encode(value: String): String =
URLEncoder.encode(value, Charsets.UTF_8).replace("+", "%20")
fun trackIdFrom(url: String): String? {
val match = TRACK_URL.find(url) ?: return null
return match.groupValues[1].takeIf { it.isNotEmpty() }
}
val TRACK_URL = Regex("deezer\\.com/(?:[a-z]{2}/)?track/(\\d+)", RegexOption.IGNORE_CASE)
}
private val throttleLock = THROTTLE_LOCK
@Volatile
private var lastRequestNanos = 0L
}
internal fun parseDeezerSearch(json: String): List<TrackCandidate> {
val parsed = runCatching {
Json { ignoreUnknownKeys = true; explicitNulls = false }
.decodeFromString<DeezerSearchResponse>(json)
}.getOrNull() ?: return emptyList()
return parsed.data.mapNotNull { it.toCandidate() }
}
internal fun parseDeezerTrack(json: String): TrackCandidate? {
val parsed = runCatching {
Json { ignoreUnknownKeys = true; explicitNulls = false }
.decodeFromString<DeezerTrackDto>(json)
}.getOrNull() ?: return null
return parsed.toCandidate(applyLengthFilter = false)
}
@Serializable
private data class DeezerSearchResponse(val data: List<DeezerTrackDto> = emptyList())
@Serializable
private data class DeezerTracksResponse(val data: List<DeezerTrackDto> = emptyList())
@Serializable
private data class DeezerArtistListResponse(val data: List<DeezerArtistRefDto> = emptyList())
@Serializable
private data class DeezerArtistRefDto(val id: Long = 0, val name: String = "")
@Serializable
private data class DeezerAlbumListResponse(val data: List<DeezerAlbumRefDto> = emptyList())
@Serializable
private data class DeezerAlbumRefDto(
val id: Long = 0,
val title: String = "",
val artist: DeezerArtistDto? = null,
@SerialName("cover_big") val coverBig: String? = null,
@SerialName("cover_xl") val coverXl: String? = null,
) {
fun cover(): String? = coverBig ?: coverXl
}
@Serializable
private data class DeezerTrackDto(
val id: Long = 0,
val title: String = "",
val duration: Int = 0,
val readable: Boolean = true,
val artist: DeezerArtistDto? = null,
val album: DeezerAlbumDto? = null,
) {
fun toCandidate(applyLengthFilter: Boolean = true): TrackCandidate? {
if (id <= 0 || !readable) return null
if (title.isBlank()) return null
val artistName = artist?.name?.takeIf { it.isNotBlank() } ?: return null
if (applyLengthFilter && duration > 0 &&
duration !in MIN_TRACK_SECONDS..MAX_TRACK_SECONDS
) {
return null
}
return TrackCandidate(
source = MusicSource.DEEZER,
externalId = id.toString(),
title = title.trim(),
artist = artistName.trim(),
album = album?.title?.takeIf { it.isNotBlank() },
duration = duration.takeIf { it > 0 },
thumbnail = album?.coverBig ?: album?.coverXl ?: album?.coverMedium,
)
}
}
@Serializable
private data class DeezerArtistDto(val name: String = "")
@Serializable
private data class DeezerAlbumDto(
val title: String? = null,
@SerialName("cover_big") val coverBig: String? = null,
@SerialName("cover_xl") val coverXl: String? = null,
@SerialName("cover_medium") val coverMedium: String? = null,
)