# Queue STOP Marker - Quick Reference

## What This Does
Allows you to gracefully halt batch processing **after a specific folder** without losing progress or interrupting an active encode.

## Why You Need This
- 20+ 4K folders in queue = **hours** of processing
- Can't halt mid-encode (loses 30+ minutes of work)
- Can't predict exactly when you'll want your computer back
- Get lost scrolling YouTube while waiting...

## Quick Start

**Step 1: Start your batch**
```bash
python main.py --paths-file paths.txt
```

**Step 2: While it's running, edit your `paths.txt`**
Find a folder in the queue you want to be the **last one**, then add `STOP` on the next line:

```
P:\tv\Show1
P:\tv\Show2
P:\tv\Show3
STOP
P:\tv\Show4
P:\tv\Show5
```

**Step 3: The tool will:**
1. Continue encoding Show1, Show2, Show3 normally
2. Finish encoding Show3 completely
3. Print `🛑 STOP marker encountered - halting batch processing`
4. Exit cleanly

**Step 4: You get your computer back!** ✅

## Usage Tips

### Add STOP Anytime
- While first folder is encoding? Add `STOP` below folder #2 → tool will complete #1 and #2, then stop
- Mid-queue? Just insert `STOP` wherever you want
- Change your mind? Delete the `STOP` line before current encode finishes

### Multiple Queue Files?
Each paths.txt is independent - `STOP` only affects the file being processed:

```bash
# File 1 - 5 folders, stops after folder 3
python main.py --paths-file paths_small.txt

# File 2 - 20 folders (can add STOP to this while first is running)
python main.py --paths-file paths_large.txt
```

### Works With:
- ✅ Any `.txt` or `.csv` batch file
- ✅ Auto-recheck for new items (STOP processed after queue recheck)
- ✅ All encoding modes (720p, 1080p, 4K, etc.)
- ✅ All parameters per-row (--r, --cq, --audio-titles, etc.)

### Does NOT:
- ❌ Stop the currently-encoding file mid-way (completes it first)
- ❌ Affect new items added to queue after STOP was placed

## Format

**Case-insensitive** - these all work:
```
STOP
stop
Stop
STOp
```

**Must be on its own line:**
```
# ✅ Good
P:\tv\Show1
STOP

# ❌ Bad - won't work
P:\tv\Show1 STOP
```

## Example Workflow

**Your paths.txt:**
```
P:\movies\Action Movies
P:\movies\Drama Movies
P:\tv\Comedy Shows
P:\tv\Crime Dramas
P:\anime\Ongoing Series
```

**You run:**
```bash
python main.py --paths-file paths.txt
```

**30 minutes later, "Action Movies" finishes. Comedy Shows is now encoding. You think:**
> "I want my computer back after Crime Dramas"

**You edit paths.txt to:**
```
P:\movies\Action Movies
P:\movies\Drama Movies
P:\tv\Comedy Shows
P:\tv\Crime Dramas
STOP
P:\anime\Ongoing Series
```

**Result:** Tool will encode Comedy Shows (current) → Crime Dramas (next) → then gracefully exit.

---

**Log Output:**
```
✓ [BATCH 3] Completed: Comedy Shows
✓ [BATCH 4] Completed: Crime Dramas
================================================================================
🛑 STOP marker encountered - halting batch processing
================================================================================
  ✓ Succeeded: 4
  (no new additions)
```