transcode manager, symlink repair and more

Master.conf

@@ -649,40 +649,58 @@ MEDIA_MAINTENANCE_JOBS=(
 # ==============================================================================================
 # ── TRANSCODES ────────────────────────────────────────────────────────────────────────────────
 # ==============================================================================================
-# Session-based storage allocator using filesystem indirection.
-# ffmpeg resolves the symlink path ONCE at session start — existing sessions are never affected
-# by symlink changes. Only NEW sessions care about where the symlink currently points.
+# Session-based storage allocator using filesystem symlink indirection.
+# ffmpeg resolves the symlink ONCE at session start — existing sessions are never affected.
+# Only new sessions care about where the symlink currently points.
 #
 # How it works:
 #   ramdisk_setup.sh     — run once at array start, creates tmpfs and sets symlink
-#   transcode_manager.sh — every 3 min, monitors ramdisk usage and flips symlink if needed
+#   transcode_manager.sh — every 3 min, monitors usage and manages symlink direction
 #   transcode_cleanup.sh — every 5 min, removes old inactive files from both locations
 #
-# Hysteresis gap between RAMDISK_WARN_GB and RAMDISK_LOW_GB prevents flip-flop
-# when usage hovers near the threshold. Gap should be at least 0.5-1GB.
-# Ramdisk is dynamic tmpfs — only uses RAM actually needed, RAMDISK_SIZE is the ceiling.
-
+# ⚠️ Docker mount warning:
+#   Do NOT add a static SSD transcode path as a second volume mount in your Emby container.
+#   If the SSD path is mounted inside the container Emby can see it and will use it
+#   independently of the symlink — breaking symlink-based routing entirely.
+#   The symlink IS your emergency lever — one mount only:
+#     /mnt/ram-transcode → /ext-ram-transcode
+ 
     RAMDISK_PATH="/mnt/ramdisk_transcodes"  # tmpfs mount point created at array start
     RAMDISK_SIZE="8G"                        # ceiling — tmpfs only uses RAM actually needed
     TRANSCODE_LINK="/mnt/ram-transcode"      # symlink Emby points at — location never changes
-    TRANSCODE_SSD="/mnt/cache/Temp_Storage/Emby/Transcodes/" # SSD fallback for edge cases only
-
-# Usage thresholds in GB
+    TRANSCODE_SSD="/mnt/cache/Temp_Storage/Emby/Transcodes/" # SSD fallback location
+ 
+# Usage thresholds in GB — hysteresis gap prevents flip-flop near threshold
     RAMDISK_WARN_GB=6.8     # flip symlink to SSD at or above this usage
-    RAMDISK_LOW_GB=5.0      # flip symlink back to ramdisk when usage drops here
+    RAMDISK_LOW_GB=5.5      # flip symlink back to ramdisk when usage drops here
     RAMDISK_SSD_MIN_GB=20   # minimum free GB on SSD required before allowing flip to SSD
-
+ 
 # Cleanup age thresholds — files must be older than these AND not open by any process
     TRANSCODE_MAX_AGE=20    # minutes before a transcode file is eligible for cleanup
-    TRANSCODE_ORPHAN_AGE=30 # minutes before an orphaned file is eligible — extra caution buffer
-
+    TRANSCODE_ORPHAN_AGE=30 # minutes before an orphaned file is eligible
+ 
 # Flip frequency alert — too many flips per hour may indicate ramdisk needs to be larger
     TRANSCODE_FLIP_WARN=3   # notify if symlink flips this many times in one hour
-
-# Permissions applied to ramdisk and SSD fallback — must match your Emby container user
+ 
+# Permissions — must match your Emby container user
     TRANSCODE_OWNER="nobody:users"
-    TRANSCODE_MODE="755"
-
+    TRANSCODE_CHMOD="755"   # renamed from TRANSCODE_MODE to avoid ambiguity with manager mode
+ 
+# Operating mode — controls symlink routing behavior
+# smart   — auto-flips between ramdisk and SSD based on usage thresholds (default)
+# ramdisk — always uses ramdisk, never flips to SSD regardless of usage
+#           useful when load is light and you want guaranteed ramdisk performance
+#           warns if usage exceeds threshold but does not flip
+# ssd     — always uses SSD, never uses ramdisk
+#           useful during ramdisk maintenance, testing, or after a flip issue
+#           switch to this mode to drain ramdisk sessions gracefully
+    TRANSCODE_MANAGER_MODE="smart"
+ 
+# Emby container check — skips threshold checks when Emby is not running
+# Prevents unnecessary symlink flips when no transcoding is happening
+    TRANSCODE_CHECK_EMBY=true
+    TRANSCODE_EMBY_CONTAINER="Emby"   # exact Docker container name — case sensitive
+ 
 # ==============================================================================================
 # ── MONITOR ───────────────────────────────────────────────────────────────────────────────────
 # ==============================================================================================