encoderPro/SIMPLIFIED-WORKFLOW.md

Simplified Workflow - Single Button Encoding

Date: December 21, 2024 Purpose: Simplified from 2-button to 1-button workflow

---

The Problem with Previous Approach

The "ready → pending → start" workflow was too confusing:

❌ Too many steps (4 total):

1. Scan
2. Select files
3. Click "Queue Selected" (marks as pending)
4. Click "Start Processing" (actually starts encoding)

❌ Two buttons that sound similar:

• "Queue Selected for Encoding"
• "Start Processing"

❌ Too many states (6):

• ready, pending, processing, completed, failed, skipped

❌ Artificial distinction between "ready" vs "pending"

---

New Simplified Workflow

✅ 3 simple steps:

1. Select files using checkboxes
2. Choose profile from dropdown
3. Click "Encode Selected" → Starts immediately

✅ One button: "Encode Selected" does exactly what it says

✅ 5 states (only actual encoding status):

• pending - Not yet encoded (gray badge, or no badge)
• processing - Currently encoding (blue)
• completed - Successfully encoded (green)
• failed - Encoding failed (red)
• skipped - No subtitles (light gray)

---

Changes Made

1. reencode.py

Removed "ready" state:

class ProcessingState(Enum):
    """File processing states"""
    PENDING = "pending"       # Not yet encoded (files with subtitles)
    PROCESSING = "processing" # Currently being encoded
    COMPLETED = "completed"   # Successfully encoded
    FAILED = "failed"         # Encoding failed, can retry
    SKIPPED = "skipped"       # No subtitles or excluded

Scan marks files as PENDING (not "ready"):

# Files with subtitles are marked as PENDING (ready to encode)
# Files without subtitles are SKIPPED
state = ProcessingState.PENDING.value if has_subtitles else ProcessingState.SKIPPED.value

2. dashboard.html

Updated Instructions:

1. Select movies using checkboxes or Quick Select buttons below.
2. Choose an encoding profile.
3. Click "Encode Selected" to start encoding immediately.

Simplified Filter Dropdown:

• All Files
• Not Encoded (pending)
• Processing
• Completed
• Failed
• Skipped

Updated Quick Select Buttons:

• 📁 Not Encoded (selects all "pending")
• 🔄 Failed (selects all "failed" to retry)

Single Button:

• Changed from "Queue Selected for Encoding"
• To "▶️ Encode Selected"
• Function renamed: reencodeSelected() → encodeSelected()

Simplified State Colors:

'pending': '#64748b',    // Gray - not yet encoded
'processing': '#3b82f6', // Blue - currently encoding
'completed': '#10b981',  // Green - successfully encoded
'failed': '#ef4444',     // Red - encoding failed
'skipped': '#94a3b8'     // Light gray - skipped (no subtitles)

Single-Step Encoding:

async function encodeSelected() {
    // 1. Queue the selected files (marks as pending)
    await fetchWithCsrf('/api/jobs/reencode-selected', {...})

    // 2. Immediately start processing
    await fetchWithCsrf('/api/jobs/start', {...})

    // Done! Encoding starts immediately
}

---

User Experience Comparison

Before (2-Button Workflow)

User: "I want to encode these 5 movies"

1. Select 5 movies ✓
2. Click "Queue Selected for Encoding"
   → Message: "Files queued! Now click Start Processing"
   → User: "Wait, didn't I just click to encode?"
3. Scroll to top
4. Click "Start Processing"
   → Finally starts encoding

Result: Confused, extra steps

After (1-Button Workflow)

User: "I want to encode these 5 movies"

1. Select 5 movies ✓
2. Choose profile ✓
3. Click "Encode Selected"
   → Immediately starts encoding ✓

Result: Clear, direct, simple

---

States Explained

PENDING (Gray/No Badge)

• What it means: File has subtitles, not yet encoded
• What user can do: Select it and click "Encode Selected"
• When it changes: When encoding starts (→ processing)

PROCESSING (Blue)

• What it means: Currently being encoded
• What user can do: Wait, or click "Stop Processing"
• When it changes: When done (→ completed/failed)

COMPLETED (Green)

• What it means: Successfully encoded
• What user can do: Nothing needed, it's done
• When it changes: Stays completed (can re-encode if needed)

FAILED (Red)

• What it means: Encoding failed
• What user can do: Select and retry by clicking "Encode Selected"
• When it changes: When re-encoded (→ processing)

SKIPPED (Light Gray)

• What it means: No subtitles, or manually excluded
• What user can do: Nothing, file doesn't meet criteria
• When it changes: Doesn't change (unless subtitles added)

---

Benefits

1. Simpler mental model: "Select → Encode" instead of "Select → Queue → Start"
2. One clear action: Button name matches what it does
3. Fewer states: Only real encoding status, not UI workflow states
4. Less confusion: No need to explain difference between "ready" and "pending"
5. Faster workflow: 3 steps instead of 4
6. Clearer UI: State colors match encoding status
7. Better UX: Immediate feedback when clicking "Encode Selected"

---

Migration

Existing Databases

• Files in "ready" state will be treated as "pending"
• Files in "pending" state remain pending
• No data loss, fully compatible

No Breaking Changes

• API endpoints unchanged
• Backend logic unchanged
• Only UI and state naming simplified

---

Testing

• Scan library → Files show as "pending" (gray badge)
• Select files → Checkbox works
• Click "Encode Selected" → Encoding starts immediately
• Check processing → Files turn blue
• Check completed → Files turn green
• Check failed → Files turn red, can retry
• Filter by "Not Encoded" → Shows pending files
• Quick Select "Not Encoded" → Selects all pending
• Quick Select "Failed" → Selects all failed

---

Version

encoderPro Version: 3.3.0 (Simplified Workflow) Date: December 21, 2024