Configure Photosensitivity Threshold in FFmpeg

The FFmpeg photosensitivity filter detects and mitigates harmful light flashes and strobing effects that can trigger seizures in photosensitive viewers. This article covers how to configure the light flashing threshold using the filter's parameters, explains the available configuration options, and provides working command-line examples to adjust flash suppression according to your needs.

Understanding the Threshold Parameter

The filter uses the threshold (or t) option to determine how aggressively it identifies and suppresses rapid luminance changes across frames.

  • Default Value: 1.0
  • Lower Values (e.g., 0.5 to 0.8): Increases sensitivity. The filter flags smaller or less intense brightness fluctuations as flashes, applying flash-reduction algorithms more frequently.
  • Higher Values (e.g., 1.2 to 2.0): Decreases sensitivity. The filter allows stronger brightness shifts before classifying them as flashes, preventing unnecessary smoothing in normal high-contrast scenes.

Basic Syntax

To set the threshold, add the photosensitivity filter to your video filtergraph (-vf) and define the threshold value.

ffmpeg -i input.mp4 -vf "photosensitivity=threshold=0.8" -c:a copy output.mp4

You can also use the shorthand parameter t:

ffmpeg -i input.mp4 -vf "photosensitivity=t=0.8" -c:a copy output.mp4

Combining Threshold with Frame History

The threshold calculation relies on a rolling window of past frames specified by the frames (or f) parameter, which defaults to 30. Adjusting the frame count alongside the threshold gives finer control over long-duration strobing versus quick, single-frame spikes.

ffmpeg -i input.mp4 -vf "photosensitivity=frames=24:threshold=0.7" -c:a copy output.mp4

Performance Optimization: Pixel Skipping

For high-resolution video (such as 4K), computing frame-by-frame luminance can slow down processing. You can adjust the skip (or s) parameter, which defines how many pixels to jump during grid evaluation, to speed up encoding while testing threshold settings:

ffmpeg -i input.mp4 -vf "photosensitivity=t=0.6:s=2" -c:a copy output.mp4

Testing Threshold Levels with Bypass Mode

To see detection statistics without modifying the video stream, set bypass=1. This logs the frame-level luminance variations to the console, allowing you to evaluate whether your chosen threshold effectively catches flashes before writing the final video:

ffmpeg -i input.mp4 -vf "photosensitivity=t=0.8:bypass=1" -f null -