Skip to content

feat: add direct play and 4K streaming guide sections #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bakerboy448 merged 4 commits into from
Mar 12, 2026
Merged

feat: add direct play and 4K streaming guide sections #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
cc85692
feat: add direct play and 4K streaming sections
bakerboy448 Mar 12, 2026
b596d8f
feat: split has_4k_content into distinct direct play and 4K controls
bakerboy448 Mar 12, 2026
b5c81c2
docs: add theme features reference and CI badges to README
bakerboy448 Mar 12, 2026
7c4d931
fix: markdownlint blank lines around fenced code blocks
bakerboy448 Mar 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,13 +21,15 @@ MkDocs documentation templates with `mkdocs-macros-plugin` for Jinja2 variable s
## Development

- Build: use a venv or Docker, never system-wide pip

```bash
cd plex-guide
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp mkdocs.sample.yml mkdocs.yml
.venv/bin/mkdocs build
```

- Lint: `npx markdownlint-cli2 "**/*.md"` and `shellcheck plex-guide/setup.sh`
- CI runs markdownlint, shellcheck, yamllint on all PRs
- GitHub Pages deploys from GHA workflow (plex guide at `/plex/` subpath)
Expand Down
21 changes: 21 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# docs-templates

[![Build Plex Guide](https://github.com/baker-scripts/docs-templates/actions/workflows/build.yml/badge.svg)](https://github.com/baker-scripts/docs-templates/actions/workflows/build.yml)
[![Lint](https://github.com/baker-scripts/docs-templates/actions/workflows/lint.yml/badge.svg)](https://github.com/baker-scripts/docs-templates/actions/workflows/lint.yml)
[![Live Preview](https://img.shields.io/badge/Live_Preview-GitHub_Pages-blue)](https://baker-scripts.github.io/docs-templates/plex/)

MkDocs documentation templates with variable substitution. Fork, customize, and deploy your own documentation site.

## Available Templates
Expand Down Expand Up @@ -116,6 +120,8 @@ Set to `true` to show the section, `false` to hide it.
| `guide_url` | `""` | Public URL for the guide |
| `has_plex_pass` | `true` | Plex Pass features section |
| `has_plex_home` | `false` | Plex Home notes |
| `has_direct_play` | `true` | Direct play optimization guide |
| `has_4k_content` | `true` | 4K streaming section |
| `has_migration` | `false` | Watch history migration section |
| `show_costs` | `false` | Server cost information |
| `server_cost` | `""` | Monthly cost string |
Expand All @@ -126,6 +132,21 @@ Templates use [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io

Conditional sections use `{% if feature_flag %}...{% endif %}` to show/hide content based on your configuration.

## Theme Features

The template uses [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) with a dark-first theme (slate) and light mode toggle. The following features are enabled:

| Feature | Description |
|---------|-------------|
| `navigation.sections` | Groups top-level sections in the sidebar with visible headers |
| `navigation.instant` | Loads pages via XHR without full page reload for faster navigation |
| `toc.follow` | Automatically scrolls the table of contents sidebar to highlight the active heading |
| `search.suggest` | Shows search term suggestions as you type in the search bar |
| `search.highlight` | Highlights matching search terms on the page after navigating from search results |
| `content.code.copy` | Adds a copy-to-clipboard button on all code blocks |
| `content.code.annotate` | Enables numbered annotations inside code blocks with expandable tooltips |
| `content.tabs.link` | Syncs tab selection across all tabbed content blocks on the page |

## Deployment

### GitHub Pages (automatic)
Expand Down
103 changes: 103 additions & 0 deletions plex-guide/docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -437,6 +437,109 @@ If your smart TV struggles with Plex, consider a dedicated streaming device. The

---

{% if has_direct_play | default(true) %}
## Direct Play (Best Quality)

**Direct play** means your device plays the video file exactly as-is, with no conversion by the server. This always gives you the best experience:

- **Best quality** — you see exactly what was encoded
- **No server load** — the server just sends the file
- **Faster start** — no waiting for the server to process

When direct play isn't possible, the server **transcodes** (converts) the video in real-time, which uses server resources and can reduce quality.

### How to Get Direct Play

#### Set Quality to Maximum/Original

The most common reason for unnecessary transcoding is the quality setting being too low.

=== "On Your TV/Streaming Device"

1. Open the Plex app
2. Go to **Settings** → **Video Quality**
3. Set **Remote Streaming** to **Original** or **Maximum**
4. Set **Home Streaming** to **Original** or **Maximum**

=== "On Your Phone/Tablet"

1. Open Plex → **Settings** (gear icon)
2. Tap **Quality**
3. Set **Remote Streaming** to **Maximum**
4. Set **Home Streaming** to **Maximum**

#### Use the Native Plex App

!!! warning "Web Browsers Force Transcoding"
Browsers (Chrome, Firefox, Safari) don't support most video codecs and will force the server to transcode. Always use the **native Plex app** on your device.

#### Check if You're Direct Playing

While watching a video:

1. Press the **info** button (or tap **...** on mobile)
2. Look for **"Direct Play"** — this means no transcoding
3. If it says **"Transcode"**, something is preventing direct play

Common reasons for transcoding:

- Quality set below **Original/Maximum** (most common!)
- Watching in a web browser instead of the Plex app
- Device doesn't support the video codec (HEVC/H.265)
- Device doesn't support the audio codec — try switching to a compatible audio track
- Image-based subtitles (PGS/ASS) being burned in — try SRT subtitles instead

{% endif %}
{% if has_4k_content | default(true) %}

---

## 4K Streaming

4K movies look incredible, but they're **massive files** — a single 4K movie can be 50-80 GB. This creates unique challenges.

!!! danger "Never Transcode 4K"
Transcoding 4K defeats the purpose — you get **worse quality** than just watching the 1080p version, while also hammering the server. If your device can't direct play 4K, watch the 1080p version instead.

### Can Your Device Handle 4K?

| Device | 4K Direct Play | HDR | Lossless Audio |
|--------|:-:|:-:|:-:|
| **Nvidia Shield TV Pro** | Yes | Yes | Yes |
| **Apple TV 4K** | Yes | Yes | Partial |
| **Fire TV Stick 4K Max** | Yes | Yes | No |
| **Onn 4K Google TV** | Yes | Yes | No |
| **Most Smart TVs** | Varies | Varies | No |
| **Web Browser** | No | No | No |
Comment on lines +506 to +513
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Search for existing device capability references in the codebase
# and check if there's any version-specific documentation

rg -n "Shield TV Pro|Apple TV 4K|Fire TV Stick 4K Max|Onn 4K" --type md -C2

Repository: baker-scripts/docs-templates

Length of output: 1643

🌐 Web query:

Plex 4K direct play device compatibility 2026

💡 Result:

Plex doesn’t publish a single “4K Direct Play compatible devices” list for 2026—Direct Play is determined at playback time based on whether your client device/app supports the container + video codec + audio codec + subtitles you’re trying to play; otherwise Plex will Direct Stream (remux) or Transcode. [1]

Devices that are commonly recommended for 4K Direct Play (local network)

From Plex community support guidance, these external streamers are repeatedly recommended over most built-in TV apps for reliable 4K playback:

  • NVIDIA Shield TV / Shield TV Pro (Android TV)
  • Apple TV 4K
  • Amazon Fire TV Stick 4K Max (Gen 2)
  • Roku (e.g., higher-end models like Ultra)
    [2]

Common reasons your “4K” stops Direct Playing (even on good devices)

  • Unsupported audio (often the real culprit): if the client can’t bitstream/play the selected track (e.g., TrueHD / DTS variants), Plex may transcode audio and sometimes triggers other compatibility fallbacks. (General rule: any unsupported stream can force transcode.) [1]
  • Subtitles (burn-in): if the client can’t render the subtitle format, Plex may have to burn subtitles into the video, which forces transcoding. This is a frequent issue on some platforms (notably with image-based subs like PGS). [1][3]
  • Container mismatch: some clients/apps may not Direct Play certain containers (and will remux/Direct Stream instead). Plex’s “supported formats” guidance notes container limitations exist per app/platform. [4]

Practical “most compatible” 4K Direct Play media profile (works on the widest range)

If you’re building/ripping/encoding for maximum odds of Direct Play across devices:

  • Video: HEVC (H.265), Main10 for HDR where applicable
  • Audio: AAC / EAC3 (Dolby Digital Plus) often travels better than TrueHD/DTS-HD across TVs/streamers
  • Subtitles: SRT (text-based) whenever possible (avoid PGS when you want to prevent burn-in)
  • Client setting: ensure “Original” quality / Direct Play enabled (per-client setting)

If you tell me (1) your target playback device(s), (2) whether you need Dolby Vision/HDR10(+), and (3) whether you need TrueHD/DTS-HD passthrough, I can give a tighter “will Direct Play / will transcode” matrix for your setup.

Sources: Plex Direct Play/Direct Stream/Transcoding overview [1], Plex forum device recommendations for 4K playback (Dec 2025 thread) [2], discussion of PGS subtitle incompatibility causing transcoding [3], Plex “What media formats are supported?” (platform/container limits vary) [4].

Clarify that device 4K capabilities depend on media codec, not just device hardware.

The table presents device capabilities as absolute (Yes/No), but Plex Direct Play depends on the specific media format being played—video codec, audio codec, container, and subtitle format all matter. A device marked "Yes" for 4K Direct Play may still transcode if the media uses unsupported codecs (e.g., TrueHD audio on some devices). The "Lossless Audio" column is particularly problematic since support varies by audio codec, not universally by device. Consider either adding codec-specific details or noting that Direct Play outcomes depend on media format compatibility, not device capability alone.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@plex-guide/docs/index.md` around lines 506 - 513, Update the device
capability table so it doesn't present absolute Yes/No answers: change the "4K
Direct Play" and "Lossless Audio" cells (and the "HDR" column where applicable)
to indicate "Depends on media codec/container" or similar, and add a short
clarifying sentence immediately above or below the table stating that Direct
Play support depends on the media's video codec, audio codec, container, and
subtitle format (e.g., TrueHD may force transcoding on some devices);
alternatively expand the table to include common codec examples per device.
Reference the table header ("Device | 4K Direct Play | HDR | Lossless Audio")
and update those cell values and the prose note accordingly.


### Bandwidth Requirements

4K content requires significantly more internet speed than HD:

| Quality | Minimum Speed Needed |
|---------|---------------------|
| 1080p | 10-20 Mbps |
| 4K SDR | 25-40 Mbps |
| 4K HDR | 40-80 Mbps |
| 4K Remux | 80-120+ Mbps |

Test your speed at [fast.com](https://fast.com). If your speed is below the requirement, Plex will transcode the video automatically — and for 4K, that means worse quality than 1080p.

!!! tip "Use Ethernet for 4K"
WiFi is unreliable for 4K streaming. A wired ethernet connection to your streaming device is the single best improvement you can make.

### Quick Reference

| Do This | Not This |
|---------|----------|
| Use the native Plex app | Watch in a web browser |
| Set quality to **Original/Maximum** | Leave it on "auto" or a lower setting |
| Use ethernet for 4K | Rely on WiFi for large files |
| Watch 1080p if 4K transcodes | Force 4K on a device that can't handle it |

{% endif %}
---

## More Help

| Resource | Link |
Expand Down
4 changes: 4 additions & 0 deletions plex-guide/mkdocs.sample.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,10 +22,12 @@ theme:
name: Switch to dark mode
features:
- navigation.sections
- navigation.instant
- toc.follow
- search.suggest
- search.highlight
- content.code.copy
- content.code.annotate
- content.tabs.link

plugins:
Expand Down Expand Up @@ -69,6 +71,8 @@ extra:
guide_url: "" # Public URL for this guide
has_plex_pass: true # Whether your server has a Plex Pass
has_plex_home: false # Whether you use Plex Home for some users
has_direct_play: true # Whether to show direct play optimization section
has_4k_content: true # Whether to show 4K streaming section
has_migration: false # Whether you offer watch history migration
show_costs: false # Whether to show server cost information
server_cost: "" # Monthly server cost (e.g., "~$50/month")
4 changes: 4 additions & 0 deletions plex-guide/setup.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,8 @@ fi

prompt_bool has_plex_pass "Does your server have a Plex Pass?" "true"
prompt_bool has_plex_home "Do you use Plex Home for some users?" "false"
prompt_bool has_direct_play "Show direct play optimization section?" "true"
prompt_bool has_4k_content "Show 4K streaming section?" "true"
prompt_bool has_migration "Do you offer watch history migration?" "false"

prompt_bool show_costs "Show server cost information?" "false"
Expand Down Expand Up @@ -156,6 +158,8 @@ update_config "has_guide_url" "$has_guide_url" true
update_config "guide_url" "$guide_url"
update_config "has_plex_pass" "$has_plex_pass" true
update_config "has_plex_home" "$has_plex_home" true
update_config "has_direct_play" "$has_direct_play" true
update_config "has_4k_content" "$has_4k_content" true
update_config "has_migration" "$has_migration" true
update_config "show_costs" "$show_costs" true
update_config "server_cost" "$server_cost"
Expand Down
Loading