DJ’s/VJ’s visualization customize

Full MIDI, HID & OSC Support

Real-Time MIDI Input via RtMidi: callback-driven capture with sub-millisecond latency and 327 ready-made presets

• MIDI: Note On/Off, Control Change and Pitch Bend per channel and control, dynamic device discovery, learn/test/save modes and a per-controller shift layer with red-highlight feedback
• HID & OSC: USB HID via hidapi (10ms polling) and network OSC via UDP listener — both normalized into the same mapping engine and action path as MIDI
• One action engine: every control can trigger visuals, styles, playlists, DMX scenes, layers, masks, schedule entries or config changes

HID Device Support

Native USB HID via hidapi: enumeration, 10ms polling, and button + axis decoding — from DJ hardware to gamepads and custom devices

• Decoding: reports become button/axis events normalized to the MIDI path, with dedicated Traktor S8 handling
• Presets: Generic HID plus Traktor, Pioneer CDJ, Hercules, EKS Otus, Sixaxis, Wiimote and a test device — all as XML mappings
• Learn, test and save: recording modes, hardware-free test injection and automatic conflict release

Custom XML Mapping System

Mixxx-compatible XML mappings: 166 presets plus 152 scripts ship in the app, and new files are auto-discovered

• Semantic entries: readable names with deck, description, channel, number and message type
• Typed actions & shift: any control fires app actions, and the shift button is read straight from the mapping
• Scripts & safe editing: optional JavaScript behaviour, protected critical controls and full learn/save round-trips

Rule-Based Shape Spawning

Non-random, semantically meaningful visual effects

• Each MIDI control type produces consistent visual feedback
• Deterministic shape selection based on channel/number combination
• Color theme assignment per control type

Control-to-Visual Mapping

• Play buttons → Energy/burst/flare shapes with Techno theme
• Cue buttons → Star/crystal/prism shapes with Electro theme
• Sync buttons → Rings/pulse/quantum shapes with Techno theme
• Pads → Plasma/nova/comet shapes with Techhouse theme

Control-to-Visual Mapping

Deterministic but varied feedback

• Jog wheels → Vortex/galaxy/spectrum shapes with Electro theme
• Volume faders → Waveform/beam/nebula shapes with Dark theme
• EQ controls → Hexagon/grid/cosmic shapes with Techhouse theme
• Unmapped controls → Orb/spiral/lightning shapes with Dark theme (fallback)

Shape Selection Algorithm

Deterministic but varied feedback

• Ensures same control always produces same shape type
• Different MIDI numbers cycle through available shapes
• Provides visual consistency while avoiding predictability

Pattern Matching Control Lookup

Intelligent control type detection

• Automatic pattern matching for control names (case-insensitive)
• Examples: “play”, “cue”, “sync”, “pad”, “jog”, “volume”, “eq”
• Fallback rules for unmapped MIDI patterns (channel/number based)
• Customizable rules for new control types

Visual Feedback

Shape spawning with theme-based colors

• Throttled spawning (80ms minimum interval) for performance
• Maximum 6 concurrent shapes on screen
• TTL-based shape lifecycle (300-1100ms duration)
• Automatic theme switching during spawn, restores after

Audio-Reactive Integration

MIDI messages trigger visual effects

• Shape size varies (90-120px) with random positioning
• Rotation applied (-40° to +40°) for visual interest
• Theme palette colors applied from 24 shape types
• Color themes: Techno, Techhouse, Electro, Dark

Debug Logging

Comprehensive MIDI processing visibility

• Detailed channel/number/velocity logging
• Rule application tracking (which rule was used)
• Mapped action confirmation (which control was detected)
• Shift state change confirmation
• Performance metrics (spawn rate, throttling statistics)

Multi-Section Interface

• Multi-Section Interface: Organized control panels (Styles, Layers, Auto Effects, Playlists, Artists, Audio Rules)
• Dynamic Visual Layer Control: Toggle backgrounds (Image, Avatar, Video), visualizers, lighting effects

Auto Effects Management

• Auto Effects Management: Audio-reactive effects with customizable thresholds and parameters
• Style Management System: Complete visual theme switching with preset configurations
• Artist Management Interface: Professional artist branding with logo display and selection

Playlist Control Center

• Playlist Control Center: Image, video, and avatar playlist management with live switching
• Audio Rules Engine: Complex automation rules with visual feedback and parameter adjustment
• Interactive Button System: Context-aware controls with hover states, active indicators, and real-time updates

Live Performance Tools

• Layer Management: Multi-layer visual composition
• Style Presets: Pre-configured visual themes and styles
• Transition Effects: Smooth transitions between content
• Animation System: Keyframe-based animation engine
• Touch Controls: Intuitive touch-based interface

Visual Themes & Customization

• Theme Engine: Complete visual theming system
• Color Schemes: Customizable color palettes
• Font Management: Typography customization
• Screen Scaling: Multi-monitor and scaling support

Integration Examples

Automatic Background Rotation:

• Search for theme (e.g., “electronic music concert”)
• Download top 10 images
• Rotate through during performance
• Metadata shows photographer credit

AI Logo Generation for Artists:

• Enter artist name and style preference
• Generate 3-5 logo variations with Gemini
• Automatic background removal
• Use in artist profiles and branding

Usage Analytics

• Comprehensive Auditing: Detailed usage tracking and analytics
• Performance Metrics: System performance monitoring
• Event Logging: Complete event history and reporting
• Distributor Management: Multi-level distribution tracking

License Management

• Activation System: Secure software activation
• License Validation: Real-time license verification
• Usage Monitoring: Detailed usage analytics
• Distributor Portal: Web-based distributor management

Configuration Server

• HTTP Config Server: built-in REST + WebSocket server (httpconfigserver.*, default port 8080) with token auth, request-id echo and uniform response envelopes
• Realtime delivery: WebSocket event broadcast (HTTP port + 1) with long-poll subscription (GET /config/subscribe) as fallback, so remote UIs stay in sync either way
• Resilient client: automatic server discovery across candidate addresses (dead interfaces skipped) plus a reconnect timer when the link drops

HTTP API

REST API: versioned /api/v1 contract (openapi-api-v1.yaml) with response envelopes and a revision counter — legacy endpoints kept working, full reference in “Complete REST Interface” below

• Config, layers, styles, artists, playlists and marquee management
• Local media plus Pixabay/Pexels stock search and download
• DMX, timecode, scheduling, screen recording and realtime events

Configuration Management API

• GET /config: Retrieve complete system configuration with all parameters
• POST /config: Update configuration (full or partial) with automatic merging
  • Supports partial updates without overwriting unchanged values
  • Automatic configuration persistence
• GET /config/subscribe: Real-time configuration change notifications via long polling
  • Long-polling mechanism for real-time updates
  • Only modified fields returned to optimize bandwidth
• Change Tracking: Only modified fields returned to optimize bandwidth

Image Management API

• GET /images/list: Retrieve all available images from current playlist
  • Returns JSON array with metadata (filename, size, modification date)
  • Reads from configuration’s currentImageFile playlist
• GET /images/download/{filename}: Download specific image file
  • Smart format support: JPG, PNG, BMP, GIF (including animated), SVG (vector graphics)
  • Metadata: File size, modification date, MIME type detection
  • Security: Path traversal protection, filename validation, safe path resolution

Video Management API

• GET /videos/list: Retrieve all available videos from current playlist
  • Returns complete video metadata for streaming preparation
  • Reads from configuration’s currentVideoFile playlist
• GET /videos/download/{filename}: Stream video files
  • Multi-format support: MP4, WebM, AVI, MOV, MKV, FLV
  • HTTP streaming for large video files without full preload
  • Metadata: Complete file information and timestamps

MCP Server

• MCP server in the app (mcpserver.*, main_mcp.cpp, config_mcp.json): STDIO plus HTTP (127.0.0.1:8800) transports proxying the local HTTP API, token auth, localhost CORS, and per-request logging of tool name and arguments
• Same contract as the API: responses carry the monotonic revision counter so agents detect config changes cheaply; get_capabilities lists styles up front; errors use stable structured codes; patches report only changed fields
• Tool coverage: full remote control of config, layers, styles, artists, playlists, media, DMX, timecode and scheduling
• Show automation for agents: program schedule entries and timecode cues, fire any action on demand, start/stop/list/download MP4 screen recordings, and manage NDI output — all remotely, covered by the automated API/MCP integration test suite

Configuration-Aware Path Resolution

• Dynamic Paths: All endpoints respect documentsPath from config.json
• Fallback Strategy: Automatic fallback to standard Documents directory
• Flexible Organization: Support for subdirectories and custom locations
• Path Structure: Automatic organization into /Visuals/Images, /Visuals/Videos, /Visuals/Avatars
• Service-Based Architecture: Dedicated ImageService, VideoService, and AvatarService classes
  • Single responsibility principle with clean separation of concerns
  • Independent configuration and error handling
  • Reusable across multiple HTTP endpoints

Media Playlist System

• Text-Based Playlists: Simple .txt files listing resources
  • Comment support: Lines starting with # are treated as comments
  • Flexible paths: Relative or absolute path support within resource directories
  • Empty line handling: Automatic filtering of empty lines
• Playlist Management: Central configuration integration
  • Reads from visualization.currentImageFile, visualization.currentVideoFile, visualization.currentAvatarFile
  • Automatic path resolution with sensible defaults
  • Support for absolute and relative paths within Documents folder

Advanced Control Interface

• Section-Based Navigation: Tabbed interface for organized control access
• Dynamic Button Grid: Auto-sizing grid with scrollable content for extensive controls
• Real-Time Visual Feedback: Active state indicators, hover effects, and flashing animations
• Nested Property Management: Complex parameter hierarchy with automatic value resolution
• Audio Rule Visualization: Live flashing indicators for triggered audio events
• Multi-Type Parameter Control: Boolean toggles, numeric sliders, decimal adjustments, and selection controls
• Touch-Optimized Interface: Responsive design with scalable elements and touch-friendly controls

Multi-Monitor Support & NDI Output

• Separate Windows: independent main and separate windows, with settingsWindow, mainMaximized and separateMaximized options in config.json plus command-line override
• Full-Screen Display: immersive full-screen visualization on any display
• Window Management: flexible window positioning and sizing across monitors
• NDI Output: the live window is streamed as an NDI source (ndioutputsender.*) with configurable source name, frame rate (default 15 fps) and scale (default 0.75), including connected-receiver tracking
• NDI Bridge: standalone bridge (main_ndibridge.cpp, ndi_config/) with JSON output definitions — named outputs, rotation, 1920×1080 crop — and presets for 3/5 screens, circle/triangle masks and panoramic orchestra setups, manageable via the NDI config API/MCP tools

Hardware Integration & Timecode Sync

• Audio Device Support: selectable capture devices and sample rates (44100, 48000, 22050, 96000, 88200, 32000), plus a dedicated audio input for LTC timecode that runs independently from music analysis
• MIDI Controllers: industry-standard hardware via RtMidi with 327 mapping presets in controllers/, plus a dedicated MIDI input reserved for MTC timecode, separate from DJ controller mapping
• HID Devices: hidapi support with 10ms polling and presets for Traktor Kontrol, Pioneer CDJ, Hercules and generic custom hardware
• Timecode Sync (MTC/LTC): 5 source modes — Off, MTC, LTC, Auto, Manual (timecodeprovider.*); MTC from lighting desks or Ableton Live, LTC/SMPTE from a dedicated audio channel with channel selection and signal-confidence readout; forward/backward detection with drop-frame and fps readout
• Manual Clock & Timecode Cues: internal controllable clock (play/pause, locate, jump, frame rate) and cue list that fires any scheduler action — style, playlist, DMX scene, layer — when the incoming position crosses a chosen HH:MM:SS:FF mark, configurable from the Timecode panel, the API and MCP

Performance Optimization

• GPU Acceleration: Hardware-accelerated rendering
• FFT Analysis: Fast Fourier Transform for real-time analysis
  • 2048-point FFT (46ms window at 44.1kHz) via kiss_fft on Windows/Linux and vDSP on macOS (audioanalyzer.h: FFT_SIZE = 2048)
  • 21.5 Hz frequency resolution at 44.1kHz sample rate
  • Real-time processing without perceptible lag

Efficient resource utilization

• Memory Management: Efficient resource utilization
• Threading: Multi-threaded processing for smooth performance
  • Audio processing on dedicated thread
  • UI updates on main thread
  • Background task processing for API calls
• Optimization Profiles: Multiple optimization levels for different hardware