From 18a1d7cd1976b8c5789250c3d6cece4c0a3415ed Mon Sep 17 00:00:00 2001 From: TapTap Date: Fri, 13 Nov 2026 12:53:06 +0000 Subject: [PATCH] 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 --- README.md | 2 +- scripts/smoke.sh | 22 +++++ .../win/taptap/musicmanager/Application.kt | 3 + .../subsonic/routes/MediaRoutes.kt | 53 ++++++++++- .../subsonic/routes/SubsonicRoutes.kt | 4 +- .../transcoding/FfmpegTranscoder.kt | 77 +++++++++++++++ .../subsonic/BrowsingRoutesTest.kt | 2 + .../musicmanager/subsonic/SystemRoutesTest.kt | 2 + .../transcoding/FfmpegTranscoderTest.kt | 93 +++++++++++++++++++ 9 files changed, 254 insertions(+), 4 deletions(-) create mode 100644 src/main/kotlin/win/taptap/musicmanager/transcoding/FfmpegTranscoder.kt create mode 100644 src/test/kotlin/win/taptap/musicmanager/transcoding/FfmpegTranscoderTest.kt diff --git a/README.md b/README.md index 4f5c69a..3602f8e 100644 --- a/README.md +++ b/README.md @@ -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] 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`). -- [ ] 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. - [ ] 7. **Packaging:** multi-stage Dockerfile (with ffmpeg), Helm chart, Gitea Actions workflow. - [ ] 8. **Tests:** integration suite as described above, plus a `curl` smoke script. diff --git a/scripts/smoke.sh b/scripts/smoke.sh index aa0ae58..89ab133 100755 --- a/scripts/smoke.sh +++ b/scripts/smoke.sh @@ -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")" 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")" if [[ "$DOWNLOAD_STATUS" == "200" ]]; then pass "download"; else fail "download" "HTTP $DOWNLOAD_STATUS"; fi diff --git a/src/main/kotlin/win/taptap/musicmanager/Application.kt b/src/main/kotlin/win/taptap/musicmanager/Application.kt index 1da3fc2..ff9e382 100644 --- a/src/main/kotlin/win/taptap/musicmanager/Application.kt +++ b/src/main/kotlin/win/taptap/musicmanager/Application.kt @@ -34,6 +34,7 @@ import win.taptap.musicmanager.scanner.CoverArtService import win.taptap.musicmanager.scanner.MediaScanner import win.taptap.musicmanager.subsonic.respondSubsonicError import win.taptap.musicmanager.subsonic.routes.subsonicRoutes +import win.taptap.musicmanager.transcoding.FfmpegTranscoder private val log = LoggerFactory.getLogger("win.taptap.musicmanager.Application") @@ -49,6 +50,7 @@ fun main() { val applicationScope = CoroutineScope(SupervisorJob() + Dispatchers.IO) val coverArtService = CoverArtService(config.dataDir) + val transcoder = FfmpegTranscoder(config.ffmpegPath) val scanner = MediaScanner(library, coverArtService) if (MediaRepository.countSongs() == 0L) { log.info("Song table is empty, starting initial library scan") @@ -95,6 +97,7 @@ fun main() { users = users, library = library, coverArtService = coverArtService, + transcoder = transcoder, startScan = { scanner.start(applicationScope) }, scanStatus = { scanner.status() }, ) diff --git a/src/main/kotlin/win/taptap/musicmanager/subsonic/routes/MediaRoutes.kt b/src/main/kotlin/win/taptap/musicmanager/subsonic/routes/MediaRoutes.kt index 5548722..c75cb42 100644 --- a/src/main/kotlin/win/taptap/musicmanager/subsonic/routes/MediaRoutes.kt +++ b/src/main/kotlin/win/taptap/musicmanager/subsonic/routes/MediaRoutes.kt @@ -1,30 +1,56 @@ package win.taptap.musicmanager.subsonic.routes +import io.ktor.http.ContentType 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.response.respondOutputStream import io.ktor.server.routing.Route 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.UsersConfig import win.taptap.musicmanager.db.LibraryRepository import win.taptap.musicmanager.scanner.CoverArtService import win.taptap.musicmanager.subsonic.respondSubsonicError +import win.taptap.musicmanager.transcoding.FfmpegTranscoder + +private val log = LoggerFactory.getLogger("win.taptap.musicmanager.MediaRoutes") fun Route.mediaRoutes( users: UsersConfig, library: LibraryConfig, coverArtService: CoverArtService, + transcoder: FfmpegTranscoder, ) { subsonicEndpoint(users, "/stream") { call, user -> - val id = call.subsonicParams()["id"] + val parameters = call.subsonicParams() + val id = parameters["id"] if (id.isNullOrBlank()) { call.respondSubsonicError(10, "Required parameter is missing: id") 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( id, user.visibleFolderIds(library), @@ -36,7 +62,30 @@ fun Route.mediaRoutes( 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 -> diff --git a/src/main/kotlin/win/taptap/musicmanager/subsonic/routes/SubsonicRoutes.kt b/src/main/kotlin/win/taptap/musicmanager/subsonic/routes/SubsonicRoutes.kt index 32bc13b..5cd99d0 100644 --- a/src/main/kotlin/win/taptap/musicmanager/subsonic/routes/SubsonicRoutes.kt +++ b/src/main/kotlin/win/taptap/musicmanager/subsonic/routes/SubsonicRoutes.kt @@ -6,19 +6,21 @@ import win.taptap.musicmanager.config.LibraryConfig import win.taptap.musicmanager.config.UsersConfig import win.taptap.musicmanager.scanner.CoverArtService import win.taptap.musicmanager.scanner.ScanStatus +import win.taptap.musicmanager.transcoding.FfmpegTranscoder /** Authenticated `/rest` subtree. */ fun Route.subsonicRoutes( users: UsersConfig, library: LibraryConfig, coverArtService: CoverArtService, + transcoder: FfmpegTranscoder, startScan: () -> Boolean, scanStatus: () -> ScanStatus, ) { route("/rest") { systemRoutes(users, library, startScan, scanStatus) browsingRoutes(users, library) - mediaRoutes(users, library, coverArtService) + mediaRoutes(users, library, coverArtService, transcoder) interactionRoutes(users, library) playlistRoutes(users, library) playQueueRoutes(users, library) diff --git a/src/main/kotlin/win/taptap/musicmanager/transcoding/FfmpegTranscoder.kt b/src/main/kotlin/win/taptap/musicmanager/transcoding/FfmpegTranscoder.kt new file mode 100644 index 0000000..78caa6c --- /dev/null +++ b/src/main/kotlin/win/taptap/musicmanager/transcoding/FfmpegTranscoder.kt @@ -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() + } + } +} diff --git a/src/test/kotlin/win/taptap/musicmanager/subsonic/BrowsingRoutesTest.kt b/src/test/kotlin/win/taptap/musicmanager/subsonic/BrowsingRoutesTest.kt index 454749d..e496059 100644 --- a/src/test/kotlin/win/taptap/musicmanager/subsonic/BrowsingRoutesTest.kt +++ b/src/test/kotlin/win/taptap/musicmanager/subsonic/BrowsingRoutesTest.kt @@ -53,6 +53,7 @@ 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.transcoding.FfmpegTranscoder import win.taptap.musicmanager.util.IdGenerator class BrowsingRoutesTest { @@ -420,6 +421,7 @@ class BrowsingRoutesTest { users = seed.users, library = seed.library, coverArtService = seed.coverArt, + transcoder = FfmpegTranscoder("ffmpeg"), startScan = { false }, scanStatus = { ScanStatus(false, 0) }, ) diff --git a/src/test/kotlin/win/taptap/musicmanager/subsonic/SystemRoutesTest.kt b/src/test/kotlin/win/taptap/musicmanager/subsonic/SystemRoutesTest.kt index 48698e2..337b0dc 100644 --- a/src/test/kotlin/win/taptap/musicmanager/subsonic/SystemRoutesTest.kt +++ b/src/test/kotlin/win/taptap/musicmanager/subsonic/SystemRoutesTest.kt @@ -28,6 +28,7 @@ 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 +import win.taptap.musicmanager.transcoding.FfmpegTranscoder class SystemRoutesTest { @@ -178,6 +179,7 @@ class SystemRoutesTest { listOf(MusicFolder(1, "Music", FolderType.MUSIC, tempDir)), ), coverArtService = CoverArtService(tempDir.resolve("data")), + transcoder = FfmpegTranscoder("ffmpeg"), startScan = startScan, scanStatus = scanStatus, ) diff --git a/src/test/kotlin/win/taptap/musicmanager/transcoding/FfmpegTranscoderTest.kt b/src/test/kotlin/win/taptap/musicmanager/transcoding/FfmpegTranscoderTest.kt new file mode 100644 index 0000000..5fd2fd1 --- /dev/null +++ b/src/test/kotlin/win/taptap/musicmanager/transcoding/FfmpegTranscoderTest.kt @@ -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) +}