135 lines
4.6 KiB
Markdown
135 lines
4.6 KiB
Markdown
# 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
|