# docs/Upscale.md
# Upscale Module (Planned) — v0.1.0

The `upscale-video` command will provide loss-minimized video upscaling.

---

## Overview

This module will allow upscaling of existing videos to higher resolutions such as:
- 720p (HD)
- 1080p (Full HD)
- 2160p (4K)

It will begin with FFmpeg’s native scaling filters and may later support machine learning-based methods.

---

## Planned Syntax

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

Optional parameters:
```
--scale <WxH>     Set explicit resolution
--filter <name>   Choose scaling filter (lanczos, bicubic, spline36)
--hevc            Encode using H.265 for smaller output
--keep-audio      Copy original audio stream without re-encoding
```

---

## Default Behavior

If no explicit resolution is provided, the tool will upscale intelligently to the nearest standard resolution above the source.

**Examples:**
- Input: 960×540 → Output: 1280×720  
- Input: 1280×720 → Output: 1920×1080

---

## Technical Notes

### FFmpeg Filter Example

```bash
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 high-quality resampling.  
- `lanczos` produces sharp, low-artifact results.  
- Future versions may introduce `zscale` or machine-learning upscalers.

---

## Planned Features

| Feature | Status |
|----------|--------|
| FFmpeg scaler (`lanczos`) | 🔜 Planned |
| ML-based upscaling (Real-ESRGAN / waifu2x) | 🚧 Research |
| Auto-resolution detection | 🔜 Planned |
| GPU acceleration support | 🔜 Planned |
| Configurable presets | 🔜 Planned |

---

End of File