[FEATURE] output filter to prevent seizure; Temporal Flash Limiting

[westurner]

Please confirm the following points:

• This feature request is NOT for the Android apps in the Play Store
• I have searched the project page to check if a similar request was already made

Application or Project

I don't know / Multiple / Other (please elaborate below)

Is Your Enhancement Related to a Problem?

Flashing lights may cause epileptic seizures. To try to prevent seizures, add a visual output filter ((also) with zero guarantee o promoting the feature).

Your Suggested Enhancement

What hertz or other patterns would need to be filtered to prevent causing epileptic seizures with a music visualization?

How would you add this safety feature to projectm?

According to Gemini 3 (an AI LLM model) FWIW:

---

Title: Feature Request: Photosensitivity Safety Filter (Epilepsy Protection)

Is your feature request related to a problem? Please describe.

Music visualizations, by nature, often contain rapid strobing, high-contrast flashing, and geometric patterns that can trigger Photosensitive Epilepsy (PSE).

Currently, projectM renders presets exactly as written by the community. Since many presets rely on rapid tan(time) oscillations or frame-inverting strobes, the software creates a high risk for users with seizure disorders. There is currently no "gatekeeper" in the rendering pipeline to ensure output remains within safe physiological limits (e.g., WCAG or Harding FPA standards).

Describe the solution you'd like

I propose implementing a Global Post-Processing Safety Shader.

Instead of editing thousands of .milk files, we should add a final render pass that intercepts the image before it hits the screen. This pass acts as a "Limiter" or "Compressor," but for luminance and flash frequency rather than audio volume.

Safety Criteria to Enforce:

1. Frequency Cap: Strictly limit full-screen luminance changes to < 3 Hz (3 flashes per second).
2. Chromatic Damping: Detect and dampen high-saturation Red (660–720 nm) transitions, which are statistically more dangerous.
3. Slew Rate Limiting: Force rapid black-to-white transitions to fade over several frames rather than toggling instantly.

Technical Implementation

We can achieve this by adding a safety_pass.frag shader in the post-processing pipeline. This requires retaining the Previous Frame texture to compare against the Current Frame.

1. The Shader Logic (GLSL Prototype)

This shader calculates the difference in luminance between the current frame and the last frame. If the difference exceeds a safe delta (calculated based on FPS to ensure <3Hz modulation), it clamps the pixel's brightness.

// safety_pass.frag
#version 330 core
uniform sampler2D u_CurrentFrame;  // Output from projectM
uniform sampler2D u_HistoryFrame;  // Output shown to user last frame
uniform float u_SafeDelta;         // Max allowed brightness change per frame

in vec2 v_TexCoord;
out vec4 FragColor;

float getLuma(vec3 color) {
    return dot(color, vec3(0.299, 0.587, 0.114));
}

void main() {
    vec4 current = texture(u_CurrentFrame, v_TexCoord);
    vec4 previous = texture(u_HistoryFrame, v_TexCoord);

    // 1. Red Dampener (Desaturate dangerous red flashes)
    if (current.r > 0.8 && current.g < 0.2 && current.b < 0.2) {
        current.rgb = mix(current.rgb, vec3(current.r * 0.5), 0.5); 
    }

    // 2. Temporal Luminance Limiter
    float lumaCur = getLuma(current.rgb);
    float lumaPrev = getLuma(previous.rgb);
    float diff = lumaCur - lumaPrev;

    // If change is too fast (Strobe detected)
    if (abs(diff) > u_SafeDelta) {
        // Clamp to maximum safe step
        float targetLuma = lumaPrev + sign(diff) * u_SafeDelta;
        
        // Apply scaling to RGB to maintain color, just darker/lighter
        float scale = targetLuma / (lumaCur + 0.0001); 
        current.rgb *= scale;
    }

    FragColor = current;
}

2. C++ Integration Strategy

In ProjectM::renderFrame (or equivalent render loop):

• 1. Render Preset: Render the visualization to an internal FBO as normal.
• 2. Calculate Delta: Determine u_SafeDelta dynamically based on current FPS.
     Formula: 1.0 / (CurrentFPS / 3.0)
• 3. Apply Safety Pass: Bind the Safety Shader. Pass the current FBO and the History FBO as textures.
• 4. Swap: Render result to screen and copy result to History FBO for the next frame.

Alternative Consideration: Preset Pruning

If a shader implementation is too resource-intensive for specific embedded targets, a secondary solution would be a Python script included in the tools directory that parses .milk files to detect and delete presets containing high-frequency triggers (e.g., searching for high-frequency sin/tan waves on monitor or ob_r variables).

---

Adding this feature might allow projectM to be used with less risk by users with photosensitive epilepsy, significantly increasing the accessibility of the project (and hopefully preventing injury and increasing enjoyment)

Alternative Solutions

Preset pruning

• Some way to cap how epileptic presets can be #742

Additional Context

I do not and cannot warrant any of this for fitness for purpose; I offer this (initial ai 'slop') in hopes of reducing probability of photoepileptic seizure.

[westurner]

Re: a way to heuristically identify presets that could cause seizure;

From the same chat: https://gemini.google.com/share/3dd44456cc3a ; CC0:

Write a script to do Preset Pruning to prevent seizures due to photosensitive epilepsy

---

# prune_presets.py
import os
import re
import shutil
import argparse

# --- CONFIGURATION ---

# The variables in MilkDrop that control global brightness/flashes
# ob = outer border, ib = inner border, mv = motion vectors, warp = feedback
TARGET_VARS = [
    r'ob_r', r'ob_g', r'ob_b',  # Outer Border (often used for full screen flashes)
    r'ib_r', r'ib_g', r'ib_b',  # Inner Border
    r'mv_r', r'mv_g', r'mv_b',  # Motion Vectors (background color often)
    r'wave_r', r'wave_g', r'wave_b' # Wave color
]

# Patterns that indicate high-frequency or strobing logic
# 1. High Frequency: sin/cos with time multiplied by a large number (>10)
#    Matches: sin(time*20), cos(time * 50.5)
FREQ_PATTERN = re.compile(r'(sin|cos|tan)\s*\(\s*time\s*\*\s*([0-9]+(?:\.[0-9]+)?)')

# 2. Inverter Strobe: toggling a value (e.g., ob_r = 1 - ob_r)
#    This creates a 0 -> 1 -> 0 hard strobe every frame
INVERT_PATTERN = re.compile(r'=\s*1\s*-\s*([a-z_]+[rgb])')

# 3. Modulo Strobe: Using modulo on frame number (e.g., frame % 2)
#    This creates specific Hz flickering based on framerate
MOD_PATTERN = re.compile(r'(frame|time)\s*%\s*([0-9]+)')

# 4. Tangent flashing: tan() goes to infinity, often causing white flashes
TAN_PATTERN = re.compile(r'tan\s*\(')

def is_dangerous(file_content):
    """
    Analyzes the content of a .milk file for seizure triggers.
    Returns: (bool, reason_string)
    """
    # We generally only care about the 'per_frame' block, 
    # but scanning the whole file is safer and simpler for this script.
    
    # Check 1: Inverter Strobe (The "Hard" Strobe)
    # logic: if a color variable is set to 1 - itself
    inverter_matches = INVERT_PATTERN.findall(file_content)
    for var in inverter_matches:
        if any(target in var for target in TARGET_VARS):
            return True, f"Inverter Strobe detected on {var}"

    # Check 2: High Frequency Oscillation
    # logic: look for sin(time * X). If X > 18 (approx 3Hz at various frame rates), flag it.
    # Note: 3Hz is the safety floor, but in math sin(t*N), N is rads/sec.
    # 3Hz = 3 * 2pi ~= 18.8 rads/sec.
    freq_matches = FREQ_PATTERN.findall(file_content)
    for func, multiplier in freq_matches:
        try:
            val = float(multiplier)
            if val > 18.0:
                return True, f"High Frequency Oscillation ({func} * {val})"
        except ValueError:
            continue

    # Check 3: Frame Modulo (Frame skipping strobes)
    # logic: if (frame % 2) is used, it's a 30Hz strobe at 60fps. Very dangerous.
    mod_matches = MOD_PATTERN.findall(file_content)
    for var, mod_val in mod_matches:
        if int(mod_val) < 4: # %2 or %3 implies very rapid flickering
            return True, f"Low-interval Frame Modulo ({var} % {mod_val})"

    return False, None

def scan_and_prune(directory, dry_run=False):
    quarantine_dir = os.path.join(directory, "quarantine_photosensitive")
    
    if not dry_run and not os.path.exists(quarantine_dir):
        os.makedirs(quarantine_dir)

    files = [f for f in os.listdir(directory) if f.endswith('.milk')]
    print(f"Scanning {len(files)} presets in {directory}...\n")

    moved_count = 0
    
    for filename in files:
        filepath = os.path.join(directory, filename)
        
        try:
            with open(filepath, 'r', encoding='utf-8', errors='ignore') as f:
                content = f.read()
            
            dangerous, reason = is_dangerous(content)
            
            if dangerous:
                print(f"[FLAGGED] {filename}")
                print(f"    Reason: {reason}")
                
                if not dry_run:
                    dest = os.path.join(quarantine_dir, filename)
                    shutil.move(filepath, dest)
                    print("    -> Moved to quarantine.")
                
                moved_count += 1
                
        except Exception as e:
            print(f"Error reading {filename}: {e}")

    print("-" * 30)
    print(f"Scan complete.")
    if dry_run:
        print(f"Found {moved_count} dangerous presets (Dry Run - no files moved).")
    else:
        print(f"Moved {moved_count} dangerous presets to '{quarantine_dir}'.")

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="Prune epilepsy-inducing projectM presets.")
    parser.add_argument("directory", help="Path to the folder containing .milk files")
    parser.add_argument("--dry-run", action="store_true", help="Scan without moving files")
    
    args = parser.parse_args()
    
    if os.path.isdir(args.directory):
        scan_and_prune(args.directory, args.dry_run)
    else:
        print("Invalid directory path provided.")

How to use this script

1. Save the code above as prune_presets.py.
2. Run it from your terminal, pointing it at your preset folder:

# Dry run first (just lists dangerous files without moving them)
python prune_presets.py "/path/to/projectm/presets" --dry-run

# Actual run (moves dangerous files to a 'quarantine_photosensitive' subfolder)
python prune_presets.py "/path/to/projectm/presets"

Explanation of Detection Logic

The script looks for three specific coding patterns commonly used in "aggressive" MilkDrop presets:

1. High-Frequency Math (sin(time * 50)):

   • In trigonometry, sin(time) oscillates slowly. sin(time * X) speeds it up.

   • The script flags any multiplier > 18.0. This corresponds roughly to 3 Hz (since $3 Hz\times 2\pi \approx 18.8$ ). Anything faster than this is moving into the danger zone for photosensitive epilepsy.

2. Inverter Strobes (ob_r = 1 - ob_r):

   • This code causes a value to flip between 0 and 1 every single frame. At 60FPS, this creates a 30Hz hard strobe, which is essentially the worst-case scenario for inducing seizures.

3. Frame Modulo (frame % 2):

   • Coders use this to make things flash on alternate frames. This creates high-contrast flicker that is extremely visually taxing.

---

Though #742 is closed - also, in addition to just filtering all composited output - what else would heuristically predict risk from a .milk preset file?

[westurner]

4. Tangent flashing: tan() goes to infinity, often causing white flashes
   TAN_PATTERN = re.compile(r'tan\s*\(')

This needs more work. What a neat problem; detecting trends toward infinity by static analysis

[kblaschke]

Yeah, it's actually a really hard problem to solve, as just looking at individual pixel values or the overall screen color not always give a good sense of how irritating an image is. For example, try cycling through red, green and blue in quick succession, which would give a super flashy image with only a small difference in overall brightness (if you multiply each color with its susceptive luminance) or none at all if you simply sum up the channels and calculate an average.

[revmischa]

Related to #742 which has extensive discussion on this topic. The Python script for preset pruning and the shader-based approach are both interesting additions to that discussion.