# Conversion Settings

This file documents the default FFmpeg parameters used in `video-tools.sh` and explains why they are chosen.

---

## Output Format
All conversions produce:
```
Format: MP4
Container: MPEG-4 Part 14
Video Codec: H.264 (libx264)
Audio Codec: AAC
```

MP4 was chosen because:
- It’s universally supported across modern devices.
- It balances size and compatibility well.
- H.264 encoding provides excellent quality at smaller bitrates.

---

## Default Parameters

| Parameter | Value | Purpose |
|------------|--------|----------|
| `-c:v libx264` | H.264 video encoding | Modern, efficient codec with wide hardware support |
| `-crf 18` | Constant Rate Factor | Maintains near-lossless visual quality; lower = better |
| `-preset slow` | Encoding preset | Improves compression efficiency; trades some speed |
| `-c:a aac` | Audio codec | Standard high-quality stereo audio |
| `-b:a 192k` | Audio bitrate | Balances fidelity and file size |
| `-movflags +faststart` | MP4 optimization | Enables faster playback start in players or web streams |
| `-fflags +genpts` | Timestamp repair | Regenerates timestamps on older AVI/MPEG inputs |

---

## Quality vs. File Size

The CRF scale (used by FFmpeg) defines quality and compression balance:

| CRF | Description | Typical Use |
|------|-------------|--------------|
| 14–16 | Near lossless | Archival or professional mastering |
| 18–20 | High quality | Everyday use, visually lossless |
| 21–24 | Medium quality | Small file sizes, light compression |
| 25+ | Low quality | Fast compression, heavy size reduction |

The default of **CRF 18** keeps visual clarity virtually identical to the original while cutting most AVI or MPG files to **40–60% smaller** sizes.

---

## Why Preset "slow"

The preset defines encoding effort vs. compression efficiency.  
Options range from `ultrafast` → `veryslow`.

- **slow** provides strong compression without extreme CPU time.
- Encoding speed is roughly 2–3× real-time on a midrange CPU.
- File sizes are typically 10–20% smaller than `medium` preset at the same quality.

---

## Audio Strategy

AAC at 192k is chosen for:
- Wide playback compatibility (phones, TVs, players).
- Transparent stereo sound for most sources.
- Reasonable storage size (~2MB/minute of stereo audio).

If future needs arise, the tool can later support:
- `-c:a copy` for untouched audio streams.
- `-b:a 320k` for high-fidelity preservation.

---

## Color Space & Scaling

No scaling is applied by default.  
The video retains original resolution and color profile.

Upscaling and filtering will be handled in a separate command (`upscale-video`) in future versions, with support for:
- FFmpeg’s `scale` and `zscale` filters.
- `lanczos` resampling (for sharp, clean upscale).
- Optional integration with ML-based models (Real-ESRGAN, waifu2x).

---

## Future Additions

| Planned Setting | Description |
|------------------|-------------|
| `upscale-mode` | Default scaling filter for upscaling tasks |
| `hevc-mode` | Switch to H.265 (libx265) for smaller files |
| `audio-pass` | Option to skip audio re-encoding |
| `config.json` | User-editable file to override default values |

---

End of File