claude-home/tdarr/scripts/README.md

---
title: "Tdarr Gaming-Aware Scheduler"
description: "User-facing README for the Tdarr gaming-aware scheduler system: quick start, preset configurations (night-only, work-safe, weekend-heavy, gaming-only), gaming process detection, cron setup, and troubleshooting."
type: guide
domain: tdarr
tags: [tdarr, scheduler, gaming-detection, cron, podman, gpu]
---

# 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:

```bash
# 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:**
   ```bash
   ./start-tdarr-gpu-podman-clean.sh
   ```

2. **Install the scheduler:**
   ```bash
   ./tdarr-schedule-manager.sh install
   ```

3. **Check current status:**
   ```bash
   ./tdarr-schedule-manager.sh status
   ```

4. **Test your current schedule:**
   ```bash
   ./tdarr-schedule-manager.sh test
   ```

## ⚙️ Configuration

### Apply Quick Presets
```bash
./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:
```bash
./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
```bash
./tdarr-schedule-manager.sh status
```

### Follow Real-time Logs  
```bash
./tdarr-schedule-manager.sh logs
tail -f /tmp/tdarr-scheduler.log
```

### Check if Current Time is Allowed
```bash
./tdarr-schedule-manager.sh test
```

## 🔧 Manual Override

### Start/Stop Manually
```bash
./start-tdarr-gpu-podman-clean.sh    # Manual start
./stop-tdarr-gpu-podman.sh           # Manual stop
```

### Remove Scheduler
```bash
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
```bash
crontab -l | grep tdarr
# Should show both:
# * * * * * .../tdarr-cron-check-configurable.sh    (scheduler)
# 0 */6 * * * find /tmp -name "tdarr-workDir2-*"...  (cleanup)
```

### Verify Podman Access
```bash
podman ps    # Should work without errors
```

### Test Gaming Detection
```bash
# Start Steam/game, then check:
tail -1 /tmp/tdarr-scheduler.log
```

### Reset to Defaults
```bash
./tdarr-schedule-manager.sh preset work-safe
./tdarr-schedule-manager.sh install
```

---
*Generated by Claude Code - Gaming-aware home lab automation*