gwutilz/gwencoder/docs/RESOLUTION_IMPLEMENTATION_GUIDE.md

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:

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:

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):

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:

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:

# 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.