encoderPro/SELECTION-ONLY-FINAL.md

# Selection-Only Workflow (Final)

**Date:** December 21, 2024
**Purpose:** Fixed the "encoding all 161 files" bug by implementing true selection-only workflow

---

## The Problem We Fixed

**Bug:** Clicking "Encode Selected" on 1 movie would encode ALL 161 movies!

**Root Cause:** Two conflicting workflows sharing the same "pending" state:
- Scan marked 161 files as "pending"
- "Encode Selected" then called "Start Processing" which processes ALL pending files
- Result: You selected 1 file but it encoded all 161!

---

## The Solution

### New State: "DISCOVERED"

Files now go through these states:

1. **DISCOVERED** (purple) - Found during scan, NOT selected
2. **PENDING** (yellow) - User selected with "Encode Selected" button
3. **PROCESSING** (blue) - Currently encoding
4. **COMPLETED** (green) - Successfully encoded
5. **FAILED** (red) - Encoding failed
6. **SKIPPED** (gray) - No subtitles

### Key Change

**Scan behavior:**
- **Before:** Marked files with subtitles as "pending" (161 files)
- **After:** Marks files with subtitles as "discovered" (0 pending)

**"Encode Selected" behavior:**
- Marks YOUR selected files as "pending"
- Then processes ONLY those pending files
- Result: Only your selection encodes!

---

## UI Changes

### Removed "Start Processing All Pending" Button

**Before:**
```
[▶ Start Processing All Pending] [⏹ Stop] [📂 Scan] [🔄 Refresh]
```

**After:**
```
[⏹ Stop] [📂 Scan] [🔄 Refresh] [🔧 Reset Stuck]
```

**Why:** This button caused confusion and the bug. You should ONLY encode via "Encode Selected".

### Stats Card

**Before:** "Pending - Files waiting to process"
**After:** "Discovered - Files found (not selected)"

### Filter Dropdown

- All Files
- **Discovered** (new!)
- Selected (Pending)
- Processing
- Completed
- Failed
- Skipped

### Quick Select Buttons

**Before:**
- 📁 Not Encoded
- 🔄 Failed

**After:**
- 📁 Discovered
- 🔄 Failed

---

## Workflow

### Simple 3-Step Process

1. **Select files** (checkboxes or "📁 Discovered" button)
2. **Choose profile** (dropdown)
3. **Click "▶️ Encode Selected"** → Encodes ONLY selected files

### What Happens Behind the Scenes

```javascript
async function encodeSelected() {
    // 1. Mark selected files as "pending"
    await API.queueSelected(fileIds, profile)

    // 2. Start processing (only processes files marked "pending")
    await API.startProcessing(profile)

    // Result: Only the files YOU selected encode!
}
```

---

## State Diagram

```
[Scan Library]
    ↓
[DISCOVERED] ← 161 files marked here (purple)
    ↓ (user selects 1 file)
    ↓ (clicks "Encode Selected")
[PENDING] ← ONLY 1 file marked here (yellow)
    ↓ (encoding starts automatically)
[PROCESSING] ← 1 file encoding (blue)
    ↓
[COMPLETED] or [FAILED] ← 1 file done (green/red)
```

---

## Code Changes

### 1. reencode.py

**Added DISCOVERED state:**
```python
class ProcessingState(Enum):
    DISCOVERED = "discovered" # Found during scan, not selected yet
    PENDING = "pending"       # User selected for encoding
    PROCESSING = "processing"
    COMPLETED = "completed"
    FAILED = "failed"
    SKIPPED = "skipped"
```

**Scan marks as DISCOVERED:**
```python
# Files with subtitles are marked as DISCOVERED (found but not selected)
# Only when user selects files do they become PENDING
state = ProcessingState.DISCOVERED.value if has_subtitles else ProcessingState.SKIPPED.value
```

### 2. dashboard.html

**Removed button:**
- Deleted "Start Processing All Pending" button entirely

**Updated stats:**
```html
<div class="card-title">Discovered</div>
<div class="card-value" id="statDiscovered">-</div>
<div class="card-subtitle">Files found (not selected)</div>
```

**Updated filters and quick-select:**
- Filter: "Discovered" instead of "Not Encoded"
- Quick Select: "📁 Discovered" button

**State colors:**
```javascript
'discovered': '#8b5cf6', // Purple - found but not selected
'pending': '#fbbf24',    // Yellow - selected for encoding
'processing': '#3b82f6', // Blue - encoding
'completed': '#10b981',  // Green - done
'failed': '#ef4444',     // Red - error
'skipped': '#94a3b8'     // Gray - no subs
```

---

## Testing Scenarios

### ✅ Scenario 1: Select One File
1. Scan library → 161 files show as "discovered" (purple)
2. Select 1 file with checkbox
3. Choose profile
4. Click "Encode Selected"
5. **Expected:** Only 1 file encodes
6. **Stats:** Discovered: 160, Processing: 1

### ✅ Scenario 2: Quick Select
1. Click "📁 Discovered" button
2. All 161 discovered files selected
3. Click "Encode Selected"
4. **Expected:** All 161 files encode
5. **Stats:** Discovered: 0, Processing: 161

### ✅ Scenario 3: Failed Retry
1. Some files fail encoding
2. They show as "failed" (red)
3. Click "🔄 Failed" quick-select
4. Click "Encode Selected"
5. **Expected:** Only failed files retry

---

## Benefits

✅ **Bug Fixed:** Selecting 1 file only encodes 1 file
✅ **Clear States:** "discovered" vs "pending" are distinct
✅ **No Confusion:** Removed "Start Processing All Pending" button
✅ **Visual Clarity:** Purple (discovered) → Yellow (selected) → Blue (encoding) → Green (done)
✅ **Intentional Actions:** User must explicitly select files
✅ **No Accidents:** Can't accidentally encode entire library

---

## Migration

### Existing Databases

Files currently in database will be treated as:
- "pending" stays as "pending" (will encode if you had queued them)
- New scans mark files as "discovered"

### Clean Slate

To reset all files to discovered state:
```sql
UPDATE files SET state = 'discovered' WHERE state = 'pending' AND has_subtitles = 1;
```

Or just rescan the library.

---

## Version

**encoderPro Version:** 3.4.0 (Selection-Only Workflow - Final)
**Date:** December 21, 2024
**Bug Fixed:** #1 - Encoding all files when selecting only one