Initial commit: video effects processing system

Add S-expression based video effects pipeline with modular effect
definitions, constructs, and recipe files.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

effects/saturation.py

@@ -0,0 +1,61 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["numpy", "opencv-python"]
+# ///
+"""
+@effect saturation
+@version 1.0.0
+@author artdag
+
+@description
+Adjusts color saturation. 0 = grayscale, 1 = original, 2 = oversaturated.
+Uses HSV color space for accurate saturation control.
+
+@param factor float
+  @range 0 3
+  @default 1.0
+  Saturation multiplier. 0 = grayscale, 1 = unchanged, 2 = double saturation.
+
+@example
+  (effect saturation :factor 0)  ; grayscale
+
+@example
+  (effect saturation :factor 1.5)  ; vibrant colors
+
+@example
+  ;; Desaturate on quiet parts, saturate on loud
+  (effect saturation :factor (bind energy :range [0.5 2.0]))
+"""
+
+import numpy as np
+import cv2
+
+
+def process_frame(frame: np.ndarray, params: dict, state: dict) -> tuple:
+    """
+    Adjust saturation of a video frame.
+
+    Args:
+        frame: Input frame as numpy array (H, W, 3) RGB uint8
+        params: Effect parameters
+            - factor: saturation 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
+
+    # Convert RGB to HSV
+    hsv = cv2.cvtColor(frame, cv2.COLOR_RGB2HSV).astype(np.float32)
+
+    # Scale saturation channel (index 1)
+    hsv[:, :, 1] = np.clip(hsv[:, :, 1] * factor, 0, 255)
+
+    # Convert back to RGB
+    result = cv2.cvtColor(hsv.astype(np.uint8), cv2.COLOR_HSV2RGB)
+
+    return result, state