How playback works

When you press play, your server checks what your device and connection can handle. It sends the original video when possible and converts it when needed. The playback dashboard shows which method is in use.

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.

For streaming, conversion happens as needed and leaves your source files unchanged. Smaller offline downloads are prepared separately before you watch.

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.
• Less widely supported 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), apps that can play HEVC (the web, desktop and Apple apps today) 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 adjusts quality to the connection:

• 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, to avoid repeated quality changes.
• What it learns about your connection carries into the next session, to help it choose a suitable starting quality.

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 do not require video conversion. SRT, ASS and similar formats are delivered as a separate track and drawn by the app. Extracting and preparing a track still uses some server resources.

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 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.

When something counts as watched#

Your server decides when a movie or episode is finished, so the result is the same on every app. A title is marked watched as soon as one of these happens:

• You reach the end credits. Where your server has detected the credits, reaching them counts, however long they run.
• You pass 90%. This catches everything else, including films with long credits that were never detected.
• Less than 5 minutes are left and you are past 75% of the way in.
• The player reaches the natural end of the file.

Very short clips, under 5 minutes, count as soon as you start them.

Once a title is marked watched, it leaves Continue Watching, the next episode moves up, and the resume point resets so the next play starts from the beginning. If you stop before any of these points, your place is kept and you resume where you left off.

Seeking back into a title you just finished, in the same viewing, does not undo the watched mark. Starting it again later counts as a rewatch and tracks a new resume point.

These points are fixed and are not a setting. To change a title's state by hand, use Mark Watched or Mark Unwatched on its details page.

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.