Add additional transcoding options to stream endpoint (e.g. support "direct stream" feature)

Type of change

  • API tweak: Add new parameter or new result fields to actual API endpoints

Proposal description

There should be an option like the “direct stream” feature of Jellyfin (e.g.) where the media will be played in its original form if the client supports it, or else will be transcoded.

I think this can be accomplished by extending the format option of the existing API to support a semicolon-separated list of multiple codecs.

Backward compatibility impact

If only one codec is set, or no codec is set, behavior can be identical to the current API. No breaking change.

API details

If the client supplies multiple codecs in the format option, the server should choose a format that requires no transcoding if possible. e.g. if format=flac;opus;mp3, an AAC file on the server should be transcoded to opus at a similar bit rate to the source file, a Wavpack file should be transcoded to flac, and an mp3 file should be streamed as-is. If both multiple formats and maxBitRate are set, the same logic should apply except that transcoding a file may still be necessary to achieve the intended bitrate even if the client supports that format. In that case, the first format in the list that can satisfy the bitrate requirements should be used.

Security impacts


Potential issues

Alternative solutions

Proposal status


I also want to use this post to discuss more transcoding options, but that are definitely lower priority than the above proposal.

  1. Adding an additional sampleRates field that allows the client to specify preferred sample rates. For example, if the client has enough bandwidth to only stream CD-quality flac, but the server has high-rez flac, or if the client’s audio device only supports 44.1/48 kHz sample rate so streaming the full 192 kHz file (e.g.) is useless, they could set format=flac;opus;mp3 sampleRates=44100;48000, and a high-rez flac would be resampled, but streamed as flac at a the lower sample rate.