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

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.
- AAC audio ensures consistent playback on all major systems including Windows, macOS, Android, and iOS.

------------------------------------------------------------
Default Parameters
------------------------------------------------------------

Parameter: -c:v libx264
Purpose: H.264 video encoding (modern, efficient, hardware-accelerated)

Parameter: -crf 18
Purpose: Constant Rate Factor for near-lossless quality (lower = higher quality)

Parameter: -preset slow
Purpose: Improves compression efficiency at moderate CPU cost

Parameter: -c:a aac
Purpose: High-quality audio encoding compatible with most players

Parameter: -b:a 192k
Purpose: Balances clarity and file size

Parameter: -movflags +faststart
Purpose: Optimizes MP4 for streaming and faster playback start

Parameter: -fflags +genpts
Purpose: Rebuilds timestamps to prevent sync issues with older containers

------------------------------------------------------------
Profile Presets
------------------------------------------------------------

Default Profile:
CRF 18
Preset slow
Audio 192k
Balanced for visual clarity and efficient storage.

Hi-Rate Profile (--hi-rate):
CRF 14
Preset veryslow
Audio 320k
Maximum quality, slower encoding, ideal for archiving or high-bitrate content.

Portable Profile (--portable):
CRF 24
Preset faster
Audio 128k
Optimized for mobile devices and reduced file sizes.

Each profile automatically adjusts encoding parameters to ensure consistent results without user intervention.

------------------------------------------------------------
Quality vs. File Size
------------------------------------------------------------

The CRF (Constant Rate Factor) scale controls perceived quality versus compression level.

CRF 14–16: Near-lossless (archival or studio preservation)
CRF 18–20: High quality (default visual transparency)
CRF 21–24: Medium (smaller file size, minimal loss)
CRF 25+: Low quality (fast encoding, visible artifacts)

Default CRF: 18
Produces files roughly 40–60 percent smaller than original sources with minimal visible loss.

------------------------------------------------------------
Preset Choice
------------------------------------------------------------

Presets define encoding speed versus compression efficiency.
Range: ultrafast → veryslow

The preset "slow" was chosen because:
- Offers a strong balance between speed and compression.
- Output files are typically 10–20 percent smaller than those encoded at "medium".
- Encoding speed is roughly two to three times real-time on a midrange CPU.

------------------------------------------------------------
Audio Strategy
------------------------------------------------------------

AAC at 192k is used for:
- Transparent stereo audio for most content.
- Low CPU usage during encoding.
- Roughly two megabytes per minute of stereo content.

Future audio options include:
- -c:a copy to preserve original streams when re-encoding is unnecessary.
- -b:a 320k for studio-grade sound reproduction.
- FLAC or PCM support for lossless audio workflows.

------------------------------------------------------------
Color and Resolution
------------------------------------------------------------

No scaling or color adjustments occur unless explicitly requested.
Source resolution, frame rate, and color space (usually bt709) are preserved.

Future command "upscale-video" will support:
- FFmpeg scale and zscale filters.
- Lanczos resampling for high-quality upscales.
- Optional machine-learning upscalers such as Real-ESRGAN or waifu2x.

------------------------------------------------------------
Future Additions
------------------------------------------------------------

upscale-mode   Choose default scaling filter for upscaling tasks
hevc-mode      Switch to H.265 (libx265) for smaller, more efficient files
audio-pass     Skip audio re-encoding when not needed
config.json    User-editable configuration to override all defaults
auto-bitrate   Compute estimated average bitrate for legacy containers

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