mirror of
https://github.com/vondas-network/videobeaux.git
synced 2025-12-05 15:30:02 +01:00
94 lines
3.5 KiB
Plaintext
94 lines
3.5 KiB
Plaintext
HDR → SDR Tone Map (videobeaux program)
|
||
======================================
|
||
|
||
Name
|
||
----
|
||
tonemap_hdr_sdr — Convert HDR (PQ/HLG) video to SDR (BT.709) using
|
||
ffmpeg `zscale` + `tonemap` with Hable (default), Mobius, Reinhard, or Clip.
|
||
|
||
What it does
|
||
------------
|
||
• Linearizes HDR content with zscale using a specified nominal peak (nits).
|
||
• Applies an SDR-target tonemap operator (default: Hable) with optional highlight desaturation.
|
||
• Converts color primaries/transfer/matrix to BT.709 and tags the stream accordingly.
|
||
• Outputs in a user-specified pixel format (default yuv420p).
|
||
• Re-encodes video (libx264 by default); audio can be copied with --copy-audio.
|
||
|
||
When to use
|
||
-----------
|
||
Use this when you have HDR10/HLG masters that need a faithful SDR deliverable
|
||
for web or broadcast players that don’t support HDR.
|
||
|
||
Invocation pattern
|
||
------------------
|
||
videobeaux -P tonemap_hdr_sdr -i <input> --outfile <output> [options]
|
||
|
||
Arguments
|
||
---------
|
||
--outfile <path>
|
||
Output file path for the SDR result. Use this instead of the global -o.
|
||
|
||
--algo {hable,mobius,reinhard,clip}
|
||
The tonemap curve/operator. Defaults to "hable".
|
||
• hable: Filmic curve with pleasing roll-off; great default.
|
||
• mobius: Preserves mid-tones; gentle shoulder.
|
||
• reinhard: Classic operator; can feel flatter.
|
||
• clip: Hard clip (avoid unless you need an absolute ceiling).
|
||
|
||
--desat <float 0.0–1.0>
|
||
Highlight desaturation applied during tonemapping. Default: 0.0.
|
||
Try 0.15–0.35 for very hot HDR sources to avoid neon colors in speculars.
|
||
|
||
--peak <nits>
|
||
Nominal peak luminance (nits) passed to zscale:npl for linearization.
|
||
Default: 1000. Use 4000 for HDR masters graded to 4000 nits.
|
||
|
||
--dither {none,ordered,random,error_diffusion}
|
||
Dithering strategy in zscale before format(). Default: error_diffusion.
|
||
|
||
--pix-fmt <ffmpeg pixel format>
|
||
Output pixel format. Common: yuv420p (default), yuv422p10le, yuv420p10le.
|
||
|
||
--x264-preset <string>
|
||
libx264 preset if encoding H.264. Default: medium. Examples: slow, fast.
|
||
|
||
--crf <number>
|
||
CRF value for libx264 quality. Default: 18 (visually lossless-ish).
|
||
|
||
--copy-audio
|
||
If set, copies audio bit-for-bit. Otherwise audio is encoded as AAC.
|
||
|
||
Standard/global flags respected (from videobeaux)
|
||
------------------------------------------------
|
||
--force Overwrite output if it exists (injects -y into ffmpeg).
|
||
|
||
Color tagging
|
||
-------------
|
||
The program writes BT.709 tags on the output:
|
||
-colorspace bt709 -color_trc bt709 -color_primaries bt709
|
||
|
||
Practical guidance
|
||
------------------
|
||
• Start with: --algo hable --peak 1000 --desat 0.2
|
||
• If midtones feel too flat, try --algo mobius.
|
||
• If highlights look too neon, increase --desat to ~0.25–0.35.
|
||
• For mezzanine masters, use 10-bit: --pix-fmt yuv422p10le and lower CRF.
|
||
|
||
Performance notes
|
||
-----------------
|
||
• zscale + tonemap is GPU-agnostic and runs on CPU; performance depends on your CPU.
|
||
• For speed, you can try a faster x264 preset (e.g., --x264-preset fast) or target ProRes.
|
||
|
||
Troubleshooting
|
||
---------------
|
||
• “Washed out” SDR: confirm your player isn’t forcing HDR or BT.2020. The output is
|
||
explicitly tagged BT.709.
|
||
• Crushed highlights: your source peak was higher than expected; try --peak 4000 or switch
|
||
operator to mobius.
|
||
• Banding: use 10-bit pix-fmt (e.g., yuv420p10le) and keep --dither error_diffusion.
|
||
|
||
Changelog
|
||
---------
|
||
v1.0.1 — Switched to program-scoped --outfile (no use of global -o).
|
||
v1.0.0 — Initial release (Hable default, Mobius/Reinhard/Clip options, desat, peak, dither, pix-fmt, CRF, copy-audio).
|