upgrade: gwencoder v3.1 with interactive menu and Tdarr alignment

gwencoder/docs/RESOLUTION_IMPLEMENTATION_GUIDE.md

@@ -0,0 +1,145 @@
+# Resolution Preset Implementation Guide
+
+## Changes Required to cmd/gwencoder/main.go
+
+Since `cmd/gwencoder/main.go` is in `.gitignore`, here's a guide for the manual changes needed:
+
+### 1. Add Resolution field to EncodingOptions struct
+
+Find the `EncodingOptions` struct (around the top of the file or where flags are defined) and add:
+
+```go
+type EncodingOptions struct {
+    // ... existing fields ...
+    
+    // Resolution preset
+    Resolution string  // "480p", "720p", "1080p", or "original"
+    
+    // ... rest of existing fields ...
+}
+```
+
+### 2. Add --resolution flag in parseFlags() function
+
+Find the `parseFlags()` function and add this flag definition with the other flags:
+
+```go
+func parseFlags() EncodingOptions {
+    // ... existing flag definitions ...
+    
+    // Resolution preset
+    resolution := flag.String("resolution", "", "Target resolution (480p, 720p, 1080p, original)")
+    
+    // ... rest of flag definitions ...
+    flag.Parse()
+    
+    // ... populate EncodingOptions struct ...
+    opts := EncodingOptions{
+        // ... existing fields ...
+        Resolution: *resolution,
+        // ... rest of fields ...
+    }
+    
+    return opts
+}
+```
+
+### 3. Update  encodeFile() function to use resolution scaling
+
+Find the `encodeFile()` function and add resolution scaling integration.
+
+Look for where the FFmpeg command is being built (likely where video filters are added):
+
+```go
+func encodeFile(file string, mode string, opts EncodingOptions) error {
+    // ... existing code ...
+    
+    // Build scale filter for resolution preset
+    scaleFilter := ""
+    if opts.Resolution != "" {
+        filter, err := encoding.BuildScaleFilter(file, opts.Resolution)
+        if err != nil {
+            fmt.Printf("⚠️  Warning: Could not build scale filter: %v\n", err)
+        } else if filter != "" {
+            scaleFilter = filter
+            targetHeight := encoding.GetResolutionPresetHeight(opts.Resolution)
+            fmt.Printf("📐 Scaling video to %dp\n", targetHeight)
+        }
+    }
+    
+    // ... when building FFmpeg command ...
+    // If scaleFilter is not empty, it should be added to the FFmpeg command
+    // Example: if there's already a video filter section, combine them
+    // or if -vf doesn't exist yet, add the scaleFilter directly
+    
+    // ... rest of encodeFile function ...
+}
+```
+
+**Note**: The exact integration point depends on how the FFmpeg command is currently constructed. Look for where other video filters (like odd height handling) are added and follow that pattern.
+
+### 4. Update printHelp() function
+
+Find the `printHelp()` function and add documentation for the new flag in the appropriate section:
+
+```go
+func printHelp() {
+    // ... existing help text ...
+    
+    fmt.Println("\n📐 Resolution Options:")
+    fmt.Println("  --resolution <preset>     Scale video to target resolution")
+    fmt.Println("                            Options: 480p, 720p, 1080p, original")
+    fmt.Println("                            Only scales down, never upscales")
+    fmt.Println("                            Maintains aspect ratio")
+    
+    // ... rest of help text ...
+}
+```
+
+## Testing the Changes
+
+After making these changes, rebuild and test:
+
+```bash
+# Rebuild
+make clean
+make build
+
+# Test with resolution scaling
+./build/gwencoder --fast --resolution 720p input_1080p.mp4
+
+# Test that it doesn't upscale
+./build/gwencoder --fast --resolution 1080p input_480p.mp4
+
+# Test original (no scaling)
+./build/gwencoder --fast --resolution original input.mp4
+```
+
+## Expected Output
+
+When resolution scaling is applied, you should see output like:
+```
+📐 Scaling video to 720p
+```
+
+When no scaling is needed (input already at or below target):
+```
+(no scaling message - continues with encoding)
+```
+
+## Troubleshooting
+
+If you encounter issues:
+
+1. **Build errors**: Check that the `encoding.BuildScaleFilter`, `encoding.GetResolution PresetHeight` functions are being called correctly
+2. **Runtime errors**: Ensure ffprobe is available and the input file exists
+3. **No scaling**: Check that the scaleFilter is being added to the actual FFmpeg command
+
+## Example FFmpeg Command
+
+The final FFmpeg command should include the scale filter like:
+```
+ffmpeg -i input.mp4 -vf scale=-2:720 ... other_args ... output.mkv
+```
+
+Where `-2` automatically calculates width based on height while maintaining aspect ratio and ensuring even dimensions.