feat: make Tdarr native-first on macOS with quality preset

Author: liamvibecodes

.env.example

@@ -8,6 +8,12 @@
 # plex (default, runs natively on macOS) or jellyfin (runs in Docker)
 MEDIA_SERVER=plex
 
+# --- TDARR ---
+# native (recommended on macOS) or docker
+TDARR_MODE=native
+# Optional pinned Tdarr version for native mode (blank = latest available)
+TDARR_VERSION=
+
 # --- PATHS ---
 MEDIA_DIR=/Users/YOURUSERNAME/Media
 

README.md

@@ -37,7 +37,7 @@ There are dozens of *arr stack Docker Compose repos on GitHub. Almost all of the
 - **Auto-wires keys.** The configure script also writes Radarr/Sonarr API keys into Recyclarr and Unpackerr automatically.
 - **Built for macOS.** Native paths, launchd instead of systemd, OrbStack or Docker Desktop instead of bare Docker. Not a Linux guide with "should work on Mac" in the footnotes.
 - **Self-healing.** Hourly health checks, download watchdog, VPN failover between providers. Runs unattended.
-- **Quality automation.** TRaSH Guides profiles filter out bad releases. Kometa keeps Plex metadata clean. Tdarr saves disk space with automatic transcoding.
+- **Quality automation.** TRaSH Guides profiles filter out bad releases. Kometa keeps Plex metadata clean. Tdarr runs native-first on macOS with a quality-preserving flow preset.
 
 New to self-hosted media? Start with the [basic version](https://github.com/liamvibecodes/mac-media-stack) first.
 
@@ -47,7 +47,7 @@ New to self-hosted media? Start with the [basic version](https://github.com/liam
 
 | Service | What It Does |
 |---------|-------------|
-| **Tdarr** | Automatic transcoding (convert codecs, save disk space) |
+| **Tdarr** | Native-first transcoding on macOS with quality-preserving HEVC flow preset |
 | **Recyclarr** | TRaSH Guides quality profiles (penalizes bad release groups, scene releases) |
 | **Kometa** | Plex metadata automation (franchise collections, resolution overlays, RT ratings) |
 | **Unpackerr** | Auto-extracts RAR'd downloads for Radarr/Sonarr |
@@ -126,6 +126,17 @@ Then open Tidarr at `http://localhost:8484` to authenticate with your Tidal acco
 Franchise sorting is kept manual by default because it requires your Plex token:
 `PLEX_TOKEN=... python3 scripts/franchise-sort.py`
 
+### Tdarr Mode
+
+- Default is `TDARR_MODE=native` (recommended on macOS).
+- Native Tdarr is installed and managed by `scripts/setup-tdarr-native.sh` (launchd server + node).
+- Docker Tdarr remains available via `TDARR_MODE=docker` and `--profile tdarr-docker`.
+- The stack preloads this Tdarr flow preset: `Quality-First HEVC (Resolution Preserving)`.
+  - No resolution downscale
+  - No hard bitrate cap
+  - H.264 -> H.265 (CRF 19, preset slow)
+  - Replace only when output size ratio stays within 25-99%
+
 ### Download Watchdog Configuration
 
 The download watchdog reads qBittorrent credentials and behavior settings from environment variables or automatically detects them from your config files. Optional environment variables:
@@ -153,6 +164,12 @@ Optional flags when running from a local clone:
 bash bootstrap.sh --media-dir /Volumes/T9/Media --install-dir ~/mac-media-stack-advanced --non-interactive
 ```
 
+Use Docker-based Tdarr instead of native Tdarr:
+
+```bash
+bash bootstrap.sh --tdarr-docker
+```
+
 To use Jellyfin instead of Plex:
 
 ```bash
@@ -188,6 +205,10 @@ bash scripts/doctor.sh           # preflight validation before first boot
 docker compose up -d
 # if MEDIA_SERVER=jellyfin in .env:
 docker compose --profile jellyfin up -d
+# if TDARR_MODE=docker in .env:
+docker compose --profile tdarr-docker up -d
+# if TDARR_MODE=native in .env (default):
+bash scripts/setup-tdarr-native.sh
 docker compose --profile autoupdate up -d watchtower  # optional auto-updates
 bash scripts/configure.sh
 bash scripts/install-launchd-jobs.sh
@@ -247,6 +268,8 @@ bash scripts/vpn-mode.sh nord
 | `scripts/auto-heal.sh` | Hourly self-healer |
 | `scripts/backup.sh` | Config and database backup |
 | `scripts/download-watchdog.py` | Stalled torrent detection and auto-fix |
+| `scripts/setup-tdarr-native.sh` | Installs/updates native Tdarr and launchd services |
+| `scripts/tdarr-apply-quality-flow.sh` | Loads quality-first HEVC flow preset into Tdarr DB |
 | `scripts/vpn-mode.sh` | Manual VPN provider switcher |
 | `scripts/vpn-failover-watch.sh` | Automatic VPN failover daemon |
 | `scripts/run-kometa.sh` | Trigger Kometa metadata run |
@@ -263,6 +286,7 @@ Pre-configured templates in `configs/` (copy to your Media folder after first bo
 
 - **recyclarr.yml** - TRaSH Guides quality profiles for Radarr and Sonarr
 - **kometa.yml** - Plex metadata automation (franchise collections, resolution overlays)
+- **tdarr-flow-quality-first-hevc.json** - Quality-first H.264 -> H.265 flow preset loaded by `scripts/tdarr-apply-quality-flow.sh`
 
 Recyclarr API keys are auto-injected by `scripts/configure.sh`. Kometa still needs your manual Plex token + TMDB API key.
 

SETUP.md

@@ -14,7 +14,7 @@ If you already have OrbStack (or Docker Desktop) and Plex installed, you can run
 curl -fsSL https://raw.githubusercontent.com/liamvibecodes/mac-media-stack-advanced/main/bootstrap.sh | bash
 ```
 
-It will prompt you for VPN keys, configure all core services, auto-wire Recyclarr + Unpackerr API keys, and install automation jobs. You'll still need to do Step 7 for Kometa/Tdarr manual setup afterward.
+It will prompt you for VPN keys, configure all core services, auto-wire Recyclarr + Unpackerr API keys, install native Tdarr on macOS, preload the quality-first Tdarr flow, and install automation jobs. You'll still need Step 7 for Kometa and final Tdarr library mapping.
 
 To run from a local clone with custom paths:
 
@@ -82,6 +82,11 @@ This stack supports two media servers. Choose one:
 
 To use Jellyfin, pass `--jellyfin` to the bootstrap command, or set `MEDIA_SERVER=jellyfin` in your `.env` file.
 
+### Tdarr Mode
+
+`TDARR_MODE=native` is the default and recommended on macOS (more reliable for hardware decode/encode behavior and avoids Docker VM overhead).  
+If you prefer containerized Tdarr, set `TDARR_MODE=docker` in `.env` or use `--tdarr-docker` with `bootstrap.sh`.
+
 ---
 
 ## Step 2: Download and Setup
@@ -130,6 +135,18 @@ If using Jellyfin, start with the profile enabled:
 docker compose --profile jellyfin up -d
 ```
 
+If using Docker Tdarr (`TDARR_MODE=docker`), also enable the Tdarr profile:
+
+```bash
+docker compose --profile tdarr-docker up -d
+```
+
+If using native Tdarr (`TDARR_MODE=native`, default), run:
+
+```bash
+bash scripts/setup-tdarr-native.sh
+```
+
 Wait for all containers to show OK. First pull takes 3-5 GB.
 
 Optional: enable automatic container updates (Watchtower):
@@ -236,9 +253,21 @@ Replace `YOUR_PLEX_TOKEN` and `YOUR_TMDB_API_KEY`, then save.
 ### Tdarr (transcoding)
 
 1. Open http://localhost:8265
-2. Configure your libraries (Movies: `/movies`, TV: `/tv`)
-3. Add transcode plugins based on your preference (H.265 conversion saves ~50% disk space)
-4. Set the temp/cache directory to `/temp`
+2. Add libraries:
+   - Native mode (`TDARR_MODE=native`):
+     - Movies source: `<MEDIA_DIR>/Movies`
+     - TV source: `<MEDIA_DIR>/TV Shows`
+     - Temp/cache: `<MEDIA_DIR>/tdarr-transcode-cache`
+   - Docker mode (`TDARR_MODE=docker`):
+     - Movies source: `/movies`
+     - TV source: `/tv`
+     - Temp/cache: `/temp`
+3. Assign the preloaded flow: `Quality-First HEVC (Resolution Preserving)`
+4. Keep the defaults in that flow for quality-first behavior:
+   - No resolution downscale
+   - No hard bitrate cap
+   - H.264 -> H.265 (CRF 19, preset slow)
+   - Replace only when output size ratio is 25-99%
 
 ### Unpackerr
 
@@ -259,6 +288,7 @@ This installs:
 - Log prune (daily cleanup, removes logs older than 30 days)
 - Download watchdog (stalled torrent auto-fix every 15 min)
 - Kometa scheduler (metadata refresh every 4 hours)
+- Native Tdarr launchd services (when `TDARR_MODE=native`)
 
 Automation logs go to `<MEDIA_DIR>/logs/` and launchd stdout/stderr logs go to `<MEDIA_DIR>/logs/launchd/` (default `~/Media/...`).
 

UPGRADE.md

@@ -70,6 +70,10 @@ bash scripts/doctor.sh
 docker compose up -d
 # If using Jellyfin:
 docker compose --profile jellyfin up -d
+# If using Docker Tdarr:
+docker compose --profile tdarr-docker up -d
+# If using native Tdarr (default):
+bash scripts/setup-tdarr-native.sh
 bash scripts/configure.sh
 bash scripts/install-launchd-jobs.sh
 ```
@@ -82,7 +86,7 @@ bash scripts/health-check.sh
 
 After either upgrade path, confirm:
 
-1. Tdarr libraries/plugins are configured at `http://localhost:8265`
+1. Tdarr is reachable at `http://localhost:8265` and libraries are assigned to `Quality-First HEVC (Resolution Preserving)`
 2. `bash scripts/health-check.sh` reports clean results
 3. If using Plex: `~/Media/config/kometa/config.yml` has `PLEX_TOKEN` + TMDB key
 4. If using Jellyfin: open Jellystat at `http://localhost:3000` and connect it to `http://jellyfin:8096`

bootstrap.sh

@@ -15,6 +15,7 @@ MEDIA_DIR="$HOME/Media"
 INSTALL_DIR="$HOME/mac-media-stack-advanced"
 NON_INTERACTIVE=false
 MEDIA_SERVER=plex
+TDARR_MODE=native
 
 usage() {
     cat <<EOF
@@ -24,12 +25,15 @@ Options:
   --media-dir DIR       Media root path (default: ~/Media)
   --install-dir DIR     Repo install directory (default: ~/mac-media-stack-advanced)
   --jellyfin            Use Jellyfin instead of Plex as the media server
+  --tdarr-mode MODE     Tdarr mode: native (default) or docker
+  --tdarr-docker        Shortcut for --tdarr-mode docker
   --non-interactive     Skip interactive prompts (manual Seerr wiring required)
   --help                Show this help message
 
 Examples:
   bash bootstrap.sh
   bash bootstrap.sh --media-dir /Volumes/T9/Media
+  bash bootstrap.sh --tdarr-docker
   bash bootstrap.sh --media-dir /Volumes/T9/Media --non-interactive
 EOF
 }
@@ -56,6 +60,18 @@ while [[ $# -gt 0 ]]; do
             MEDIA_SERVER=jellyfin
             shift
             ;;
+        --tdarr-mode)
+            if [[ $# -lt 2 || "$2" == --* ]]; then
+                echo "Missing value for --tdarr-mode"
+                exit 1
+            fi
+            TDARR_MODE="$2"
+            shift 2
+            ;;
+        --tdarr-docker)
+            TDARR_MODE="docker"
+            shift
+            ;;
         --non-interactive)
             NON_INTERACTIVE=true
             shift
@@ -75,6 +91,12 @@ done
 MEDIA_DIR="${MEDIA_DIR/#\~/$HOME}"
 INSTALL_DIR="${INSTALL_DIR/#\~/$HOME}"
 
+if [[ "$TDARR_MODE" != "native" && "$TDARR_MODE" != "docker" ]]; then
+    echo -e "${RED}Invalid TDARR mode:${NC} $TDARR_MODE"
+    echo "Use --tdarr-mode native or --tdarr-mode docker"
+    exit 1
+fi
+
 echo ""
 echo "======================================="
 echo "  Mac Media Stack Installer (Advanced)"
@@ -171,6 +193,7 @@ else
         echo "  You can continue and install Plex later."
     fi
 fi
+echo -e "${GREEN}OK${NC}  Tdarr mode: $TDARR_MODE"
 
 # Check git
 if ! command -v git &>/dev/null; then
@@ -213,6 +236,11 @@ if [[ -f .env ]]; then
     else
         sed -i '' "1s|^|MEDIA_SERVER=$MEDIA_SERVER\n|" .env
     fi
+    if grep -q '^TDARR_MODE=' .env; then
+        sed -i '' "s|^TDARR_MODE=.*|TDARR_MODE=$TDARR_MODE|" .env
+    else
+        printf '\nTDARR_MODE=%s\n' "$TDARR_MODE" >> .env
+    fi
 fi
 
 # Create Jellyfin config directory if needed
@@ -269,8 +297,15 @@ echo ""
 echo -e "${CYAN}Starting media stack (first run downloads ~3-5 GB)...${NC}"
 echo ""
 COMPOSE_UP_CMD="docker compose up -d"
+COMPOSE_PROFILES=()
 if [[ "$MEDIA_SERVER" == "jellyfin" ]]; then
-    COMPOSE_UP_CMD="docker compose --profile jellyfin up -d"
+    COMPOSE_PROFILES+=(--profile jellyfin)
+fi
+if [[ "$TDARR_MODE" == "docker" ]]; then
+    COMPOSE_PROFILES+=(--profile tdarr-docker)
+fi
+if [[ ${#COMPOSE_PROFILES[@]} -gt 0 ]]; then
+    COMPOSE_UP_CMD="docker compose ${COMPOSE_PROFILES[*]} up -d"
 fi
 if ! $COMPOSE_UP_CMD; then
     echo ""
@@ -289,11 +324,23 @@ wait_for_service "Prowlarr" "http://localhost:9696" || true
 wait_for_service "Radarr" "http://localhost:7878" || true
 wait_for_service "Sonarr" "http://localhost:8989" || true
 wait_for_service "Seerr" "http://localhost:5055" || true
-wait_for_service "Tdarr" "http://localhost:8265" || true
 if [[ "$MEDIA_SERVER" == "jellyfin" ]]; then
     wait_for_service "Jellyfin" "http://localhost:8096/health" || true
 fi
 
+if [[ "$TDARR_MODE" == "native" ]]; then
+    echo ""
+    echo -e "${CYAN}Setting up native Tdarr...${NC}"
+    if ! bash scripts/setup-tdarr-native.sh --media-dir "$MEDIA_DIR"; then
+        echo -e "${RED}Native Tdarr setup failed.${NC}"
+        echo "Run this after fixing the issue:"
+        echo "  bash scripts/setup-tdarr-native.sh --media-dir $MEDIA_DIR"
+        exit 1
+    fi
+else
+    wait_for_service "Tdarr" "http://localhost:8265" || true
+fi
+
 # Configure
 echo ""
 if [[ "$NON_INTERACTIVE" == true ]]; then
@@ -322,15 +369,26 @@ echo "  Tdarr:  http://localhost:8265"
 echo ""
 echo "  Media location: $MEDIA_DIR"
 echo ""
+
+if [[ "$TDARR_MODE" == "docker" ]]; then
+    TDARR_MOVIES_PATH="/movies"
+    TDARR_TV_PATH="/tv"
+else
+    TDARR_MOVIES_PATH="$MEDIA_DIR/Movies"
+    TDARR_TV_PATH="$MEDIA_DIR/TV Shows"
+fi
+
 echo "  Remaining manual steps:"
 if [[ "$MEDIA_SERVER" == "jellyfin" ]]; then
     echo "    1. Complete Jellyfin setup wizard at http://localhost:8096"
     echo "       Add libraries: Movies = /data/movies, TV Shows = /data/tvshows"
-    echo "    2. Configure Tdarr at http://localhost:8265"
+    echo "    2. In Tdarr, add libraries ($TDARR_MOVIES_PATH and $TDARR_TV_PATH) and assign the preloaded"
+    echo "       'Quality-First HEVC (Resolution Preserving)' flow"
 else
     echo "    1. Set up Plex libraries (Movies: $MEDIA_DIR/Movies, TV: $MEDIA_DIR/TV Shows)"
     echo "    2. Edit $MEDIA_DIR/config/kometa/config.yml with Plex token + TMDB key"
-    echo "    3. Configure Tdarr at http://localhost:8265"
+    echo "    3. In Tdarr, add libraries ($TDARR_MOVIES_PATH and $TDARR_TV_PATH) and assign the preloaded"
+    echo "       'Quality-First HEVC (Resolution Preserving)' flow"
 fi
 echo ""
 echo "  Optional - Music (Lidarr + Tidarr):"