winhdrshot

Windows HDR / SDR desktop screenshot library. Captures desktop frames via DXGI Desktop Duplication, normalizes them to linear scRGB, then encodes to PQ HDR AVIF.

Features

• DXGI Desktop Duplication (IDXGIOutput5::DuplicateOutput1) capture, direct D3D11 texture readback
• Three desktop formats supported:
  • R16G16B16A16_FLOAT (HDR scRGB, 16-bit float linear)
  • R10G10B10A2_UNORM (HDR10 / Auto HDR, 10:10:10:2 packed)
  • B8G8R8A8_UNORM (SDR 8-bit)
• Unified to linear scRGB float32 (H, W, 3)
• scRGB → PQ (SMPTE ST 2084) → 10-bit AVIF, with CICP metadata (BT.709 primaries + PQ transfer)

Install

pip install winhdrshot

Usage

from winhdrshot import HDRScreenCapture, encode_scrgb_frame_to_avif, list_monitors

print(list_monitors())

with HDRScreenCapture(monitor_index=0) as cap:
    scrgb = cap.grab_frame()                       # scRGB float32 (H, W, 3), HDR or SDR
    avif_bytes = encode_scrgb_frame_to_avif(scrgb) # HDR AVIF bytes
    open("out.avif", "wb").write(avif_bytes)

Dependencies

• comtypes — COM interface calls
• d3dshot — comtypes declarations for DXGI / D3D11 interfaces
• imagecodecs — AVIF encoding (libavif), supports CICP metadata
• numpy

Limitations

• Windows only (DXGI Desktop Duplication API)
• Requires a D3D11.0+ device
• R10G10B10A2 (HDR10) format clips HDR highlights to 1.0 — this is the inherent ceiling of 10-bit UNORM, not a bug; for the full HDR dynamic range the desktop must be in R16G16B16A16_FLOAT mode
• AVIF is lossy (lossless mode unavailable), so some color deviation is expected
• Color space: desktop duplication yields scRGB (BT.709 primaries + linear + (1,1,1)=80 nits), not BT.2020

License

AGPL-3.0-or-later