How playback works

When you press play, your server and your app negotiate the cheapest way to get the video to your screen. Most of the time that is the original file, untouched. Sometimes the server has to do work first. This page explains when and why, so a "Transcode" badge in the dashboard is never a mystery.

The three ways a stream can play#

Direct Play. The app plays the original file exactly as it sits on disk. No conversion, no quality loss, almost no load on your server. This is the goal, and it is what happens whenever the file, your device, your connection, and your settings all line up.

Direct Stream. The file is repackaged on the fly, but the video itself is not touched. This happens when the container is the problem rather than the content, for example an MKV file in a web browser. The picture is identical to the original and the server load is small. It also covers the case where only the audio needs converting, say a surround track on a laptop with stereo output. The video is still passed through untouched.

Transcode. The server re-encodes the video before sending it. This is the expensive one, and the only one where picture quality can change. The server only does it when there is no other way to play the title on that screen.

Your server never converts anything in advance. Files stay exactly as you put them there, and conversion happens only for the stream, only while someone is watching.

Why a stream converts#

A transcode always has a reason, and the playback dashboard shows it. The common ones:

• The quality you picked, or Auto picked, is below the original. Sending a 40 Mbps file over a 10 Mbps connection would just buffer, so the server makes a smaller version in real time.
• Subtitles are burned in. Drawing subtitles into the picture requires re-encoding it. Regular text subtitles do not do this, see below.
• The device can't play the codec. An older TV that doesn't know AV1, or a browser facing a format it can't decode.
• HDR on a screen that can't show it. The server tone-maps HDR down to SDR so colors don't look washed out.
• A few genuinely awkward formats, like 10-bit H.264 or interlaced video, which many devices claim to play and then don't.

One thing that never forces a transcode on its own: the container. A container mismatch only costs the light repackaging step.

When the server is not sure, it leans toward not converting. An unknown bitrate or bit depth plays the original rather than starting a conversion that might not be needed.

When a full conversion does run, the video comes out as H.264, which everything plays. If your server has HEVC full-transcode encoding turned on (Admin, then Settings, under Hardware transcoding; off by default), devices that support HEVC get that instead, which keeps more detail at the same bandwidth.

Picking a quality#

The quality menu in the player offers Original plus a ladder of smaller versions, from 1080p down to 360p. The menu is source-aware: you will only see options that are actually smaller than the file, so a 720p file does not pretend to offer 1080p.

Admins can also set a Max quality per person in Admin, then Users. That cap applies to everything the person plays and is useful for guests on limited upload.

What Auto does#

Auto is the default, and it is designed so you never think about it:

• Before playback it runs a quick speed check against your server and picks the highest quality your connection can carry with comfortable headroom.
• If your connection can carry the original, Auto plays the original. Auto is not "always convert".
• During playback it watches for trouble. If the stream stalls or rebuffers, it drops straight to a quality that fits the bandwidth it is actually seeing, rather than stepping down one notch at a time and stuttering through each step.
• After a long stretch of clean playback it climbs back up carefully, one step at a time. If a climb turns out to be too optimistic it corrects once and then stops climbing for that session, so quality never see-saws.
• What it learns about your connection carries into the next session, so a link that failed at a quality tier yesterday does not get to fail at it again today.

If you would rather always get the untouched file and let the player buffer, pick Original in the player, or set your default under Settings, then Playback.

Subtitles and audio#

Text subtitles are free. SRT, ASS and similar formats are delivered as a separate track and drawn by the app, so turning them on never changes video quality or server load.

Burned-in subtitles cost a transcode. If you explicitly ask for subtitles to be burned into the picture, the video has to be re-encoded. Image-based subtitles from discs (PGS, VobSub) are drawn by the app itself where the app supports it.

Audio converts independently. If only the audio track is the problem, the server converts just the audio and passes the video through untouched. When a file carries several audio tracks, the server prefers one your device can play natively before it converts anything.

What your server can handle#

Repackaging and audio-only conversion are cheap; a server can do many of those at once. Full video transcodes are the expensive part, and your server protects itself:

• CPU transcodes are capped. The default sizes the cap to your CPU so the machine stays responsive; you can pin a number under Settings if a heavy 4K transcode ever makes the box struggle.
• GPU transcodes run in their own separate pool on top of the CPU budget. If your machine has a supported GPU, turning on hardware transcoding is the single biggest capacity upgrade you can give your server, and it is free.
• If a transcode genuinely cannot keep up with real time, the app tells you plainly instead of buffering forever. That is your cue to lower the quality, or to set up hardware transcoding.

If something is off#

• Quality drops during playback. That is Auto reacting to your connection, most often on the relay path. Check which connection path you are on, and see Local, direct, or relay.
• A title shows "Transcode" and you expected Direct Play. Open the playback dashboard; the reason is shown next to the session. The usual suspects are a burned-in subtitle, an HDR file on an SDR screen, or a per-user quality cap.
• "The server can't convert this fast enough." The box is out of transcode headroom. Lower the quality for now, and set up hardware transcoding if your machine qualifies.
• Playback stutters on big files on the local network. Make sure the app is actually connecting locally rather than over the relay. Local, direct, or relay shows how to tell.

Still stuck? Getting help & feedback covers what to send us.