feat(subsonic): implement OpenSubsonic Transcoding extension (#4990)

* feat(subsonic): implement transcode decision logic and codec handling for media files Signed-off-by: Deluan <deluan@navidrome.org> * fix(subsonic): update codec limitation structure and decision logic for improved clarity Signed-off-by: Deluan <deluan@navidrome.org> * fix(transcoding): update bitrate handling to use kilobits per second (kbps) across transcode decision logic Signed-off-by: Deluan <deluan@navidrome.org> * refactor(transcoding): simplify container alias handling in matchesContainer function Signed-off-by: Deluan <deluan@navidrome.org> * fix(transcoding): enforce POST method for GetTranscodeDecision and handle non-POST requests Signed-off-by: Deluan <deluan@navidrome.org> * feat(transcoding): add enums for protocol, comparison operators, limitations, and codec profiles in transcode decision logic Signed-off-by: Deluan <deluan@navidrome.org> * refactor(transcoding): streamline limitation checks and applyLimitation logic for improved readability and maintainability Signed-off-by: Deluan <deluan@navidrome.org> * refactor(transcoding): replace strings.EqualFold with direct comparison for protocol and limitation checks Signed-off-by: Deluan <deluan@navidrome.org> * refactor(transcoding): rename token methods to CreateTranscodeParams and ParseTranscodeParams for clarity Signed-off-by: Deluan <deluan@navidrome.org> * refactor(transcoding): enhance logging for transcode decision process and client info conversion Signed-off-by: Deluan <deluan@navidrome.org> * refactor(transcoding): rename TranscodeDecision to Decider and update related methods for clarity Signed-off-by: Deluan <deluan@navidrome.org> * refactor(transcoding): enhance transcoding config lookup logic for audio codecs Signed-off-by: Deluan <deluan@navidrome.org> * refactor(transcoding): enhance transcoding options with sample rate support and improve command handling Signed-off-by: Deluan <deluan@navidrome.org> * refactor(transcoding): add bit depth support for audio transcoding and enhance related logic Signed-off-by: Deluan <deluan@navidrome.org> * refactor(transcoding): enhance AAC command handling and support for audio channels in streaming Signed-off-by: Deluan <deluan@navidrome.org> * refactor(transcoding): streamline transcoding logic by consolidating stream parameter handling and enhancing alias mapping Signed-off-by: Deluan <deluan@navidrome.org> * refactor(transcoding): update default command handling and add codec support for transcoding Signed-off-by: Deluan <deluan@navidrome.org> * fix: implement noopDecider for transcoding decision handling in tests Signed-off-by: Deluan <deluan@navidrome.org> * fix: address review findings for OpenSubsonic transcoding PR Fix multiple issues identified during code review of the transcoding extension: add missing return after error in shared stream handler preventing nil pointer panic, replace dead r.Body nil check with MaxBytesReader size limit, distinguish not-found from other DB errors, fix bpsToKbps integer truncation with rounding, add "pcm" to isLosslessFormat for consistency with model.IsLossless(), add sampleRate/bitDepth/channels to streaming log, fix outdated test comment, and add tests for conversion functions and GetTranscodeStream parameter passing. * feat(transcoding): add sourceUpdatedAt to decision and validate transcode parameters Signed-off-by: Deluan <deluan@navidrome.org> * fix: small issues Updated mock AAC transcoding command to use the new default (ipod with fragmented MP4) matching the migration, ensuring tests exercise the same buildDynamicArgs code path as production. Improved archiver test mock to match on the whole StreamRequest struct instead of decomposing fields, making it resilient to future field additions. Added named constants for JWT claim keys in the transcode token and wrapped ParseTranscodeParams errors with ErrTokenInvalid for consistency. Documented the IsLossless BitDepth fallback heuristic as temporary until Codec column is populated. Signed-off-by: Deluan <deluan@navidrome.org> * fix(transcoding): adapt transcode claims to struct-based auth.Claims Updated transcode token handling to use the struct-based auth.Claims introduced on master, replacing the previous map[string]any approach. Extended auth.Claims with transcoding-specific fields (MediaID, DirectPlay, UpdatedAt, Channels, SampleRate, BitDepth) and added float64 fallback in ClaimsFromToken for numeric claims that lose their Go type during JWT string serialization. Also added the missing lyrics parameter to all subsonic.New() calls in test files. * feat(model): add ProbeData field and UpdateProbeData repository method Add probe_data TEXT column to media_file for caching ffprobe results. Add UpdateProbeData to MediaFileRepository interface and implementations. Use hash:"ignore" tag so probe data doesn't affect MediaFile fingerprints. * feat(ffmpeg): add ProbeAudioStream for authoritative audio metadata Add ProbeAudioStream to FFmpeg interface, using ffprobe to extract codec, profile, bitrate, sample rate, bit depth, and channels. Parse bits_per_raw_sample as fallback for FLAC/ALAC bit depth. Normalize "unknown" profile to empty string. All parseProbeOutput tests use real ffprobe JSON from actual files. * feat(transcoding): integrate ffprobe into transcode decisions Add ensureProbed to probe media files on first transcode decision, caching results in probe_data. Build SourceStream from probe data with fallback to tag-based metadata. Refactor decision logic to pass StreamDetails instead of MediaFile, enabling codec profile limitations (e.g., audioProfile) to use probe data. Add normalizeProbeCodec to map ffprobe codec names (dsd_lsbf_planar, pcm_s16le) to internal names (dsd, pcm). NewDecider now accepts ffmpeg.FFmpeg; wire_gen.go regenerated. * feat(transcoding): add DevEnableMediaFileProbe config flag Add DevEnableMediaFileProbe (default true) to allow disabling ffprobe- based media file probing as a safety fallback. When disabled, the decider uses tag-based metadata from the scanner instead. * test(transcode): add ensureProbed unit tests Test probing when ProbeData is empty, skipping when already set, error propagation from ffprobe, and DevEnableMediaFileProbe flag. * refactor(ffmpeg): use command constant and select_streams for ProbeAudioStream Move ffprobe arguments to a probeAudioStreamCmd constant, following the same pattern as extractImageCmd and probeCmd. Add -select_streams a:0 to only probe the first audio stream, avoiding unnecessary parsing of video and artwork streams. Derive the ffprobe binary path safely using filepath.Dir/Base instead of replacing within the full path string. * refactor(transcode): decouple transcode token claims from auth.Claims Remove six transcode-specific fields (MediaID, DirectPlay, UpdatedAt, Channels, SampleRate, BitDepth) from auth.Claims, which is shared with session and share tokens. Transcode tokens are signed parameter-passing tokens, not authentication tokens, so coupling them to auth created misleading dependencies. The transcode package now owns its own JWT claim serialization via Decision.toClaimsMap() and paramsFromToken(), using generic auth.EncodeToken/DecodeAndVerifyToken wrappers that keep TokenAuth encapsulated. Wire format (JWT claim keys) is unchanged, so in-flight tokens remain compatible. Signed-off-by: Deluan <deluan@navidrome.org> * refactor(transcode): simplify code after review Extract getIntClaim helper to eliminate repeated int/int64/float64 JWT claim extraction pattern in paramsFromToken and ClaimsFromToken. Rewrite checkIntLimitation as a one-liner delegating to applyIntLimitation. Return probe result from ensureProbed to avoid redundant JSON round-trip. Extract toResponseStreamDetails helper and mediaTypeSong constant in the API layer, and use transcode.ProtocolHTTP constant instead of hardcoded string. Signed-off-by: Deluan <deluan@navidrome.org> * fix(ffmpeg): enhance bit_rate parsing logic for audio streams Signed-off-by: Deluan <deluan@navidrome.org> * fix(transcode): improve code review findings across transcode implementation - Fix parseProbeData to return nil on JSON unmarshal failure instead of a zero-valued struct, preventing silent degradation of source stream details - Use probe-resolved codec for lossless detection in buildSourceStream instead of the potentially stale scanner data - Remove MediaFile.IsLossless() (dead code) and consolidate lossless detection in isLosslessFormat(), using codec name only — bit depth is not reliable since lossy codecs like ADPCM report non-zero values - Add "wavpack" to lossless codec list (ffprobe codec_name for WavPack) - Guard bpsToKbps against negative input values - Fix misleading comment in buildTemplateArgs about conditional injection - Avoid leaking internal error details in Subsonic API responses - Add missing test for ErrNotFound branch in GetTranscodeDecision - Add TODO for hardcoded protocol in toResponseStreamDetails * refactor(transcode): streamline transcoding command lookup and format resolution Signed-off-by: Deluan <deluan@navidrome.org> * feat(transcode): implement server-side transcoding override for player formats Signed-off-by: Deluan <deluan@navidrome.org> * fix(transcode): honor bit depth and channel constraints in transcoding selection selectTranscodingOptions only checked sample rate when deciding whether same-format transcoding was needed, ignoring requested bit depth and channel reductions. This caused the streamer to return raw audio when the transcode decision requested downmix or bit-depth conversion. * refactor(transcode): unify streaming decision engine via MakeDecision Move transcoding decision-making out of mediaStreamer and into the subsonic Stream/Download handlers, using transcode.Decider.MakeDecision as the single decision engine. This eliminates selectTranscodingOptions and the mismatch between decision and streaming code paths (decision used LookupTranscodeCommand with built-in fallbacks, while streaming used FindByFormat which only checked the DB). - Add DecisionOptions with SkipProbe to MakeDecision so the legacy streaming path never calls ffprobe - Add buildLegacyClientInfo to translate legacy stream params (format, maxBitRate, DefaultDownsamplingFormat) into a synthetic ClientInfo - Add resolveStreamRequest on the subsonic Router to resolve legacy params into a fully specified StreamRequest via MakeDecision - Simplify DoStream to a dumb executor that receives pre-resolved params - Remove selectTranscodingOptions entirely Signed-off-by: Deluan <deluan@navidrome.org> * refactor(transcode): move MediaStreamer into core/transcode and unify StreamRequest Moved MediaStreamer, Stream, TranscodingCache and related types from core/media_streamer.go into core/transcode/, eliminating the duplicate StreamRequest type. The transcode.StreamRequest now carries all fields (ID, Format, BitRate, SampleRate, BitDepth, Channels, Offset) and ResolveStream returns a fully-populated value, removing manual field copying at every call site. Also moved buildLegacyClientInfo into the transcode package alongside ResolveStream, and unexported ParseTranscodeParams since it was only used internally by ValidateTranscodeParams. * refactor(transcode): rename Decider methods and unexport Params type Rename ResolveStream → ResolveRequest and ValidateTranscodeParams → ResolveRequestFromToken for clarity and consistency. The new ResolveRequestFromToken returns a StreamRequest directly (instead of the intermediate Params type), eliminating manual Params→StreamRequest conversion in callers. Unexport Params to params since it is now only used internally for JWT token parsing. * test(transcode): remove redundant tests and use constants Remove tests that duplicate coverage from integration-level tests (toClaimsMap, paramsFromToken round-trips, applyServerOverride direct call, duplicate 410 handler test). Replace raw "http" strings with ProtocolHTTP constant. Consolidate lossy -sample_fmt tests into DescribeTable. * refactor(transcode): split oversized files into focused modules Split transcode.go and transcode_test.go into focused files by concern: - decider.go: decision engine (MakeDecision, direct play/transcode evaluation, probe) - token.go: JWT token encode/decode (params, toClaimsMap, paramsFromToken, CreateTranscodeParams, ResolveRequestFromToken) - legacy_client.go: legacy Subsonic bridge (buildLegacyClientInfo, ResolveRequest) - codec_test.go: isLosslessFormat and normalizeProbeCodec tests - token_test.go: token round-trip and ResolveRequestFromToken tests Moved the Decider interface from types.go to decider.go to keep it near its implementation, and cleaned up types.go to contain only pure type definitions and constants. No public API changes. * refactor(transcode): reorder parameters in applyServerOverride function Signed-off-by: Deluan <deluan@navidrome.org> * test(e2e): add NewTestStream function and implement spyStreamer for testing Signed-off-by: Deluan <deluan@navidrome.org> --------- Signed-off-by: Deluan <deluan@navidrome.org>
2026-03-08 23:57:49 -04:00
parent e1b3412999
commit ae1e0ddb11
51 changed files with 4828 additions and 352 deletions
@@ -27,7 +27,7 @@ var _ = Describe("Album Lists", func() {
 		ds = &tests.MockDataStore{}
 		auth.Init(ds)
 		mockRepo = ds.Album(ctx).(*tests.MockAlbumRepo)
-		router = New(ds, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+		router = New(ds, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
 		w = httptest.NewRecorder()
 	})

@@ -19,6 +19,7 @@ import (
 	"github.com/navidrome/navidrome/core/playback"
 	playlistsvc "github.com/navidrome/navidrome/core/playlists"
 	"github.com/navidrome/navidrome/core/scrobbler"
+	"github.com/navidrome/navidrome/core/transcode"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/server"
@@ -36,42 +37,44 @@ type handlerRaw = func(http.ResponseWriter, *http.Request) (*responses.Subsonic,

 type Router struct {
 	http.Handler
-	ds        model.DataStore
-	artwork   artwork.Artwork
-	streamer  core.MediaStreamer
-	archiver  core.Archiver
-	players   core.Players
-	provider  external.Provider
-	playlists playlistsvc.Playlists
-	scanner   model.Scanner
-	broker    events.Broker
-	scrobbler scrobbler.PlayTracker
-	share     core.Share
-	playback  playback.PlaybackServer
-	metrics   metrics.Metrics
-	lyrics    lyricssvc.Lyrics
+	ds                model.DataStore
+	artwork           artwork.Artwork
+	streamer          transcode.MediaStreamer
+	archiver          core.Archiver
+	players           core.Players
+	provider          external.Provider
+	playlists         playlistsvc.Playlists
+	scanner           model.Scanner
+	broker            events.Broker
+	scrobbler         scrobbler.PlayTracker
+	share             core.Share
+	playback          playback.PlaybackServer
+	metrics           metrics.Metrics
+	lyrics            lyricssvc.Lyrics
+	transcodeDecision transcode.Decider
 }

-func New(ds model.DataStore, artwork artwork.Artwork, streamer core.MediaStreamer, archiver core.Archiver,
+func New(ds model.DataStore, artwork artwork.Artwork, streamer transcode.MediaStreamer, archiver core.Archiver,
 	players core.Players, provider external.Provider, scanner model.Scanner, broker events.Broker,
 	playlists playlistsvc.Playlists, scrobbler scrobbler.PlayTracker, share core.Share, playback playback.PlaybackServer,
-	metrics metrics.Metrics, lyrics lyricssvc.Lyrics,
+	metrics metrics.Metrics, lyrics lyricssvc.Lyrics, transcodeDecision transcode.Decider,
 ) *Router {
 	r := &Router{
-		ds:        ds,
-		artwork:   artwork,
-		streamer:  streamer,
-		archiver:  archiver,
-		players:   players,
-		provider:  provider,
-		playlists: playlists,
-		scanner:   scanner,
-		broker:    broker,
-		scrobbler: scrobbler,
-		share:     share,
-		playback:  playback,
-		metrics:   metrics,
-		lyrics:    lyrics,
+		ds:                ds,
+		artwork:           artwork,
+		streamer:          streamer,
+		archiver:          archiver,
+		players:           players,
+		provider:          provider,
+		playlists:         playlists,
+		scanner:           scanner,
+		broker:            broker,
+		scrobbler:         scrobbler,
+		share:             share,
+		playback:          playback,
+		metrics:           metrics,
+		lyrics:            lyrics,
+		transcodeDecision: transcodeDecision,
 	}
 	r.Handler = r.routes()
 	return r
@@ -176,6 +179,8 @@ func (api *Router) routes() http.Handler {
 			h(r, "getLyricsBySongId", api.GetLyricsBySongId)
 			hr(r, "stream", api.Stream)
 			hr(r, "download", api.Download)
+			hr(r, "getTranscodeDecision", api.GetTranscodeDecision)
+			hr(r, "getTranscodeStream", api.GetTranscodeStream)
 		})
 		r.Group(func(r chi.Router) {
 			// configure request throttling
@@ -27,7 +27,7 @@ var _ = Describe("MediaAnnotationController", func() {
 		ds = &tests.MockDataStore{}
 		playTracker = &fakePlayTracker{}
 		eventBroker = &fakeEventBroker{}
-		router = New(ds, nil, nil, nil, nil, nil, nil, eventBroker, nil, playTracker, nil, nil, nil, nil)
+		router = New(ds, nil, nil, nil, nil, nil, nil, eventBroker, nil, playTracker, nil, nil, nil, nil, nil)
 	})

 	Describe("Scrobble", func() {
@@ -34,7 +34,7 @@ var _ = Describe("MediaRetrievalController", func() {
 			MockedMediaFile: mockRepo,
 		}
 		artwork = &fakeArtwork{data: "image data"}
-		router = New(ds, artwork, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, lyrics.NewLyrics(nil))
+		router = New(ds, artwork, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, lyrics.NewLyrics(nil), nil)
 		w = httptest.NewRecorder()
 		DeferCleanup(configtest.SetupConfig())
 		conf.Server.LyricsPriority = "embedded,.lrc"
@@ -13,6 +13,7 @@ func (api *Router) GetOpenSubsonicExtensions(_ *http.Request) (*responses.Subson
 		{Name: "formPost", Versions: []int32{1}},
 		{Name: "songLyrics", Versions: []int32{1}},
 		{Name: "indexBasedQueue", Versions: []int32{1}},
+		{Name: "transcoding", Versions: []int32{1}},
 	}
 	return response, nil
 }
@@ -19,7 +19,7 @@ var _ = Describe("GetOpenSubsonicExtensions", func() {
 	)

 	BeforeEach(func() {
-		router = subsonic.New(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+		router = subsonic.New(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
 		w = httptest.NewRecorder()
 		r = httptest.NewRequest("GET", "/getOpenSubsonicExtensions?f=json", nil)
 	})
@@ -35,11 +35,12 @@ var _ = Describe("GetOpenSubsonicExtensions", func() {
 		err := json.Unmarshal(w.Body.Bytes(), &response)
 		Expect(err).NotTo(HaveOccurred())
 		Expect(*response.Subsonic.OpenSubsonicExtensions).To(SatisfyAll(
-			HaveLen(4),
+			HaveLen(5),
 			ContainElement(responses.OpenSubsonicExtension{Name: "transcodeOffset", Versions: []int32{1}}),
 			ContainElement(responses.OpenSubsonicExtension{Name: "formPost", Versions: []int32{1}}),
 			ContainElement(responses.OpenSubsonicExtension{Name: "songLyrics", Versions: []int32{1}}),
 			ContainElement(responses.OpenSubsonicExtension{Name: "indexBasedQueue", Versions: []int32{1}}),
+			ContainElement(responses.OpenSubsonicExtension{Name: "transcoding", Versions: []int32{1}}),
 		))
 	})
 })
@@ -24,7 +24,7 @@ var _ = Describe("buildPlaylist", func() {

 	BeforeEach(func() {
 		ds = &tests.MockDataStore{}
-		router = New(ds, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+		router = New(ds, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
 		ctx = context.Background()
 	})

@@ -224,7 +224,7 @@ var _ = Describe("UpdatePlaylist", func() {
 	BeforeEach(func() {
 		ds = &tests.MockDataStore{}
 		playlists = &fakePlaylists{}
-		router = New(ds, nil, nil, nil, nil, nil, nil, nil, playlists, nil, nil, nil, nil, nil)
+		router = New(ds, nil, nil, nil, nil, nil, nil, nil, playlists, nil, nil, nil, nil, nil, nil)
 	})

 	It("clears the comment when parameter is empty", func() {
@@ -61,6 +61,7 @@ type Subsonic struct {
 	OpenSubsonicExtensions *OpenSubsonicExtensions `xml:"openSubsonicExtensions,omitempty"  json:"openSubsonicExtensions,omitempty"`
 	LyricsList             *LyricsList             `xml:"lyricsList,omitempty"              json:"lyricsList,omitempty"`
 	PlayQueueByIndex       *PlayQueueByIndex       `xml:"playQueueByIndex,omitempty" json:"playQueueByIndex,omitempty"`
+	TranscodeDecision      *TranscodeDecision      `xml:"transcodeDecision,omitempty"       json:"transcodeDecision,omitempty"`
 }

 const (
@@ -617,3 +618,26 @@ func marshalJSONArray[T any](v []T) ([]byte, error) {
 	}
 	return json.Marshal(v)
 }
+
+// TranscodeDecision represents the response for getTranscodeDecision (OpenSubsonic transcoding extension)
+type TranscodeDecision struct {
+	CanDirectPlay    bool           `xml:"canDirectPlay,attr"               json:"canDirectPlay"`
+	CanTranscode     bool           `xml:"canTranscode,attr"                json:"canTranscode"`
+	TranscodeReasons []string       `xml:"transcodeReason,omitempty"        json:"transcodeReason,omitempty"`
+	ErrorReason      string         `xml:"errorReason,attr,omitempty"       json:"errorReason,omitempty"`
+	TranscodeParams  string         `xml:"transcodeParams,attr,omitempty"   json:"transcodeParams,omitempty"`
+	SourceStream     *StreamDetails `xml:"sourceStream,omitempty"           json:"sourceStream,omitempty"`
+	TranscodeStream  *StreamDetails `xml:"transcodeStream,omitempty"        json:"transcodeStream,omitempty"`
+}
+
+// StreamDetails describes audio stream properties for transcoding decisions
+type StreamDetails struct {
+	Protocol        string `xml:"protocol,attr,omitempty"        json:"protocol,omitempty"`
+	Container       string `xml:"container,attr,omitempty"       json:"container,omitempty"`
+	Codec           string `xml:"codec,attr,omitempty"           json:"codec,omitempty"`
+	AudioChannels   int32  `xml:"audioChannels,attr,omitempty"   json:"audioChannels,omitempty"`
+	AudioBitrate    int32  `xml:"audioBitrate,attr,omitempty"     json:"audioBitrate,omitempty"`
+	AudioProfile    string `xml:"audioProfile,attr,omitempty"    json:"audioProfile,omitempty"`
+	AudioSamplerate int32  `xml:"audioSamplerate,attr,omitempty" json:"audioSamplerate,omitempty"`
+	AudioBitdepth   int32  `xml:"audioBitdepth,attr,omitempty"   json:"audioBitdepth,omitempty"`
+}
@@ -21,7 +21,7 @@ var _ = Describe("Search", func() {
 		ds = &tests.MockDataStore{}
 		auth.Init(ds)

-		router = New(ds, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
+		router = New(ds, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)

 		// Get references to the mock repositories so we can inspect their Options
 		mockAlbumRepo = ds.Album(nil).(*tests.MockAlbumRepo)
@@ -9,7 +9,7 @@ import (
 	"strings"

 	"github.com/navidrome/navidrome/conf"
-	"github.com/navidrome/navidrome/core"
+	"github.com/navidrome/navidrome/core/transcode"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
@@ -17,7 +17,7 @@ import (
 	"github.com/navidrome/navidrome/utils/req"
 )

-func (api *Router) serveStream(ctx context.Context, w http.ResponseWriter, r *http.Request, stream *core.Stream, id string) {
+func (api *Router) serveStream(ctx context.Context, w http.ResponseWriter, r *http.Request, stream *transcode.Stream, id string) {
 	if stream.Seekable() {
 		http.ServeContent(w, r, stream.Name(), stream.ModTime(), stream)
 	} else {
@@ -60,7 +60,13 @@ func (api *Router) Stream(w http.ResponseWriter, r *http.Request) (*responses.Su
 	format, _ := p.String("format")
 	timeOffset := p.IntOr("timeOffset", 0)

-	stream, err := api.streamer.NewStream(ctx, id, format, maxBitRate, timeOffset)
+	mf, err := api.ds.MediaFile(ctx).Get(id)
+	if err != nil {
+		return nil, err
+	}
+
+	streamReq := api.transcodeDecision.ResolveRequest(ctx, mf, format, maxBitRate, timeOffset)
+	stream, err := api.streamer.DoStream(ctx, mf, streamReq)
 	if err != nil {
 		return nil, err
 	}
@@ -129,7 +135,8 @@ func (api *Router) Download(w http.ResponseWriter, r *http.Request) (*responses.

 	switch v := entity.(type) {
 	case *model.MediaFile:
-		stream, err := api.streamer.NewStream(ctx, id, format, maxBitRate, 0)
+		streamReq := api.transcodeDecision.ResolveRequest(ctx, v, format, maxBitRate, 0)
+		stream, err := api.streamer.DoStream(ctx, v, streamReq)
 		if err != nil {
 			return nil, err
 		}
@@ -0,0 +1,381 @@
+package subsonic
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"slices"
+	"strconv"
+
+	"github.com/navidrome/navidrome/core/transcode"
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/server/subsonic/responses"
+	"github.com/navidrome/navidrome/utils/req"
+)
+
+// API-layer request structs for JSON unmarshaling (decoupled from core structs)
+
+// clientInfoRequest represents client playback capabilities from the request body
+type clientInfoRequest struct {
+	Name                       string                      `json:"name,omitempty"`
+	Platform                   string                      `json:"platform,omitempty"`
+	MaxAudioBitrate            int                         `json:"maxAudioBitrate,omitempty"`
+	MaxTranscodingAudioBitrate int                         `json:"maxTranscodingAudioBitrate,omitempty"`
+	DirectPlayProfiles         []directPlayProfileRequest  `json:"directPlayProfiles,omitempty"`
+	TranscodingProfiles        []transcodingProfileRequest `json:"transcodingProfiles,omitempty"`
+	CodecProfiles              []codecProfileRequest       `json:"codecProfiles,omitempty"`
+}
+
+// directPlayProfileRequest describes a format the client can play directly
+type directPlayProfileRequest struct {
+	Containers       []string `json:"containers,omitempty"`
+	AudioCodecs      []string `json:"audioCodecs,omitempty"`
+	Protocols        []string `json:"protocols,omitempty"`
+	MaxAudioChannels int      `json:"maxAudioChannels,omitempty"`
+}
+
+// transcodingProfileRequest describes a transcoding target the client supports
+type transcodingProfileRequest struct {
+	Container        string `json:"container,omitempty"`
+	AudioCodec       string `json:"audioCodec,omitempty"`
+	Protocol         string `json:"protocol,omitempty"`
+	MaxAudioChannels int    `json:"maxAudioChannels,omitempty"`
+}
+
+// codecProfileRequest describes codec-specific limitations
+type codecProfileRequest struct {
+	Type        string              `json:"type,omitempty"`
+	Name        string              `json:"name,omitempty"`
+	Limitations []limitationRequest `json:"limitations,omitempty"`
+}
+
+// limitationRequest describes a specific codec limitation
+type limitationRequest struct {
+	Name       string   `json:"name,omitempty"`
+	Comparison string   `json:"comparison,omitempty"`
+	Values     []string `json:"values,omitempty"`
+	Required   bool     `json:"required,omitempty"`
+}
+
+// toCoreClientInfo converts the API request struct to the transcode.ClientInfo struct.
+// The OpenSubsonic spec uses bps for bitrate values; core uses kbps.
+func (r *clientInfoRequest) toCoreClientInfo() *transcode.ClientInfo {
+	ci := &transcode.ClientInfo{
+		Name:                       r.Name,
+		Platform:                   r.Platform,
+		MaxAudioBitrate:            bpsToKbps(r.MaxAudioBitrate),
+		MaxTranscodingAudioBitrate: bpsToKbps(r.MaxTranscodingAudioBitrate),
+	}
+
+	for _, dp := range r.DirectPlayProfiles {
+		ci.DirectPlayProfiles = append(ci.DirectPlayProfiles, transcode.DirectPlayProfile{
+			Containers:       dp.Containers,
+			AudioCodecs:      dp.AudioCodecs,
+			Protocols:        dp.Protocols,
+			MaxAudioChannels: dp.MaxAudioChannels,
+		})
+	}
+
+	for _, tp := range r.TranscodingProfiles {
+		ci.TranscodingProfiles = append(ci.TranscodingProfiles, transcode.Profile{
+			Container:        tp.Container,
+			AudioCodec:       tp.AudioCodec,
+			Protocol:         tp.Protocol,
+			MaxAudioChannels: tp.MaxAudioChannels,
+		})
+	}
+
+	for _, cp := range r.CodecProfiles {
+		coreCP := transcode.CodecProfile{
+			Type: cp.Type,
+			Name: cp.Name,
+		}
+		for _, lim := range cp.Limitations {
+			coreLim := transcode.Limitation{
+				Name:       lim.Name,
+				Comparison: lim.Comparison,
+				Values:     lim.Values,
+				Required:   lim.Required,
+			}
+			// Convert audioBitrate limitation values from bps to kbps
+			if lim.Name == transcode.LimitationAudioBitrate {
+				coreLim.Values = convertBitrateValues(lim.Values)
+			}
+			coreCP.Limitations = append(coreCP.Limitations, coreLim)
+		}
+		ci.CodecProfiles = append(ci.CodecProfiles, coreCP)
+	}
+
+	return ci
+}
+
+// bpsToKbps converts bits per second to kilobits per second (rounded).
+func bpsToKbps(bps int) int {
+	if bps < 0 {
+		return 0
+	}
+	return (bps + 500) / 1000
+}
+
+// kbpsToBps converts kilobits per second to bits per second.
+func kbpsToBps(kbps int) int {
+	return kbps * 1000
+}
+
+// convertBitrateValues converts a slice of bps string values to kbps string values.
+func convertBitrateValues(bpsValues []string) []string {
+	result := make([]string, len(bpsValues))
+	for i, v := range bpsValues {
+		n, err := strconv.Atoi(v)
+		if err == nil {
+			result[i] = strconv.Itoa(bpsToKbps(n))
+		} else {
+			result[i] = v // preserve unparseable values as-is
+		}
+	}
+	return result
+}
+
+// validate checks that all enum fields in the request contain valid values per the OpenSubsonic spec.
+func (r *clientInfoRequest) validate() error {
+	for _, dp := range r.DirectPlayProfiles {
+		for _, p := range dp.Protocols {
+			if !isValidProtocol(p) {
+				return fmt.Errorf("invalid protocol: %s", p)
+			}
+		}
+	}
+	for _, tp := range r.TranscodingProfiles {
+		if tp.Protocol != "" && !isValidProtocol(tp.Protocol) {
+			return fmt.Errorf("invalid protocol: %s", tp.Protocol)
+		}
+	}
+	for _, cp := range r.CodecProfiles {
+		if !isValidCodecProfileType(cp.Type) {
+			return fmt.Errorf("invalid codec profile type: %s", cp.Type)
+		}
+		for _, lim := range cp.Limitations {
+			if !isValidLimitationName(lim.Name) {
+				return fmt.Errorf("invalid limitation name: %s", lim.Name)
+			}
+			if !isValidComparison(lim.Comparison) {
+				return fmt.Errorf("invalid comparison: %s", lim.Comparison)
+			}
+		}
+	}
+	return nil
+}
+
+// Only support songs for now
+var validMediaTypes = []string{
+	"song",
+}
+
+func isValidMediaType(mediaType string) bool {
+	return slices.Contains(validMediaTypes, mediaType)
+}
+
+var validProtocols = []string{
+	transcode.ProtocolHTTP,
+	transcode.ProtocolHLS,
+}
+
+func isValidProtocol(p string) bool {
+	return slices.Contains(validProtocols, p)
+}
+
+var validCodecProfileTypes = []string{
+	transcode.CodecProfileTypeAudio,
+}
+
+func isValidCodecProfileType(t string) bool {
+	return slices.Contains(validCodecProfileTypes, t)
+}
+
+var validLimitationNames = []string{
+	transcode.LimitationAudioChannels,
+	transcode.LimitationAudioBitrate,
+	transcode.LimitationAudioProfile,
+	transcode.LimitationAudioSamplerate,
+	transcode.LimitationAudioBitdepth,
+}
+
+func isValidLimitationName(n string) bool {
+	return slices.Contains(validLimitationNames, n)
+}
+
+var validComparisons = []string{
+	transcode.ComparisonEquals,
+	transcode.ComparisonNotEquals,
+	transcode.ComparisonLessThanEqual,
+	transcode.ComparisonGreaterThanEqual,
+}
+
+func isValidComparison(c string) bool {
+	return slices.Contains(validComparisons, c)
+}
+
+// toResponseStreamDetails converts a core StreamDetails to the API response type.
+func toResponseStreamDetails(sd *transcode.StreamDetails) *responses.StreamDetails {
+	return &responses.StreamDetails{
+		Protocol:        transcode.ProtocolHTTP, // TODO: derive from decision when HLS support is added
+		Container:       sd.Container,
+		Codec:           sd.Codec,
+		AudioBitrate:    int32(kbpsToBps(sd.Bitrate)),
+		AudioProfile:    sd.Profile,
+		AudioSamplerate: int32(sd.SampleRate),
+		AudioBitdepth:   int32(sd.BitDepth),
+		AudioChannels:   int32(sd.Channels),
+	}
+}
+
+// GetTranscodeDecision handles the OpenSubsonic getTranscodeDecision endpoint.
+// It receives client capabilities and returns a decision on whether to direct play or transcode.
+func (api *Router) GetTranscodeDecision(w http.ResponseWriter, r *http.Request) (*responses.Subsonic, error) {
+	if r.Method != http.MethodPost {
+		w.Header().Set("Allow", "POST")
+		http.Error(w, "Method Not Allowed", http.StatusMethodNotAllowed)
+		return nil, nil
+	}
+
+	ctx := r.Context()
+	p := req.Params(r)
+
+	mediaID, err := p.String("mediaId")
+	if err != nil {
+		return nil, newError(responses.ErrorMissingParameter, "missing required parameter: mediaId")
+	}
+
+	mediaType, err := p.String("mediaType")
+	if err != nil {
+		return nil, newError(responses.ErrorMissingParameter, "missing required parameter: mediaType")
+	}
+
+	if !isValidMediaType(mediaType) {
+		return nil, newError(responses.ErrorGeneric, "mediaType '%s' is not yet supported", mediaType)
+	}
+
+	// Parse and validate ClientInfo from request body (required per OpenSubsonic spec)
+	var clientInfoReq clientInfoRequest
+	r.Body = http.MaxBytesReader(w, r.Body, 1<<20) // 1 MB limit
+	if err := json.NewDecoder(r.Body).Decode(&clientInfoReq); err != nil {
+		return nil, newError(responses.ErrorGeneric, "invalid JSON request body")
+	}
+	if err := clientInfoReq.validate(); err != nil {
+		return nil, newError(responses.ErrorGeneric, "%v", err)
+	}
+	clientInfo := clientInfoReq.toCoreClientInfo()
+
+	// Get media file
+	mf, err := api.ds.MediaFile(ctx).Get(mediaID)
+	if err != nil {
+		if errors.Is(err, model.ErrNotFound) {
+			return nil, newError(responses.ErrorDataNotFound, "media file not found: %s", mediaID)
+		}
+		log.Error(ctx, "Error retrieving media file", "mediaID", mediaID, err)
+		return nil, newError(responses.ErrorGeneric, "error retrieving media file")
+	}
+
+	// Make the decision
+	decision, err := api.transcodeDecision.MakeDecision(ctx, mf, clientInfo, transcode.DecisionOptions{})
+	if err != nil {
+		log.Error(ctx, "Failed to make transcode decision", "mediaID", mediaID, err)
+		return nil, newError(responses.ErrorGeneric, "failed to make transcode decision")
+	}
+
+	// Only create a token when there is a valid playback path
+	var transcodeParams string
+	if decision.CanDirectPlay || decision.CanTranscode {
+		transcodeParams, err = api.transcodeDecision.CreateTranscodeParams(decision)
+		if err != nil {
+			log.Error(ctx, "Failed to create transcode token", "mediaID", mediaID, err)
+			return nil, newError(responses.ErrorGeneric, "failed to create transcode token")
+		}
+	}
+
+	// Build response (convert kbps from core to bps for the API)
+	response := newResponse()
+	response.TranscodeDecision = &responses.TranscodeDecision{
+		CanDirectPlay:    decision.CanDirectPlay,
+		CanTranscode:     decision.CanTranscode,
+		TranscodeReasons: decision.TranscodeReasons,
+		ErrorReason:      decision.ErrorReason,
+		TranscodeParams:  transcodeParams,
+		SourceStream:     toResponseStreamDetails(&decision.SourceStream),
+	}
+
+	if decision.TranscodeStream != nil {
+		response.TranscodeDecision.TranscodeStream = toResponseStreamDetails(decision.TranscodeStream)
+	}
+
+	return response, nil
+}
+
+// GetTranscodeStream handles the OpenSubsonic getTranscodeStream endpoint.
+// It streams media using the decision encoded in the transcodeParams JWT token.
+// All errors are returned as proper HTTP status codes (not Subsonic error responses).
+func (api *Router) GetTranscodeStream(w http.ResponseWriter, r *http.Request) (*responses.Subsonic, error) {
+	ctx := r.Context()
+	p := req.Params(r)
+
+	mediaID, err := p.String("mediaId")
+	if err != nil {
+		http.Error(w, "Bad Request", http.StatusBadRequest)
+		return nil, nil
+	}
+
+	mediaType, err := p.String("mediaType")
+	if err != nil {
+		http.Error(w, "Bad Request", http.StatusBadRequest)
+		return nil, nil
+	}
+
+	transcodeParamsToken, err := p.String("transcodeParams")
+	if err != nil {
+		http.Error(w, "Bad Request", http.StatusBadRequest)
+		return nil, nil
+	}
+
+	if !isValidMediaType(mediaType) {
+		http.Error(w, "Bad Request", http.StatusBadRequest)
+		return nil, nil
+	}
+
+	// Validate the token and resolve streaming parameters
+	streamReq, mf, err := api.transcodeDecision.ResolveRequestFromToken(ctx, transcodeParamsToken, mediaID, p.IntOr("offset", 0))
+	if err != nil {
+		switch {
+		case errors.Is(err, transcode.ErrMediaNotFound):
+			http.Error(w, "Not Found", http.StatusNotFound)
+		case errors.Is(err, transcode.ErrTokenInvalid), errors.Is(err, transcode.ErrTokenStale):
+			http.Error(w, "Gone", http.StatusGone)
+		default:
+			log.Error(ctx, "Error validating transcode params", err)
+			http.Error(w, "Internal Server Error", http.StatusInternalServerError)
+		}
+		return nil, nil
+	}
+
+	// Create stream (use DoStream to avoid duplicate DB fetch)
+	stream, err := api.streamer.DoStream(ctx, mf, streamReq)
+	if err != nil {
+		log.Error(ctx, "Error creating stream", "mediaID", mediaID, err)
+		http.Error(w, "Internal Server Error", http.StatusInternalServerError)
+		return nil, nil
+	}
+
+	// Make sure the stream will be closed at the end
+	defer func() {
+		if err := stream.Close(); err != nil && log.IsGreaterOrEqualTo(log.LevelDebug) {
+			log.Error("Error closing stream", "id", mediaID, "file", stream.Name(), err)
+		}
+	}()
+
+	w.Header().Set("X-Content-Type-Options", "nosniff")
+
+	api.serveStream(ctx, w, r, stream, mediaID)
+
+	return nil, nil
+}
@@ -0,0 +1,406 @@
+package subsonic
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+
+	"github.com/navidrome/navidrome/core/transcode"
+	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("Transcode endpoints", func() {
+	var (
+		router     *Router
+		ds         *tests.MockDataStore
+		mockTD     *mockTranscodeDecision
+		w          *httptest.ResponseRecorder
+		mockMFRepo *tests.MockMediaFileRepo
+	)
+
+	BeforeEach(func() {
+		mockMFRepo = &tests.MockMediaFileRepo{}
+		ds = &tests.MockDataStore{MockedMediaFile: mockMFRepo}
+		mockTD = &mockTranscodeDecision{}
+		router = New(ds, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, mockTD)
+		w = httptest.NewRecorder()
+	})
+
+	Describe("GetTranscodeDecision", func() {
+		It("returns 405 for non-POST requests", func() {
+			r := newGetRequest("mediaId=123", "mediaType=song")
+			resp, err := router.GetTranscodeDecision(w, r)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(resp).To(BeNil())
+			Expect(w.Code).To(Equal(http.StatusMethodNotAllowed))
+			Expect(w.Header().Get("Allow")).To(Equal("POST"))
+		})
+
+		It("returns error when mediaId is missing", func() {
+			r := newJSONPostRequest("mediaType=song", "{}")
+			_, err := router.GetTranscodeDecision(w, r)
+			Expect(err).To(HaveOccurred())
+		})
+
+		It("returns error when mediaType is missing", func() {
+			r := newJSONPostRequest("mediaId=123", "{}")
+			_, err := router.GetTranscodeDecision(w, r)
+			Expect(err).To(HaveOccurred())
+		})
+
+		It("returns error for unsupported mediaType", func() {
+			r := newJSONPostRequest("mediaId=123&mediaType=podcast", "{}")
+			_, err := router.GetTranscodeDecision(w, r)
+			Expect(err).To(HaveOccurred())
+			Expect(err.Error()).To(ContainSubstring("not yet supported"))
+		})
+
+		It("returns ErrorDataNotFound when media file does not exist", func() {
+			// mockMFRepo has no data set, so Get() returns model.ErrNotFound
+			r := newJSONPostRequest("mediaId=nonexistent&mediaType=song", "{}")
+			_, err := router.GetTranscodeDecision(w, r)
+			Expect(err).To(HaveOccurred())
+			Expect(err.Error()).To(ContainSubstring("media file not found"))
+		})
+
+		It("returns error when media file retrieval fails", func() {
+			mockMFRepo.SetError(true)
+			r := newJSONPostRequest("mediaId=song-1&mediaType=song", "{}")
+			_, err := router.GetTranscodeDecision(w, r)
+			Expect(err).To(HaveOccurred())
+			Expect(err.Error()).To(ContainSubstring("error retrieving media file"))
+		})
+
+		It("returns error when body is empty", func() {
+			r := newJSONPostRequest("mediaId=song-1&mediaType=song", "")
+			_, err := router.GetTranscodeDecision(w, r)
+			Expect(err).To(HaveOccurred())
+		})
+
+		It("returns error when body contains invalid JSON", func() {
+			r := newJSONPostRequest("mediaId=song-1&mediaType=song", "not-json{{{")
+			_, err := router.GetTranscodeDecision(w, r)
+			Expect(err).To(HaveOccurred())
+		})
+
+		It("returns error for invalid protocol in direct play profile", func() {
+			body := `{"directPlayProfiles":[{"containers":["mp3"],"audioCodecs":["mp3"],"protocols":["ftp"]}]}`
+			r := newJSONPostRequest("mediaId=song-1&mediaType=song", body)
+			_, err := router.GetTranscodeDecision(w, r)
+			Expect(err).To(HaveOccurred())
+			Expect(err.Error()).To(ContainSubstring("invalid protocol"))
+		})
+
+		It("returns error for invalid comparison operator", func() {
+			body := `{"codecProfiles":[{"type":"AudioCodec","name":"mp3","limitations":[{"name":"audioBitrate","comparison":"InvalidOp","values":["320"]}]}]}`
+			r := newJSONPostRequest("mediaId=song-1&mediaType=song", body)
+			_, err := router.GetTranscodeDecision(w, r)
+			Expect(err).To(HaveOccurred())
+			Expect(err.Error()).To(ContainSubstring("invalid comparison"))
+		})
+
+		It("returns error for invalid limitation name", func() {
+			body := `{"codecProfiles":[{"type":"AudioCodec","name":"mp3","limitations":[{"name":"unknownField","comparison":"Equals","values":["320"]}]}]}`
+			r := newJSONPostRequest("mediaId=song-1&mediaType=song", body)
+			_, err := router.GetTranscodeDecision(w, r)
+			Expect(err).To(HaveOccurred())
+			Expect(err.Error()).To(ContainSubstring("invalid limitation name"))
+		})
+
+		It("returns error for invalid codec profile type", func() {
+			body := `{"codecProfiles":[{"type":"VideoCodec","name":"mp3"}]}`
+			r := newJSONPostRequest("mediaId=song-1&mediaType=song", body)
+			_, err := router.GetTranscodeDecision(w, r)
+			Expect(err).To(HaveOccurred())
+			Expect(err.Error()).To(ContainSubstring("invalid codec profile type"))
+		})
+
+		It("rejects wrong-case protocol", func() {
+			body := `{"directPlayProfiles":[{"containers":["mp3"],"audioCodecs":["mp3"],"protocols":["HTTP"]}]}`
+			r := newJSONPostRequest("mediaId=song-1&mediaType=song", body)
+			_, err := router.GetTranscodeDecision(w, r)
+			Expect(err).To(HaveOccurred())
+			Expect(err.Error()).To(ContainSubstring("invalid protocol"))
+		})
+
+		It("rejects wrong-case codec profile type", func() {
+			body := `{"codecProfiles":[{"type":"audiocodec","name":"mp3"}]}`
+			r := newJSONPostRequest("mediaId=song-1&mediaType=song", body)
+			_, err := router.GetTranscodeDecision(w, r)
+			Expect(err).To(HaveOccurred())
+			Expect(err.Error()).To(ContainSubstring("invalid codec profile type"))
+		})
+
+		It("rejects wrong-case comparison operator", func() {
+			body := `{"codecProfiles":[{"type":"AudioCodec","name":"mp3","limitations":[{"name":"audioBitrate","comparison":"lessthanequal","values":["320"]}]}]}`
+			r := newJSONPostRequest("mediaId=song-1&mediaType=song", body)
+			_, err := router.GetTranscodeDecision(w, r)
+			Expect(err).To(HaveOccurred())
+			Expect(err.Error()).To(ContainSubstring("invalid comparison"))
+		})
+
+		It("rejects wrong-case limitation name", func() {
+			body := `{"codecProfiles":[{"type":"AudioCodec","name":"mp3","limitations":[{"name":"AudioBitrate","comparison":"Equals","values":["320"]}]}]}`
+			r := newJSONPostRequest("mediaId=song-1&mediaType=song", body)
+			_, err := router.GetTranscodeDecision(w, r)
+			Expect(err).To(HaveOccurred())
+			Expect(err.Error()).To(ContainSubstring("invalid limitation name"))
+		})
+
+		It("returns a valid decision response", func() {
+			mockMFRepo.SetData(model.MediaFiles{
+				{ID: "song-1", Suffix: "mp3", Codec: "MP3", BitRate: 320, Channels: 2, SampleRate: 44100},
+			})
+			mockTD.decision = &transcode.Decision{
+				MediaID:       "song-1",
+				CanDirectPlay: true,
+				SourceStream: transcode.StreamDetails{
+					Container: "mp3", Codec: "mp3", Bitrate: 320,
+					SampleRate: 44100, Channels: 2,
+				},
+			}
+			mockTD.token = "test-jwt-token"
+
+			body := `{"directPlayProfiles":[{"containers":["mp3"],"protocols":["http"]}]}`
+			r := newJSONPostRequest("mediaId=song-1&mediaType=song", body)
+			resp, err := router.GetTranscodeDecision(w, r)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(resp.TranscodeDecision).ToNot(BeNil())
+			Expect(resp.TranscodeDecision.CanDirectPlay).To(BeTrue())
+			Expect(resp.TranscodeDecision.TranscodeParams).To(Equal("test-jwt-token"))
+			Expect(resp.TranscodeDecision.SourceStream).ToNot(BeNil())
+			Expect(resp.TranscodeDecision.SourceStream.Protocol).To(Equal("http"))
+			Expect(resp.TranscodeDecision.SourceStream.Container).To(Equal("mp3"))
+			Expect(resp.TranscodeDecision.SourceStream.AudioBitrate).To(Equal(int32(320_000)))
+		})
+
+		It("includes transcode stream when transcoding", func() {
+			mockMFRepo.SetData(model.MediaFiles{
+				{ID: "song-2", Suffix: "flac", Codec: "FLAC", BitRate: 1000, Channels: 2, SampleRate: 96000, BitDepth: 24},
+			})
+			mockTD.decision = &transcode.Decision{
+				MediaID:          "song-2",
+				CanDirectPlay:    false,
+				CanTranscode:     true,
+				TargetFormat:     "mp3",
+				TargetBitrate:    256,
+				TranscodeReasons: []string{"container not supported"},
+				SourceStream: transcode.StreamDetails{
+					Container: "flac", Codec: "flac", Bitrate: 1000,
+					SampleRate: 96000, BitDepth: 24, Channels: 2,
+				},
+				TranscodeStream: &transcode.StreamDetails{
+					Container: "mp3", Codec: "mp3", Bitrate: 256,
+					SampleRate: 96000, Channels: 2,
+				},
+			}
+			mockTD.token = "transcode-token"
+
+			r := newJSONPostRequest("mediaId=song-2&mediaType=song", "{}")
+			resp, err := router.GetTranscodeDecision(w, r)
+
+			Expect(err).ToNot(HaveOccurred())
+			Expect(resp.TranscodeDecision.CanTranscode).To(BeTrue())
+			Expect(resp.TranscodeDecision.TranscodeReasons).To(ConsistOf("container not supported"))
+			Expect(resp.TranscodeDecision.TranscodeStream).ToNot(BeNil())
+			Expect(resp.TranscodeDecision.TranscodeStream.Container).To(Equal("mp3"))
+		})
+	})
+
+	Describe("GetTranscodeStream", func() {
+		It("returns 400 when mediaId is missing", func() {
+			r := newGetRequest("mediaType=song", "transcodeParams=abc")
+			resp, err := router.GetTranscodeStream(w, r)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(resp).To(BeNil())
+			Expect(w.Code).To(Equal(http.StatusBadRequest))
+		})
+
+		It("returns 400 when transcodeParams is missing", func() {
+			r := newGetRequest("mediaId=123", "mediaType=song")
+			resp, err := router.GetTranscodeStream(w, r)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(resp).To(BeNil())
+			Expect(w.Code).To(Equal(http.StatusBadRequest))
+		})
+
+		It("returns 410 for invalid or mismatched token", func() {
+			mockTD.resolveErr = transcode.ErrTokenInvalid
+			r := newGetRequest("mediaId=123", "mediaType=song", "transcodeParams=bad-token")
+			resp, err := router.GetTranscodeStream(w, r)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(resp).To(BeNil())
+			Expect(w.Code).To(Equal(http.StatusGone))
+		})
+
+		It("returns 404 when media file not found", func() {
+			mockTD.resolveErr = transcode.ErrMediaNotFound
+			r := newGetRequest("mediaId=gone-id", "mediaType=song", "transcodeParams=valid-token")
+			resp, err := router.GetTranscodeStream(w, r)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(resp).To(BeNil())
+			Expect(w.Code).To(Equal(http.StatusNotFound))
+		})
+
+		It("returns 410 when media file has changed (stale token)", func() {
+			mockTD.resolveErr = transcode.ErrTokenStale
+			r := newGetRequest("mediaId=song-1", "mediaType=song", "transcodeParams=stale-token")
+			resp, err := router.GetTranscodeStream(w, r)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(resp).To(BeNil())
+			Expect(w.Code).To(Equal(http.StatusGone))
+		})
+
+		It("builds correct StreamRequest for direct play", func() {
+			fakeStreamer := &fakeMediaStreamer{}
+			router = New(ds, nil, fakeStreamer, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, mockTD)
+			mockTD.resolvedReq = transcode.StreamRequest{ID: "song-1"}
+			mockTD.resolvedMF = &model.MediaFile{ID: "song-1"}
+
+			r := newGetRequest("mediaId=song-1", "mediaType=song", "transcodeParams=valid-token")
+			_, _ = router.GetTranscodeStream(w, r)
+
+			Expect(fakeStreamer.captured).ToNot(BeNil())
+			Expect(fakeStreamer.captured.ID).To(Equal("song-1"))
+			Expect(fakeStreamer.captured.Format).To(BeEmpty())
+			Expect(fakeStreamer.captured.BitRate).To(BeZero())
+			Expect(fakeStreamer.captured.SampleRate).To(BeZero())
+			Expect(fakeStreamer.captured.BitDepth).To(BeZero())
+			Expect(fakeStreamer.captured.Channels).To(BeZero())
+		})
+
+		It("builds correct StreamRequest for transcoding", func() {
+			fakeStreamer := &fakeMediaStreamer{}
+			router = New(ds, nil, fakeStreamer, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, mockTD)
+			mockTD.resolvedReq = transcode.StreamRequest{
+				ID:         "song-2",
+				Format:     "mp3",
+				BitRate:    256,
+				SampleRate: 44100,
+				BitDepth:   16,
+				Channels:   2,
+			}
+			mockTD.resolvedMF = &model.MediaFile{ID: "song-2"}
+
+			r := newGetRequest("mediaId=song-2", "mediaType=song", "transcodeParams=valid-token", "offset=10")
+			_, _ = router.GetTranscodeStream(w, r)
+
+			Expect(fakeStreamer.captured).ToNot(BeNil())
+			Expect(fakeStreamer.captured.ID).To(Equal("song-2"))
+			Expect(fakeStreamer.captured.Format).To(Equal("mp3"))
+			Expect(fakeStreamer.captured.BitRate).To(Equal(256))
+			Expect(fakeStreamer.captured.SampleRate).To(Equal(44100))
+			Expect(fakeStreamer.captured.BitDepth).To(Equal(16))
+			Expect(fakeStreamer.captured.Channels).To(Equal(2))
+			Expect(fakeStreamer.captured.Offset).To(Equal(10))
+		})
+	})
+
+	Describe("bpsToKbps", func() {
+		It("converts standard bitrates", func() {
+			Expect(bpsToKbps(128000)).To(Equal(128))
+			Expect(bpsToKbps(320000)).To(Equal(320))
+			Expect(bpsToKbps(256000)).To(Equal(256))
+		})
+		It("returns 0 for 0", func() {
+			Expect(bpsToKbps(0)).To(Equal(0))
+		})
+		It("rounds instead of truncating", func() {
+			Expect(bpsToKbps(999)).To(Equal(1))
+			Expect(bpsToKbps(500)).To(Equal(1))
+			Expect(bpsToKbps(499)).To(Equal(0))
+		})
+		It("returns 0 for negative values", func() {
+			Expect(bpsToKbps(-1)).To(Equal(0))
+			Expect(bpsToKbps(-1000)).To(Equal(0))
+			Expect(bpsToKbps(-1000000)).To(Equal(0))
+		})
+	})
+
+	Describe("kbpsToBps", func() {
+		It("converts standard bitrates", func() {
+			Expect(kbpsToBps(128)).To(Equal(128000))
+			Expect(kbpsToBps(320)).To(Equal(320000))
+		})
+		It("returns 0 for 0", func() {
+			Expect(kbpsToBps(0)).To(Equal(0))
+		})
+	})
+
+	Describe("convertBitrateValues", func() {
+		It("converts valid bps strings to kbps", func() {
+			Expect(convertBitrateValues([]string{"128000", "320000"})).To(Equal([]string{"128", "320"}))
+		})
+		It("preserves unparseable values", func() {
+			Expect(convertBitrateValues([]string{"128000", "bad", "320000"})).To(Equal([]string{"128", "bad", "320"}))
+		})
+		It("handles empty slice", func() {
+			Expect(convertBitrateValues([]string{})).To(Equal([]string{}))
+		})
+	})
+})
+
+// newJSONPostRequest creates an HTTP POST request with JSON body and query params
+func newJSONPostRequest(queryParams string, jsonBody string) *http.Request {
+	r := httptest.NewRequest("POST", "/getTranscodeDecision?"+queryParams, bytes.NewBufferString(jsonBody))
+	r.Header.Set("Content-Type", "application/json")
+	return r
+}
+
+// mockTranscodeDecision is a test double for transcode.Decider
+type mockTranscodeDecision struct {
+	decision    *transcode.Decision
+	token       string
+	tokenErr    error
+	resolvedReq transcode.StreamRequest
+	resolvedMF  *model.MediaFile
+	resolveErr  error
+}
+
+func (m *mockTranscodeDecision) MakeDecision(_ context.Context, _ *model.MediaFile, _ *transcode.ClientInfo, _ transcode.DecisionOptions) (*transcode.Decision, error) {
+	if m.decision != nil {
+		return m.decision, nil
+	}
+	return &transcode.Decision{}, nil
+}
+
+func (m *mockTranscodeDecision) ResolveRequest(_ context.Context, _ *model.MediaFile, _ string, _ int, _ int) transcode.StreamRequest {
+	return transcode.StreamRequest{Format: "raw"}
+}
+
+func (m *mockTranscodeDecision) CreateTranscodeParams(_ *transcode.Decision) (string, error) {
+	return m.token, m.tokenErr
+}
+
+func (m *mockTranscodeDecision) ResolveRequestFromToken(_ context.Context, _ string, _ string, offset int) (transcode.StreamRequest, *model.MediaFile, error) {
+	if m.resolveErr != nil {
+		return transcode.StreamRequest{}, nil, m.resolveErr
+	}
+	req := m.resolvedReq
+	req.Offset = offset
+	return req, m.resolvedMF, nil
+}
+
+// fakeMediaStreamer captures the StreamRequest and returns a sentinel error,
+// allowing tests to verify parameter passing without constructing a real Stream.
+var errStreamCaptured = errors.New("stream request captured")
+
+type fakeMediaStreamer struct {
+	captured *transcode.StreamRequest
+}
+
+func (f *fakeMediaStreamer) NewStream(_ context.Context, req transcode.StreamRequest) (*transcode.Stream, error) {
+	f.captured = &req
+	return nil, errStreamCaptured
+}
+
+func (f *fakeMediaStreamer) DoStream(_ context.Context, _ *model.MediaFile, req transcode.StreamRequest) (*transcode.Stream, error) {
+	f.captured = &req
+	return nil, errStreamCaptured
+}