4.6 KiB
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