feat: add browsing and media endpoints

- user-scoped getMusicFolders, getIndexes, getArtists, getArtist,
  getAlbum and getSong
- search3 with pagination, literal matching and empty/wildcard queries
- stream and download with Range support and RFC 5987 filenames
- getCoverArt with cached size variants and visibility checks
- V2 migration for per-user album and artist ratings
This commit is contained in:
TapTap committed 2026-11-13 11:53:57 +00:00
1 parent 1f73d901d5
commit 643ee42f09
14 files changed
+1364 -4

No files matched your search

@@ -46,7 +46,8 @@ fun main() {
ConfigRepository.sync(library, users)
val applicationScope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
val scanner = MediaScanner(library, CoverArtService(config.dataDir))
val coverArtService = CoverArtService(config.dataDir)
val scanner = MediaScanner(library, coverArtService)
if (MediaRepository.countSongs() == 0L) {
log.info("Song table is empty, starting initial library scan")
scanner.start(applicationScope)
@@ -80,6 +81,8 @@ fun main() {
get("/health") { call.respondText("ok") }
subsonicRoutes(
users = users,
library = library,
coverArtService = coverArtService,
startScan = { scanner.start(applicationScope) },
scanStatus = { scanner.status() },
)
@@ -0,0 +1,518 @@
package win.taptap.musicmanager.db
import java.nio.file.Files
import java.nio.file.Path
import org.jetbrains.exposed.sql.JoinType
import org.jetbrains.exposed.sql.ResultRow
import org.jetbrains.exposed.sql.SortOrder
import org.jetbrains.exposed.sql.Transaction
import org.jetbrains.exposed.sql.and
import org.jetbrains.exposed.sql.selectAll
import org.jetbrains.exposed.sql.transactions.transaction
import org.jetbrains.exposed.sql.union
import win.taptap.musicmanager.config.LibraryConfig
import win.taptap.musicmanager.util.IdGenerator
data class ArtistRefRecord(val id: String, val name: String)
data class UserItemState(val starredAt: String?, val rating: Int?)
data class UserSongState(
val playCount: Int,
val starredAt: String?,
val rating: Int?,
)
data class ArtistRecord(
val id: String,
val name: String,
val sortName: String,
val albumCount: Int,
val starredAt: String?,
val rating: Int?,
)
data class AlbumRecord(
val id: String,
val name: String,
val artistId: String?,
val artistName: String?,
val year: Int?,
val coverArt: String?,
val songCount: Int,
val duration: Int,
val playCount: Int,
val created: String,
val starredAt: String?,
val rating: Int?,
val genres: List<String>,
)
data class SongRecord(
val id: String,
val albumId: String,
val albumName: String,
val artistId: String?,
val artistName: String,
val displayArtist: String,
val title: String,
val trackNumber: Int?,
val discNumber: Int,
val year: Int?,
val duration: Int,
val bitRate: Int,
val size: Long,
val suffix: String,
val contentType: String,
val coverArt: String?,
val folderId: Int,
val relativePath: String,
val created: String,
val starredAt: String?,
val rating: Int?,
val playCount: Int,
val artists: List<ArtistRefRecord>,
val genres: List<String>,
)
data class ResolvedSong(val song: SongRecord, val file: Path)
/**
* Read-side queries for browsing and media. Every method takes the set of folder
* IDs visible to the requesting user; an album or artist without a visible song
* is never returned.
*/
object LibraryRepository {
fun artists(folderIds: Set<Int>, userName: String): List<ArtistRecord> = read {
if (folderIds.isEmpty()) return@read emptyList()
val visibleSongs = visibleSongs(folderIds)
val visibleAlbums = visibleAlbums(folderIds)
val trackArtists = SongArtistsTable
.select(SongArtistsTable.artistId)
.where { SongArtistsTable.songId inSubQuery visibleSongs }
val albumArtists = AlbumArtistsTable
.select(AlbumArtistsTable.artistId)
.where { AlbumArtistsTable.albumId inSubQuery visibleAlbums }
val albumCounts = AlbumArtistsTable
.select(AlbumArtistsTable.artistId, AlbumArtistsTable.albumId)
.withDistinct()
.where { AlbumArtistsTable.albumId inSubQuery visibleAlbums }
.groupingBy { it[AlbumArtistsTable.artistId] }
.eachCount()
val states = itemStates(userName, "artist")
return@read ArtistsTable
.selectAll()
.where { ArtistsTable.id inSubQuery trackArtists.union(albumArtists) }
.map { row ->
val id = row[ArtistsTable.id]
val state = states[id]
ArtistRecord(
id = id,
name = row[ArtistsTable.name],
sortName = row[ArtistsTable.sortName],
albumCount = albumCounts[id] ?: 0,
starredAt = state?.starredAt,
rating = state?.rating,
)
}
.sortedBy { IdGenerator.normalize(it.sortName) }
}
fun artist(artistId: String, folderIds: Set<Int>, userName: String): ArtistRecord? = read {
if (folderIds.isEmpty()) return@read null
val row = ArtistsTable.selectAll()
.where { ArtistsTable.id eq artistId }
.singleOrNull() ?: return@read null
val albumCount = AlbumArtistsTable
.select(AlbumArtistsTable.albumId)
.withDistinct()
.where {
(AlbumArtistsTable.artistId eq artistId) and
(AlbumArtistsTable.albumId inSubQuery visibleAlbums(folderIds))
}
.count()
.toInt()
val hasVisibleSong = SongArtistsTable
.select(SongArtistsTable.songId)
.where {
(SongArtistsTable.artistId eq artistId) and
(SongArtistsTable.songId inSubQuery visibleSongs(folderIds))
}
.any()
if (albumCount == 0 && !hasVisibleSong) return@read null
val state = itemStates(userName, "artist")[artistId]
ArtistRecord(
id = artistId,
name = row[ArtistsTable.name],
sortName = row[ArtistsTable.sortName],
albumCount = albumCount,
starredAt = state?.starredAt,
rating = state?.rating,
)
}
fun albumsForArtist(artistId: String, folderIds: Set<Int>, userName: String): List<AlbumRecord> = read {
if (folderIds.isEmpty()) return@read emptyList()
val albumIds = AlbumArtistsTable
.select(AlbumArtistsTable.albumId)
.withDistinct()
.where {
(AlbumArtistsTable.artistId eq artistId) and
(AlbumArtistsTable.albumId inSubQuery visibleAlbums(folderIds))
}
.map { it[AlbumArtistsTable.albumId] }
albumIds.mapNotNull { albumRecord(it, folderIds, userName) }
.sortedBy { it.name.lowercase() }
}
fun album(albumId: String, folderIds: Set<Int>, userName: String): AlbumRecord? = read {
albumRecord(albumId, folderIds, userName)
}
fun albumSongs(albumId: String, folderIds: Set<Int>, userName: String): List<SongRecord> = read {
if (folderIds.isEmpty()) return@read emptyList()
val rows = SongsTable.selectAll()
.where {
(SongsTable.albumId eq albumId) and
(SongsTable.folderId inList folderIds)
}
.orderBy(
SongsTable.discNumber to SortOrder.ASC,
SongsTable.trackNumber to SortOrder.ASC,
SongsTable.title to SortOrder.ASC,
)
.toList()
enrichSongs(rows, userName)
}
fun song(songId: String, folderIds: Set<Int>, userName: String): SongRecord? = read {
if (folderIds.isEmpty()) return@read null
val row = SongsTable.selectAll()
.where {
(SongsTable.id eq songId) and
(SongsTable.folderId inList folderIds)
}
.singleOrNull() ?: return@read null
enrichSongs(listOf(row), userName).single()
}
fun allAlbums(limit: Int, offset: Int, folderIds: Set<Int>, userName: String): List<AlbumRecord> = read {
if (folderIds.isEmpty()) return@read emptyList()
val ids = AlbumsTable
.select(AlbumsTable.id)
.where { AlbumsTable.id inSubQuery visibleAlbums(folderIds) }
.orderBy(AlbumsTable.name to SortOrder.ASC)
.limit(limit)
.offset(offset.toLong())
.map { it[AlbumsTable.id] }
ids.mapNotNull { albumRecord(it, folderIds, userName) }
}
fun allSongs(limit: Int, offset: Int, folderIds: Set<Int>, userName: String): List<SongRecord> = read {
if (folderIds.isEmpty()) return@read emptyList()
val rows = SongsTable.selectAll()
.where { SongsTable.folderId inList folderIds }
.orderBy(SongsTable.title to SortOrder.ASC)
.limit(limit)
.offset(offset.toLong())
.toList()
enrichSongs(rows, userName)
}
fun searchArtists( query: String,
limit: Int,
offset: Int,
folderIds: Set<Int>,
userName: String,
): List<ArtistRecord> = read {
if (folderIds.isEmpty()) return@read emptyList()
val pattern = likePattern(query)
val visibleSongs = visibleSongs(folderIds)
val visibleAlbums = visibleAlbums(folderIds)
val trackArtists = SongArtistsTable.select(SongArtistsTable.artistId)
.where { SongArtistsTable.songId inSubQuery visibleSongs }
val albumArtists = AlbumArtistsTable.select(AlbumArtistsTable.artistId)
.where { AlbumArtistsTable.albumId inSubQuery visibleAlbums }
val ids = ArtistsTable
.select(ArtistsTable.id)
.where {
(ArtistsTable.searchText like pattern) and
(ArtistsTable.id inSubQuery trackArtists.union(albumArtists))
}
.orderBy(ArtistsTable.sortName to SortOrder.ASC)
.limit(limit)
.offset(offset.toLong())
.map { it[ArtistsTable.id] }
ids.mapNotNull { artist(it, folderIds, userName) }
}
fun searchAlbums(
query: String,
limit: Int,
offset: Int,
folderIds: Set<Int>,
userName: String,
): List<AlbumRecord> = read {
if (folderIds.isEmpty()) return@read emptyList()
val pattern = likePattern(query)
val ids = AlbumsTable
.select(AlbumsTable.id)
.where {
(AlbumsTable.searchText like pattern) and
(AlbumsTable.id inSubQuery visibleAlbums(folderIds))
}
.orderBy(AlbumsTable.name to SortOrder.ASC)
.limit(limit)
.offset(offset.toLong())
.map { it[AlbumsTable.id] }
ids.mapNotNull { albumRecord(it, folderIds, userName) }
}
fun searchSongs(
query: String,
limit: Int,
offset: Int,
folderIds: Set<Int>,
userName: String,
): List<SongRecord> = read {
if (folderIds.isEmpty()) return@read emptyList()
val pattern = likePattern(query)
val rows = SongsTable.selectAll()
.where {
(SongsTable.searchText like pattern) and
(SongsTable.folderId inList folderIds)
}
.orderBy(SongsTable.title to SortOrder.ASC)
.limit(limit)
.offset(offset.toLong())
.toList()
enrichSongs(rows, userName)
}
fun resolveSong(
songId: String,
folderIds: Set<Int>,
userName: String,
library: LibraryConfig,
): ResolvedSong? {
val song = song(songId, folderIds, userName) ?: return null
val folder = library.byId(song.folderId) ?: return null
val file = folder.path.resolve(song.relativePath).normalize()
if (!file.startsWith(folder.path)) return null
if (!Files.isRegularFile(file)) return null
return ResolvedSong(song, file)
}
fun albumIdForSong(songId: String, folderIds: Set<Int>): String? = read {
if (folderIds.isEmpty()) return@read null
SongsTable
.select(SongsTable.albumId)
.where {
(SongsTable.id eq songId) and
(SongsTable.folderId inList folderIds)
}
.singleOrNull()
?.get(SongsTable.albumId)
}
private fun albumRecord(albumId: String, folderIds: Set<Int>, userName: String): AlbumRecord? {
if (folderIds.isEmpty()) return null
val albumRow = AlbumsTable.selectAll()
.where { AlbumsTable.id eq albumId }
.singleOrNull() ?: return null
val songs = SongsTable.selectAll()
.where {
(SongsTable.albumId eq albumId) and
(SongsTable.folderId inList folderIds)
}
.toList()
if (songs.isEmpty()) return null
val primaryArtist = AlbumArtistsTable
.join(ArtistsTable, JoinType.INNER, AlbumArtistsTable.artistId, ArtistsTable.id)
.select(AlbumArtistsTable.albumId, ArtistsTable.id, ArtistsTable.name, AlbumArtistsTable.position)
.where { AlbumArtistsTable.albumId eq albumId }
.orderBy(AlbumArtistsTable.position to SortOrder.ASC)
.firstOrNull()
val playCount = songStates(userName, songs.map { it[SongsTable.id] })
.values
.sumOf { it.playCount }
val state = itemStates(userName, "album")[albumId]
return AlbumRecord(
id = albumId,
name = albumRow[AlbumsTable.name],
artistId = primaryArtist?.get(ArtistsTable.id),
artistName = primaryArtist?.get(ArtistsTable.name),
year = albumRow[AlbumsTable.year],
coverArt = albumRow[AlbumsTable.coverArt],
songCount = songs.size,
duration = songs.sumOf { it[SongsTable.duration] },
playCount = playCount,
created = albumRow[AlbumsTable.createdAt],
starredAt = state?.starredAt,
rating = state?.rating,
genres = AlbumGenresTable
.select(AlbumGenresTable.genre)
.where { AlbumGenresTable.albumId eq albumId }
.map { it[AlbumGenresTable.genre] }
.sorted(),
)
}
private fun enrichSongs(rows: List<ResultRow>, userName: String): List<SongRecord> {
if (rows.isEmpty()) return emptyList()
val songIds = rows.map { it[SongsTable.id] }
val albumIds = rows.map { it[SongsTable.albumId] }.distinct()
val songArtists = SongArtistsTable
.join(ArtistsTable, JoinType.INNER, SongArtistsTable.artistId, ArtistsTable.id)
.select(SongArtistsTable.songId, ArtistsTable.id, ArtistsTable.name, SongArtistsTable.position)
.where { SongArtistsTable.songId inList songIds }
.orderBy(SongArtistsTable.position to SortOrder.ASC)
.groupBy { it[SongArtistsTable.songId] }
.mapValues { (_, artistRows) ->
artistRows.map { ArtistRefRecord(it[ArtistsTable.id], it[ArtistsTable.name]) }
}
val albumArtists = AlbumArtistsTable
.join(ArtistsTable, JoinType.INNER, AlbumArtistsTable.artistId, ArtistsTable.id)
.select(AlbumArtistsTable.albumId, ArtistsTable.id, ArtistsTable.name, AlbumArtistsTable.position)
.where { AlbumArtistsTable.albumId inList albumIds }
.orderBy(AlbumArtistsTable.position to SortOrder.ASC)
.groupBy { it[AlbumArtistsTable.albumId] }
.mapValues { (_, artistRows) ->
ArtistRefRecord(artistRows.first()[ArtistsTable.id], artistRows.first()[ArtistsTable.name])
}
val covers = AlbumsTable.selectAll()
.where { AlbumsTable.id inList albumIds }
.associate { it[AlbumsTable.id] to it[AlbumsTable.coverArt] }
val genres = SongGenresTable.selectAll()
.where { SongGenresTable.songId inList songIds }
.groupBy { it[SongGenresTable.songId] }
.mapValues { (_, genreRows) -> genreRows.map { it[SongGenresTable.genre] }.sorted() }
val states = songStates(userName, songIds)
return rows.map { row ->
val id = row[SongsTable.id]
val albumId = row[SongsTable.albumId]
val primaryArtist = albumArtists[albumId]
val state = states[id]
SongRecord(
id = id,
albumId = albumId,
albumName = row[SongsTable.albumName],
artistId = primaryArtist?.id,
artistName = row[SongsTable.displayArtist],
displayArtist = row[SongsTable.displayArtist],
title = row[SongsTable.title],
trackNumber = row[SongsTable.trackNumber],
discNumber = row[SongsTable.discNumber],
year = row[SongsTable.year],
duration = row[SongsTable.duration],
bitRate = row[SongsTable.bitRate],
size = row[SongsTable.size],
suffix = row[SongsTable.suffix],
contentType = row[SongsTable.contentType],
coverArt = covers[albumId],
folderId = row[SongsTable.folderId],
relativePath = row[SongsTable.relativePath],
created = row[SongsTable.createdAt],
starredAt = state?.starredAt,
rating = state?.rating,
playCount = state?.playCount ?: 0,
artists = songArtists[id].orEmpty(),
genres = genres[id].orEmpty(),
)
}
}
private fun visibleSongs(folderIds: Set<Int>) =
SongsTable
.select(SongsTable.id)
.where { SongsTable.folderId inList folderIds }
private fun visibleAlbums(folderIds: Set<Int>) =
SongsTable
.select(SongsTable.albumId)
.withDistinct()
.where { SongsTable.folderId inList folderIds }
private fun itemStates(userName: String, itemType: String): Map<String, UserItemState> =
UserStarsTable.selectAll()
.where {
(UserStarsTable.userName eq userName) and
(UserStarsTable.itemType eq itemType)
}
.associate {
it[UserStarsTable.itemId] to UserItemState(
starredAt = it[UserStarsTable.starredAt],
rating = it[UserStarsTable.rating],
)
}
private fun songStates(userName: String, songIds: Collection<String>): Map<String, UserSongState> {
if (songIds.isEmpty()) return emptyMap()
return UserSongStateTable.selectAll()
.where {
(UserSongStateTable.userName eq userName) and
(UserSongStateTable.songId inList songIds.toList())
}
.associate {
it[UserSongStateTable.songId] to UserSongState(
playCount = it[UserSongStateTable.playCount],
starredAt = it[UserSongStateTable.starredAt],
rating = it[UserSongStateTable.rating],
)
}
}
/** Literal substring matching; `%` and `_` are removed instead of acting as wildcards. */
private fun likePattern(query: String): String {
val needle = IdGenerator.normalize(query).replace("%", "").replace("_", "")
return "%$needle%"
}
private fun <T> read(block: Transaction.() -> T): T = transaction { block() }
}
@@ -118,6 +118,7 @@ object UserStarsTable : Table("user_stars") {
val itemType = varchar("item_type", 16)
val itemId = varchar("item_id", 32)
val starredAt = varchar("starred_at", 40)
val rating = integer("rating").nullable()
override val primaryKey = PrimaryKey(userName, itemType, itemId)
}
@@ -0,0 +1,114 @@
package win.taptap.musicmanager.subsonic.models
import kotlinx.serialization.json.JsonArray
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.JsonPrimitive
import kotlinx.serialization.json.add
import kotlinx.serialization.json.buildJsonArray
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.put
import win.taptap.musicmanager.db.AlbumRecord
import win.taptap.musicmanager.db.ArtistRecord
import win.taptap.musicmanager.db.SongRecord
import win.taptap.musicmanager.util.IdGenerator
const val IGNORED_ARTICLES = "The El La Los Las Le Les"
fun songJson(song: SongRecord): JsonObject = buildJsonObject {
put("id", song.id)
put("parent", song.albumId)
put("isDir", false)
put("title", song.title)
put("album", song.albumName)
put("artist", song.artistName)
put("displayArtist", song.displayArtist)
song.trackNumber?.let { put("track", it) }
song.year?.let { put("year", it) }
song.genres.firstOrNull()?.let { put("genre", it) }
song.coverArt?.let { put("coverArt", it) }
put("size", song.size)
put("contentType", song.contentType)
put("suffix", song.suffix)
put("duration", song.duration)
put("bitRate", song.bitRate)
put("path", song.relativePath)
put("isVideo", false)
put("type", "music")
put("albumId", song.albumId)
song.artistId?.let { put("artistId", it) }
put("discNumber", song.discNumber)
put("created", song.created)
put("playCount", song.playCount)
song.starredAt?.let { put("starred", it) }
song.rating?.let { put("userRating", it) }
put("artists", buildJsonArray {
song.artists.forEach { artist ->
add(buildJsonObject {
put("id", artist.id)
put("name", artist.name)
})
}
})
put("genres", stringArray(song.genres))
}
fun albumJson(album: AlbumRecord, songs: List<SongRecord>? = null): JsonObject = buildJsonObject {
put("id", album.id)
put("name", album.name)
album.artistName?.let { put("artist", it) }
album.artistId?.let { put("artistId", it) }
album.coverArt?.let { put("coverArt", it) }
put("songCount", album.songCount)
put("duration", album.duration)
put("playCount", album.playCount)
put("created", album.created)
album.year?.let { put("year", it) }
album.genres.firstOrNull()?.let { put("genre", it) }
album.starredAt?.let { put("starred", it) }
album.rating?.let { put("userRating", it) }
put("genres", stringArray(album.genres))
songs?.let { list ->
put("song", buildJsonArray { list.forEach { add(songJson(it)) } })
}
}
fun artistJson(artist: ArtistRecord, albums: List<AlbumRecord>? = null): JsonObject = buildJsonObject {
put("id", artist.id)
put("name", artist.name)
put("albumCount", artist.albumCount)
put("sortName", artist.sortName)
artist.starredAt?.let { put("starred", it) }
artist.rating?.let { put("userRating", it) }
albums?.let { list ->
put("album", buildJsonArray { list.forEach { add(albumJson(it)) } })
}
}
fun artistIndexArray(artists: List<ArtistRecord>): JsonArray {
val groups = artists.groupBy { indexLetter(it.sortName) }
val keys = groups.keys.sortedWith(compareBy { if (it == "#") "\uFFFF" else it })
return buildJsonArray {
keys.forEach { key ->
add(buildJsonObject {
put("name", key)
put("artist", buildJsonArray {
groups.getValue(key)
.sortedBy { IdGenerator.normalize(it.sortName) }
.forEach { add(artistJson(it)) }
})
})
}
}
}
private fun indexLetter(sortName: String): String {
val first = IdGenerator.normalize(sortName).firstOrNull() ?: return "#"
return if (first.isLetter()) first.uppercaseChar().toString() else "#"
}
private fun stringArray(values: List<String>): JsonArray = buildJsonArray {
values.forEach { add(JsonPrimitive(it)) }
}
@@ -0,0 +1,167 @@
package win.taptap.musicmanager.subsonic.routes
import io.ktor.http.Parameters
import io.ktor.server.application.ApplicationCall
import io.ktor.server.routing.Route
import kotlinx.serialization.json.buildJsonArray
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.put
import win.taptap.musicmanager.config.LibraryConfig
import win.taptap.musicmanager.config.UsersConfig
import win.taptap.musicmanager.db.LibraryRepository
import win.taptap.musicmanager.subsonic.models.IGNORED_ARTICLES
import win.taptap.musicmanager.subsonic.models.albumJson
import win.taptap.musicmanager.subsonic.models.artistIndexArray
import win.taptap.musicmanager.subsonic.models.artistJson
import win.taptap.musicmanager.subsonic.models.songJson
import win.taptap.musicmanager.subsonic.respondSubsonic
import win.taptap.musicmanager.subsonic.respondSubsonicError
fun Route.browsingRoutes(users: UsersConfig, library: LibraryConfig) {
subsonicGet(users, "/getMusicFolders") { call, user ->
val visible = user.visibleFolderIds(library)
call.respondSubsonic(
buildJsonObject {
put("musicFolders", buildJsonObject {
put("musicFolder", buildJsonArray {
library.folders
.filter { it.id in visible }
.sortedBy { it.id }
.forEach { folder ->
add(buildJsonObject {
put("id", folder.id)
put("name", folder.name)
})
}
})
})
},
)
}
subsonicGet(users, "/getIndexes") { call, user ->
val artists = LibraryRepository.artists(user.visibleFolderIds(library), user.name)
call.respondSubsonic(
buildJsonObject {
put("indexes", buildJsonObject {
put("ignoredArticles", IGNORED_ARTICLES)
put("lastModified", 0)
put("index", artistIndexArray(artists))
})
},
)
}
subsonicGet(users, "/getArtists") { call, user ->
val artists = LibraryRepository.artists(user.visibleFolderIds(library), user.name)
call.respondSubsonic(
buildJsonObject {
put("artists", buildJsonObject {
put("ignoredArticles", IGNORED_ARTICLES)
put("index", artistIndexArray(artists))
})
},
)
}
subsonicGet(users, "/getArtist") { call, user ->
val id = call.subsonicParams()["id"]
if (id.isNullOrBlank()) {
call.respondSubsonicError(10, "Required parameter is missing: id")
return@subsonicGet
}
val folders = user.visibleFolderIds(library)
val artist = LibraryRepository.artist(id, folders, user.name)
if (artist == null) {
call.respondSubsonicError(70, "Artist not found")
return@subsonicGet
}
val albums = LibraryRepository.albumsForArtist(id, folders, user.name)
call.respondSubsonic(buildJsonObject { put("artist", artistJson(artist, albums)) })
}
subsonicGet(users, "/getAlbum") { call, user ->
val id = call.subsonicParams()["id"]
if (id.isNullOrBlank()) {
call.respondSubsonicError(10, "Required parameter is missing: id")
return@subsonicGet
}
val folders = user.visibleFolderIds(library)
val album = LibraryRepository.album(id, folders, user.name)
if (album == null) {
call.respondSubsonicError(70, "Album not found")
return@subsonicGet
}
val songs = LibraryRepository.albumSongs(id, folders, user.name)
call.respondSubsonic(buildJsonObject { put("album", albumJson(album, songs)) })
}
subsonicGet(users, "/getSong") { call, user ->
val id = call.subsonicParams()["id"]
if (id.isNullOrBlank()) {
call.respondSubsonicError(10, "Required parameter is missing: id")
return@subsonicGet
}
val song = LibraryRepository.song(id, user.visibleFolderIds(library), user.name)
if (song == null) {
call.respondSubsonicError(70, "Song not found")
return@subsonicGet
}
call.respondSubsonic(buildJsonObject { put("song", songJson(song)) })
}
subsonicGet(users, "/search3") { call, user ->
val parameters = call.subsonicParams()
val query = parameters["query"].orEmpty()
val folders = user.visibleFolderIds(library)
val all = query.isBlank() || query == "*"
val artistCount = parameters.intParam("artistCount", 20)
val artistOffset = parameters.intParam("artistOffset", 0, minimum = 0)
val albumCount = parameters.intParam("albumCount", 20)
val albumOffset = parameters.intParam("albumOffset", 0, minimum = 0)
val songCount = parameters.intParam("songCount", 20)
val songOffset = parameters.intParam("songOffset", 0, minimum = 0)
val artists = if (all) {
LibraryRepository.artists(folders, user.name)
.drop(artistOffset)
.take(artistCount)
} else {
LibraryRepository.searchArtists(query, artistCount, artistOffset, folders, user.name)
}
val albums = if (all) {
LibraryRepository.allAlbums(albumCount, albumOffset, folders, user.name)
} else {
LibraryRepository.searchAlbums(query, albumCount, albumOffset, folders, user.name)
}
val songs = if (all) {
LibraryRepository.allSongs(songCount, songOffset, folders, user.name)
} else {
LibraryRepository.searchSongs(query, songCount, songOffset, folders, user.name)
}
call.respondSubsonic(
buildJsonObject {
put("searchResult3", buildJsonObject {
put("artist", buildJsonArray { artists.forEach { add(artistJson(it)) } })
put("album", buildJsonArray { albums.forEach { add(albumJson(it)) } })
put("song", buildJsonArray { songs.forEach { add(songJson(it)) } })
})
},
)
}
}
private fun Parameters.intParam(name: String, default: Int, minimum: Int = 0): Int {
val raw = this[name] ?: return default
val parsed = raw.toIntOrNull() ?: return default
return parsed.coerceIn(minimum, 500)
}
@@ -0,0 +1,117 @@
package win.taptap.musicmanager.subsonic.routes
import io.ktor.http.HttpHeaders
import io.ktor.http.HttpStatusCode
import io.ktor.server.response.respond
import io.ktor.server.response.respondFile
import io.ktor.server.routing.Route
import java.net.URLEncoder
import win.taptap.musicmanager.config.LibraryConfig
import win.taptap.musicmanager.config.UsersConfig
import win.taptap.musicmanager.db.LibraryRepository
import win.taptap.musicmanager.scanner.CoverArtService
import win.taptap.musicmanager.subsonic.respondSubsonicError
fun Route.mediaRoutes(
users: UsersConfig,
library: LibraryConfig,
coverArtService: CoverArtService,
) {
subsonicGet(users, "/stream") { call, user ->
val id = call.subsonicParams()["id"]
if (id.isNullOrBlank()) {
call.respondSubsonicError(10, "Required parameter is missing: id")
return@subsonicGet
}
val resolved = LibraryRepository.resolveSong(
id,
user.visibleFolderIds(library),
user.name,
library,
)
if (resolved == null) {
call.respondSubsonicError(70, "Song not found")
return@subsonicGet
}
call.respondFile(resolved.file.toFile())
}
subsonicGet(users, "/download") { call, user ->
val id = call.subsonicParams()["id"]
if (id.isNullOrBlank()) {
call.respondSubsonicError(10, "Required parameter is missing: id")
return@subsonicGet
}
val resolved = LibraryRepository.resolveSong(
id,
user.visibleFolderIds(library),
user.name,
library,
)
if (resolved == null) {
call.respondSubsonicError(70, "Song not found")
return@subsonicGet
}
call.response.headers.append(
HttpHeaders.ContentDisposition,
contentDisposition(resolved.file.fileName.toString()),
)
call.respondFile(resolved.file.toFile())
}
subsonicGet(users, "/getCoverArt") { call, user ->
val parameters = call.subsonicParams()
val id = parameters["id"]
if (id.isNullOrBlank()) {
call.respondSubsonicError(10, "Required parameter is missing: id")
return@subsonicGet
}
val requestedSize = parameters["size"]
val size = requestedSize?.toIntOrNull()
if (requestedSize != null && (size == null || size !in 1..2048)) {
call.respondSubsonicError(10, "Invalid cover size")
return@subsonicGet
}
val folders = user.visibleFolderIds(library)
val albumId = if (id.startsWith("sg-")) {
LibraryRepository.albumIdForSong(id, folders)
} else if (LibraryRepository.album(id, folders, user.name) != null) {
id
} else {
null
}
if (albumId == null) {
call.respond(HttpStatusCode.NotFound)
return@subsonicGet
}
val cover = if (size == null) {
coverArtService.coverFile(albumId)
} else {
coverArtService.resizedCover(albumId, size)
}
if (cover == null) {
call.respond(HttpStatusCode.NotFound)
} else {
call.respondFile(cover.toFile())
}
}
}
private fun contentDisposition(fileName: String): String {
val encoded = URLEncoder.encode(fileName, Charsets.UTF_8).replace("+", "%20")
val ascii = fileName.map { character ->
if (character.code in 32..126 && character != '"' && character != '\\') character else '_'
}.joinToString("")
return "attachment; filename=\"$ascii\"; filename*=UTF-8''$encoded"
}
@@ -11,6 +11,11 @@ import io.ktor.util.AttributeKey
import win.taptap.musicmanager.config.UserAccount
val CurrentUserKey = AttributeKey<UserAccount>("musicmanager.currentUser")
val SubsonicParametersKey = AttributeKey<Parameters>("musicmanager.parameters")
/** Parameters captured during authentication, so POST bodies are only read once. */
fun ApplicationCall.subsonicParams(): Parameters =
attributes.getOrNull(SubsonicParametersKey) ?: request.queryParameters
/**
* Unified parameter access for Subsonic: query parameters plus URL-encoded form
@@ -28,6 +28,7 @@ internal fun Route.subsonicGet(
call.respondSubsonicError(40, "Wrong username or password")
} else {
call.attributes.put(CurrentUserKey, user)
call.attributes.put(SubsonicParametersKey, parameters)
handler(call, user)
}
}
@@ -2,16 +2,22 @@ package win.taptap.musicmanager.subsonic.routes
import io.ktor.server.routing.Route
import io.ktor.server.routing.route
import win.taptap.musicmanager.config.LibraryConfig
import win.taptap.musicmanager.config.UsersConfig
import win.taptap.musicmanager.scanner.CoverArtService
import win.taptap.musicmanager.scanner.ScanStatus
/** Authenticated `/rest` subtree. */
fun Route.subsonicRoutes(
users: UsersConfig,
library: LibraryConfig,
coverArtService: CoverArtService,
startScan: () -> Boolean,
scanStatus: () -> ScanStatus,
) {
route("/rest") {
systemRoutes(users, startScan, scanStatus)
browsingRoutes(users, library)
mediaRoutes(users, library, coverArtService)
}
}
@@ -0,0 +1,3 @@
-- Album and artist ratings are per user, like song ratings. Stars already live in
-- user_stars; add the missing rating column instead of duplicating the table.
ALTER TABLE user_stars ADD COLUMN rating INTEGER CHECK (rating IS NULL OR rating BETWEEN 1 AND 5);
@@ -37,7 +37,7 @@ class DatabaseFactoryTest {
}
}
}
assertEquals(1, migrations)
assertTrue(migrations >= 2, "Expected at least the V1 and V2 migrations")
} finally {
db.close()
}
@@ -0,0 +1,409 @@
package win.taptap.musicmanager.subsonic
import io.ktor.client.request.get
import io.ktor.client.request.header
import io.ktor.client.statement.bodyAsBytes
import io.ktor.client.statement.bodyAsText
import io.ktor.http.HttpHeaders
import io.ktor.http.HttpStatusCode
import io.ktor.serialization.kotlinx.json.json
import io.ktor.server.application.install
import io.ktor.server.plugins.contentnegotiation.ContentNegotiation
import io.ktor.server.plugins.partialcontent.PartialContent
import io.ktor.server.routing.routing
import io.ktor.server.testing.ApplicationTestBuilder
import io.ktor.server.testing.testApplication
import java.nio.file.Files
import java.nio.file.Path
import java.time.Instant
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.int
import kotlinx.serialization.json.jsonArray
import kotlinx.serialization.json.jsonObject
import kotlinx.serialization.json.jsonPrimitive
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertNotNull
import kotlin.test.assertTrue
import org.jetbrains.exposed.sql.insert
import org.jetbrains.exposed.sql.transactions.transaction
import org.junit.jupiter.api.io.TempDir
import win.taptap.musicmanager.TestAudio
import win.taptap.musicmanager.config.AppConfig
import win.taptap.musicmanager.config.FolderType
import win.taptap.musicmanager.config.LibraryConfig
import win.taptap.musicmanager.config.MusicFolder
import win.taptap.musicmanager.config.UserAccount
import win.taptap.musicmanager.config.UsersConfig
import win.taptap.musicmanager.db.AlbumArtistsTable
import win.taptap.musicmanager.db.AlbumGenresTable
import win.taptap.musicmanager.db.AlbumsTable
import win.taptap.musicmanager.db.ArtistsTable
import win.taptap.musicmanager.db.ConfigRepository
import win.taptap.musicmanager.db.DatabaseFactory
import win.taptap.musicmanager.db.DatabaseHandle
import win.taptap.musicmanager.db.MediaRepository
import win.taptap.musicmanager.db.SongArtistsTable
import win.taptap.musicmanager.db.SongGenresTable
import win.taptap.musicmanager.db.SongsTable
import win.taptap.musicmanager.scanner.CoverArtService
import win.taptap.musicmanager.scanner.ScanStatus
import win.taptap.musicmanager.subsonic.routes.subsonicRoutes
import win.taptap.musicmanager.util.IdGenerator
class BrowsingRoutesTest {
@TempDir
lateinit var tempDir: Path
@Test
fun `music folders are scoped to the user and long-form is shared`() {
seededContext().use { seed ->
testApplication {
setupApp(seed)
val alice = parseBody(client.get("/rest/getMusicFolders?${credentials("alice", "alice-pw")}").bodyAsText())
val aliceIds = folderIds(alice)
assertEquals(listOf(1, 10), aliceIds)
val bob = parseBody(client.get("/rest/getMusicFolders?${credentials("bob", "bob-pw")}").bodyAsText())
assertEquals(listOf(2, 10), folderIds(bob))
}
}
}
@Test
fun `artist and album browsing only exposes visible music`() {
seededContext().use { seed ->
testApplication {
setupApp(seed)
val artists = parseBody(client.get("/rest/getArtists?${credentials("alice", "alice-pw")}").bodyAsText())
val index = artists["artists"]!!.jsonObject["index"]!!.jsonArray
val names = index.flatMap { it.jsonObject["artist"]!!.jsonArray }
.map { it.jsonObject["name"]!!.jsonPrimitive.content }
assertEquals(listOf("Alice Artist"), names)
val artist = parseBody(
client.get("/rest/getArtist?${credentials("alice", "alice-pw")}&id=${seed.aliceArtistId}").bodyAsText(),
)
val albums = artist["artist"]!!.jsonObject["album"]!!.jsonArray
assertEquals(1, albums.size)
assertEquals(seed.aliceAlbumId, albums[0].jsonObject["id"]!!.jsonPrimitive.content)
val album = parseBody(
client.get("/rest/getAlbum?${credentials("alice", "alice-pw")}&id=${seed.aliceAlbumId}").bodyAsText(),
)
val songs = album["album"]!!.jsonObject["song"]!!.jsonArray
assertEquals(1, songs.size)
assertEquals(seed.aliceSongId, songs[0].jsonObject["id"]!!.jsonPrimitive.content)
assertEquals("mp3", songs[0].jsonObject["suffix"]!!.jsonPrimitive.content)
assertEquals("audio/mpeg", songs[0].jsonObject["contentType"]!!.jsonPrimitive.content)
val hidden = parseBody(
client.get("/rest/getSong?${credentials("alice", "alice-pw")}&id=${seed.bobSongId}").bodyAsText(),
)
assertEquals("failed", hidden["status"]!!.jsonPrimitive.content)
assertEquals(70, hidden["error"]!!.jsonObject["code"]!!.jsonPrimitive.int)
}
}
}
@Test
fun `search3 filters by query and supports empty and wildcard queries`() {
seededContext().use { seed ->
testApplication {
setupApp(seed)
val alice = parseSearch(
client.get("/rest/search3?${credentials("alice", "alice-pw")}&query=alice").bodyAsText(),
)
assertEquals(1, alice["artist"]!!.jsonArray.size)
assertEquals(1, alice["album"]!!.jsonArray.size)
assertEquals(1, alice["song"]!!.jsonArray.size)
val none = parseSearch(
client.get("/rest/search3?${credentials("alice", "alice-pw")}&query=nothing-matches").bodyAsText(),
)
assertEquals(0, none["artist"]!!.jsonArray.size)
assertEquals(0, none["album"]!!.jsonArray.size)
assertEquals(0, none["song"]!!.jsonArray.size)
val all = parseSearch(
client.get("/rest/search3?${credentials("bob", "bob-pw")}&query=*").bodyAsText(),
)
assertEquals(1, all["song"]!!.jsonArray.size)
assertEquals(seed.bobSongId, all["song"]!!.jsonArray[0].jsonObject["id"]!!.jsonPrimitive.content)
}
}
}
@Test
fun `streams and downloads the original file and serves covers`() {
seededContext().use { seed ->
testApplication {
setupApp(seed)
val stream = client.get("/rest/stream?${credentials("alice", "alice-pw")}&id=${seed.aliceSongId}")
assertEquals(HttpStatusCode.OK, stream.status)
assertEquals(seed.aliceAudioBytes.toList(), stream.bodyAsBytes().toList())
val ranged = client.get("/rest/stream?${credentials("alice", "alice-pw")}&id=${seed.aliceSongId}") {
header(HttpHeaders.Range, "bytes=0-3")
}
assertEquals(HttpStatusCode.PartialContent, ranged.status)
assertEquals(seed.aliceAudioBytes.take(4), ranged.bodyAsBytes().toList())
val download = client.get("/rest/download?${credentials("alice", "alice-pw")}&id=${seed.aliceSongId}")
assertEquals(HttpStatusCode.OK, download.status)
assertTrue(
download.headers["Content-Disposition"]!!
.contains("filename*=UTF-8''song.mp3"),
)
val cover = client.get(
"/rest/getCoverArt?${credentials("alice", "alice-pw")}&id=${seed.aliceAlbumId}&size=16",
)
assertEquals(HttpStatusCode.OK, cover.status)
assertTrue(cover.bodyAsBytes().isNotEmpty())
val otherUsersCover = client.get(
"/rest/getCoverArt?${credentials("bob", "bob-pw")}&id=${seed.aliceAlbumId}",
)
assertEquals(HttpStatusCode.NotFound, otherUsersCover.status)
val otherUsersSong = parseBody(
client.get("/rest/stream?${credentials("bob", "bob-pw")}&id=${seed.aliceSongId}").bodyAsText(),
)
assertEquals(70, otherUsersSong["error"]!!.jsonObject["code"]!!.jsonPrimitive.int)
}
}
}
@Test
fun `getSong returns the expected offline metadata`() {
seededContext().use { seed ->
testApplication {
setupApp(seed)
val song = parseBody(
client.get("/rest/getSong?${credentials("alice", "alice-pw")}&id=${seed.aliceSongId}").bodyAsText(),
)["song"]!!.jsonObject
assertEquals(seed.aliceSongId, song["id"]!!.jsonPrimitive.content)
assertEquals(seed.aliceAlbumId, song["albumId"]!!.jsonPrimitive.content)
assertEquals(seed.aliceArtistId, song["artistId"]!!.jsonPrimitive.content)
assertEquals(seed.aliceFileSize.toString(), song["size"]!!.jsonPrimitive.content)
assertEquals("Rock", song["genre"]!!.jsonPrimitive.content)
assertEquals(128, song["bitRate"]!!.jsonPrimitive.int)
assertEquals("music", song["type"]!!.jsonPrimitive.content)
}
}
}
private fun ApplicationTestBuilder.setupApp(seed: Seed) {
application {
install(ContentNegotiation) {
json(Json { ignoreUnknownKeys = true; encodeDefaults = true })
}
install(PartialContent)
routing {
subsonicRoutes(
users = seed.users,
library = seed.library,
coverArtService = seed.coverArt,
startScan = { false },
scanStatus = { ScanStatus(false, 0) },
)
}
}
}
private fun seededContext(): Seed {
val musicA = Files.createDirectories(tempDir.resolve("music-a"))
val musicB = Files.createDirectories(tempDir.resolve("music-b"))
val longform = Files.createDirectories(tempDir.resolve("longform"))
val library = LibraryConfig(
listOf(
MusicFolder(1, "Alice Music", FolderType.MUSIC, musicA),
MusicFolder(2, "Bob Music", FolderType.MUSIC, musicB),
MusicFolder(10, "Long-form", FolderType.LONGFORM, longform),
),
)
val users = UsersConfig(
listOf(
UserAccount("alice", "alice-pw", admin = true, folders = setOf(1)),
UserAccount("bob", "bob-pw", admin = false, folders = setOf(2)),
),
)
val db = DatabaseFactory.connect(
AppConfig(
port = 8080,
dataDir = tempDir.resolve("data"),
libraryConfigPath = tempDir.resolve("library.yaml"),
usersFile = tempDir.resolve("users.yaml"),
ffmpegPath = "ffmpeg",
),
)
ConfigRepository.sync(library, users)
val aliceAudio = musicA.resolve("Alice Artist/Alice Album/song.mp3")
Files.createDirectories(aliceAudio.parent)
val audioBytes = "ID3-fake-audio-payload".toByteArray()
Files.write(aliceAudio, audioBytes)
val bobAudio = musicB.resolve("Bob Artist/Bob Album/song.mp3")
Files.createDirectories(bobAudio.parent)
Files.write(bobAudio, "ID3-bob".toByteArray())
val alice = seedSong(
db = db,
folderId = 1,
artistName = "Alice Artist",
albumName = "Alice Album",
title = "Alice Song",
relativePath = "Alice Artist/Alice Album/song.mp3",
genre = "Rock",
fileSize = Files.size(aliceAudio),
)
val bob = seedSong(
db = db,
folderId = 2,
artistName = "Bob Artist",
albumName = "Bob Album",
title = "Bob Song",
relativePath = "Bob Artist/Bob Album/song.mp3",
genre = "Jazz",
fileSize = Files.size(bobAudio),
)
val coverArt = CoverArtService(tempDir.resolve("data"))
val coverPng = tempDir.resolve("cover.png")
TestAudio.writePng(coverPng, 64, 64)
coverArt.saveCover(alice.albumId, Files.readAllBytes(coverPng))
MediaRepository.setAlbumCover(alice.albumId)
return Seed(
db = db,
library = library,
users = users,
coverArt = coverArt,
aliceArtistId = alice.artistId,
aliceAlbumId = alice.albumId,
aliceSongId = alice.songId,
bobArtistId = bob.artistId,
bobAlbumId = bob.albumId,
bobSongId = bob.songId,
aliceAudioBytes = audioBytes,
aliceFileSize = Files.size(aliceAudio),
)
}
private fun seedSong(
db: DatabaseHandle,
folderId: Int,
artistName: String,
albumName: String,
title: String,
relativePath: String,
genre: String,
fileSize: Long,
): SeededSong {
val artistId = IdGenerator.artistId(artistName)
val albumId = IdGenerator.albumId(artistName, albumName)
val songId = IdGenerator.songId(folderId, relativePath)
val now = Instant.now().toString()
transaction(db.database) {
ArtistsTable.insert {
it[id] = artistId
it[name] = artistName
it[sortName] = artistName
it[searchText] = IdGenerator.normalize(artistName)
}
AlbumsTable.insert {
it[id] = albumId
it[name] = albumName
it[createdAt] = now
it[searchText] = IdGenerator.normalize("$albumName $artistName")
}
AlbumArtistsTable.insert {
it[this.albumId] = albumId
it[this.artistId] = artistId
it[position] = 0
}
SongsTable.insert {
it[id] = songId
it[this.albumId] = albumId
it[this.folderId] = folderId
it[this.title] = title
it[displayArtist] = artistName
it[this.albumName] = albumName
it[trackNumber] = 1
it[discNumber] = 1
it[year] = 2026
it[duration] = 120
it[bitRate] = 128
it[size] = fileSize
it[suffix] = "mp3"
it[contentType] = "audio/mpeg"
it[this.relativePath] = relativePath
it[fileMtime] = 0
it[createdAt] = now
it[searchText] = IdGenerator.normalize("$title $artistName $albumName $artistName")
}
SongArtistsTable.insert {
it[this.songId] = songId
it[this.artistId] = artistId
it[position] = 0
}
SongGenresTable.insert {
it[this.songId] = songId
it[this.genre] = genre
}
AlbumGenresTable.insert {
it[this.albumId] = albumId
it[this.genre] = genre
}
}
return SeededSong(artistId, albumId, songId)
}
private fun credentials(user: String, password: String): String {
val salt = "test-salt"
return "u=$user&t=${SubsonicAuthenticator.md5Hex(password + salt)}&s=$salt"
}
private fun parseBody(body: String): JsonObject =
Json.parseToJsonElement(body).jsonObject["subsonic-response"]!!.jsonObject
private fun parseSearch(body: String): JsonObject =
parseBody(body)["searchResult3"]!!.jsonObject
private fun folderIds(body: JsonObject): List<Int> =
body["musicFolders"]!!.jsonObject["musicFolder"]!!.jsonArray
.map { it.jsonObject["id"]!!.jsonPrimitive.int }
private data class SeededSong(val artistId: String, val albumId: String, val songId: String)
private data class Seed(
val db: DatabaseHandle,
val library: LibraryConfig,
val users: UsersConfig,
val coverArt: CoverArtService,
val aliceArtistId: String,
val aliceAlbumId: String,
val aliceSongId: String,
val bobArtistId: String,
val bobAlbumId: String,
val bobSongId: String,
val aliceAudioBytes: ByteArray,
val aliceFileSize: Long,
) : AutoCloseable {
override fun close() = db.close()
}
}
@@ -19,13 +19,21 @@ import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertFalse
import kotlin.test.assertTrue
import org.junit.jupiter.api.io.TempDir
import win.taptap.musicmanager.config.FolderType
import win.taptap.musicmanager.config.LibraryConfig
import win.taptap.musicmanager.config.MusicFolder
import win.taptap.musicmanager.config.UserAccount
import win.taptap.musicmanager.config.UsersConfig
import win.taptap.musicmanager.scanner.CoverArtService
import win.taptap.musicmanager.scanner.ScanStatus
import win.taptap.musicmanager.subsonic.routes.subsonicRoutes
class SystemRoutesTest {
@TempDir
lateinit var tempDir: java.nio.file.Path
@Test
fun `ping returns the OpenSubsonic envelope for both route variants`() = testApplication {
setupApp()
@@ -115,7 +123,15 @@ class SystemRoutesTest {
json(Json { ignoreUnknownKeys = true; encodeDefaults = true })
}
routing {
subsonicRoutes(users = users, startScan = startScan, scanStatus = scanStatus)
subsonicRoutes(
users = users,
library = LibraryConfig(
listOf(MusicFolder(1, "Music", FolderType.MUSIC, tempDir)),
),
coverArtService = CoverArtService(tempDir.resolve("data")),
startScan = startScan,
scanStatus = scanStatus,
)
}
}
}