Feature: Video Wall Support (WALL_GENLOCKED, WALL_FAST_SWITCHED)

[switch180]

Problem

The integration currently does not support SDVoE Video Wall display modes, which are designed for multi-display configurations where a single video source is distributed across multiple synchronized displays (e.g., 2x2, 3x3 display grids).

Current State

Supported Display Modes:

• ✅ Genlock (GENLOCKED)
• ✅ Genlock Scaling (GENLOCK_SCALING)
• ✅ Fast Switch (FAST_SWITCHED)
• ✅ Fast Switch Stretch (FAST_SWITCHED_STRETCH)
• ✅ Fast Switch Crop (FAST_SWITCHED_CROP)

Missing Display Modes:

• ❌ Genlock Wall (WALL_GENLOCKED) - Zero-frame latency video wall
• ❌ Fast Switch Wall (WALL_FAST_SWITCHED) - Fast switch video wall

SDVoE API Video Wall Modes

According to the SDVoE API documentation, two video wall display modes are available:

1. WALL_GENLOCKED (Genlock Wall)

• Description: Zero-frame latency synchronized video wall mode
• Use Case: When ultra-low latency is critical across all displays
• Synchronization: Displays are genlocked for perfect sync
• Best For: Live events, control rooms, mission-critical applications

2. WALL_FAST_SWITCHED (Fast Switch Wall)

• Description: Fast switch video wall mode
• Use Case: When switching between sources quickly is needed
• Synchronization: Fast switching with multi-display support
• Best For: Presentation spaces, digital signage walls

Video Wall Configuration Parameters

Video wall modes require additional configuration parameters beyond standard display modes:

# From SDVoE API documentation
{
  "display_mode": "WALL_GENLOCKED",  # or "WALL_FAST_SWITCHED"
  "video": {
    "width": 1920,
    "height": 1080,
    "fps": 60,
    "horiz_offset": 0,      # Horizontal offset for this display
    "vert_offset": 1080,    # Vertical offset for this display
    "keep_width": 1920,     # Width of source region to display
    "keep_height": 1080     # Height of source region to display
  }
}

Configuration Parameters Explained:

• horiz_offset / vert_offset: Position of this display in the overall wall canvas
• keep_width / keep_height: Size of the source region to display on this screen
• Viewport settings: Define which portion of the source image this display shows

Example Video Wall Configurations

2x2 Video Wall (4 Displays)

Display Layout:
┌─────────┬─────────┐
│ Display │ Display │
│    1    │    2    │  Each: 1920x1080
├─────────┼─────────┤
│ Display │ Display │
│    3    │    4    │
└─────────┴─────────┘

Configuration per display:
Display 1: horiz_offset=0,    vert_offset=0
Display 2: horiz_offset=1920, vert_offset=0
Display 3: horiz_offset=0,    vert_offset=1080
Display 4: horiz_offset=1920, vert_offset=1080

3x3 Video Wall (9 Displays)

┌────┬────┬────┐
│ 1  │ 2  │ 3  │
├────┼────┼────┤
│ 4  │ 5  │ 6  │  Each: 1920x1080
├────┼────┼────┤
│ 7  │ 8  │ 9  │
└────┴────┴────┘

Total canvas: 5760x3240

Proposed Implementation

1. Add Video Wall Display Modes to Constants

File: custom_components/riverlink/const.py

# Add new display mode constants
DISPLAY_MODE_WALL_GENLOCK = "WALL_GENLOCKED"
DISPLAY_MODE_WALL_FAST_SWITCH = "WALL_FAST_SWITCHED"

# Update display modes list
DISPLAY_MODES = [
    DISPLAY_MODE_GENLOCK,
    DISPLAY_MODE_GENLOCK_SCALING,
    DISPLAY_MODE_FAST_SWITCH,
    DISPLAY_MODE_FAST_SWITCH_STRETCH,
    DISPLAY_MODE_FAST_SWITCH_CROP,
    DISPLAY_MODE_WALL_GENLOCK,          # NEW
    DISPLAY_MODE_WALL_FAST_SWITCH,      # NEW
]

2. Update API Client to Support Video Wall Parameters

File: custom_components/riverlink/api.py

async def async_set_video_mode(
    self,
    device_id: str,
    mode: str,
    width: int | None = None,
    height: int | None = None,
    fps: int | None = None,
    horiz_offset: int | None = None,     # NEW - for video wall
    vert_offset: int | None = None,      # NEW - for video wall
    keep_width: int | None = None,       # NEW - for video wall
    keep_height: int | None = None,      # NEW - for video wall
) -> dict[str, Any]:
    """Configure display mode with optional video wall parameters."""
    
    if mode in [DISPLAY_MODE_WALL_GENLOCK, DISPLAY_MODE_WALL_FAST_SWITCH]:
        # Video wall modes require all parameters
        if not all([width, height, fps, horiz_offset is not None, 
                    vert_offset is not None, keep_width, keep_height]):
            raise ValueError("Video wall modes require all position and size parameters")
        
        command = (
            f"set {device_id} video {mode} "
            f"size {width} {height} fps {fps} "
            f"horiz_offset {horiz_offset} vert_offset {vert_offset} "
            f"keep_width {keep_width} keep_height {keep_height}"
        )
    else:
        # Existing logic for non-wall modes
        ...

3. Add Video Wall Configuration UI

Options:

Option A: Extended Select Entity

• Add video wall parameters as entity attributes
• Require manual configuration through developer tools
• Simple but limited UX

Option B: Dedicated Video Wall Configuration

• New configuration flow for video wall setups
• Step-by-step wizard for multi-display configuration
• Better UX but more complex

Option C: Service Call Configuration

• Expose video wall setup via service calls
• Allow automation-based configuration
• Most flexible for advanced users

Use Cases

Control Room Video Wall

# 2x2 video wall showing surveillance feeds
# Displays synchronized with zero-frame latency
# Each display shows portion of 4K canvas

Digital Signage Wall

# 3x3 video wall in retail space
# Fast switch between content sources
# Bezel compensation for seamless image

Command Center

# Mixed configuration with some displays in wall mode
# Others showing independent content
# Critical for monitoring applications

Implementation Phases

Phase 1: Basic Support

• Add video wall display mode constants
• Update API client with video wall parameters
• Add video wall modes to display mode select
• Update coordinator parsing for video wall config
• Basic documentation

Phase 2: Enhanced UI

• Video wall configuration wizard
• Visual wall layout designer
• Bezel compensation calculator
• Preview/test functionality

Phase 3: Advanced Features

• Auto-configuration based on display arrangement
• Source-independent wall features
• Dynamic wall reconfiguration
• Save/load wall presets

Technical Considerations

Device Requirements:

• Devices must support AVP (Advanced Video Processing)
• Not all SDVoE devices support video wall modes
• Need capability detection in coordinator

Frame Buffer Node:

• Video wall config stored in FRAME_BUFFER node
• Includes viewport and offset parameters
• Must parse and expose in entity attributes

Testing Requirements:

• Requires hardware with video wall support
• Multiple displays for proper testing
• Coordination testing across displays

Benefits

• Professional Installations: Support enterprise video wall deployments
• Control Rooms: Critical for monitoring and command centers
• Digital Signage: Large-scale retail and public displays
• Complete Feature Set: Full SDVoE API capability coverage
• Competitive Advantage: Matches capability of commercial SDVoE controllers

Priority

🟡 Medium

Effort & Complexity

• Effort: High (multi-phase implementation)
• Complexity: High (requires hardware, complex configuration)
• Dependencies: Requires hardware with video wall support for testing

References

• SDVoE API Documentation: Section 2.5.2 Video Display Mode Argument
• SDVoE API Documentation: Section 4.9.4 Examples (WALL_GENLOCKED, WALL_FAST_SWITCHED)
• SDVoE API Documentation: Section 6.8.8 Frame Buffer Node
• Related Issue: #TBD (Hardcoded stream index)