mirror of
https://github.com/vondas-network/videobeaux.git
synced 2026-01-23 07:11:08 +01:00
94 lines
3.8 KiB
Plaintext
94 lines
3.8 KiB
Plaintext
videobeaux — gamma_fix
|
||
========================
|
||
|
||
Purpose
|
||
-------
|
||
Normalize overall exposure for web/broadcast delivery by sampling video luma
|
||
(YAVG) with a fast prepass, computing gentle contrast/brightness (and optional
|
||
gamma), then encoding the adjusted video. Optionally clamp output to
|
||
broadcast-legal (TV/limited) range.
|
||
|
||
How It Works
|
||
------------
|
||
1) Probe pass: ffmpeg + signalstats collects per-frame YAVG values (0..255).
|
||
2) Robust center: we take the median YAVG to avoid bright/dark spikes.
|
||
3) Mapping:
|
||
- Choose contrast ~= target/current (clamped to a friendly range).
|
||
- Solve brightness so the current median maps near the desired target.
|
||
- Optional gamma curve if you request it.
|
||
4) Optional “legalize” remaps to TV range and outputs yuv420p for broad
|
||
compatibility.
|
||
|
||
Basic Invocation
|
||
----------------
|
||
videobeaux -P gamma_fix -i INPUT -o OUTPUT [options]
|
||
|
||
Where -P selects the program, and -i/-o/--force and similar are provided by
|
||
videobeaux’s CLI front-end.
|
||
|
||
Inputs / Outputs
|
||
----------------
|
||
- Input: Any ffmpeg-readable video file.
|
||
- Output: Encoded video with exposure normalization applied.
|
||
- Audio: Encoded using --acodec/--ab (defaults aac/160k).
|
||
|
||
Key Options (program-specific)
|
||
------------------------------
|
||
--target-yavg FLOAT Target average luma, 0..255 (default: 64.0)
|
||
~64 is a balanced midpoint for web. Try 60–70 for
|
||
darker looks, 70–90 for brighter looks.
|
||
|
||
--min-contrast FLOAT Lower clamp for the auto contrast (default: 0.80)
|
||
--max-contrast FLOAT Upper clamp for the auto contrast (default: 1.35)
|
||
|
||
--gamma FLOAT Optional gamma adjustment (default: 1.00 = neutral).
|
||
Leave at 1.00 to rely purely on contrast/brightness.
|
||
|
||
--sat FLOAT Saturation multiplier via hue filter (default: 1.00).
|
||
Example: 1.10 = +10% saturation.
|
||
|
||
--legalize Clamp output to broadcast-legal (TV/limited) range,
|
||
then convert to yuv420p for delivery safety.
|
||
|
||
--vcodec STR Video codec (default: libx264)
|
||
--crf STR Quality factor for x264/x265 (default: 18)
|
||
--preset STR Encoder preset (default: medium)
|
||
--acodec STR Audio codec (default: aac)
|
||
--ab STR Audio bitrate (default: 160k)
|
||
|
||
Notes on Global Options (provided by videobeaux CLI)
|
||
----------------------------------------------------
|
||
-i PATH Input file path
|
||
-o PATH Output file path
|
||
--force Overwrite output if it exists
|
||
|
||
Quality / Performance Tips
|
||
--------------------------
|
||
- Start with --target-yavg 64 (neutral) and tweak by ±5–10 for taste.
|
||
- Keep contrast clamps near defaults for natural results; widening them can
|
||
push highlights/shadows into clipping on contrasty scenes.
|
||
- --legalize is recommended for broadcast or when downstream platforms expect
|
||
limited (TV) range. For purely web, it’s optional but safe.
|
||
- A small --sat like 1.05–1.12 often livens washed-out sources without
|
||
overshooting.
|
||
- If your footage is very dark or very bright across the entire piece, adjust
|
||
--target-yavg rather than forcing aggressive contrast.
|
||
|
||
Edge Cases
|
||
----------
|
||
- Extremely low dynamic range (flat/cast) may require manual grading beyond
|
||
this auto-normalizer.
|
||
- Heavily stylized content (crushed blacks, hard clipping) can benefit from a
|
||
lower --max-contrast and modest --sat.
|
||
- If probing fails (rare), the module defaults to a neutral pass (contrast=1,
|
||
brightness=0).
|
||
|
||
Examples
|
||
--------
|
||
See the separate “gamma_fix_EXAMPLES.txt” file for ready-to-run commands.
|
||
|
||
Versioning
|
||
----------
|
||
Keep this program additive to your baseline. Do not remove other features in
|
||
videobeaux; this module is designed as a drop-in program callable via -P.
|