How playback works

When you press Play, Credenza looks at the file on disk and at the device you are watching on, and picks one of two ways to get the picture to you:

Direct play — the file is sent exactly as it is. Nothing is converted, and the server does almost no work.
Transcoding — ffmpeg converts the file into a stream your device is guaranteed to play, a few seconds at a time, while you watch.

You never have to choose between them. But knowing how the choice is made helps you understand why one film starts instantly and another makes your server’s fans spin up.

Direct play: when your device can play the file as it is

Before a video starts, the player asks your browser (or the Android app) which formats it can open, and sends that list to the server. The server compares it against the file. If your device can open the container and decode both the video and the file’s default audio track inside it, the file is played directly.

Direct play is only ever considered for these formats. Anything else is always transcoded.

	Can direct play, if your device supports it
Containers	MP4 (`.mp4`, `.m4v`), MOV, MKV, WebM
Video	H.264, HEVC (H.265), VP9, VP8, AV1
Audio	AAC, MP3, AC-3, E-AC-3, Opus, Vorbis, FLAC

Whether a particular combination works depends on the device, not the server. For example, Chrome plays H.264 with AAC inside an MKV file, but Safari does not, and HEVC support varies from one device to the next. Because the answer comes from the device itself, the same file can play directly on one screen and be transcoded on another.

What makes the server transcode instead

Even when your device could play the file directly, some choices mean the server has to transcode it:

A subtitle that is a picture rather than text (PGS or VobSub, common on Blu-ray and DVD rips). It has to be drawn into the video. See Subtitles.
An audio track other than the file’s default. A device playing a whole file can only play the track the file marks as default, so choosing another means the audio is converted.
A specific quality from the Quality menu. Picking Original or a resolution is a request to transcode, and the server honours it.

When a video is being transcoded, the playback stats panel shows a Reason row with the exact explanation, for example “This player cannot decode HEVC video in a MKV file, so the stream is transcoded.”

Transcoding: what the server does

When transcoding, the server converts the video to H.264 and the audio to stereo AAC, the combination every browser can play, and sends it as HLS: a stream of short segments, six seconds each by default. ffmpeg starts at the point you are watching and works forwards, staying ahead of the player.

The conversion runs on the CPU, or on a graphics card if your server has a supported one. See Hardware acceleration.

Seeking during a transcode

You can jump to any point in a video, even one ffmpeg has not reached yet. If the point is behind what has already been converted, or only a few segments ahead, the player simply fetches it. If you jump further ahead than that, the server stops the current conversion and starts a new one at the point you jumped to. Segments already made during the session are kept, so jumping back to them is instant.

A jump to an unconverted point takes a moment before the picture appears, because the first segment there has to be encoded before anything can play. On a slow machine this is where you will notice transcoding most.

In direct play, seeking works like any video file: the device asks for the part of the file it needs.

Choosing a quality

The Quality entry in the player’s settings menu (the gear icon) lists what this file can be played at. It only appears when there is more than one option.

Option	What it does
Direct play	Sends the file as it is. Shown only when your device can play this file directly. The hint next to it is the file’s own bitrate.
Original	Transcodes at the file’s own resolution, capped at the server’s bitrate ceiling.
1080p, 720p, 480p, 360p	Transcodes at that height, at up to 8, 4, 2 and 1 Mbps respectively, never above the server’s bitrate ceiling. Only resolutions below the file’s own are offered.

By default the player uses Direct play when it can and Original when it cannot.

Changing quality restarts the stream at the second you were watching, with a new conversion at the new setting. The choice is remembered per browser, not per account, because the right quality depends on the connection a device is on. Pick 720p on a laptop in a hotel, and your TV at home keeps playing at full quality.

Administrators set the bitrate ceiling, encoder speed and quality at Settings → Server → Transcoding. See Hardware acceleration for that page.

Choosing an audio track

If a file has more than one audio track, an Audio entry appears in the settings menu. Tracks are labelled by their title where the file gives one (such as “Commentary”), otherwise by language, with the codec and channel layout alongside.

Changing track restarts the stream at the same second. The player remembers the language you picked, not the track itself, so the next episode starts in the same language even if its tracks are in a different order.

When transcoding, audio is always converted to stereo AAC, so surround sound is mixed down to two channels. When playing directly, you get the file’s own audio.

What playback costs your server

Direct play costs almost nothing. The server reads the file from disk and sends it. Direct-play sessions do not count towards the concurrent stream limit, so a server set to four streams can serve many more viewers who are all playing directly.

Transcoding is the most expensive thing Credenza does. Each transcoded stream is a full video encode running for as long as someone is watching:

CPU or GPU. A software encode can keep several CPU cores busy. Hardware encoding moves the encoding to a graphics card but, as the next page explains, decoding the source still happens on the CPU.
Concurrent streams. The server transcodes at most four videos at once by default (Concurrent streams in the transcoding settings). Anyone starting a fifth sees “Maximum concurrent streaming sessions reached” until another stream stops. Set it to 0 to remove the limit.
Disk. Segments are written to the transcoding folder while someone watches, roughly a gigabyte per hour of 1080p video, and deleted when the stream stops.

A stream stops when the viewer leaves the player. Closing a tab doesn’t notify the server, so a stream nobody has requested anything from for five minutes (Idle timeout) is stopped automatically.

Why the server doesn’t just repackage the file

Some media servers can “re-mux” a file: they copy the video untouched into a new container, which costs very little and avoids re-encoding. Credenza deliberately does not do this yet.

The reason is seeking. Credenza tells the player up front exactly how long the video is and where every segment falls, which is what lets you jump anywhere at any time. When video is copied rather than encoded, segments can only be cut at the keyframes already in the file, which fall wherever the original encoder placed them. The segments would no longer line up with what the player was told, so jumps would land in the wrong place and the video would end at the wrong time, with no error to show anything was wrong.

In practice, this means a file whose picture your device could play, but whose container or audio it cannot, is fully transcoded. If that happens often, converting those files to MP4 with AAC audio lets them play directly.

Resume and continue watching

While you watch, the player reports your position to the server every ten seconds. Positions belong to your account, not your device, so you can stop a film on your phone and pick it up on your TV.

If you stop more than a minute in, the film or episode appears in Continue watching on the home page, and its page shows Resume with the time left. Start from the beginning forgets your position.
When you reach the last 5% of the running time (never less than one minute or more than five minutes before the end), it counts as Watched and leaves Continue watching.
Mark as watched and Mark as unwatched, on a title’s page or a tile’s menu, do the same by hand. Remove from Continue watching takes it off the row by forgetting your position, without marking it watched.

Resuming starts a fresh conversion at the second you stopped. The previous session’s segments are not kept between viewings.

The next-episode card

When an episode plays to its end, a card appears over the picture showing Up next: the next episode’s number and title with its season’s poster, and Play now and Cancel buttons. By default it counts down from ten seconds and then starts the next episode. It follows the show’s order across seasons and skips episodes that are not available to play.

To keep the card but stop the countdown, turn off Autoplay next episode in the player’s settings menu. That choice is remembered per browser. The countdown pauses while the tab is in the background, so it won’t start a new episode in a tab nobody is looking at.

Separately, the home page’s Up next row suggests the next episode of each show you have finished an episode of.

Who is watching now

Administrators can see who is watching at a glance on the Activity page, in its Right now section. Watching now lists each account that is currently playing or paused, what they are watching and how far in they are. Recently watched lists what people watched earlier.

The list relies on players checking in, so a viewer who closes the tab stays listed for up to about a minute and a half before dropping off.

To see what the server itself is doing with a particular stream, such as which encoder it is running on, open the playback stats panel in that player.