encoderPro/FILTER-FEATURE-SUMMARY.md

# Video Attribute Filtering Feature - Summary

## What Was Added

Users can now filter videos by specific attributes like resolution, audio channels, file size, codec, and more. This makes it easy to find and encode specific types of files.

## Available Filters

### Audio
- **🔊 5.1+ Audio** - Videos with surround sound (6+ channels)
- **🔉 Stereo Only** - Videos with stereo or mono audio (< 6 channels)

### Subtitles
- **📝 Has Subtitles** - Videos with embedded subtitles
- **❌ No Subtitles** - Videos without subtitles

### Resolution
- **📺 4K** - 3840x2160 or higher
- **📺 1080p** - 1920x1080 to 3839x2159

### Codec
- **🎞️ H.264** - Videos encoded with H.264/AVC
- **🎞️ H.265** - Videos encoded with H.265/HEVC

### File Size
- **💾 Large Files (>5GB)** - Files larger than 5GB

### Other
- **All Videos** - Show all videos (removes filter)

## How It Works

### Backend Changes

#### 1. Database Schema Updates (dashboard.py)
Added new columns to the `files` table:
- `video_codec` - Video codec name (h264, hevc, etc.)
- `audio_codec` - Audio codec name (aac, ac3, dts, etc.)
- `audio_channels` - Number of audio channels (2, 6, 8, etc.)
- `width` - Video width in pixels
- `height` - Video height in pixels
- `duration` - Video duration in seconds
- `bitrate` - Video bitrate in bits per second

Migration automatically adds these columns to existing databases.

#### 2. Media Inspection (reencode.py)
Updated `LibraryScanner.scan()` to extract media attributes using FFprobe:
- Parses video streams for codec, resolution
- Parses audio streams for codec, channels
- Extracts format info for duration, bitrate
- Saves all attributes to database

#### 3. Filter Query Logic (dashboard.py)
Added `filter_type` parameter to `get_files()` method with SQL filters:
```python
if filter_type == 'surround_sound':
    query += " AND audio_channels >= 6"
elif filter_type == '4k':
    query += " AND width >= 3840"
# etc...
```

#### 4. API Endpoint (dashboard.py)
`/api/files` now accepts `filter` parameter:
```
GET /api/files?filter=surround_sound
GET /api/files?filter=4k&state=discovered
```

### Frontend Changes

#### 1. Filter Buttons UI (dashboard.html)
Added filter button bar with 10 filter options:
- Visual design matches dashboard style
- Active filter highlighted in blue
- Inactive filters in gray

#### 2. JavaScript Functions (dashboard.html)
- `applyFilter(filterType)` - Sets active filter and reloads file list
- `currentAttributeFilter` - Tracks active filter
- `loadFileQuality()` - Updated to include filter in API call

#### 3. Button State Management
Filter buttons update styling to show active state:
- Active: Blue background, bold font
- Inactive: Gray background, normal font

## User Experience

### Before
Users could only filter by state (discovered, pending, completed, etc.) or search by filename.

### After
Users can:
1. Click a filter button to show only matching videos
2. Combine filters with state filters (e.g., "Show discovered files with 5.1 audio")
3. See exactly which videos match their criteria
4. Easily find videos that need re-encoding (e.g., all H.264 videos to convert to H.265)

## Example Use Cases

### 1. Convert All H.264 to H.265
1. Click **🎞️ H.264** filter
2. Click **📁 Discovered** quick select
3. Choose `sweetspot_qsv` profile
4. Click **▶️ Encode Selected**

### 2. Prioritize Large Files
1. Click **💾 Large Files (>5GB)** filter
2. Select files with checkboxes
3. Encode to save disk space

### 3. Find 4K Content
1. Click **📺 4K** filter
2. See all 4K videos in library
3. Use appropriate 4K encoding profile

### 4. Upgrade Stereo to Surround
1. Click **🔉 Stereo Only** filter
2. Find videos that could benefit from audio upgrade
3. Plan audio enhancement workflow

## Files Modified

### dashboard.py
- Lines 145-170: Added new columns to database schema
- Lines 197-215: Added database migration for new columns
- Lines 322-381: Updated `get_files()` to support attribute filtering
- Lines 739-749: Updated `/api/files` endpoint to accept `filter` parameter

### reencode.py
- Lines 364-398: Updated `add_file()` to accept media attributes
- Lines 899-943: Updated `scan()` to extract and save media attributes

### templates/dashboard.html
- Lines 605-640: Added filter buttons UI
- Lines 1434: Added `currentAttributeFilter` variable
- Lines 1445-1452: Updated `loadFileQuality()` to include filter in API call
- Lines 1613-1631: Added `applyFilter()` function

## Testing

To test the feature:

1. **Scan Library**
   - Click "Scan Library" button
   - Scanner will extract media attributes for all files
   - May take longer than before due to FFprobe calls

2. **Apply Filters**
   - Click different filter buttons
   - File table should update to show only matching files
   - Active filter should be highlighted in blue

3. **Combine with State Filters**
   - Select a state from dropdown (e.g., "Discovered")
   - Click an attribute filter (e.g., "5.1+ Audio")
   - Should show only discovered files with surround sound

4. **Select and Encode**
   - Apply a filter
   - Select files with checkboxes or "Discovered" button
   - Choose profile and encode

## Performance Considerations

- **Scanning**: Now slightly slower due to FFprobe calls for each file
- **Filtering**: SQL queries are efficient with proper indexing
- **First Scan**: Existing files need rescanning to populate new attributes

## Future Enhancements

Possible additions:
- **HDR Detection** - Filter for HDR/Dolby Vision content
- **Bitrate Ranges** - Custom bitrate thresholds
- **Frame Rate** - Filter by 24fps, 30fps, 60fps, etc.
- **720p Filter** - Add 720p resolution option
- **Codec Combinations** - Filter by video+audio codec pairs
- **File Age** - Filter by when files were added
- **Compression Ratio** - Filter by how much compression potential exists