feat: transcode streams with ffmpeg

- FfmpegTranscoder with maxBitRate, format fallback to MP3 and timeOffset
- direct play when no transcode is required, preserving HTTP Range support
- transcoded responses are chunked audio/mpeg with process cleanup
- unit tests for policy and real ffmpeg output
- smoke test covers maxBitRate, timeOffset and format fallback
This commit is contained in:
TapTap committed 2026-11-13 12:53:06 +00:00
1 parent 722f486c3a
commit 18a1d7cd19
9 files changed
+254 -4

No files matched your search

+1 -1
View File
@@ -694,7 +694,7 @@ Verify each step with `./gradlew test` and/or `curl`:
- [x] 2. **Scanner & covers:** `IdGenerator.kt`, `Mp3TagExtractor.kt`, `CoverArtService.kt`, `MediaScanner.kt` (delta + orphan cleanup + startup scan when empty). - [x] 2. **Scanner & covers:** `IdGenerator.kt`, `Mp3TagExtractor.kt`, `CoverArtService.kt`, `MediaScanner.kt` (delta + orphan cleanup + startup scan when empty).
- [x] 3. **Ktor core & auth:** `PartialContent`, content negotiation (`ignoreUnknownKeys`, `encodeDefaults`), `SubsonicAuth`, response wrapper, health endpoint. - [x] 3. **Ktor core & auth:** `PartialContent`, content negotiation (`ignoreUnknownKeys`, `encodeDefaults`), `SubsonicAuth`, response wrapper, health endpoint.
- [x] 4. **Browsing & media:** system, browsing, genre and media routes (`stream`, `download`, `getCoverArt`). - [x] 4. **Browsing & media:** system, browsing, genre and media routes (`stream`, `download`, `getCoverArt`).
- [ ] 5. **Transcoding:** `FfmpegTranscoder.kt`, `maxBitRate`/`format`/`timeOffset`, extension declaration. - [x] 5. **Transcoding:** `FfmpegTranscoder.kt`, `maxBitRate`/`format`/`timeOffset`, extension declaration.
- [x] 6. **Interaction & playlists:** `getAlbumList2`, `getRandomSongs`, `getStarred2`, `search3`, `scrobble`, `star`/`unstar`, `setRating`, bookmarks, playlists. - [x] 6. **Interaction & playlists:** `getAlbumList2`, `getRandomSongs`, `getStarred2`, `search3`, `scrobble`, `star`/`unstar`, `setRating`, bookmarks, playlists.
- [ ] 7. **Packaging:** multi-stage Dockerfile (with ffmpeg), Helm chart, Gitea Actions workflow. - [ ] 7. **Packaging:** multi-stage Dockerfile (with ffmpeg), Helm chart, Gitea Actions workflow.
- [ ] 8. **Tests:** integration suite as described above, plus a `curl` smoke script. - [ ] 8. **Tests:** integration suite as described above, plus a `curl` smoke script.
+22
View File
@@ -208,6 +208,28 @@ fi
RANGE_STATUS="$(curl -s -o /dev/null -w '%{http_code}' -H 'Range: bytes=0-9' "$BASE/rest/stream.view?$AUTH&id=$SONG_ID")" RANGE_STATUS="$(curl -s -o /dev/null -w '%{http_code}' -H 'Range: bytes=0-9' "$BASE/rest/stream.view?$AUTH&id=$SONG_ID")"
if [[ "$RANGE_STATUS" == "206" ]]; then pass "stream range"; else fail "stream range" "HTTP $RANGE_STATUS"; fi if [[ "$RANGE_STATUS" == "206" ]]; then pass "stream range"; else fail "stream range" "HTTP $RANGE_STATUS"; fi
TRANSCODE_STATUS="$(curl -s -D "$WORK/transcode.headers" -o "$WORK/transcoded.mp3" -w '%{http_code}' "$BASE/rest/stream.view?$AUTH&id=$SONG_ID&maxBitRate=64")"
if [[ "$TRANSCODE_STATUS" == "200" && -s "$WORK/transcoded.mp3" ]] \
&& grep -qi '^content-type: audio/mpeg' "$WORK/transcode.headers"; then
pass "stream transcode (maxBitRate)"
else
fail "stream transcode (maxBitRate)" "HTTP $TRANSCODE_STATUS, $(wc -c < "$WORK/transcoded.mp3" 2>/dev/null || echo 0) bytes"
fi
OFFSET_STATUS="$(curl -s -o "$WORK/offset.mp3" -w '%{http_code}' "$BASE/rest/stream.view?$AUTH&id=$SONG_ID&timeOffset=1")"
if [[ "$OFFSET_STATUS" == "200" && -s "$WORK/offset.mp3" ]]; then
pass "stream transcode (timeOffset)"
else
fail "stream transcode (timeOffset)" "HTTP $OFFSET_STATUS"
fi
FORMAT_STATUS="$(curl -s -o "$WORK/format.mp3" -w '%{http_code}' "$BASE/rest/stream.view?$AUTH&id=$SONG_ID&format=flac")"
if [[ "$FORMAT_STATUS" == "200" && -s "$WORK/format.mp3" ]]; then
pass "stream transcode (format fallback)"
else
fail "stream transcode (format fallback)" "HTTP $FORMAT_STATUS"
fi
DOWNLOAD_STATUS="$(curl -s -o /dev/null -w '%{http_code}' "$BASE/rest/download.view?$AUTH&id=$SONG_ID")" DOWNLOAD_STATUS="$(curl -s -o /dev/null -w '%{http_code}' "$BASE/rest/download.view?$AUTH&id=$SONG_ID")"
if [[ "$DOWNLOAD_STATUS" == "200" ]]; then pass "download"; else fail "download" "HTTP $DOWNLOAD_STATUS"; fi if [[ "$DOWNLOAD_STATUS" == "200" ]]; then pass "download"; else fail "download" "HTTP $DOWNLOAD_STATUS"; fi
@@ -34,6 +34,7 @@ import win.taptap.musicmanager.scanner.CoverArtService
import win.taptap.musicmanager.scanner.MediaScanner import win.taptap.musicmanager.scanner.MediaScanner
import win.taptap.musicmanager.subsonic.respondSubsonicError import win.taptap.musicmanager.subsonic.respondSubsonicError
import win.taptap.musicmanager.subsonic.routes.subsonicRoutes import win.taptap.musicmanager.subsonic.routes.subsonicRoutes
import win.taptap.musicmanager.transcoding.FfmpegTranscoder
private val log = LoggerFactory.getLogger("win.taptap.musicmanager.Application") private val log = LoggerFactory.getLogger("win.taptap.musicmanager.Application")
@@ -49,6 +50,7 @@ fun main() {
val applicationScope = CoroutineScope(SupervisorJob() + Dispatchers.IO) val applicationScope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
val coverArtService = CoverArtService(config.dataDir) val coverArtService = CoverArtService(config.dataDir)
val transcoder = FfmpegTranscoder(config.ffmpegPath)
val scanner = MediaScanner(library, coverArtService) val scanner = MediaScanner(library, coverArtService)
if (MediaRepository.countSongs() == 0L) { if (MediaRepository.countSongs() == 0L) {
log.info("Song table is empty, starting initial library scan") log.info("Song table is empty, starting initial library scan")
@@ -95,6 +97,7 @@ fun main() {
users = users, users = users,
library = library, library = library,
coverArtService = coverArtService, coverArtService = coverArtService,
transcoder = transcoder,
startScan = { scanner.start(applicationScope) }, startScan = { scanner.start(applicationScope) },
scanStatus = { scanner.status() }, scanStatus = { scanner.status() },
) )
@@ -1,30 +1,56 @@
package win.taptap.musicmanager.subsonic.routes package win.taptap.musicmanager.subsonic.routes
import io.ktor.http.ContentType
import io.ktor.http.HttpHeaders import io.ktor.http.HttpHeaders
import io.ktor.http.HttpStatusCode import io.ktor.http.HttpStatusCode
import io.ktor.server.response.respond import io.ktor.server.response.respond
import io.ktor.server.response.respondFile import io.ktor.server.response.respondFile
import io.ktor.server.response.respondOutputStream
import io.ktor.server.routing.Route import io.ktor.server.routing.Route
import java.net.URLEncoder import java.net.URLEncoder
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import org.slf4j.LoggerFactory
import win.taptap.musicmanager.config.LibraryConfig import win.taptap.musicmanager.config.LibraryConfig
import win.taptap.musicmanager.config.UsersConfig import win.taptap.musicmanager.config.UsersConfig
import win.taptap.musicmanager.db.LibraryRepository import win.taptap.musicmanager.db.LibraryRepository
import win.taptap.musicmanager.scanner.CoverArtService import win.taptap.musicmanager.scanner.CoverArtService
import win.taptap.musicmanager.subsonic.respondSubsonicError import win.taptap.musicmanager.subsonic.respondSubsonicError
import win.taptap.musicmanager.transcoding.FfmpegTranscoder
private val log = LoggerFactory.getLogger("win.taptap.musicmanager.MediaRoutes")
fun Route.mediaRoutes( fun Route.mediaRoutes(
users: UsersConfig, users: UsersConfig,
library: LibraryConfig, library: LibraryConfig,
coverArtService: CoverArtService, coverArtService: CoverArtService,
transcoder: FfmpegTranscoder,
) { ) {
subsonicEndpoint(users, "/stream") { call, user -> subsonicEndpoint(users, "/stream") { call, user ->
val id = call.subsonicParams()["id"] val parameters = call.subsonicParams()
val id = parameters["id"]
if (id.isNullOrBlank()) { if (id.isNullOrBlank()) {
call.respondSubsonicError(10, "Required parameter is missing: id") call.respondSubsonicError(10, "Required parameter is missing: id")
return@subsonicEndpoint return@subsonicEndpoint
} }
val rawMaxBitRate = parameters["maxBitRate"]
val maxBitRate = rawMaxBitRate?.toIntOrNull()
if (rawMaxBitRate != null && (maxBitRate == null || maxBitRate < 0)) {
call.respondSubsonicError(10, "Invalid maxBitRate")
return@subsonicEndpoint
}
val rawTimeOffset = parameters["timeOffset"]
val timeOffset = rawTimeOffset?.toIntOrNull()
if (rawTimeOffset != null && (timeOffset == null || timeOffset < 0)) {
call.respondSubsonicError(10, "Invalid timeOffset")
return@subsonicEndpoint
}
val offset = timeOffset ?: 0
val format = parameters["format"]
val resolved = LibraryRepository.resolveSong( val resolved = LibraryRepository.resolveSong(
id, id,
user.visibleFolderIds(library), user.visibleFolderIds(library),
@@ -36,7 +62,30 @@ fun Route.mediaRoutes(
return@subsonicEndpoint return@subsonicEndpoint
} }
call.respondFile(resolved.file.toFile()) if (!transcoder.shouldTranscode(resolved.song.bitRate, maxBitRate, format, offset)) {
call.respondFile(resolved.file.toFile())
return@subsonicEndpoint
}
val process = try {
transcoder.start(resolved.file, maxBitRate, offset)
} catch (e: Exception) {
log.error("Failed to start ffmpeg for {}", resolved.file, e)
call.respondSubsonicError(0, "Transcoding failed")
return@subsonicEndpoint
}
try {
call.response.headers.append(HttpHeaders.CacheControl, "no-store")
call.respondOutputStream(ContentType.parse("audio/mpeg")) {
val output = this
withContext(Dispatchers.IO) {
process.inputStream.use { input -> input.copyTo(output) }
}
}
} finally {
transcoder.stop(process)
}
} }
subsonicEndpoint(users, "/download") { call, user -> subsonicEndpoint(users, "/download") { call, user ->
@@ -6,19 +6,21 @@ import win.taptap.musicmanager.config.LibraryConfig
import win.taptap.musicmanager.config.UsersConfig import win.taptap.musicmanager.config.UsersConfig
import win.taptap.musicmanager.scanner.CoverArtService import win.taptap.musicmanager.scanner.CoverArtService
import win.taptap.musicmanager.scanner.ScanStatus import win.taptap.musicmanager.scanner.ScanStatus
import win.taptap.musicmanager.transcoding.FfmpegTranscoder
/** Authenticated `/rest` subtree. */ /** Authenticated `/rest` subtree. */
fun Route.subsonicRoutes( fun Route.subsonicRoutes(
users: UsersConfig, users: UsersConfig,
library: LibraryConfig, library: LibraryConfig,
coverArtService: CoverArtService, coverArtService: CoverArtService,
transcoder: FfmpegTranscoder,
startScan: () -> Boolean, startScan: () -> Boolean,
scanStatus: () -> ScanStatus, scanStatus: () -> ScanStatus,
) { ) {
route("/rest") { route("/rest") {
systemRoutes(users, library, startScan, scanStatus) systemRoutes(users, library, startScan, scanStatus)
browsingRoutes(users, library) browsingRoutes(users, library)
mediaRoutes(users, library, coverArtService) mediaRoutes(users, library, coverArtService, transcoder)
interactionRoutes(users, library) interactionRoutes(users, library)
playlistRoutes(users, library) playlistRoutes(users, library)
playQueueRoutes(users, library) playQueueRoutes(users, library)
@@ -0,0 +1,77 @@
package win.taptap.musicmanager.transcoding
import java.nio.file.Path
import java.util.concurrent.TimeUnit
import org.slf4j.LoggerFactory
/**
* MP3-to-MP3 transcoding through ffmpeg. The source library is MP3-only for now,
* so the target is always MP3 (`libmp3lame`); unsupported requested formats fall
* back to MP3 as documented.
*/
class FfmpegTranscoder(private val ffmpegPath: String) {
private val log = LoggerFactory.getLogger(FfmpegTranscoder::class.java)
/**
* Direct play is preferred whenever possible. We only invoke ffmpeg when the
* requested bitrate is lower than the source, a time offset is requested, or
* the client asked for a format we do not serve natively.
*/
fun shouldTranscode(
sourceBitRate: Int,
maxBitRate: Int?,
format: String?,
timeOffset: Int,
): Boolean {
val target = maxBitRate?.takeIf { it > 0 }
val needsBitRate = target != null && sourceBitRate > target
val needsOffset = timeOffset > 0
val needsFormat = !format.isNullOrBlank() &&
!format.equals("mp3", ignoreCase = true) &&
!format.equals("raw", ignoreCase = true)
return needsBitRate || needsOffset || needsFormat
}
/** Starts an ffmpeg process writing MP3 bytes to stdout. */
fun start(source: Path, maxBitRate: Int?, timeOffset: Int): Process {
val command = buildList {
add(ffmpegPath)
add("-hide_banner")
add("-loglevel")
add("error")
add("-nostdin")
if (timeOffset > 0) {
add("-ss")
add(timeOffset.toString())
}
add("-i")
add(source.toString())
add("-vn")
add("-map_metadata")
add("-1")
add("-c:a")
add("libmp3lame")
add("-f")
add("mp3")
maxBitRate?.takeIf { it > 0 }?.let {
add("-b:a")
add("${it.coerceIn(8, 320)}k")
}
add("pipe:1")
}
log.debug("Transcoding {} with: {}", source, command.joinToString(" "))
return ProcessBuilder(command)
.redirectError(ProcessBuilder.Redirect.DISCARD)
.start()
}
fun stop(process: Process) {
runCatching {
if (process.isAlive) process.destroy()
if (!process.waitFor(2, TimeUnit.SECONDS)) process.destroyForcibly()
}
}
}
@@ -53,6 +53,7 @@ import win.taptap.musicmanager.db.SongsTable
import win.taptap.musicmanager.scanner.CoverArtService import win.taptap.musicmanager.scanner.CoverArtService
import win.taptap.musicmanager.scanner.ScanStatus import win.taptap.musicmanager.scanner.ScanStatus
import win.taptap.musicmanager.subsonic.routes.subsonicRoutes import win.taptap.musicmanager.subsonic.routes.subsonicRoutes
import win.taptap.musicmanager.transcoding.FfmpegTranscoder
import win.taptap.musicmanager.util.IdGenerator import win.taptap.musicmanager.util.IdGenerator
class BrowsingRoutesTest { class BrowsingRoutesTest {
@@ -420,6 +421,7 @@ class BrowsingRoutesTest {
users = seed.users, users = seed.users,
library = seed.library, library = seed.library,
coverArtService = seed.coverArt, coverArtService = seed.coverArt,
transcoder = FfmpegTranscoder("ffmpeg"),
startScan = { false }, startScan = { false },
scanStatus = { ScanStatus(false, 0) }, scanStatus = { ScanStatus(false, 0) },
) )
@@ -28,6 +28,7 @@ import win.taptap.musicmanager.config.UsersConfig
import win.taptap.musicmanager.scanner.CoverArtService import win.taptap.musicmanager.scanner.CoverArtService
import win.taptap.musicmanager.scanner.ScanStatus import win.taptap.musicmanager.scanner.ScanStatus
import win.taptap.musicmanager.subsonic.routes.subsonicRoutes import win.taptap.musicmanager.subsonic.routes.subsonicRoutes
import win.taptap.musicmanager.transcoding.FfmpegTranscoder
class SystemRoutesTest { class SystemRoutesTest {
@@ -178,6 +179,7 @@ class SystemRoutesTest {
listOf(MusicFolder(1, "Music", FolderType.MUSIC, tempDir)), listOf(MusicFolder(1, "Music", FolderType.MUSIC, tempDir)),
), ),
coverArtService = CoverArtService(tempDir.resolve("data")), coverArtService = CoverArtService(tempDir.resolve("data")),
transcoder = FfmpegTranscoder("ffmpeg"),
startScan = startScan, startScan = startScan,
scanStatus = scanStatus, scanStatus = scanStatus,
) )
@@ -0,0 +1,93 @@
package win.taptap.musicmanager.transcoding
import java.nio.file.Files
import java.nio.file.Path
import java.util.concurrent.TimeUnit
import kotlin.test.Test
import kotlin.test.assertFalse
import kotlin.test.assertTrue
import org.junit.jupiter.api.Assumptions.assumeTrue
import org.junit.jupiter.api.io.TempDir
class FfmpegTranscoderTest {
@TempDir
lateinit var tempDir: Path
private val transcoder = FfmpegTranscoder("ffmpeg")
@Test
fun `direct play is used when no transcode is requested`() {
assertFalse(transcoder.shouldTranscode(320, null, null, 0))
assertFalse(transcoder.shouldTranscode(128, 0, "mp3", 0))
assertFalse(transcoder.shouldTranscode(128, 128, "mp3", 0))
assertFalse(transcoder.shouldTranscode(128, 320, "mp3", 0))
assertFalse(transcoder.shouldTranscode(128, null, "raw", 0))
}
@Test
fun `transcodes for lower bitrate time offsets and foreign formats`() {
assertTrue(transcoder.shouldTranscode(320, 128, null, 0))
assertTrue(transcoder.shouldTranscode(128, null, null, 30))
assertTrue(transcoder.shouldTranscode(128, null, "flac", 0))
assertTrue(transcoder.shouldTranscode(128, 96, "mp3", 10))
}
@Test
fun `ffmpeg produces mp3 bytes`() {
assumeTrue(ffmpegAvailable(), "ffmpeg is not installed")
val source = createMp3()
val process = transcoder.start(source, maxBitRate = 64, timeOffset = 0)
val bytes = process.inputStream.readBytes()
assertTrue(process.waitFor(10, TimeUnit.SECONDS))
assertTrue(bytes.isNotEmpty(), "transcoded output is empty")
// MP3 frames start with an 0xFF sync byte (or an ID3 header when metadata is kept).
assertTrue(bytes[0] == 0xFF.toByte() || bytes[0] == 'I'.code.toByte())
}
@Test
fun `time offset produces a shorter stream`() {
assumeTrue(ffmpegAvailable(), "ffmpeg is not installed")
val source = createMp3()
val full = transcoder.start(source, maxBitRate = 64, timeOffset = 0).let { process ->
val bytes = process.inputStream.readBytes()
process.waitFor(10, TimeUnit.SECONDS)
bytes
}
val offset = transcoder.start(source, maxBitRate = 64, timeOffset = 1).let { process ->
val bytes = process.inputStream.readBytes()
process.waitFor(10, TimeUnit.SECONDS)
bytes
}
assertTrue(full.isNotEmpty())
assertTrue(offset.isNotEmpty())
assertTrue(offset.size < full.size, "offset stream should be shorter")
}
private fun createMp3(): Path {
val target = tempDir.resolve("source.mp3")
val process = ProcessBuilder(
"ffmpeg", "-hide_banner", "-loglevel", "error", "-y",
"-f", "lavfi", "-i", "sine=frequency=440:duration=3",
"-metadata", "title=Transcode Test",
"-q:a", "9",
target.toString(),
).redirectError(ProcessBuilder.Redirect.DISCARD).start()
assertTrue(process.waitFor(20, TimeUnit.SECONDS))
assertTrue(Files.size(target) > 0)
return target
}
private fun ffmpegAvailable(): Boolean = runCatching {
val process = ProcessBuilder("ffmpeg", "-version")
.redirectErrorStream(true)
.start()
process.inputStream.readBytes()
process.waitFor(5, TimeUnit.SECONDS)
true
}.getOrDefault(false)
}