Add brightness control to Key Colors targets with HAOS integration

Adds brightness (0.0-1.0) to KeyColorsSettings, applies scaling in the
KC processing pipeline after smoothing, exposes a slider on the WebUI
target card, and creates a HA number entity for KC target brightness.

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

server/src/wled_controller/api/routes/picture_targets.py

@@ -106,6 +106,7 @@ def _kc_settings_to_schema(settings: KeyColorsSettings) -> KeyColorsSettingsSche
         interpolation_mode=settings.interpolation_mode,
         smoothing=settings.smoothing,
         pattern_template_id=settings.pattern_template_id,
+        brightness=settings.brightness,
     )
 
 
@@ -116,6 +117,7 @@ def _kc_schema_to_settings(schema: KeyColorsSettingsSchema) -> KeyColorsSettings
         interpolation_mode=schema.interpolation_mode,
         smoothing=schema.smoothing,
         pattern_template_id=schema.pattern_template_id,
+        brightness=schema.brightness,
     )
 
 

server/src/wled_controller/api/schemas/picture_targets.py

@@ -52,6 +52,7 @@ class KeyColorsSettingsSchema(BaseModel):
     interpolation_mode: str = Field(default="average", description="Color mode (average, median, dominant)")
     smoothing: float = Field(default=0.3, description="Temporal smoothing (0.0-1.0)", ge=0.0, le=1.0)
     pattern_template_id: str = Field(default="", description="Pattern template ID for rectangle layout")
+    brightness: float = Field(default=1.0, description="Output brightness (0.0-1.0)", ge=0.0, le=1.0)
 
 
 class ExtractedColorResponse(BaseModel):

server/src/wled_controller/core/processing/kc_target_processor.py

@@ -34,7 +34,7 @@ KC_WORK_SIZE = (160, 90)  # (width, height) — small enough for fast color calc
 # CPU-bound frame processing (runs in thread pool via asyncio.to_thread)
 # ---------------------------------------------------------------------------
 
-def _process_kc_frame(capture, rect_names, rect_bounds, calc_fn, prev_colors_arr, smoothing):
+def _process_kc_frame(capture, rect_names, rect_bounds, calc_fn, prev_colors_arr, smoothing, brightness):
     """All CPU-bound work for one KC frame.
 
     Returns (colors, colors_arr, timing_ms) where:
@@ -59,7 +59,13 @@ def _process_kc_frame(capture, rect_names, rect_bounds, calc_fn, prev_colors_arr
     if prev_colors_arr is not None and smoothing > 0:
         colors_arr = colors_arr * (1 - smoothing) + prev_colors_arr * smoothing
 
-    colors_u8 = np.clip(colors_arr, 0, 255).astype(np.uint8)
+    # Apply brightness scaling
+    if brightness < 1.0:
+        output_arr = colors_arr * brightness
+    else:
+        output_arr = colors_arr
+
+    colors_u8 = np.clip(output_arr, 0, 255).astype(np.uint8)
     t2 = time.perf_counter()
 
     # Build output dict
@@ -256,6 +262,7 @@ class KCTargetProcessor(TargetProcessor):
 
         target_fps = settings.fps
         smoothing = settings.smoothing
+        brightness = settings.brightness
 
         # Select color calculation function
         calc_fns = {
@@ -328,7 +335,7 @@ class KCTargetProcessor(TargetProcessor):
                     colors, colors_arr, frame_timing = await asyncio.to_thread(
                         _process_kc_frame,
                         capture, rect_names, rect_bounds, calc_fn,
-                        prev_colors_arr, smoothing,
+                        prev_colors_arr, smoothing, brightness,
                     )
 
                     prev_colors_arr = colors_arr

server/src/wled_controller/static/js/app.js

@@ -58,6 +58,7 @@ import {
     createKCTargetCard, testKCTarget, toggleKCTestAutoRefresh,
     showKCEditor, closeKCEditorModal, forceCloseKCEditorModal, saveKCEditor,
     deleteKCTarget, disconnectAllKCWebSockets,
+    updateKCBrightnessLabel, saveKCBrightness,
 } from './features/kc-targets.js';
 import {
     createPatternTemplateCard,
@@ -210,6 +211,8 @@ Object.assign(window, {
     saveKCEditor,
     deleteKCTarget,
     disconnectAllKCWebSockets,
+    updateKCBrightnessLabel,
+    saveKCBrightness,
 
     // pattern-templates
     createPatternTemplateCard,

server/src/wled_controller/static/js/features/kc-targets.js

@@ -39,6 +39,8 @@ export function createKCTargetCard(target, sourceMap, patternTemplateMap) {
     const kcSettings = target.key_colors_settings || {};
 
     const isProcessing = state.processing || false;
+    const brightness = kcSettings.brightness ?? 1.0;
+    const brightnessInt = Math.round(brightness * 255);
 
     const source = sourceMap[target.picture_source_id];
     const sourceName = source ? source.name : (target.picture_source_id || 'No source');
@@ -74,11 +76,18 @@ export function createKCTargetCard(target, sourceMap, patternTemplateMap) {
                 <span class="stream-card-prop" title="${t('kc.pattern_template')}">📄 ${escapeHtml(patternName)}</span>
                 <span class="stream-card-prop">▭ ${rectCount} rect${rectCount !== 1 ? 's' : ''}</span>
             </div>
+            <div class="brightness-control" data-kc-brightness-wrap="${target.id}">
+                <input type="range" class="brightness-slider" min="0" max="255"
+                       value="${brightnessInt}" data-kc-brightness="${target.id}"
+                       oninput="updateKCBrightnessLabel('${target.id}', this.value)"
+                       onchange="saveKCBrightness('${target.id}', this.value)"
+                       title="${Math.round(brightness * 100)}%">
+            </div>
+            <div id="kc-swatches-${target.id}" class="kc-color-swatches">
+                ${swatchesHtml}
+            </div>
+            ${isProcessing ? `
             <div class="card-content">
-                <div id="kc-swatches-${target.id}" class="kc-color-swatches">
-                    ${swatchesHtml}
-                </div>
-                ${isProcessing ? `
                 <div class="metrics-grid">
                     <div class="metric">
                         <div class="metric-label">${t('device.metrics.actual_fps')}</div>
@@ -127,8 +136,8 @@ export function createKCTargetCard(target, sourceMap, patternTemplateMap) {
                     </div>
                 </div>
                 ` : ''}
-                ` : ''}
             </div>
+            ` : ''}
             <div class="card-actions">
                 ${isProcessing ? `
                     <button class="btn btn-icon btn-danger" onclick="stopTargetProcessing('${target.id}')" title="${t('targets.button.stop')}">
@@ -521,6 +530,26 @@ export async function deleteKCTarget(targetId) {
     }
 }
 
+// ===== KC BRIGHTNESS =====
+
+export function updateKCBrightnessLabel(targetId, value) {
+    const slider = document.querySelector(`[data-kc-brightness="${targetId}"]`);
+    if (slider) slider.title = Math.round(parseInt(value) / 255 * 100) + '%';
+}
+
+export async function saveKCBrightness(targetId, value) {
+    const brightness = parseInt(value) / 255;
+    try {
+        await fetch(`${API_BASE}/picture-targets/${targetId}`, {
+            method: 'PUT',
+            headers: getHeaders(),
+            body: JSON.stringify({ key_colors_settings: { brightness } }),
+        });
+    } catch (err) {
+        console.error('Failed to save KC brightness:', err);
+    }
+}
+
 // ===== KEY COLORS WEBSOCKET =====
 
 export function connectKCWebSocket(targetId) {

server/src/wled_controller/storage/key_colors_picture_target.py

@@ -45,6 +45,7 @@ class KeyColorsSettings:
     interpolation_mode: str = "average"
     smoothing: float = 0.3
     pattern_template_id: str = ""
+    brightness: float = 1.0
 
     def to_dict(self) -> dict:
         return {
@@ -52,6 +53,7 @@ class KeyColorsSettings:
             "interpolation_mode": self.interpolation_mode,
             "smoothing": self.smoothing,
             "pattern_template_id": self.pattern_template_id,
+            "brightness": self.brightness,
         }
 
     @classmethod
@@ -61,6 +63,7 @@ class KeyColorsSettings:
             interpolation_mode=data.get("interpolation_mode", "average"),
             smoothing=data.get("smoothing", 0.3),
             pattern_template_id=data.get("pattern_template_id", ""),
+            brightness=data.get("brightness", 1.0),
         )