# docs/Upscale.md
Upscale Module (Planned) - v0.1.2

The upscale-video command will provide high-quality resolution upscaling with minimal visual loss.
It will begin with traditional FFmpeg filters and later introduce machine learning based upscalers.

------------------------------------------------------------
Overview
------------------------------------------------------------

The goal of this module is to let users upscale existing videos to standardized modern resolutions such as:
- 720p (HD)
- 1080p (Full HD)
- 2160p (4K UHD)

The first release will use FFmpeg’s built-in scaling filters including lanczos, bicubic, and spline36.
Future updates will explore GPU and ML-based upscaling options such as Real-ESRGAN and waifu2x.

------------------------------------------------------------
Planned Syntax
------------------------------------------------------------

video-tools upscale-video <input> <output.mp4> --scale 1920x1080

Optional parameters:
--scale <WxH>       Specify custom resolution
--filter <name>     Choose scaling filter (lanczos, bicubic, spline36, bilinear)
--hevc              Encode output with H.265 for reduced file size
--keep-audio        Copy the original audio stream without re-encoding

------------------------------------------------------------
Default Behavior
------------------------------------------------------------

When no scale or filter is provided, the tool will automatically upscale to the next common resolution above the source.

Examples:
Input: 960x540  → Output: 1280x720
Input: 1280x720 → Output: 1920x1080
Input: 1440x1080 → Output: 1920x1080

The tool will retain the same aspect ratio and avoid unnecessary stretching or cropping.

------------------------------------------------------------
Technical Notes
------------------------------------------------------------

Example FFmpeg usage:
ffmpeg -i input.mp4 -vf scale=1920:1080:flags=lanczos -c:v libx264 -crf 18 -preset slow -c:a aac -b:a 192k output_1080p.mp4

Explanation:
scale=1920:1080:flags=lanczos performs resampling using the Lanczos algorithm for sharp, high-quality results.
Lanczos minimizes aliasing and ringing while retaining edge detail.
Future implementations may use zscale for improved color management or GPU-accelerated scaling with CUDA or Vulkan.

------------------------------------------------------------
Planned Features
------------------------------------------------------------

FFmpeg scaler (lanczos)             Planned
zscale and bicubic scaling          Planned
ML-based upscaling (Real-ESRGAN)    Research stage
Auto-resolution detection           Planned
GPU acceleration support            Planned
Configurable quality presets        Planned
HEVC and AV1 encoder options        Planned
Batch folder upscaling mode         Planned

------------------------------------------------------------
Example Future Commands
------------------------------------------------------------

Upscale to 1080p using default settings:
video-tools upscale-video "movie.mp4" "movie_1080p.mp4"

Upscale to 4K using HEVC and Lanczos filter:
video-tools upscale-video "movie.mp4" "movie_4k.mp4" --scale 3840x2160 --hevc --filter lanczos

Copy original audio without re-encoding:
video-tools upscale-video "documentary.mp4" "documentary_upscaled.mp4" --keep-audio

------------------------------------------------------------
End of File