LinuxtoolsTested on real hardware

Plex Transcoder Tuning for Weak CPUs (API)

Tune a headless Plex server's transcoder over the API for low-power hardware: disable broken hardware acceleration, prefer speed, cap concurrent transcodes, and use a RAM temp dir.

Distrosubuntu, debian, alpine
Shellbash
Updated
Script
bash
#!/usr/bin/env bash
# Tune Plex transcoder prefs for a low-power CPU via the API.
# No UI needed — works on a headless server.
set -euo pipefail

PLEX_HOST="${PLEX_HOST:-http://127.0.0.1:32400}"
PLEX_TOKEN="${PLEX_TOKEN:?Set PLEX_TOKEN to your X-Plex-Token}"

setpref() {
  local key="$1" val="$2"
  curl -fsS -X PUT \
    "${PLEX_HOST}/:/prefs?${key}=${val}&X-Plex-Token=${PLEX_TOKEN}" \
    && echo "set ${key}=${val}"
}

# Hardware transcoding OFF — broken on video engines that don't cover
# your library's codecs (e.g. old QuickSync = H.264 only, no HEVC/AV1).
setpref HardwareAcceleratedCodecs 0

# Prefer speed over quality — a weak CPU can't afford "make my CPU hurt".
# 0=slower/higher-quality ... higher=faster/lower-quality
setpref TranscoderQuality 1

# Cap simultaneous CPU transcodes so one stream can't starve the rest.
setpref TranscodeCountLimit 2

# Scratch on a RAM tmpfs keeps churn off the media array (Plex makes its
# own Transcode/ subdir here). /tmp is tmpfs on many systems.
setpref TranscoderTempDirectory /tmp

# Tone-map HDR->SDR correctly WHEN a transcode does happen.
setpref TranscoderToneMapping 1

What this does

Applies a set of transcoder settings tuned for a low-power Plex server, entirely over the API — no web UI needed, which is ideal for a headless NAS or container. The goal is not to make transcoding fast (you can’t, on weak hardware) but to keep the occasional unavoidable transcode from overwhelming the box, and to stop a broken hardware-acceleration setting from breaking playback outright.

The ideal is that almost nothing transcodes — see the Direct Play and transcoding guide for how to get there. These settings are the safety net for the rare stream that does.

Prerequisites

  • curl installed
  • Your X-Plex-Token — grab it from any authenticated Plex web request, or from the server’s Preferences.xml (PlexOnlineToken)
  • The server reachable at http://<server-ip>:32400

Usage

bash

export PLEX_TOKEN="YOUR_PLEX_TOKEN"
export PLEX_HOST="http://127.0.0.1:32400"   # or your server IP
chmod +x plex-transcoder-tune.sh
./plex-transcoder-tune.sh

What each setting does

Preference key Value set Effect
HardwareAcceleratedCodecs 0 Hardware transcoding off — safe on chips whose video engine doesn’t cover HEVC/AV1
TranscoderQuality 1 Prefer higher speed over quality
TranscodeCountLimit 2 Max simultaneous CPU transcodes
TranscoderTempDirectory /tmp Scratch on RAM tmpfs, off the media array
TranscoderToneMapping 1 Correct HDR→SDR tone-mapping when a transcode happens

Notes

  • Only enable hardware acceleration if your chip’s video engine covers your codecs. On an old QuickSync generation (H.264-only), turning it on causes “neither Direct Play nor conversion available” for HEVC/AV1. Confirm the generation first.
  • Client-side matters too: set the Plex client’s streaming quality to Maximum / Original so it Direct Plays instead of requesting a lower bitrate that forces a down-transcode.
  • Verify: re-read the current values any time with curl -s "$PLEX_HOST/:/prefs?X-Plex-Token=$PLEX_TOKEN" and grep for the keys above.
  • Don’t enable TranscoderCanOnlyRemuxVideo — it breaks bandwidth-limited remote streams (e.g. a phone on cellular) that legitimately need a transcode.
All playbooks