# docs/Conversion_Settings.md
# Conversion Settings (v0.1.0)

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
```

**Why MP4?**
- Universally supported across modern devices.
- Balances quality, compression, and compatibility.
- H.264 encoding provides excellent visual quality at modest 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 at moderate CPU cost |
| `-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 the balance between quality and compression:

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

**Default CRF: 18**  
Provides visually lossless results while reducing most AVI/MPG files to **40–60% smaller sizes**.

---

## Why Use Preset “slow”

The preset defines the trade-off between encoding speed and compression efficiency.  
Range: `ultrafast` → `veryslow`.

- `slow` offers excellent compression without excessive CPU time.  
- Typical speed: ~2–3× real-time on a midrange CPU.  
- Output files are usually **10–20% smaller** than with `medium` preset at the same quality.

---

## Audio Strategy

**AAC at 192k** is chosen for:
- Broad device compatibility (phones, TVs, web players).  
- Transparent stereo sound for most content.  
- Efficient storage (~2 MB/min of stereo audio).

Future options may include:
- `-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 its original resolution and color profile.

Planned future command: `upscale-video`, supporting:
- FFmpeg’s `scale` and `zscale` filters.  
- `lanczos` resampling for sharp, clean upscales.  
- Optional ML upscaling (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