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.
