Automatic Gain Control

Automatic Gain Control operator properties for Script Engine. Measures the average brightness inside a chosen sensor area and either reports the change or automatically nudges the image back towards a stored reference brightness. Useful for stabilising exposure on cameras that hunt or drift, keeping a key on a presenter consistent when the lighting changes, holding a target luminance on signage or ambient feeds, or flagging when a feed has dropped/spiked in level. Set the sensor area, store a reference luminance, then optionally enable autocorrect.

Property	Type	Access	Description
`UseFullScreen`	`bool`	`get/set`	When on, brightness is measured across the entire image; when off, the crop region defines the sensor area. On is the right choice when overall scene brightness matters. Off is better when only a specific area should drive the gain — e.g. the presenter's face but not the screen behind them. Turning this on locks the crop sliders.
`CropLeft`	`int`	`get/set`	Pixels to skip from the left edge before sampling. [min=0, max=4096, default=0]. 0 starts the sensor area at the very left edge. Increase to exclude an area on the left (e.g. a fixed graphic). Only active when `UseFullScreen` is off.
`CropRight`	`int`	`get/set`	Pixels to skip from the right edge before sampling. [min=0, max=4096, default=0]. 0 ends the sensor area at the very right edge. Increase to exclude an area on the right. Only active when `UseFullScreen` is off.
`CropTop`	`int`	`get/set`	Pixels to skip from the top edge before sampling. [min=0, max=4096, default=0]. 0 starts the sensor area at the very top edge. Increase to exclude an area at the top (e.g. a banner or scoreboard). Only active when `UseFullScreen` is off.
`CropBottom`	`int`	`get/set`	Pixels to skip from the bottom edge before sampling. [min=0, max=4096, default=0]. 0 ends the sensor area at the very bottom edge. Increase to exclude an area at the bottom (e.g. a lower-third or ticker). Only active when `UseFullScreen` is off.
`ShowCropArea`	`bool`	`get/set`	When on, overlays the configured sensor rectangle on the output for visual setup; off for normal operation. Use this while positioning the crop sliders to confirm the sensor area is on the right part of the image. Turn it off before going on-air — autocorrect is disabled while the overlay is visible.
`LuminanceString`	`string`	`get`	Current average brightness inside the sensor area, formatted as a percentage (read-only).
`LuminanceChangeString`	`string`	`get`	Difference between the current measured luminance and the stored reference, as a percentage (read-only). 0 means the brightness is at or near the stored reference. Negative values mean the scene is darker than the reference; positive values mean it is brighter.
`LuminanceChanged`	`bool`	`get`	True when the measured luminance differs from the stored reference (read-only). Useful as a trigger for scripts that should react to exposure drifts — e.g. logging an alert or activating a backup feed. Becomes false again when the values match.
`LuminanceAutoCorrect`	`bool`	`get/set`	When on, automatically nudges image brightness to match the stored reference luminance. Off by default — turn on once a stored reference is set and the sensor area is positioned. Has no effect while `ShowCropArea` is on. Useful for keeping a feed visually consistent when the source slowly drifts in exposure.
`StoreLuminanceCommand`	`Command`	`get`	Capture the current measured luminance and store it as the reference for autocorrect. Run when the scene looks correctly exposed; the stored value becomes the target that autocorrect will pull the image back towards. Re-run after changing the sensor area.
`StoredLuminanceString`	`string`	`get/set`	The reference luminance value captured by Store luminance, formatted as a percentage (read-only).
`PixelCount`	`int`	`get`	Number of pixels included in the most recent measurement (read-only, debug).
`LuminanceSum`	`int`	`get`	Sum of the luminance values across all sampled pixels in the most recent measurement (read-only, debug).

Inherits from: AbstractOperator, AbstractAudioMetering.

See also: Automatic Gain Control in Operators — user-facing introduction, screenshots, and section summaries.