claude-home/tdarr/scripts/README.md

Tdarr Gaming-Aware Scheduler

Intelligent Tdarr node management with automatic gaming detection and flexible time-based scheduling.

🎮 Overview

This system automatically manages your Tdarr transcoding node to avoid conflicts with gaming and other GPU-intensive activities. It detects gaming processes, monitors GPU usage, and respects customizable time windows.

📁 Files

File	Purpose
start-tdarr-gpu-podman-clean.sh	Start mapped Tdarr container with GPU support
stop-tdarr-gpu-podman.sh	Stop Tdarr container
tdarr-cron-check-configurable.sh	Main scheduler (runs every minute via cron)
tdarr-schedule-manager.sh	Management interface and configuration tool
tdarr-schedule.conf	Configuration file with schedule and settings

🧹 Automated Maintenance

Temporary Directory Cleanup

A cron job automatically cleans up abandoned Tdarr transcoding directories:

# Runs every 6 hours (12 AM, 6 AM, 12 PM, 6 PM)
0 */6 * * * find /tmp -name "tdarr-workDir2-*" -type d -mmin +360 -exec rm -rf {} \; 2>/dev/null || true

What it does:

• Removes Tdarr temp directories older than 6 hours
• Protects active transcoding jobs (< 6 hours old)
• Prevents /tmp from filling up with abandoned work files
• Safe to run - only targets Tdarr-specific directories

When cleanup happens:

• Failed transcoding jobs leave tdarr-workDir2-* directories
• Gaming interruptions can abandon partial work
• Cleanup preserves resume capability for active jobs

🚀 Quick Start

1. Start the mapped Tdarr node:

   ./start-tdarr-gpu-podman-clean.sh
   

2. Install the scheduler:

   ./tdarr-schedule-manager.sh install
   

3. Check current status:

   ./tdarr-schedule-manager.sh status
   

4. Test your current schedule:

   ./tdarr-schedule-manager.sh test
   

⚙️ Configuration

Apply Quick Presets

./tdarr-schedule-manager.sh preset night-only      # 10PM-7AM only
./tdarr-schedule-manager.sh preset work-safe       # Nights + work hours  
./tdarr-schedule-manager.sh preset weekend-heavy   # Maximum transcoding time
./tdarr-schedule-manager.sh preset gaming-only     # No time limits, gaming detection only

Custom Schedule Format

Edit tdarr-schedule.conf or use the manager:

./tdarr-schedule-manager.sh edit

Time Block Format: "HOUR_START-HOUR_END:DAYS"

• "22-07:daily" - 10PM to 7AM every day (overnight)
• "09-17:1-5" - 9AM to 5PM Monday-Friday
• "14-16:6,7" - 2PM to 4PM Saturday and Sunday
• "08-20:6-7" - 8AM to 8PM weekends only

🎮 Gaming Detection

Automatically detects these processes:

• Steam, Lutris, Heroic Games Launcher
• Wine, Bottles (Windows compatibility layers)
• GameMode, MangoHUD (gaming utilities)
• GPU usage >15% (configurable threshold)

📊 Monitoring

View Status

./tdarr-schedule-manager.sh status

Follow Real-time Logs

./tdarr-schedule-manager.sh logs
tail -f /tmp/tdarr-scheduler.log

Check if Current Time is Allowed

./tdarr-schedule-manager.sh test

🔧 Manual Override

Start/Stop Manually

./start-tdarr-gpu-podman-clean.sh    # Manual start
./stop-tdarr-gpu-podman.sh           # Manual stop

Remove Scheduler

crontab -e    # Delete the tdarr line

🎯 How It Works

1. Cron runs every minute → checks gaming processes & GPU usage
2. Gaming detected → immediately stops Tdarr
3. No gaming + allowed time → starts Tdarr
4. Outside allowed hours → stops Tdarr
5. Logs all activity → /tmp/tdarr-scheduler.log

🏗️ Architecture

Node Configuration: Mapped node with direct media access

• /mnt/media/TV:/media/TV - Direct TV library access
• /mnt/media/Movies:/media/Movies - Direct Movies library access
• /mnt/NV2/tdarr-cache:/cache - NVMe cache for optimal performance
• /mnt/media/tdarr/tdarr-cache-clean:/temp - Temp processing space

Scheduler Flow:

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   cron (1min)   │───▶│  configurable.sh │───▶│ start/stop.sh   │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                       ┌────────▼────────┐
                       │ schedule.conf   │
                       │ - Time blocks   │
                       │ - Gaming procs  │ 
                       │ - GPU threshold │
                       └─────────────────┘

🚨 Troubleshooting

Check Cron Installation

crontab -l | grep tdarr
# Should show both:
# * * * * * .../tdarr-cron-check-configurable.sh    (scheduler)
# 0 */6 * * * find /tmp -name "tdarr-workDir2-*"...  (cleanup)

Verify Podman Access

podman ps    # Should work without errors

Test Gaming Detection

# Start Steam/game, then check:
tail -1 /tmp/tdarr-scheduler.log

Reset to Defaults

./tdarr-schedule-manager.sh preset work-safe
./tdarr-schedule-manager.sh install

---

Generated by Claude Code - Gaming-aware home lab automation