# /// script
# requires-python = ">=3.10"
# dependencies = ["numpy"]
# ///
"""
@effect brightness
@version 1.0.0
@author artdag

@description
Adjusts the brightness of each frame by multiplying pixel values.
Values > 1.0 brighten, < 1.0 darken. Useful for pulse effects synced to music.

@param factor float
  @range 0 3
  @default 1.0
  Brightness multiplier. 0 = black, 1 = unchanged, 2 = double brightness.
  Bind to bass/energy for reactive brightness pulses.

@example
  (effect brightness :factor 1.5)

@example
  ;; Pulse brighter on bass hits
  (effect brightness :factor (bind bass :range [1.0 2.0] :transform sqrt))
"""

import numpy as np


def process_frame(frame: np.ndarray, params: dict, state: dict) -> tuple:
    """
    Adjust brightness of a video frame.

    Args:
        frame: Input frame as numpy array (H, W, 3) RGB uint8
        params: Effect parameters
            - factor: brightness multiplier (default 1.0)
        state: Persistent state dict (unused)

    Returns:
        Tuple of (processed_frame, new_state)
    """
    factor = params.get("factor", 1.0)

    if factor == 1.0:
        return frame, state

    # Apply brightness multiplier with clipping
    result = np.clip(frame.astype(np.float32) * factor, 0, 255).astype(np.uint8)

    return result, state