wiki: add Plex 4K codec guide and mdadm USB recovery; update yt-dlp, indexes

New articles:
- 04-streaming/plex/plex-4k-codec-compatibility.md
- 05-troubleshooting/storage/mdadm-usb-hub-disconnect-recovery.md

Updated:
- yt-dlp.md: Plex section and config reflect new HEVC auto-convert workflow
- SUMMARY.md, index.md, README.md, section indexes: 39 → 41 articles
- MajorWiki-Deploy-Status.md: count + date

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

03-opensource/media-creative/yt-dlp.md

@@ -40,19 +40,15 @@ yt-dlp -o "/path/to/output/%(title)s.%(ext)s" URL
 
 ## Plex-Optimized Download
 
-For Plex direct play, you want H.264 video in an MP4 container with embedded subtitles:
+Download best quality and auto-convert to HEVC for Apple TV direct play:
 
 ```bash
-yt-dlp -f 'bestvideo[ext=mp4]+bestaudio[ext=m4a]/bestvideo+bestaudio' \
+yt-dlp URL
-  --merge-output-format mp4 \
-  -o "/plex/plex/%(title)s.%(ext)s" \
-  --write-auto-subs --embed-subs \
-  URL
 ```
 
-- `-f 'bestvideo[ext=mp4]+bestaudio[ext=m4a]/...'` — prefer MP4 video + M4A audio; fall back to best available
+That's it — if your config is set up correctly (see Config File section below). The config handles format selection, output path, subtitles, and automatic AV1/VP9 → HEVC conversion.
-- `--merge-output-format mp4` — merge streams into MP4 container (requires ffmpeg)
+
-- `--write-auto-subs --embed-subs` — download auto-generated subtitles and bake them in
+> [!note] `bestvideo[ext=mp4]` caps at 1080p because YouTube only serves H.264 up to 1080p. Use `bestvideo+bestaudio` to get true 4K, then let the post-download hook convert AV1/VP9 to HEVC. See [Plex 4K Codec Compatibility](../../04-streaming/plex/plex-4k-codec-compatibility.md) for the full setup.
 
 ---
 
@@ -92,15 +88,17 @@ Persist your preferred flags so you don't repeat them every command:
 ```bash
 mkdir -p ~/.config/yt-dlp
 cat > ~/.config/yt-dlp/config << 'EOF'
--f bestvideo[ext=mp4]+bestaudio[ext=m4a]/bestvideo+bestaudio
+--remote-components ejs:github
+--format bestvideo+bestaudio
 --merge-output-format mp4
+--output /plex/plex/%(title)s.%(ext)s
 --write-auto-subs
 --embed-subs
---remote-components ejs:github
+--exec /usr/local/bin/yt-dlp-hevc-convert.sh {}
 EOF
 ```
 
-After this, a bare `yt-dlp URL` uses all your preferred settings automatically.
+After this, a bare `yt-dlp URL` downloads best quality, saves to `/plex/plex/`, embeds subtitles, and auto-converts AV1/VP9 to HEVC. See [Plex 4K Codec Compatibility](../../04-streaming/plex/plex-4k-codec-compatibility.md) for the conversion hook setup.
 
 ---
 

04-streaming/index.md

@@ -5,3 +5,7 @@ Guides for live streaming and podcast production, with a focus on OBS Studio.
 ## OBS Studio
 
 - [OBS Studio Setup & Encoding](obs/obs-studio-setup-encoding.md)
+
+## Plex
+
+- [Plex 4K Codec Compatibility (Apple TV)](plex/plex-4k-codec-compatibility.md)

04-streaming/plex/plex-4k-codec-compatibility.md

@@ -0,0 +1,148 @@
+# Plex 4K Codec Compatibility (Apple TV)
+
+4K content on YouTube is delivered in AV1 or VP9 — neither of which the Plex app on Apple TV can direct play. This forces Plex to transcode, and most home server CPUs can't transcode 4K in real time. The fix is converting to HEVC before Plex ever sees the file.
+
+## Codec Compatibility Matrix
+
+| Codec | Apple TV (Plex direct play) | YouTube 4K | Notes |
+|---|---|---|---|
+| H.264 (AVC) | ✅ | ❌ (max 1080p) | Most compatible, but no 4K |
+| HEVC (H.265) | ✅ | ❌ | Best choice: 4K compatible, widely supported |
+| VP9 | ❌ | ✅ | Google's royalty-free codec, forces transcode |
+| AV1 | ❌ | ✅ | Best compression, requires modern hardware to decode |
+
+**Target format: HEVC.** Direct plays on Apple TV, supports 4K/HDR, and modern hardware can encode it quickly.
+
+## Why AV1 and VP9 Cause Problems
+
+When Plex can't direct play a file it transcodes it on the server. AV1 and VP9 decoding is CPU-intensive — most home server CPUs can't keep up with 4K60 in real time. Intel Quick Sync (HD 630 era) supports VP9 hardware decode but not AV1. AV1 hardware support requires 11th-gen Intel or RTX 30-series+.
+
+## Batch Converting Existing Files
+
+For files already in your Plex library, use this script to find all AV1/VP9 files and convert them to HEVC via VAAPI (Intel Quick Sync):
+
+```bash
+#!/bin/bash
+VAAPI_DEV=/dev/dri/renderD128
+PLEX_DIR="/plex/plex"
+LOG="/root/av1_to_hevc.log"
+TMPDIR="/tmp/av1_convert"
+
+mkdir -p "$TMPDIR"
+echo "=== AV1→HEVC batch started $(date) ===" | tee -a "$LOG"
+
+find "$PLEX_DIR" -iname "*.mp4" -o -iname "*.mkv" | while IFS= read -r f; do
+  codec=$(mediainfo --Inform='Video;%Format%' "$f" 2>/dev/null)
+  [ "$codec" != "AV1" ] && [ "$codec" != "VP9" ] && continue
+
+  echo "[$(date +%H:%M:%S)] Converting: $(basename "$f")" | tee -a "$LOG"
+  tmp="${TMPDIR}/$(basename "${f%.*}").mp4"
+
+  ffmpeg -hide_banner -loglevel error \
+    -vaapi_device "$VAAPI_DEV" \
+    -i "$f" \
+    -vf 'format=nv12,hwupload' \
+    -c:v hevc_vaapi \
+    -qp 22 \
+    -c:a copy \
+    -movflags +faststart \
+    "$tmp"
+
+  if [ $? -eq 0 ] && [ -s "$tmp" ]; then
+    mv "$tmp" "${f%.*}_hevc.mp4"
+    rm -f "$f"
+  else
+    rm -f "$tmp"
+    echo "  FAILED — original kept." | tee -a "$LOG"
+  fi
+done
+```
+
+Run in a tmux session so it survives SSH disconnect:
+
+```bash
+tmux new-session -d -s av1-convert '/root/av1_to_hevc.sh'
+tail -f /root/av1_to_hevc.log
+```
+
+After completion, trigger a Plex library scan to pick up the renamed files.
+
+## Automating Future Downloads (yt-dlp)
+
+Prevent the problem at the source with a post-download conversion hook.
+
+### 1. Create the conversion script
+
+Save to `/usr/local/bin/yt-dlp-hevc-convert.sh`:
+
+```bash
+#!/bin/bash
+INPUT="$1"
+VAAPI_DEV=/dev/dri/renderD128
+LOG=/var/log/yt-dlp-convert.log
+
+[ -z "$INPUT" ] && exit 0
+[ ! -f "$INPUT" ] && exit 0
+
+CODEC=$(mediainfo --Inform='Video;%Format%' "$INPUT" 2>/dev/null)
+if [ "$CODEC" != "AV1" ] && [ "$CODEC" != "VP9" ]; then
+  exit 0
+fi
+
+echo "[$(date '+%Y-%m-%d %H:%M:%S')] Converting ($CODEC): $(basename "$INPUT")" >> "$LOG"
+TMPOUT="${INPUT%.*}_hevc_tmp.mp4"
+
+ffmpeg -hide_banner -loglevel error \
+  -vaapi_device "$VAAPI_DEV" \
+  -i "$INPUT" \
+  -vf 'format=nv12,hwupload' \
+  -c:v hevc_vaapi \
+  -qp 22 \
+  -c:a copy \
+  -movflags +faststart \
+  "$TMPOUT"
+
+if [ $? -eq 0 ] && [ -s "$TMPOUT" ]; then
+  mv "$TMPOUT" "${INPUT%.*}.mp4"
+  [ "${INPUT%.*}.mp4" != "$INPUT" ] && rm -f "$INPUT"
+  echo "[$(date '+%Y-%m-%d %H:%M:%S')] OK: $(basename "${INPUT%.*}.mp4")" >> "$LOG"
+else
+  rm -f "$TMPOUT"
+  echo "[$(date '+%Y-%m-%d %H:%M:%S')] FAILED — original kept: $(basename "$INPUT")" >> "$LOG"
+fi
+```
+
+```bash
+chmod +x /usr/local/bin/yt-dlp-hevc-convert.sh
+```
+
+### 2. Configure yt-dlp
+
+`~/.config/yt-dlp/config`:
+
+```
+--remote-components ejs:github
+--format bestvideo+bestaudio
+--merge-output-format mp4
+--output /plex/plex/%(title)s.%(ext)s
+--write-auto-subs
+--embed-subs
+--exec /usr/local/bin/yt-dlp-hevc-convert.sh {}
+```
+
+With this config, `yt-dlp <URL>` downloads the best available quality (including 4K AV1/VP9), then immediately converts any AV1 or VP9 output to HEVC before Plex indexes it.
+
+> [!note] The `--format bestvideo+bestaudio` selector gets true 4K from YouTube (served as AV1 or VP9). The hook converts it to HEVC. Without the hook, using `bestvideo[ext=mp4]` would cap downloads at 1080p since YouTube only serves H.264 up to 1080p.
+
+## Enabling Hardware Transcoding in Plex
+
+Even with automatic conversion in place, enable hardware acceleration in Plex as a fallback for any files that slip through:
+
+**Plex Web → Settings → Transcoder → "Use hardware acceleration when available"**
+
+This requires Plex Pass. On Intel systems with Quick Sync, VP9 will hardware transcode even without pre-conversion. AV1 will still fall back to CPU on pre-Alder Lake hardware.
+
+## Related
+
+- [yt-dlp: Video Downloading](../../03-opensource/media-creative/yt-dlp.md)
+- [OBS Studio Setup & Encoding](../obs/obs-studio-setup-encoding.md)

05-troubleshooting/index.md

@@ -19,6 +19,9 @@ Practical fixes for common Linux, networking, and application problems.
 ## 🔒 SELinux
 - [SELinux: Fixing Dovecot Mail Spool Context (/var/vmail)](selinux-dovecot-vmail-context.md)
 
+## 💾 Storage
+- [mdadm RAID Recovery After USB Hub Disconnect](storage/mdadm-usb-hub-disconnect-recovery.md)
+
 ## 📝 Application Specific
 - [Obsidian Vault Recovery — Loading Cache Hang](obsidian-cache-hang-recovery.md)
 - [Gemini CLI Manual Update](gemini-cli-manual-update.md)

05-troubleshooting/storage/mdadm-usb-hub-disconnect-recovery.md

@@ -0,0 +1,105 @@
+# mdadm RAID Recovery After USB Hub Disconnect
+
+A software RAID array managed by mdadm can appear to catastrophically fail when the drives are connected via USB rather than SATA. The array is fine — the hub dropped out. Here's how to diagnose and recover.
+
+## Symptoms
+
+- rsync or other I/O to the RAID mount returns `Input/output error`
+- `cat /proc/mdstat` shows `broken raid0` or `FAILED`
+- `mdadm --detail /dev/md0` shows `State: broken, FAILED`
+- `lsblk` no longer lists the RAID member drives (e.g. `sdd`, `sde` gone)
+- XFS (or other filesystem) logs in dmesg:
+  ```
+  XFS (md0): log I/O error -5
+  XFS (md0): Filesystem has been shut down due to log error (0x2).
+  ```
+- `smartctl -H /dev/sdd` returns `No such device`
+
+## Why It Happens
+
+If your RAID drives are in a USB enclosure (e.g. TerraMaster via ASMedia hub), a USB disconnect — triggered by a power fluctuation, plugging in another device, or a hub reset — causes mdadm to see the drives disappear. mdadm cannot distinguish a USB dropout from a physical drive failure, so it declares the array failed.
+
+The failure message in dmesg will show `hostbyte=DID_ERROR` rather than a drive-level error:
+
+```
+md/raid0md0: Disk failure on sdd1 detected, failing array.
+sd X:0:0:0: [sdd] Synchronize Cache(10) failed: Result: hostbyte=DID_ERROR driverbyte=DRIVER_OK
+```
+
+`DID_ERROR` means the SCSI host adapter (USB controller) reported the error — the drives themselves are likely fine.
+
+## Diagnosis
+
+### 1. Check if the USB hub recovered
+
+```bash
+lsblk -o NAME,SIZE,TYPE,FSTYPE,MODEL
+```
+
+After a hub reconnects, drives will reappear — often with **new device names** (e.g. `sdd`/`sde` become `sdg`/`sdh`). Look for drives with `linux_raid_member` filesystem type.
+
+```bash
+dmesg | grep -iE 'usb|disconnect|DID_ERROR' | tail -30
+```
+
+A hub dropout looks like multiple devices disconnecting at the same time on the same USB port.
+
+### 2. Confirm drives have intact superblocks
+
+```bash
+mdadm --examine /dev/sdg1
+mdadm --examine /dev/sdh1
+```
+
+If the superblocks are present and show matching UUID/array info, the data is intact.
+
+## Recovery
+
+### 1. Unmount and stop the degraded array
+
+```bash
+umount /majorRAID   # or wherever md0 is mounted
+mdadm --stop /dev/md0
+```
+
+If umount fails due to a busy mount or already-failed filesystem, it may already be unmounted by the kernel. Proceed with `--stop`.
+
+### 2. Reassemble with the new device names
+
+```bash
+mdadm --assemble /dev/md0 /dev/sdg1 /dev/sdh1
+```
+
+mdadm matches drives by their superblock UUID, not device name. As long as both drives are present the assembly will succeed regardless of what they're called.
+
+### 3. Mount and verify
+
+```bash
+mount /dev/md0 /majorRAID
+df -h /majorRAID
+ls /majorRAID
+```
+
+If the filesystem mounts and data is visible, recovery is complete.
+
+### 4. Create or update /etc/mdadm.conf
+
+If `/etc/mdadm.conf` doesn't exist (or references old device names), update it:
+
+```bash
+mdadm --detail --scan > /etc/mdadm.conf
+cat /etc/mdadm.conf
+```
+
+The output uses UUID rather than device names — the array will reassemble correctly on reboot even if drive letters change again.
+
+## Prevention
+
+The root cause is drives on USB rather than SATA. Short of moving the drives to a SATA controller, options are limited. When planning a migration off the RAID array (e.g. to SnapRAID + MergerFS), prioritize getting drives onto SATA connections.
+
+> [!warning] RAID 0 has no redundancy. A USB dropout that causes the array to fail mid-write could corrupt data even if the drives themselves are healthy. Keep current backups before any maintenance involving the enclosure.
+
+## Related
+
+- [SnapRAID & MergerFS Storage Setup](../../01-linux/storage/snapraid-mergerfs-setup.md)
+- [rsync Backup Patterns](../../02-selfhosting/storage-backup/rsync-backup-patterns.md)

MajorWiki-Deploy-Status.md

@@ -31,7 +31,7 @@ DNS record and Caddy entry have been removed.
 
 ## Content
 
-- 39 articles across 5 domains
+- 41 articles across 5 domains
 - Source of truth: `MajorVault/20-Projects/MajorTwin/08-Wiki/`
 - Deployed via Gitea webhook (push from MajorAir → auto-pull on majorlab)
 
@@ -63,7 +63,7 @@ rsync -av --include="*.md" --include="*/" --exclude="*" \
 
 ---
 
-*Updated 2026-03-14*
+*Updated 2026-03-15*
 
 ## Canonical Update Workflow
 

README.md

@@ -2,8 +2,8 @@
 
 > A growing reference of Linux, self-hosting, open source, streaming, and troubleshooting guides. Written by MajorLinux. Used by MajorTwin.
 >
-**Last updated:** 2026-03-14
+**Last updated:** 2026-03-15
-**Article count:** 39
+**Article count:** 41
 
 ## Domains
 
@@ -12,8 +12,8 @@
 | 🐧 Linux & Sysadmin | `01-linux/` | 9 |
 | 🏠 Self-Hosting & Homelab | `02-selfhosting/` | 8 |
 | 🔓 Open Source Tools | `03-opensource/` | 9 |
-| 🎙️ Streaming & Podcasting | `04-streaming/` | 1 |
+| 🎙️ Streaming & Podcasting | `04-streaming/` | 2 |
-| 🔧 General Troubleshooting | `05-troubleshooting/` | 12 |
+| 🔧 General Troubleshooting | `05-troubleshooting/` | 13 |
 
 ---
 
@@ -96,6 +96,9 @@
 ### OBS Studio
 - [OBS Studio Setup & Encoding](04-streaming/obs/obs-studio-setup-encoding.md) — installation, NVENC/x264 settings, scene setup, audio filters, Linux Wayland notes
 
+### Plex
+- [Plex 4K Codec Compatibility (Apple TV)](04-streaming/plex/plex-4k-codec-compatibility.md) — AV1/VP9 vs HEVC, batch conversion script, yt-dlp auto-convert hook
+
 ---
 
 ## 🔧 General Troubleshooting
@@ -111,6 +114,7 @@
 - [MajorWiki Setup & Pipeline](05-troubleshooting/majwiki-setup-and-pipeline.md) — setting up MajorWiki and the Obsidian → Gitea → MkDocs publishing pipeline
 - [Gitea Actions Runner: Boot Race Condition Fix](05-troubleshooting/gitea-runner-boot-race-network-target.md) — fixing act_runner crash loop on boot caused by DNS not ready at startup
 - [SELinux: Fixing Dovecot Mail Spool Context (/var/vmail)](05-troubleshooting/selinux-dovecot-vmail-context.md) — fixing thousands of AVC denials when /var/vmail has wrong SELinux context
+- [mdadm RAID Recovery After USB Hub Disconnect](05-troubleshooting/storage/mdadm-usb-hub-disconnect-recovery.md) — diagnosing and recovering a failed mdadm array caused by a USB hub dropout
 
 ---
 
@@ -118,6 +122,9 @@
 
 | Date | Article | Domain |
 |---|---|---|
+| 2026-03-15 | [Plex 4K Codec Compatibility (Apple TV)](04-streaming/plex/plex-4k-codec-compatibility.md) | Streaming |
+| 2026-03-15 | [mdadm RAID Recovery After USB Hub Disconnect](05-troubleshooting/storage/mdadm-usb-hub-disconnect-recovery.md) | Troubleshooting |
+| 2026-03-15 | [yt-dlp: Video Downloading](03-opensource/media-creative/yt-dlp.md) | Open Source |
 | 2026-03-14 | [SELinux: Fixing Dovecot Mail Spool Context (/var/vmail)](05-troubleshooting/selinux-dovecot-vmail-context.md) | Troubleshooting |
 | 2026-03-14 | [Gitea Actions Runner: Boot Race Condition Fix](05-troubleshooting/gitea-runner-boot-race-network-target.md) | Troubleshooting |
 | 2026-03-14 | [Mail Client Stops Receiving: Fail2ban IMAP Self-Ban](05-troubleshooting/networking/fail2ban-imap-self-ban-mail-client.md) | Troubleshooting |

SUMMARY.md

@@ -30,6 +30,7 @@
     * [yt-dlp: Video Downloading](03-opensource/media-creative/yt-dlp.md)
 * [Streaming & Podcasting](04-streaming/index.md)
     * [OBS Studio Setup & Encoding](04-streaming/obs/obs-studio-setup-encoding.md)
+    * [Plex 4K Codec Compatibility (Apple TV)](04-streaming/plex/plex-4k-codec-compatibility.md)
 * [Troubleshooting](05-troubleshooting/index.md)
     * [Apache Outage: Fail2ban Self-Ban + Missing iptables Rules](05-troubleshooting/networking/fail2ban-self-ban-apache-outage.md)
     * [Mail Client Stops Receiving: Fail2ban IMAP Self-Ban](05-troubleshooting/networking/fail2ban-imap-self-ban-mail-client.md)
@@ -42,3 +43,4 @@
     * [MajorWiki Setup & Publishing Pipeline](05-troubleshooting/majwiki-setup-and-pipeline.md)
     * [Gitea Actions Runner: Boot Race Condition Fix](05-troubleshooting/gitea-runner-boot-race-network-target.md)
     * [SELinux: Fixing Dovecot Mail Spool Context (/var/vmail)](05-troubleshooting/selinux-dovecot-vmail-context.md)
+    * [mdadm RAID Recovery After USB Hub Disconnect](05-troubleshooting/storage/mdadm-usb-hub-disconnect-recovery.md)

index.md

@@ -2,8 +2,8 @@
 
 > A growing reference of Linux, self-hosting, open source, streaming, and troubleshooting guides. Written by MajorLinux. Used by MajorTwin.
 >
-> **Last updated:** 2026-03-14
+> **Last updated:** 2026-03-15
-> **Article count:** 39
+> **Article count:** 41
 
 ## Domains
 
@@ -12,8 +12,8 @@
 | 🐧 Linux & Sysadmin | `01-linux/` | 9 |
 | 🏠 Self-Hosting & Homelab | `02-selfhosting/` | 8 |
 | 🔓 Open Source Tools | `03-opensource/` | 9 |
-| 🎙️ Streaming & Podcasting | `04-streaming/` | 1 |
+| 🎙️ Streaming & Podcasting | `04-streaming/` | 2 |
-| 🔧 General Troubleshooting | `05-troubleshooting/` | 12 |
+| 🔧 General Troubleshooting | `05-troubleshooting/` | 13 |
 
 ---
 
@@ -96,6 +96,9 @@
 ### OBS Studio
 - [OBS Studio Setup & Encoding](04-streaming/obs/obs-studio-setup-encoding.md) — installation, NVENC/x264 settings, scene setup, audio filters, Linux Wayland notes
 
+### Plex
+- [Plex 4K Codec Compatibility (Apple TV)](04-streaming/plex/plex-4k-codec-compatibility.md) — AV1/VP9 vs HEVC, batch conversion script, yt-dlp auto-convert hook
+
 ---
 
 ## 🔧 General Troubleshooting
@@ -111,6 +114,7 @@
 - [MajorWiki Setup & Pipeline](05-troubleshooting/majwiki-setup-and-pipeline.md) — setting up MajorWiki and the Obsidian → Gitea → MkDocs publishing pipeline
 - [Gitea Actions Runner: Boot Race Condition Fix](05-troubleshooting/gitea-runner-boot-race-network-target.md) — fixing act_runner crash loop on boot caused by DNS not ready at startup
 - [SELinux: Fixing Dovecot Mail Spool Context (/var/vmail)](05-troubleshooting/selinux-dovecot-vmail-context.md) — fixing thousands of AVC denials when /var/vmail has wrong SELinux context
+- [mdadm RAID Recovery After USB Hub Disconnect](05-troubleshooting/storage/mdadm-usb-hub-disconnect-recovery.md) — diagnosing and recovering a failed mdadm array caused by a USB hub dropout
 
 ---
 
@@ -118,6 +122,9 @@
 
 | Date | Article | Domain |
 |---|---|---|
+| 2026-03-15 | [Plex 4K Codec Compatibility (Apple TV)](04-streaming/plex/plex-4k-codec-compatibility.md) | Streaming |
+| 2026-03-15 | [mdadm RAID Recovery After USB Hub Disconnect](05-troubleshooting/storage/mdadm-usb-hub-disconnect-recovery.md) | Troubleshooting |
+| 2026-03-15 | [yt-dlp: Video Downloading](03-opensource/media-creative/yt-dlp.md) | Open Source |
 | 2026-03-14 | [SELinux: Fixing Dovecot Mail Spool Context (/var/vmail)](05-troubleshooting/selinux-dovecot-vmail-context.md) | Troubleshooting |
 | 2026-03-14 | [Gitea Actions Runner: Boot Race Condition Fix](05-troubleshooting/gitea-runner-boot-race-network-target.md) | Troubleshooting |
 | 2026-03-14 | [Mail Client Stops Receiving: Fail2ban IMAP Self-Ban](05-troubleshooting/networking/fail2ban-imap-self-ban-mail-client.md) | Troubleshooting |