encoderPro/MANUAL-SELECTION-ONLY.md

Manual Selection Only - No Bulk Processing

Date: December 21, 2024 Purpose: Remove bulk processing, require explicit user selection for all encodings

---

Changes Made

New State: "READY"

Added a new file state to distinguish between discovered files and queued files:

State	Color	Meaning
READY	Purple	File has been discovered and has subtitles, ready to be selected
PENDING	Yellow	User explicitly queued this file for encoding
PROCESSING	Blue	Currently being encoded
COMPLETED	Green	Successfully encoded
FAILED	Red	Encoding failed
SKIPPED	Gray	No subtitles or other skip reason

Workflow Changes

OLD Workflow (Automatic):

1. Scan library → Files with subtitles automatically marked as "pending"
2. Start Processing → ALL files with subtitles encode

NEW Workflow (Manual Selection Required):

1. Scan library → Files with subtitles marked as "ready" (NOT pending)
2. User selects files → Choose specific movies using checkboxes or Quick Select
3. Queue for encoding → Click "Queue Selected for Encoding" → Marks files as "pending"
4. Start Processing → Only processes files explicitly marked as "pending"

---

Code Changes

1. reencode.py

ProcessingState Enum (lines 46-53):

class ProcessingState(Enum):
    """File processing states"""
    READY = "ready"           # Discovered, has subtitles, ready to be selected
    PENDING = "pending"       # User-selected, queued for encoding
    PROCESSING = "processing" # Currently being encoded
    COMPLETED = "completed"   # Successfully encoded
    FAILED = "failed"         # Encoding failed
    SKIPPED = "skipped"       # No subtitles or other skip reason

add_file Method (lines 357-359):

# Files are marked as READY (not PENDING) when discovered
# User must explicitly select files to mark them as PENDING
state = ProcessingState.READY.value if has_subtitles else ProcessingState.SKIPPED.value

2. templates/dashboard.html

State Badge Colors (lines 1224-1230):

const stateBadgeColors = {
    'ready': '#8b5cf6',      // Purple - ready to be selected
    'pending': '#fbbf24',    // Yellow - queued for encoding
    'processing': '#3b82f6', // Blue - currently encoding
    'completed': '#10b981',  // Green - done
    'failed': '#ef4444',     // Red - error
    'skipped': '#64748b'     // Gray - skipped
};

Filter Dropdown (lines 560-566):

• Added "Ready" option
• Changed "Pending" to "Pending (Queued)" for clarity

Quick Select Buttons (lines 589-595):

• Added "🎬 Ready" button (purple)
• Removed "Pending" and "Completed" buttons (only keep Ready and Failed)
• Reasoning: Users select "Ready" files to queue, or "Failed" files to retry

State Tooltips (lines 1239-1251):

• ready: "Ready to encode - select this file to queue for encoding"
• pending: "Queued for encoding - will process when you click Start Processing"

Instructions Banner (lines 387-392):

Step 1: Select movies from the table below (use checkboxes or Quick Select buttons).
Step 2: Click "Queue Selected for Encoding" to mark them as pending.
Step 3: Click "Start Processing" at the top to begin encoding.

Button Text (line 610):

• Changed from "🎬 Encode Selected Movies"
• To "📥 Queue Selected for Encoding"

Confirmation Messages:

• Queue: "Queue N file(s) for encoding using profile X? They will be marked as PENDING..."
• Success: "N file(s) marked as PENDING! They are now queued for encoding. Now click Start Processing..."

---

User Experience

Before (Automatic Bulk Processing)

1. Scan library
2. ALL files with subtitles automatically queued
3. Start Processing → encodes everything
4. ❌ User has no control over what gets encoded
5. ❌ Can't select specific files
6. ❌ Unclear what "Start Processing" will do

After (Manual Selection Only)

1. Scan library → Files show as "READY" (purple)
2. User browses and selects specific files
3. User clicks "Queue Selected for Encoding" → Files become "PENDING" (yellow)
4. User clicks "Start Processing" → Only pending files encode
5. ✅ Complete control over what gets encoded
6. ✅ Clear workflow with visual feedback
7. ✅ Can queue in batches
8. ✅ Obvious what will happen when clicking Start

---

Migration Path

Existing Databases

Files currently in "pending" state will remain pending and will be processed when Start Processing is clicked. This is intentional - they were already queued.

New scans will mark files as "ready" instead of "pending".

No Breaking Changes

• API endpoints unchanged
• Database schema compatible (just new state value)
• Config files unchanged
• Docker commands unchanged

---

Benefits

1. User Control: Users explicitly choose every file to encode
2. Clarity: Clear 3-step workflow with visual indicators
3. Safety: No accidental bulk encoding of entire library
4. Flexibility: Queue files in batches, different profiles
5. Transparency: Always know what's queued vs ready
6. Better UX: Purple → Yellow → Blue → Green progression

---

Testing Checklist

• Scan library → Files marked as "ready" (purple)
• Select ready files → Checkbox works
• Click "Queue Selected for Encoding" → Files become "pending" (yellow)
• Click "Start Processing" → Only pending files encode
• Failed files → Can select and retry
• Filter by "Ready" → Shows only ready files
• Quick Select "Ready" → Selects all ready files
• Quick Select "Failed" → Selects all failed files
• Tooltips show correct information
• Success messages clear and helpful

---

Version

encoderPro Version: 3.3.0 (Manual Selection Only) Date: December 21, 2024