Transcoding

Sovereign re-encodes as little as possible. Every time a title starts, it compares the source file against what the client says it can decode and picks the cheapest delivery that will play. It also records reasons for that choice, every way the stream differs from the file, and they’re the first thing to check when a stream is heavier than you expected.

The Three Playback Modes

Whatever the source, Sovereign delivers HLS with fMP4 segments. What differs is how much of the file has to be rebuilt to get there.

Mode	Video	Audio	Cost
Direct Play	Copied as-is	Every track copied as-is	Near zero: the file is repackaged, not re-encoded
Remux	Copied as-is	At least one track converted	Low: audio encoding only
Transcode	Re-encoded	Copied or converted per track	High: this is the one that uses your CPU or GPU

Remux is reported as its own mode because video encoding is where nearly all of the cost lives. A session that only had to fix an audio track is far closer to a direct play than to a full transcode.

How the Decision Is Made

Every playback start runs the same decision before the first segment exists. The client says what it can play, Sovereign compares the source against it, and the result fixes the play mode for the whole session. Playback Decisions walks through every step of it, with a chart, and covers what each check does when it has nothing to go on.

sequenceDiagram
  participant C as Client device
  participant S as Sovereign
  participant E as Encoder

  C->>S: Start playback, with device capabilities
  alt Capabilities incomplete
    S-->>C: Refuse the start
  else Capabilities complete
    loop Each audio track
      Note over S: Copy it if the client decodes it,<br/>otherwise convert it to the<br/>best format the client named
    end
    Note over S: Video checks, in order:<br/>format, bit depth, colour,<br/>display range, frame size,<br/>segment size, scan type
    alt Every check passes
      Note over S: Copy the video. Direct Play,<br/>or Remux if any audio converts
    else A check fails
      Note over S: Every failing check<br/>becomes a reason
      S->>E: Re-encode the video
      Note over E: HDR is kept only if the<br/>client and GPU support it
    end
    S-->>C: Playlist, play mode and reasons
    loop While playing
      C->>S: Next segment
      S-->>C: Segment, copied or encoded
    end
  end

Every client describes itself completely when it asks to play: the codecs it decodes and at what bit depth and resolution, which dynamic ranges its display shows, how much video it can buffer, and any alignment its decoder needs. A description with anything missing is refused before any of the checks run, and the error says what was missing. So Sovereign never guesses on a device’s behalf, and there’s no fallback transcode for a device that said nothing.

For the video stream, Sovereign works through a series of checks. Every one of them has to pass for the video to be copied. It runs all of them on every play, so when several fail, each one is reported:

Container compatibility - the source codec must be one that’s valid in fMP4: H.264, H.265, VP9, or AV1.
Client support - the client must have advertised that codec as decodable.
Bit depth - the client must have advertised that codec at or above the source’s bit depth. Advertising “HEVC” isn’t the same as advertising 10-bit HEVC.
Dolby Vision base layer - a Dolby Vision source is only copyable if the picture underneath its Dolby Vision data is a standard one that an ordinary decoder renders correctly.
Display range - the source’s dynamic range (SDR, HLG or PQ) has to be one the client said its display can show.
Geometry - the source frame must be within the client’s decode resolution tier and must satisfy any frame-alignment requirement the client’s hardware decoder imposes.
Peak segment size - if the client’s media buffer is a fixed size, the heaviest stretch of the source has to fit inside it.
Progressive video - an interlaced source is never copied.

A transcode forced by something other than colour (a frame too large for the device, a segment too heavy for its buffer, an interlaced source) can keep an HDR title in HDR. Sovereign keeps the picture in HDR when the transcode emits H.265 or AV1, the client said its display shows that HDR format and decodes that codec at 10 bits, and the GPU passed a 10-bit encode test at startup. A transcode emits H.264 unless the client can’t take the full frame in H.264 and your GPU can encode H.265 or AV1 for it, so in practice HDR survives on 4K titles sent to a device whose H.264 decoding stops at 1080p, as Roku’s does. If any of those conditions is missing, the picture is converted to SDR, which is also what always happens to a Dolby Vision Profile 5 source.

Audio is planned separately, one decision per track. Each track is copied when its codec is fMP4-valid (AAC, AC3, EAC3, Opus, FLAC, DTS, TrueHD, AC-4) and the client can decode it. Both conditions matter: a format Sovereign can package is still converted unless the client says it can play it.

That second condition is what makes lossless passthrough work. No browser can decode DTS or TrueHD, so on the web those tracks are always converted. A living-room device wired to an AV receiver is a different matter: it reports the formats the receiver accepts, and Sovereign then hands the bitstream over untouched. This is also how a Dolby Atmos mix survives, because the object metadata rides inside the TrueHD (or E-AC-3) track and doesn’t survive any conversion.

When a track does have to be converted, Sovereign picks the best format the client advertised: EAC3 first, then AC3, then AAC as the fallback every client accepts. The two Dolby formats carry up to six channels, so a 5.1 mix stays 5.1 instead of folding down to stereo, and a 7.1 mix becomes 5.1. Sovereign never adds channels that weren’t in the source, so a stereo track stays stereo.

Playback Reasons

A direct play carries no reasons: nothing about the stream differs from the file. Every other play carries one or more, and each is one of two kinds:

Cause - why the source couldn’t be sent as it is: a check the video failed, or an audio track the client can’t play.
Consequence - what a re-encode that was already happening lost on the way: the HDR it couldn’t keep, the frame size it had to cap, audio channels it folded down.

The video’s causes come first, in the order of the checks above, then what the re-encode lost, then the audio. A misaligned frame or an oversized peak reported alongside another cause is marked minor: the transcode the other cause forced repairs it anyway, so it changes nothing about what you get.

Causes

Reason	Resulting Mode	What It Means
`AudioTranscode`	Remux	Video is copied, but at least one audio track isn’t playable as-is and is re-encoded.
`VideoCodecNotStreamable`	Transcode	The source video codec can’t be carried in fMP4 at all, whatever the client decodes.
`VideoCodecUnsupported`	Transcode	The client can’t decode the source video codec, or the codec was never identified.
`VideoBitDepthUnsupported`	Transcode	The client can’t decode the source’s bit depth (e.g. 10-bit HEVC on an 8-bit client), so the video is re-encoded.
`DolbyVisionUnsupported`	Transcode	The source is a Dolby Vision format no ordinary decoder can render, so the video is re-encoded and tone-mapped.
`VideoRangeUnsupported`	Transcode	The client’s display can’t present the source’s HDR format, so the video is re-encoded and tone-mapped.
`ExceedsDecodeResolution`	Transcode	The source resolution exceeds the client’s decode limit, so the video is re-encoded and downscaled.
`NonAlignedResolution`	Transcode	The source display dimensions violate the client’s macroblock alignment, so the video is re-encoded and padded.
`ExceedsPeakBitrate`	Transcode	The source’s heaviest stretch is larger than the client’s media buffer can hold, so the video is re-encoded.
`InterlacedSource`	Transcode	The source is interlaced, so the video is re-encoded with the fields woven back into whole frames.

AudioTranscode also appears on a transcode whose audio had to be converted too, alongside the video’s own causes.

Consequences

Reason	What It Means
`ThroughputCapDolbyVision`	A 4K Dolby Vision Profile 5 title was held to 1080p, because converting it on this Intel GPU is too slow at 4K.
`ThroughputCapSoftware`	A 4K HDR title was held to 1080p, because its tone-map runs on the processor and is too slow at 4K.
`HdrOutputUnsupported`	An HDR title was converted to SDR, because the client can’t decode 10-bit HEVC or AV1.
`HdrEncodeUnavailable`	An HDR title was converted to SDR, because no encoder on the server can produce 10-bit HEVC or AV1 for it.
`AudioDownmixedToStereo`	The default audio track was mixed down to stereo, because the client named no surround format.
`AudioDownmixedToFiveOne`	A 7.1 default audio track was mixed down to 5.1, the most the AC3 and EAC3 encoders carry.

A consequence another reason already explains isn’t repeated: a Profile 5 source, or a display that can’t show HDR, accounts for its own SDR output.

Direct Play

Mode: Direct Play. Nothing is re-encoded, and no reason is reported.

The source video codec is fMP4-compatible, the client advertised it at the source’s bit depth, the frame geometry is fine, and every audio track is independently copyable. Sovereign repackages the existing streams into HLS segments and hands them over untouched.

This is the outcome to aim for. It costs almost nothing and preserves the source exactly, including lossless and Atmos audio that a conversion would lose. No encoder runs, so the Video Quality settings have no effect. The same is true of a Remux, whose video is copied too.

AudioTranscode

Mode: Remux. Video copied, audio partially converted.

The video passed every check and is being copied. One or more audio tracks, however, are in a format the client can’t decode, most often DTS or TrueHD on a client with no receiver attached, but also any codec the client didn’t advertise. Those tracks are re-encoded; any track that is playable is still copied alongside them.

You’ll see this on remuxed Blu-ray sources, which routinely carry a lossless TrueHD or DTS-HD track as the primary audio. It’s a cheap outcome, since audio encoding is a rounding error next to video, and the surround layout is preserved whenever the client can take EAC3 or AC3. Only a client limited to AAC receives a stereo fold-down.

To get a copy instead: play the title on a device that can pass the format through to an AV receiver, or add an AAC, AC3, or EAC3 track to the file alongside the lossless one. Sovereign builds one HLS rendition per source track, so a compatible track is available for selection and is copied intact.

VideoCodecNotStreamable

Mode: Transcode. Full video re-encode.

The source video codec can’t live in an fMP4 container at all: MPEG-2, VC-1, MPEG-4 Part 2, and anything else outside H.264, H.265, VP9, and AV1. It doesn’t matter what the client decodes, because the format Sovereign streams can’t carry the video as it is.

This covers older library content: DVD rips, TV recordings, and early encodes. There’s no way around a re-encode for these titles.

To avoid it: re-encode the affected titles in your library to H.264, which every client Sovereign supports can decode. This trades disk space for never paying the transcode cost again.

VideoCodecUnsupported

Mode: Transcode. Full video re-encode.

The source codec is one Sovereign can stream, but the client never advertised it. AV1 is the common example: a modern browser on a recent machine decodes it, an older TV or streaming stick doesn’t. Browser support for HEVC is patchy too. The same file can direct play in one room and transcode in another, and that’s expected.

The same reason appears when the source’s codec was never identified at all, typically because the library recorded nothing for it. Sovereign can’t show that a copy of an unknown codec would play, so it re-encodes.

To avoid it: play the title on a device that decodes the codec, or re-encode the title to H.264, which every client Sovereign supports can decode.

VideoBitDepthUnsupported

Mode: Transcode. Full video re-encode.

The client advertised the source’s codec, but only at a lower bit depth than the source actually uses. In practice this always means a 10-bit source (usually HEVC Main 10, which most HDR and a good deal of modern SDR content uses) on a client that only decodes 8-bit HEVC.

It’s checked separately from codec support because a codec name alone doesn’t say enough. A client that reports “HEVC” while meaning “8-bit HEVC only” will accept a 10-bit stream and then fail to decode it: playback appears to start, then stalls with no useful error. So if the client didn’t advertise the bit depth the file uses, Sovereign re-encodes the file to something the client can play.

To avoid it: nothing on the server side. This is a property of the playback device. A client that decodes 10-bit HEVC will direct play the same file that forced a transcode elsewhere.

DolbyVisionUnsupported

Mode: Transcode. Video re-encoded and tone-mapped.

Most Dolby Vision files are a normal HDR10, HLG or SDR picture with Dolby Vision instructions riding alongside it. A device that knows nothing about Dolby Vision ignores the instructions and shows the ordinary picture, which is correct, so those files copy like anything else.

Profile 5 is the exception. Its base picture isn’t a standard one: handed to a decoder that does no Dolby Vision processing, it renders in lurid green and purple. Sovereign never sends Profile 5 to a client as it is, so the only way to show the film is to convert it. Like an interlaced source, it’s converted whichever device you watch on. A Dolby Vision file whose base picture can’t be identified at all is treated the same way.

How good the converted picture looks depends on your GPU. On an NVIDIA GPU set up for HDR tone mapping, and on an AMD GPU whose Vulkan tone-map passed its startup check, the conversion applies the file’s Dolby Vision reshaping data and the colours come out right. Intel’s own tone-map and the CPU conversion can’t apply it, so on those hosts a Profile 5 title plays, but with a colour cast.

To avoid it: nothing on the server side. A Profile 5 file is the problem; a copy of the title in any other Dolby Vision profile, or in plain HDR10, direct plays.

VideoRangeUnsupported

Mode: Transcode. Video re-encoded and tone-mapped to SDR.

Every client tells Sovereign which dynamic ranges its display can actually show, and the source’s isn’t one of them. The usual case is an HDR10 title on a device with an SDR panel: the decoder would handle the stream, but the picture would come out washed out and dark with no error to show anything went wrong. Converting it to SDR avoids that.

Browsers are included. The web app asks the browser whether the screen it’s on shows HDR, so a browser on an ordinary SDR monitor gets a tone-mapped transcode of an HDR title rather than the copy, and the same browser on an HDR display gets the copy.

To avoid it: watch HDR content on a display that reports HDR support. The conversion is the fallback for a screen that can’t show it.

ExceedsDecodeResolution

Mode: Transcode. Video re-encoded and downscaled.

The source frame is larger than the resolution the client advertised it can decode for that codec, such as a 4K source on a client that reported decoding only up to 1080p. The video is re-encoded and scaled down to a size the client can handle.

The limit that matters is the client’s advertised decode capability, not the size of its screen. Sovereign doesn’t downscale to panel size: a 4K file plays fine on a 1080p display if the device can decode it, and a transcode there would cost hardware time for no visible benefit.

The target is also sized against the codec being emitted, not the source codec. A client that decodes 4K H.264 but only 1080p HEVC will take a 4K HEVC source, re-encode it to H.264, and keep it at 4K, because in H.264 the client can handle that frame size. The same works the other way: when a title is re-encoded for another reason and the frame has to be scaled down to fit the codec it’s re-encoded to, this reason is reported alongside the cause.

To avoid it: this one is largely inherent to mixing 4K sources with 1080p-class devices. If a specific device is transcoding everything, confirm what it actually advertises before assuming it’s capable of more.

NonAlignedResolution

Mode: Transcode. Video re-encoded and padded.

The client requires that a copied stream’s display dimensions be a multiple of a fixed block size, and the source isn’t. The video is re-encoded and padded up to an aligned size.

This is the least intuitive reason on the list. H.264 encodes in 16×16 blocks, which means a frame whose display height isn’t a multiple of 16 is physically stored as a larger aligned frame plus an instruction to crop it on output. Browsers apply that crop. Some hardware decoders, Roku’s among them, refuse the stream instead, even though the frame is legal.

Where this bites is cinematic aspect ratios. A film letterboxed to 2.40:1 and encoded at 1920×800 is fine, but the same film at 1920×1036 isn’t, and neither is anything else that lands on an odd height. It’s common enough in real libraries that you’ll see it, and it has nothing to do with quality or bitrate.

Sovereign repairs it by padding the frame up to the next aligned size (1920×1036 becomes 1920×1040) so that the stored frame and the displayed frame are identical and no crop survives for the decoder to reject. When another cause has already forced a transcode, this reason is marked minor, because that transcode pads the frame anyway.

ExceedsPeakBitrate

Mode: Transcode. Video re-encoded under the client’s bitrate ceiling.

Some devices buffer each segment of the stream whole, in a fixed amount of memory. A copied stream carries the source’s own bitrate, so a dense passage of a high-bitrate remux can produce a segment that doesn’t fit, and playback stops partway through the film rather than at the start.

Sovereign measures the heaviest stretch of the file rather than its average, because the average predicts nothing here: an action sequence routinely runs two or three times the mean for a whole segment. Where a copy would overflow the buffer, Sovereign first tries cutting the stream into shorter segments, which is enough to rescue most titles and costs nothing in quality. This reason appears only when even that doesn’t fit. Behind another cause it’s marked minor, since the transcode’s bitrate cap keeps its segments inside the buffer anyway.

A file whose peak can’t be measured is given the benefit of the doubt and copied, so this never fires speculatively. A browser’s buffer grows as it needs to, so a browser never sees this reason.

To avoid it: the constraint is the playback device’s memory, so it’s largely inherent to playing very high-bitrate remuxes on streaming sticks and TVs. A lower-bitrate copy of the title direct plays.

InterlacedSource

Mode: Transcode. Video re-encoded with the fields woven into whole frames.

The source stores each frame as two interlaced half-frames, the way broadcast television and DVDs did. Handed to a modern progressive decoder, that shows as combing on anything moving, and MPEG-2 interlaced sources often don’t play at all.

You’ll see this on DVD rips, off-air recordings and older TV content, often beside VideoCodecNotStreamable, since those sources tend to be MPEG-2 as well. A title that reports this reason alone passed every other check: the codec, bit depth, geometry and bitrate were all fine. A file that doesn’t say how it’s scanned is treated as progressive.

The deinterlace filter runs in system memory, so this is one of the transcodes a GPU can’t fully take off your processor. See System Requirements for what that means for sizing.

To avoid it: re-encode the affected titles as progressive video. There’s no way to copy an interlaced source safely.

Throughput Caps

Consequences: ThroughputCapDolbyVision and ThroughputCapSoftware. Output held to 1080p.

Two ways of converting HDR to SDR can’t keep up with a 4K picture in real time, so when a 4K HDR title has to be converted on one of them, Sovereign holds the output to 1080p rather than let playback stall:

ThroughputCapDolbyVision - a Dolby Vision Profile 5 title on an Intel GPU. The conversion that applies its reshaping data runs well below real time at 4K there.
ThroughputCapSoftware - any HDR title whose tone-map runs on the processor, because no GPU on the server can do it. That’s below real time even at 1080p on a four-core machine, and far below it at 4K.

Every other GPU tone-map has the headroom for 4K, so nothing else is capped. To avoid it: give the server a GPU whose tone-map passes its startup check; see Hardware Acceleration.

HdrOutputUnsupported

Consequence. HDR title converted to SDR.

A transcode can keep HDR only in 10-bit HEVC or 10-bit AV1. This client decodes neither at 10 bits, so the HDR title it’s being re-encoded for comes out in SDR. Its display may well show HDR; it’s the decoder that can’t take an HDR stream.

To avoid it: nothing on the server side. A device that decodes 10-bit HEVC or AV1 keeps the HDR.

HdrEncodeUnavailable

Consequence. HDR title converted to SDR.

The client could have taken HDR, but no encoder on this server can produce 10-bit HEVC or AV1 for this transcode, so the title comes out in SDR. A server with no GPU always lands here, since Sovereign has no software encoder for either codec at 10 bits. So does a GPU that failed the 10-bit encode test Sovereign runs at startup.

To avoid it: use a GPU that encodes 10-bit HEVC or AV1. The Hardware Acceleration page lists what each family supports.

Audio Downmixes

Consequences: AudioDownmixedToStereo and AudioDownmixedToFiveOne. The default track lost channels.

These report what converting the default audio track cost:

AudioDownmixedToStereo - a surround track was converted for a client that named no surround format, so it ends up as stereo AAC.
AudioDownmixedToFiveOne - a 7.1 track was converted to EAC3 or AC3, which carry at most 5.1.

Only the default track is reported, because that’s the one playback starts on. To avoid it: play on a device that passes the original format through to a receiver, or add a 5.1 AC3 or EAC3 track to the file.

Where to Find the Reason

Three places report it.

The admin Active Streams page shows the mode as a badge for every live session, with the Playback decision icon (?) beside it. That opens the reasons and the whole route the server took to them, gate by gate, which Playback Decisions explains. This is the fastest way to answer “why is this one transcoding right now”, and the same view is kept on each play in the activity log for after it has ended.

The server log records the reasons when the session starts, minor ones marked, alongside the encoder that was selected, any geometry change that was applied, whether the source was deinterlaced and what happened to its colour:

Stream started for user 4, media 812, device roku-1: Transcode (reasons=VideoCodecUnsupported,
NonAlignedResolution(minor), video=h264_qsv, geometry=pad=1920x1040, deinterlace=False,
color=none, audioTracks=2, acceleration=HardwareEncoding, hwAccel=none)

The log is the better source when you want to see the pattern across a whole library rather than one title.

Whoever is watching can see them as well, without an admin account. Every client shows the play mode in its playback info panel with a line for each reason beneath it: “This device cannot decode the video codec”, “Resolution is above this device’s limit”, and so on. The wording is composed on the server rather than in the app, so every client words it identically and one that predates a reason still renders it correctly. A direct play shows no reason, because nothing was re-encoded.

Reducing Transcodes

If your server is working harder than you’d like, the reasons tell you where to aim:

VideoCodecNotStreamable or VideoCodecUnsupported dominating - your library and your clients disagree about codecs. Re-encoding the offending titles to H.264 permanently removes the cost.
AudioTranscode dominating - cheap, and usually not worth chasing. If you want the surround mix preserved, add a compatible audio track to the file.
VideoBitDepthUnsupported or ExceedsDecodeResolution dominating - the constraint is the playback device, not the server. Either accept the transcode or use a more capable client.
VideoRangeUnsupported dominating - HDR titles meeting SDR screens. The conversion is right for those screens; an HDR display gets the copy.
NonAlignedResolution on titles that used to be fine - suspect storage before you suspect the file.
InterlacedSource dominating - an older library. Re-encoding those titles as progressive video is the only fix, and it also buys back the processor time the deinterlace filter costs.
ExceedsPeakBitrate dominating - very high-bitrate remuxes meeting a device with a small media buffer. Keeping a lighter copy of those titles removes it.

To find out whether a device would direct play a title before anyone presses play, use the Playback Simulator. Where a transcode can’t be avoided, you can still make it cheaper: Hardware Acceleration moves the encode onto a GPU, and the Video Quality settings control how many bits each transcode is allowed to spend.

Next Steps

Playback Decisions - every step of the decision, and what each check does without evidence
Video Quality - quality tiers and the bitrate ceiling applied to a transcode
Hardware Acceleration - GPU encoding and how a device is selected
Active Streams - the live view of every session and its mode
Configuration Overview - full environment variable reference

Titles, artwork, people and descriptions shown in screenshots are fictional and were created for illustration. Sovereign doesn't include or supply any media: it plays the library you bring.