Playback and transcoding

Collectoh plays most files exactly as they are. When a device can't play a file, the server converts only what it has to and tells you why. This page covers that decision, how to use a graphics chip, and the player's subtitle, sound and skipping options.

#How Collectoh decides what to send

Each time you press play, the player tells the server what it can handle, and the server compares that with the file. The decision is made per device, so the same film can play untouched on your television and be converted for an older phone.

Picture and sound are decided separately. The most common conversion copies the picture and converts only the sound, for example a TrueHD 7.1 track to stereo. That costs very little.

#Seeing why

Open Stream info in the player's controls, or press I. It shows the method, every reason for it, and what is happening to the video and the audio. Some reasons you may see:

Sometimes a stream can't start at all: the server is set to remux only, your account isn't allowed conversions, or a profile is outside its viewing hours. The player then tells you why.

#Choosing the quality

The player's Quality menu sets how much this device asks the server to send:

• Automatic, for this connection (the default): sized to what your connection carried last time.
• Original, converted only if it must be: the file as it is whenever the device can play it.
• A limit, from 40 Mb/s down to 750 kb/s: a film over it is converted down to fit. Each says the tallest picture it carries, such as 3.0 Mb/s, up to 720p.

A new choice restarts the stream where you are. It's kept on this device only, because a phone on a train and the television at home aren't the same connection. You can also set it in Settings → Playback → Streaming quality on this device. Your server's own limits for streams from away still apply.

#Choosing a version

When a film has several versions, such as 4K HDR and 1080p, the player's Version menu lists each one with what it would take to play. Your choice is remembered for that film on that device. If you haven't chosen, Settings → Playback → Which version plays decides. (Settings is in the menu under your avatar.)

#Hardware acceleration

Software conversion always works. A graphics chip does the same work with far less effort, so more people can watch at once.

The FFmpeg in the Docker image already supports NVENC, Quick Sync and VAAPI, and it bundles the Intel and AMD drivers. The arm64 image has no NVENC and no Intel driver.

#Docker with Intel or AMD graphics

1. On the host, find the render group's id:

   getent group render | cut -d: -f3

   Copy

2. Put it in your .env file, for example RENDER_GID=993.

3. Start Collectoh with the GPU overlay that ships beside docker-compose.yml:

   docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d

   Copy

The overlay passes the render device into the container and adds its group:

services:
  server:
    devices:
      - /dev/dri:/dev/dri
    group_add:
      - '${RENDER_GID:-993}'

A wrong group id is the most common reason hardware conversion "doesn't work" in a container. Collectoh detects it and gives the fix in its start-up log and on the Diagnostics page.

#Docker with NVIDIA graphics

1. Install the NVIDIA driver and the NVIDIA Container Toolkit on the host.

2. In docker-compose.gpu.yml, uncomment the environment and deploy blocks. The server section then also contains:

       environment:
         NVIDIA_VISIBLE_DEVICES: all
         NVIDIA_DRIVER_CAPABILITIES: compute,video,utility
       deploy:
         resources:
           reservations:
             devices:
               - driver: nvidia
                 count: 1
                 capabilities: [gpu, video]

   Copy

3. Start with both compose files, as above.

Without Docker, Collectoh uses the ffmpeg on your PATH, or the one FFMPEG_PATH points to, and can accelerate anything that build supports. AMF on Windows and VideoToolbox on a Mac work this way.

#Checking it works

An encoder can be built into FFmpeg and still not work. So at start-up, Collectoh asks each encoder to encode a one-second test picture. Admin → Diagnostics → Transcoding shows:

• Will use: the encoder that new conversions get.
• Each encoder: works, failed (with FFmpeg's error) or not in this FFmpeg build, with its HEVC encoder listed beneath it.
• HDR tone mapping: the method this machine uses.
• Render device (Linux only): whether /dev/dri/renderD128 can be opened, and the exact fix if it can't.

After changing drivers or compose files, press Re-probe hardware. The next stream uses the new result. While something plays, Admin → Sessions shows which encoder each conversion is using.

Collectoh picks the best working encoder by itself. To choose one yourself, use Hardware acceleration in Admin → Settings → Transcoding: automatic, off (the processor only), or a particular chip. It applies to the next stream that starts. As the server was started follows the HW_ACCEL environment variable, which takes nvenc, qsv, vaapi, amf, videotoolbox, or none for software only.

Consumer NVIDIA cards limit how many NVENC sessions can run at once, so Collectoh stops at five. HW_SESSION_LIMIT changes this. Past the limit, new conversions run in software. If a hardware session fails partway through, it carries on in software from the same point.

#Conversion settings

These settings are in Admin → Settings → Transcoding. Changes apply from the next stream.

#HEVC

HEVC carries the same picture in roughly 40% fewer bits than H.264. That matters most on a slow connection: at 3 Mb/s, HEVC gives 1080p where H.264 manages 720p.

A conversion uses HEVC only when all three of these are true:

• The setting allows it.
• The device plays HEVC.
• Your hardware's HEVC encoder passed its test (see the HEVC line on Diagnostics).

There is no software HEVC, because it would be far too slow. If a hardware HEVC encoder fails partway through a film, the stream stops with a message. Retry carries on in H.264, and that device stays on H.264 for three hours.

#Sizing to the connection

The web player measures how fast the stream arrives and sends that measurement with its next request. The next conversion is then the tallest picture your connection can carry comfortably, not a bigger picture squeezed until it looks blocky.

Each conversion is a single quality. The server can also encode several qualities at once for a device that asks for adaptive streaming. Each quality is a separate encode, so TRANSCODE_MAX_RUNGS (default 6) caps how many run across the whole server.

#HDR and Dolby Vision

HDR10, HLG and Dolby Vision play untouched on a device that can show them. For a screen that can't, the picture is converted and tone-mapped to SDR so it doesn't look washed out. Collectoh uses the best method your machine can run: the graphics chip where the FFmpeg build allows it, otherwise libplacebo, OpenCL or plain software. Diagnostics shows which one it uses. Tone mapping in plain software roughly halves conversion speed. HDR tone mapping in Admin → Settings → Transcoding switches it off, if you'd rather have the speed and don't mind the washed-out colours.

Dolby Vision profiles 7 and 8 carry an HDR10 picture underneath, so they are treated as HDR10. Profile 5 has no such fallback. For any other kind of screen it is always converted, and its colours are correct wherever libplacebo works.

#Limits on simultaneous streams

Only converting the picture counts towards these limits. Direct play, remuxing and sound-only conversions are never refused because the server is busy.

When the limit is reached, a new conversion gets a clear message instead of a stream that stutters. When the server is full, a session that has been paused for more than five minutes gives up its place.

Admin → Sessions shows every stream, how many conversion slots are in use and which viewers are remote. Each stream shows the device playing it and its address, the picture's height and bitrate, and the viewer's connection speed. From there you can end a stream, with an optional message to the viewer, or read its FFmpeg log. At the top, graphs show the last hour of the machine's and the server's processor and memory use, and the bandwidth sent to players at home and away.

A number chosen in the settings takes over from MAX_CONCURRENT_TRANSCODES straight away; Automatic hands it back. The variables go in the server's environment: section of docker-compose.yml. If a graphics chip does the work, you can usually allow more conversions:

services:
  server:
    environment:
      MAX_CONCURRENT_TRANSCODES: 4

#Subtitles

Collectoh finds subtitles inside the video file and in separate files beside it. A separate file is a .srt, .ass or .vtt named after the video. The name can also include a language and forced or sdh, as in Heat (1995).en.srt (see how to name your files). Files in older text encodings, such as Windows-1252, display correctly.

Choose a track from the player's Subtitles menu, or press C to step through the tracks.

To have tracks chosen for you, open Settings → Audio and subtitle languages:

• Audio language plays that language's track when a film has one, instead of the file's default.
• Subtitle language and Subtitles come on decide when subtitles appear by themselves: only when you choose them, when the audio is in another language, or always. With the audio in your subtitle language, forced subtitles still show, for the lines spoken in another language.
• Prefer subtitles for the deaf and hard of hearing picks those over the plain ones when a film has both.

These are kept on your account, so they apply on every device. A track you pick in the player is remembered for that film instead.

• Plain text (SRT, WebVTT) is drawn by the browser. You can set its size, font, colour, background and edge in Settings → Accessibility → Subtitles.
• Styled ASS and SSA keep their own styling, positioning and embedded fonts. The browser draws them while the film keeps playing directly.
• Picture subtitles (PGS from Blu-ray, VobSub from DVD) can't be drawn by a browser. They are burned into the picture, which means the picture is converted. If you pick one mid-film, the stream restarts at the same moment.

#Finding subtitles online

OpenSubtitles is built in, with nothing to set up: your server asks it through your Collectoh account, a number of files a day. With an OpenSubtitles account of your own, set in Admin → Metadata agents, it asks directly, as many as that account allows.

1. Get an API consumer key from opensubtitles.com, and create an account there. Downloads count against the account (20 a day on a free account).

2. In Admin → Metadata agents, under Subtitles, save the key, your username and your password. They take effect straight away. Or add all three values to .env and restart with docker compose up -d:

   OPENSUBTITLES_API_KEY=your-key
   OPENSUBTITLES_USERNAME=your-username
   OPENSUBTITLES_PASSWORD=your-password

   Copy

An admin can then use Find subtitles on a film's or episode's page, or in the player's Subtitles menu:

1. Choose a language.
2. Choose whether you want SDH (subtitles for the deaf and hard of hearing), or search by title instead.
3. Press Download.

The track is ready straight away. It is saved beside the video if the library's Save fetched subtitles beside the media option is on and the folder can be written to. Otherwise it is kept in the server's metadata folder.

Subtitles are also fetched by themselves. Each night, Collectoh asks OpenSubtitles for a subtitle in the library's language for every film and episode that has no subtitle file, newest first, as many as your account allows that day. The rest wait for the next night. Nothing is read from your videos: a film is found by its IMDb or TMDB id, so it gets a subtitle once it has been matched. Turn this off for a library by clearing Fetch missing subtitles in its settings.

#Fixing timing

If a track runs early or late, an admin can press Fix sync under Timing in the Subtitles menu. Collectoh listens for speech and moves the track to match it. It corrects both a fixed delay and the gradual drift of subtitles made for a different frame rate, such as 23.976 fps subtitles on a 25 fps film. The first fix on a film can take a minute or two. To have films with subtitles listened to ahead of time, so the first fix is instant, set Voice activity in Admin → Settings → Library to run at night. It's off by default, because it listens to every such film in full.

The buttons beside Fix sync move the track 0.1 or 0.5 seconds earlier or later. Reset restores the track's original timing. The correction is saved with the track, so everyone gets it, and playback doesn't restart.

#Searching what's said

A film's, episode's or video's subtitle file also becomes a transcript of it, so the main search finds a line said in it, and In-video hits open the player at that moment. Only subtitle files are used: the ones beside your videos and the ones Collectoh fetches, never subtitles stored inside a video file. Collectoh reads the one in the library's language, and never a forced one. When a subtitle's timing is fixed, its transcript moves with it.

#Skipping intros and credits

Collectoh finds intros by listening for the stretch of sound that a season's episodes share. It does this overnight, for seasons of three or more episodes and for the repeated openers of course lessons. Intro markers and Credits markers in Admin → Settings → Library choose when each happens: never, at night, or at night and as soon as new episodes are added (the default). It finds credits from the closing theme, the picture going dark and the sound fading away. Skip Credits is offered only when the detection is confident.

• Skip Intro appears just before an intro starts. Press it, or press S.
• To skip without being asked, turn on Settings → Playback → Skip intros and credits without asking, or use the switch in the player's Chapters menu.
• The seek bar shows intros and credits as bands, and chapters as ticks. Page Down and Page Up jump between chapters.
• At the end of an episode the next one starts by itself after a five-second countdown, which Cancel stops. Turn that off, or change the countdown, with Settings → Playback → Play the next episode by itself and Before it starts. It applies to the next item in a queue too; a course has its own switch beside its lessons.
• Admins can correct markers from the Chapters menu. They can add an intro, credits or a chapter at the current position, move a start or an end, or remove a marker. Detection never overwrites markers made by hand.

Watched when the credits start, in Admin → Settings → Playback, counts a film as watched as soon as its credits begin.

#Scrubbing previews

Hover over or drag along the seek bar to see the picture at that moment. The previews, one for every five seconds of video, are made during the nightly maintenance window (Admin → Maintenance). A newly added video has them after its first night. Videos shorter than 30 seconds don't get previews. Preview thumbnails in Admin → Settings → Library can switch them off, or leave them to the nightly catch-up only.

#Optimised versions

An optimised version is a copy made in advance for devices that would otherwise need a conversion. It is H.264 video with stereo AAC sound in an MP4 file, no taller than 1080p, 720p or 480p. The copy becomes another version of the item. Because direct play always wins, a device that can't play the original gets the copy automatically.

• For one item, an admin chooses a height under Optimised copy on the item's page.
• For a whole library, turn on Keep an optimised copy of everything in the library's settings (Admin → Libraries → Edit). New files get their copies as they are scanned, and a nightly task makes any that are missing.

Copies are made one at a time and kept in the metadata folder, never among your media. Background conversions in Admin → Settings → Transcoding changes both: the preset they're encoded at (slower makes a smaller file for the same picture, and keeps the processor busy for longer) and how many are made at a time. Offline copies for downloads follow the same settings. A file that is already a suitable H.264 MP4 isn't copied. If an original changes, its copy is made again.

Admin → Optimized shows two lists:

• Converting now: the copy being made, with how far it has got, and the ones waiting after it. Offline copies for downloads are made in the same line and appear here too, with who asked for them.
• Optimised copies: every copy kept, largest first, with its library, height, size and date, and how much space they take together. Remove deletes one after you confirm. A library that keeps a copy of everything makes it again at night, so turn that setting off first if you want it gone for good.

#Before a film: trailers and pre-roll

With Collectoh Plus, a film can open like a night at the cinema. Set these in Admin → Settings → Pre-roll:

• Cinema trailers: play one to five trailers of other films in your libraries first. They're picked at random from films the person watching hasn't seen yet. From films released can keep them to recent films. A trailer is a film's own trailer file, such as Heat (1995)-trailer.mp4 or a file in a Trailers folder beside the film; see Naming and organising your files.
• Pre-roll videos: your own clips, such as a "please silence your phones", played after the trailers. Add each one as a file inside one of your storages, then choose whether to play them all in order or one at random.

Nothing plays before an episode or a lesson, or when a film is resumed. Skip goes straight to the film. A library can switch all of this off in its own settings. Trailers and pre-rolls play as they are, so keep them to MP4 (H.264 with AAC).

#Downloads for offline

If your account may download, Download appears on films, episodes and courses.

1. Choose a quality: Same as the original, Up to 1080p, Up to 720p or Up to 480p, smallest.
2. Choose whether to include subtitles and, for a course, its resources.
3. Press Prepare.

The Downloads page shows the copy being prepared, then offers Save file when it's ready. A course is prepared lesson by lesson but tracked as one download. Prepared downloads are removed after thirty days. Who may download is set per account and per library: see sharing and accounts.

#Sound

Choose an audio track from the player's Audio menu. Surround sound goes straight through to a device that plays it. For a device that doesn't, it is folded down to stereo.

Dialogue boost helps when that fold-down buries the voices. Set it to Off, Light or Strong (night mode) in Settings → Playback or in the player's Audio menu.

• It raises the centre channel, which carries the dialogue, and evens out loud and quiet passages.
• Strong also limits the loudest peaks, so explosions don't wake the house.

Dialogue boost works only when Collectoh itself folds surround sound down to stereo. The Audio menu shows "On for this stream" when it is working.

The speed menu, or the [ and ] keys, sets speeds from 0.5× to 2×.

#Sleep timer

The player's Sleep menu stops playback after 15, 30, 45, 60 or 90 minutes, or at the end of the episode. The sound fades out over the last ten seconds, playback pauses, and nothing else starts. The music and audiobook players have the same timer.

Separately, when three items in a row have started by themselves, the fourth waits until you press Keep watching. If nobody answers within 30 seconds, playback stops there.

The Help page, in the menu under your avatar, lists every keyboard shortcut.