slPhantomRemote – Devialet Speaker Controller Technical Specification
This describes what the code should do.
Product Version: 1.0.0.813 RC
Build Version: 813
Specification: 2507
Target Framework: .NET 8.0 Windows Forms
Compatibility: Windows 10/11 with .NET 8.0 Runtime
Last Updated: 8/11/2025
slPhantomRemote is a WinForms application for discovering, connecting to, and controlling Devialet speakers using the Devialet IP Control API. The application provides device discovery via mDNS, playback control, source management, audio features, and logging capabilities.
Overview & Goals
This application provides:
- Automatic mDNS discovery of Devialet speakers with multiple service type scanning
- Manual device entry for devices not discoverable via mDNS
- Namespace-aware control supporting Devices, Systems, and Groups API endpoints
- Real-time source enumeration and switching with visual status indicators
- Comprehensive playback control including play/pause and precise volume control
- Advanced audio features including Night Mode, experimental equalizer, and Stream Sensing (not implemented)
- Persistent configuration with device favorites, window positioning, and external change detection
- Advanced logging system with dedicated log window and verbose debugging
- Real-time status monitoring with automatic device state polling
- Unicode-based UI icons for optimal cross-platform display compatibility
- Accessibility features including keyboard navigation, screen reader support, and high-contrast compatibility
- Comprehensive command line interface for automation, scripting, and quick operations without GUI
Built for .NET 8.0 (WinForms), the application minimizes external dependencies while providing a user experience with audio control capabilities.
Dependencies
- .NET 8.0 (Windows Forms) - Latest LTS framework
- Newtonsoft.Json (13.0.3) - JSON serialization for API communication and configuration persistence
- Zeroconf (3.7.16) - Cross-platform mDNS discovery library for network device detection
- System.Net.Http - For API communication with Devialet devices
- System.IO.FileSystem.Watcher - For monitoring configuration file changes
- Microsoft.Extensions.Logging.Abstractions - For structured logging support
The application is designed with minimal external dependencies, ensuring a small installation footprint and reduced security surface area.
Architecture & Design Patterns
Namespace Architecture
The application supports three Devialet API namespaces with intelligent fallback and automatic detection:
Namespace |
Endpoint Pattern |
Use Case |
Default |
Devices |
/ipcontrol/v1/devices/current/ |
Individual speaker control |
No |
Systems |
/ipcontrol/v1/systems/current/ |
Stereo pairs, multi-device setups |
Yes |
Groups |
/ipcontrol/v1/groups/current/ |
Zone control, logical groupings |
No |
Users can switch between namespaces via a dropdown in the control interface, with the selection persisted in configuration and automatic namespace detection based on device capabilities.
UI State Management
The application implements a dual-mode interface pattern with smooth transitions:
Discovery View: Device list with mDNS discovery, favorites management with star icons, hidden device support, and manual entry with IP validation
Control View: Comprehensive device control interface with real-time status, Unicode-based playback controls, advanced audio features, and source management with color coding
Detached Log Window: Real-time verbose logging with configurable positioning, auto-scroll with pause capability, and persistent window state
Configuration Management
All settings are persisted to config.json
with advanced features:
{
"DeviceNames": {
"192.168.0.30": "Arch-e86b",
"192.168.0.31": "Gold Phantom-Left"
},
"FavoriteDevices": ["192.168.0.31"],
"HiddenDevices": ["192.168.0.11", "192.168.0.30"],
"DeviceSettings": {},
"DeviceInfoCache": {
"192.168.0.31": {
"DeviceId": "e6e97c6f-0ac8-5a35-b68d-52f70cef57af",
"SystemId": "256b186f-76bc-5ca2-ab74-076795765bc7",
"GroupId": "9131a5fd-0afc-40b0-bb5c-3032377d1d11",
"Model": "Phantom I Gold",
"Serial": "N07P000734U10",
"FirmwareVersion": "2.18.3",
"LastUpdated": "2025-07-26T20:12:12.7228997-07:00"
}
},
"SourceFriendlyNames": {
"1972effc-5b53-42c7-9d1f-ce67a1635bcf": "Arch"
},
"HiddenSources": [
"c08fe6f4-4524-403b-ba12-f57c6660f797"
],
"SourceIdentifiers": {},
"PreferredNamespace": 2,
"PollingIntervalSeconds": 20,
"ConnectionTimeoutSeconds": 3,
"MainWindow": {
"Left": -329,
"Top": -837,
"Width": 512,
"Height": 383
},
"LogWindow": {
"Left": 282,
"Top": -992,
"Width": 1119,
"Height": 593
},
// "EqualizerWindow": { // Feature removed
"Left": 0,
"Top": 0,
"Width": 0,
"Height": 0
},
"MinimumLogLevel": 0,
"MaxLogFileSizeMB": 10,
"MaxLogFileAgeDays": 7,
"Theme": 0,
"UseCustomColors": false,
"CustomLightColors": {
"BackgroundColor": "White",
"ForegroundColor": "Black",
"PanelColor": "WhiteSmoke",
"AccentColor": "0, 120, 212",
"AccentLightColor": "16, 110, 190",
"AccentDarkColor": "0, 90, 158",
"MutedColor": "138, 138, 138",
"ErrorColor": "209, 52, 56",
"SuccessColor": "16, 124, 16",
"WarningColor": "255, 185, 0",
"LinkColor": "0, 120, 212"
},
"CustomDarkColors": {
"BackgroundColor": "White",
"ForegroundColor": "Black",
"PanelColor": "WhiteSmoke",
"AccentColor": "0, 120, 212",
"AccentLightColor": "16, 110, 190",
"AccentDarkColor": "0, 90, 158",
"MutedColor": "138, 138, 138",
"ErrorColor": "209, 52, 56",
"SuccessColor": "16, 124, 16",
"WarningColor": "255, 185, 0",
"LinkColor": "0, 120, 212"
},
"EnableAutoSave": true,
"AutoSaveIntervalSeconds": 30
}
Design Patterns
Key Design Patterns Used:
- Observer Pattern - For real-time updates between components (LoggingService events, DeviceStatus changes)
- Strategy Pattern - For flexible API namespace handling and dynamic endpoint generation
- Factory Pattern - For creating appropriate device controllers based on device type and capabilities
- Singleton Pattern - For global services like LoggingService and ConfigManager
- Repository Pattern - For abstracting configuration storage and retrieval
- Command Pattern - For implementing UI actions and keyboard shortcuts
- Decorator Pattern - For adding functionality to base HTTP client with logging and retry capabilities
High-Level Workflow
Startup: Program.Main
→ DeviceForm
initialization → Configuration loading with validation → UI setup with Unicode icons
Discovery:
- Multi-service mDNS scanning (4 service types:
_devialet._tcp.local.
, _phantom._tcp.local.
, _http._tcp.local.
, _airplay._tcp.local.
)
- Intelligent device filtering with Devialet-specific keywords
- Manual device entry fallback with IP validation if no devices found
- Device list population with star favorites indication and hidden device filtering
- Automatic duplicate prevention across service types
Connection:
- Single-click selects device (enables context menu)
- Double-click initiates connection process with visual feedback
- Connectivity testing with 3-second timeout
- Namespace-aware controller initialization with automatic detection
- Device state loading and smooth transitions
- Real-time polling initialization with user-configurable intervals
Control Interface:
- Real-time device status polling (20-second intervals, user-controllable)
- Source enumeration with visual type indicators and color coding
- Live playback and volume control with 200ms throttling to prevent API spam
- Namespace switching with automatic reconnection and state preservation
- Advanced audio features integration (Night Mode, Experimental Equalizer, Stream Sensing - not implemented)
Source Management:
- Inline source selection via ListView with double-click activation
- Color-coded source types (Spotify: Green, Bluetooth: Blue, AirPlay: Yellow, Optical: Pink)
- Active source highlighting with gold background and bold text
- Advanced source management form with hide/show and renaming capabilities
- Unicode symbols for visibility status (✓ Visible / ✗ Hidden)
- No legacy dialogs - modern inline UI for streamlined user experience
Logging & Debugging:
- Comprehensive verbose logging to detached window with structured format
- Real-time status updates in main window status bar with auto-reset timer
- Persistent log window positioning with automatic bounds restoration
- Performance timing and operation tracking with millisecond precision
- Configuration change tracking with recent changes queue
- External file monitoring with reload notifications
- Log file rotation with configurable retention policy
- Log export capabilities for troubleshooting
Shutdown & Cleanup:
- Graceful disconnection from active devices with state preservation
- Final configuration save with integrity verification
- Resource cleanup including network connections and file handles
- Persistent window state storage for next launch
- Temporary file cleanup and log rotation
Application Structure
slPhantomRemote is built as a .NET 8.0 Windows Forms application with the following key components:
- Windows Forms UI - Main interface with device discovery, playback controls, and settings
- Command Line Interface - Headless automation and scripting support
- Devialet API Integration - HTTP client for Phantom speaker control
- Device Discovery - mDNS/Zeroconf network scanning
- Configuration Management - JSON-based settings with auto-save
- Theme System - Light/dark mode support
- Icon Resources - 35+ embedded icons for UI elements
- Documentation - Comprehensive user guides and technical specs
The application follows a layered architecture with separate concerns for UI, business logic, and data access.
6. Core Components
Discovery Panel Features:
- Device ListView with Unicode star favorites (⭐) and right-click context menu
- Single-click selection for context menu access, double-click for immediate connection
- Star icon click area (first 28 pixels) for favorite toggling with visual feedback
- Rich context menu: Test Connection, Connect to Device, Manage Sources, Toggle Favorite, Rename Device, Hide Device, Remove Device
- Empty area right-click: Show Hidden Devices, Add Manual Device, Discover Devices
- Unicode discovery icon (🔍) with tooltip and click handler
- Hidden device count display in status messages
- Last seen timestamp display for each device
- Connection quality indicator with signal strength visualization
- Device grouping by network segment with collapsible sections
Control Panel Features:
- Device information with real-time status and namespace indicator
- Track metadata display with title and artist extraction
- Prominently placed Experimental Equalizer icon (🎛️) with highlighted background for easy discovery
- Unicode-based playback controls (▶ Play, ⏸ Pause, ⏮ Previous, ⏭ Next)
- Volume slider with device synchronization and 200ms throttling
- Unicode volume controls (🔉 Down, 🔊 Up) with API integration
- Unicode mute button (🔊) with visual state indication
- Unicode Night Mode button (🌙) with visual state feedback
- Namespace selection dropdown with live switching capability
- Inline source enumeration ListView with color-coded types and gold highlighting for active source
- Experimental equalizer access
- Unicode Stream Sensing indicator (🎵) with mode display positioned next to EQ icon
- Album artwork display when available from streaming sources
- Source grouping by type with collapsible categories
- Connection health monitor with real-time latency display
- Speaker battery level indicator for portable Devialet models
Status & Navigation:
- Status bar with real-time operation feedback and auto-reset timer (2-second display)
- Quick access icons: Config file opener, Discovery trigger, Polling pause/resume, Back to discovery, Log window launcher
- Dynamic icon positioning with automatic layout on window resize
- Visual polling status indicator with play/pause states
- Icon tooltips with context-sensitive information
- Progress indicators for long-running operations
- Connectivity status with signal strength visualization
- Preferences access with system integration options
- Help section with keyboard shortcut reference
System Tray Integration:
- Hamburger menu (☰) consolidates all advanced options including "Minimize to System Tray"
- System tray icon appears only when minimized to tray, maintaining clean system tray
- Double-click tray icon to restore application window
- Rich tray context menu with:
- Restore (bold, default action) - brings app back to foreground
- Mute - toggles mute on/off when connected to device
- Volume Up/Down - adjusts volume in 10% increments with balloon notifications
- Exit - completely closes the application
- Dynamic tray tooltip showing connection status and playback state
- Playback controls automatically enable/disable based on device connection
- Balloon notifications for minimize action and volume adjustments
- Preserves window close (X) behavior - closes app completely (no auto-minimize to tray)
- Tray icon properly disposed on application exit to prevent orphaned icons
DevialetController (API Client)
Core Capabilities:
- Multi-namespace support with automatic endpoint generation and intelligent fallback
- Connectivity testing with 3-second timeout and exponential backoff retry logic
- Alternative endpoint fallback for API compatibility across DOS versions
- Comprehensive logging of all HTTP operations with millisecond timing precision
- Thread-safe operations with proper async/await patterns and cancellation support
- Volume throttling with 200ms delay to prevent API spam per Devialet specifications
- Automatic namespace detection by testing source availability across endpoints
- Advanced audio feature support (Experimental Equalizer, Night Mode, Stream Sensing - not implemented)
- API version detection with compatibility adaptation
- Resilient connection handling with automatic recovery
- Device capability discovery and feature adaptation
Discovery Service
Multi-service mDNS scanning:
_devialet._tcp.local.
- Official Devialet service discovery ✅
_phantom._tcp.local.
- Phantom-specific service discovery ✅
_http._tcp.local.
- Generic HTTP services with filtering ✅
_airplay._tcp.local.
- AirPlay-enabled devices with Devialet detection ✅
Note: The following services are not currently implemented: _raop._tcp.local.
(Remote Audio Output Protocol) and _spotify-connect._tcp.local.
(Spotify Connect enabled devices). Device filtering uses keyword detection for "devialet", "phantom", or "r1" in display names.
Configuration System
Advanced Persistence Features:
- Automatic persistence of all user preferences to JSON with atomic writes
- Window state management for log window positioning with bounds validation
- Device naming with friendly name override and input validation
- Source visibility management with hide/show capabilities and bulk operations
- Device visibility management with hidden device tracking and restoration
- Namespace preference with session persistence and validation
- External file change detection with FileSystemWatcher and conflict resolution
- Auto-save timer with 30-second intervals and dirty state tracking
UI Component Summary
UI Components (7 Total):
- DeviceForm.cs - Main dual-mode application window with discovery and control interfaces, source list with refresh button, volume/playback controls
- DeviceManagementForm.cs - Device management interface showing full GUIDs (Device ID, System ID, Group ID) with tooltips, device info caching
- LogForm.cs - Detached logging window with structured properties display, auto-scroll, pause capabilities, and persistent positioning
- EqualizerForm.cs - Experimental equalizer interface with preset support (requires Systems namespace)
- SourcesManagementForm.cs - Source visibility and naming management with hide/show capabilities
- NetworkDiagnosticsForm.cs - Network troubleshooting with connectivity tests
- InputBox.cs - Universal input dialog for text entry (device names, IP addresses) with validation
Service Components (8 Total):
- DevialetController.cs - HTTP API client with namespace support, logging, string array source parsing
- HttpClientService.cs - Static HttpClient factory to prevent socket exhaustion, per-device client instances
- LoggingService.cs - Centralized logging with structured properties, event system, file rotation
- ConfigManager.cs - JSON configuration persistence with FileSystemWatcher, external change detection
- DeviceDiscoveryService.cs - mDNS discovery with multiple service types, Devialet device filtering
- ThemeManager.cs - Light/dark theme management
- SourceColorHelper.cs - Maps source types to colors for visual identification
- IDeviceApiService.cs - Interface defining device API contract
Enhanced Audio Features
Night Mode (Dynamic Range Compression):
- Toggle button in device control interface using Unicode moon icon (🌙)
- Available on Systems namespace endpoints
- Real-time toggle with visual state feedback
Equalizer System (Experimental):
- Experimental equalizer interface accessible via button in control view
- Only available on Systems namespace (API limitation)
- Automatic fallback to Systems endpoint for other namespaces
- Preset support as provided by Devialet API
Stream Sensing (Not Implemented):
- Stream Sensing endpoints not available in current Devialet API
- Methods return null/no-op in current implementation
- Button visible in UI but functionality not available
API Integration Details
7.1 Supported Endpoints
Base URL Pattern: http://{device_ip}:80/ipcontrol/v1/{namespace}/current/
Device Information & Status:
GET /sources # List all available sources
GET /sources/current # Get current source state & metadata
GET /sources/current/soundControl/volume # Get current volume (0-100)
GET /devices/current # Get device information and capabilities
Playback Control:
POST /sources/current/playback/play # Start playback
POST /sources/current/playback/pause # Pause playback
POST /sources/current/playback/next # Next track
POST /sources/current/playback/previous # Previous track
POST /sources/current/playback/mute # Mute audio
POST /sources/current/playback/unmute # Unmute audio
Post /groups/current/sources/current/playback/position # The position within the current track
Volume Control:
POST /sources/current/soundControl/volume # Set volume {"volume": 0-100}
POST /sources/current/soundControl/volumeUp # Increment volume
POST /sources/current/soundControl/volumeDown # Decrement volume
POST /bluetooth/startAdvertising # Start Bluetooth Advertising
Source Control:
GET /groups/current/sources # get a list of sources
GET /groups/current/sources/current # get the current playback state info
POST/sources/{sourceId}/playback/play # Switch source with auto-play
Advanced Audio Features:
GET /equalizer # Get current equalizer settings
POST /equalizer # Set equalizer settings
GET /audio/nightMode # Get Night Mode status
POST /audio/nightMode # Set Night Mode {"enabled": true/false}
GET /audio/streamSensing # Get Stream Sensing data
POST /audio/streamSensing/mode # Set Stream Sensing mode
GET /audio/presets # Get available audio presets
POST /audio/presets/current # Set current preset
System Control:
POST /powerOff # Power off
POST /restart # reboot
POST /resetToFactorySettings # Reset to factory settings
GET baseurl # Get device | system | group information
EQ Endpoint Info
GET, POST, /systems/{systemId}/settings/audio/equalizer
Query or set equalizer gains/preset for the designated system.
Minimal version:
- DOS >= 2.16
Parameters / fields:
{ enabled:
, (GET only)
preset:
,
currentEqualization: (GET only)
{
BAND_LABEL:
{ frequency:
(optional), gain:
}, ...
},
customEqualization: (optional for POST)
{
BAND_LABEL:
{ gain:
}, ... },
gainRange: (GET only)
{ min:
, max:
, stepPrecision:
},
availablePresets: (GET only)
[
, ...
]
}
enabled indicates if the equalizer is active. It can become inactive in certain special audio processing modes of the product. When it is inactive, the client application may manipulate all the settings as usual, but there will be no audible impact. However, for better user experience, it is usually recommended to disable equalizer controls in this case. This field is read-only (the equalizer can not be re-enabled via this endpoint).
preset is the selection of one of the available presets. Possible values are "flat", "custom", and "voice". currentEqualization provides gains and other information for all bands for the currently used equalizer preset.
Different systems may have different BAND_LABEL values. BAND_LABEL examples include: "low", "high". currentEqualization.frequency provides a user-facing “central frequency” (it actually may be rounded) for the given band, in hertz. This value may be absent.
currentEqualization.gain provides a positive or negative gain for the given band, in steps (may be fractional). customEqualization provides gains and other information for all bands for the "custom" equalizer preset.
The BAND_LABEL values are the same as in currentEqualization above. customEqualization.gain provides a positive or negative gain for the given band, in steps (may be fractional). For POST requests, it will be rounded to the nearest authorized value by the device (in this case, the value read back by the client application may be slightly different).
If the value is out of authorized bounds, "InvalidValue" error code is reported. Although these gains only have an effect when the "custom" preset is selected, it is possible to change their values at any time. The stored custom gain values can be modified independently from the preset. I.e., one can modify custom gain values while using a different (non-"custom") preset.
Also, modifying just a preset does not trigger any changes to the stored custom gain values. The gains may be provided either simultaneously for all or for some bands (in which case the device guarantees to apply the new settings for all provided bands at the same moment) or one by one.
Both preset and customEqualization are present in the response. However, customEqualization can be omitted in the POST request, in which case the values of the gains corresponding to the "custom" preset will not be modified.
If provided equalizer parameters already correspond to the current state, the call will succeed. gainRange.min provides the minimal authorized value for the gain when using the "custom" preset, in steps. It applies to all bands. gainRange.max provides the maximal authorized value for the gain when using the"custom" preset, in steps. It applies to all bands.
gainRange.stepPrecision provides the step precision, in arbitrary units. This value determines how the gain rounding operates: the gain values are rounded to the nearest positive or negative multiple of the step precision. This value can be used by the client application to adapt the UI so as to match the device gain precision as closely as possible. Typical values are 0.1, 0.25, 0.5, and 1.
availablePresets provides a full list of available equalizer presets on the designated system.
For POST requests, if the system leader is absent, the "SystemLeaderAbsent" error code is reported.
GET example:
{
"preset": "flat", "currentEqualization":
{ "low":
{
"frequency": 400,
"gain": 0
}, "high":
{
"frequency": 2000,
"gain": 0
}
},
"customEqualization":
{ "low":
{
"gain": -0.5
}, "high":
{
"gain": 2.25
}
}, "gainRange":
{
"min": -6,
"max": 6,
"stepPrecision": 1
}, "availablePresets":
[
"flat",
"custom",
"voice"
]
}
POST example 1:
{ "preset": "custom", "customEqualization":
{ "low":
{
"gain": 3.0
}, "high":
{
"gain": 3.0
}
}
}
POST example 2:
{
"preset": "flat"
}
User Interaction Patterns
Device List Interactions
Action |
Trigger |
Result |
Visual Feedback |
Select Device |
Single-click |
Device selected, context menu enabled |
Highlight in list, status update |
Connect to Device |
Double-click or Context Menu → Connect |
Switch to control mode, initiate connection |
Mode change, "Connecting..." status, UI transition |
Toggle Favorite |
Click star icon (first 28px) or Context Menu |
Add/remove from favorites |
Star filled/empty (⭐/☆), status message |
Device Management |
Right-click device |
Show context menu |
Context menu with 8 management options |
Hidden Device Management |
Right-click empty area |
Show empty area menu |
Context menu with 3 discovery options |
Discovery Trigger |
Click discovery icon (🔍) |
Start network device discovery |
"Discovering..." status, icon feedback |
Network Diagnostics |
Context Menu → Diagnostics |
Open network diagnostics tool |
Diagnostics form with device-specific tests |
Control Interface Interactions
Control |
Interaction |
Behavior |
Throttling/Limits |
Volume Slider |
Drag or click |
Set volume 0-100% with live preview |
200ms throttling, immediate UI update |
Volume Up/Down (🔉/🔊) |
Button click |
Increment/decrement volume by device step |
300ms delay + state refresh |
Play/Pause (▶/⏸) |
Button click |
Toggle playback state with icon update |
500ms delay + state refresh |
Mute/Unmute (🔊) |
Button click |
Toggle mute state with visual feedback |
300ms delay + state refresh |
Night Mode (🌙) |
Button click |
Toggle night mode with button color change |
300ms delay + state refresh |
Source Selection |
Double-click ListView item |
Switch source + auto-play with color change |
800ms switch + 1200ms refresh |
Namespace Change |
ComboBox selection |
Reconnect with new namespace |
Full reconnection cycle with progress |
Equalizer Access |
Click equalizer icon |
Open experimental equalizer dialog |
Modal dialog with real-time preview |
Track Progress |
Hover/click progress bar |
Show position, enable seeking |
500ms update interval, 300ms seek throttling |
Source Context Menu |
Right-click source item |
Show source-specific options |
Immediate menu display |
Keyboard Shortcuts & Controls
Implementation Status: Most keyboard shortcuts are implemented for the main forms. Equalizer, Log, and Network Diagnostics forms do not have keyboard shortcuts.
Main Interface
Key Combination |
Context |
Action |
Availability |
F5 |
Discovery Mode |
Refresh/discover devices |
When in discovery view |
F5 |
Control Mode |
Reconnect to current device |
When connected to device |
F12 |
Any Mode |
Open log window |
Always available |
Escape |
Control Mode |
Return to discovery |
When connected to device |
Space |
Control Mode |
Play/pause toggle |
When connected to device |
Ctrl+O |
Any Mode |
Open config file |
Always available |
Ctrl+E |
Control Mode |
Open equalizer (experimental) |
When connected to device |
Ctrl+N |
Control Mode |
Toggle Night Mode |
When connected to device |
Ctrl+P |
Control Mode |
Toggle polling pause/resume |
When connected to device |
Ctrl+S |
Control Mode |
Manage sources |
When connected to device |
Up Arrow |
Control Mode |
Volume up |
When connected to device |
Down Arrow |
Control Mode |
Volume down |
When connected to device |
Left Arrow |
Control Mode |
Previous track |
When connected to device |
Right Arrow |
Control Mode |
Next track |
When connected to device |
Ctrl+D |
Control Mode |
Open network diagnostics |
When connected to device |
Ctrl+M |
Control Mode |
Open device management |
When connected to device |
Ctrl+A |
Discovery Mode |
Add device manually |
When in discovery view |
Sources Management Form
Key |
Action |
Description |
Implementation Status |
Space |
Toggle Visibility |
Show/hide selected source (✓/✗) |
✅ Implemented |
F2 |
Rename Source |
Edit friendly name |
✅ Implemented |
Delete |
Reset Name |
Restore default name |
✅ Implemented |
Ctrl+I |
Change Icon |
Select custom icon for source |
✅ Implemented |
Escape |
Close Form |
Close without saving |
✅ Implemented |
Enter |
Save & Close |
Apply changes and close |
✅ Implemented |
Ctrl+D |
Cleanup Invalid |
Remove invalid entries |
✅ Implemented |
Device Management Form
Key |
Action |
Description |
Implementation Status |
F5 |
Refresh Device |
Refresh device information |
✅ Implemented |
Space / Enter |
Unhide Device |
Restore hidden device to list |
✅ Implemented |
F2 |
Rename Device |
Edit friendly name |
✅ Implemented |
Delete |
Remove Device |
Permanently remove |
✅ Implemented |
Escape |
Close Form |
Close dialog |
✅ Implemented |
Ctrl+R |
Restart Device |
Restart selected device |
✅ Implemented |
Ctrl+L |
Open Log File |
Open application log file |
✅ Implemented |
Equalizer Form
Key |
Action |
Description |
Implementation Status |
No keyboard shortcuts implemented |
Log Form
Key |
Action |
Description |
Implementation Status |
No keyboard shortcuts implemented |
Network Diagnostics Form
Key |
Action |
Description |
Implementation Status |
No keyboard shortcuts implemented |
Command Line Interface
slPhantomRemote V3 includes a command line interface for automation, scripting, and quick operations without launching the GUI. This enables integration with external tools, scheduled tasks, and rapid device control.
Command Line Usage
slPhantomRemote.exe [command] [parameters]
Available Commands
Device Discovery and Connection
Command |
Description |
Example |
-discover |
Scan network for Phantom devices using mDNS/Zeroconf |
slPhantomRemote.exe -discover |
-connect <IP> |
Open GUI connected to specific device |
slPhantomRemote.exe -connect 192.168.1.100 |
-dump |
Comprehensive network interrogation (all devices, all info) |
slPhantomRemote.exe -dump |
-testendpoints <IP> |
Test which API namespace works with device |
slPhantomRemote.exe -testendpoints 192.168.1.100 |
Playback Control
Command |
Description |
Example |
<IP> -play |
Play current source |
slPhantomRemote.exe 192.168.1.100 -play |
<IP> -pause |
Pause playback |
slPhantomRemote.exe 192.168.1.100 -pause |
<IP> -getnowplaying |
Get current playing information |
slPhantomRemote.exe 192.168.1.100 -getnowplaying |
Volume Control
Command |
Description |
Example |
<IP> -volup |
Increase volume by 5% |
slPhantomRemote.exe 192.168.1.100 -volup |
<IP> -voldown |
Decrease volume by 5% |
slPhantomRemote.exe 192.168.1.100 -voldown |
<IP> -volume <level> |
Set volume to specific level (0-100) |
slPhantomRemote.exe 192.168.1.100 -volume 30 |
-volup |
Volume up on last connected device |
slPhantomRemote.exe -volup |
-voldown |
Volume down on last connected device |
slPhantomRemote.exe -voldown |
-mute |
Toggle mute on last connected device |
slPhantomRemote.exe -mute |
Source Management
Command |
Description |
Example |
<IP> -getsourcelist |
List all available sources |
slPhantomRemote.exe 192.168.1.100 -getsourcelist |
<IP> -playsource <source> |
Play source by index, ID, name, or type |
slPhantomRemote.exe 192.168.1.100 -playsource "My Spotify" |
Device Power Management
Command |
Description |
Example |
<IP> -restart |
Restart the Phantom device |
slPhantomRemote.exe 192.168.1.100 -restart |
<IP> -poweroff |
Power off the Phantom device |
slPhantomRemote.exe 192.168.1.100 -poweroff |
Advanced Usage
You can specify the namespace explicitly for devices that support multiple namespaces:
slPhantomRemote.exe <IP> <namespace> <operation>
Where namespace is: devices
, systems
, or groups
Source Selection Methods
The -playsource
command supports multiple selection methods:
- Index number:
0
, 1
, 2
... (based on source list order)
- Source ID: Full UUID like
12345678-1234-1234-1234-123456789012
- Friendly name: User-configured name like
"My Spotify"
or "Living Room TV"
- Source type: Generic type like
"spotify"
, "airplay"
, "bluetooth"
Example Command Sequences
# Discover all devices on network
slPhantomRemote.exe -discover
# Connect GUI to specific device
slPhantomRemote.exe -connect 192.168.1.100
# Full network interrogation
slPhantomRemote.exe -dump
# Play/pause controls
slPhantomRemote.exe 192.168.1.100 -play
slPhantomRemote.exe 192.168.1.100 -pause
# Volume control
slPhantomRemote.exe 192.168.1.100 -volume 30
slPhantomRemote.exe 192.168.1.100 -volup
# Source selection
slPhantomRemote.exe 192.168.1.100 -getsourcelist
slPhantomRemote.exe 192.168.1.100 -playsource "My Spotify"
slPhantomRemote.exe 192.168.1.100 -playsource 0
# Explicit namespace usage
slPhantomRemote.exe 192.168.1.100 groups -play
slPhantomRemote.exe 192.168.1.100 systems -volume 25
Network Interrogation (-dump)
The -dump
command provides information about all Phantom devices on your network:
- Device identification (ID, name, model, serial, firmware)
- Group membership and roles (leader/follower)
- Current playback status and metadata
- Available sources with friendly names
- Stream quality information
- Volume and audio settings
- Equalizer and night mode status
- Available operations per namespace
This is particularly useful for:
- Debugging connectivity issues
- Documenting your Phantom setup
- Understanding device capabilities
- Identifying which namespace to use
Integration Examples
Windows Task Scheduler
Create scheduled tasks to automate device control:
# Morning wake-up routine
slPhantomRemote.exe 192.168.1.100 -volume 20
slPhantomRemote.exe 192.168.1.100 -playsource "Morning Playlist"
slPhantomRemote.exe 192.168.1.100 -play
PowerShell Scripting
Integrate with PowerShell for advanced automation:
# Check if music is playing and adjust volume
$status = & slPhantomRemote.exe 192.168.1.100 -getnowplaying
if ($status -match "playing") {
& slPhantomRemote.exe 192.168.1.100 -volume 15
}
Batch File Automation
Create batch files for common operations:
@echo off
REM Party mode script
slPhantomRemote.exe 192.168.1.100 -playsource "Party Mix"
slPhantomRemote.exe 192.168.1.100 -volume 60
slPhantomRemote.exe 192.168.1.100 -play
Configuration Schema
Note: The configuration file is automatically created and maintained by the application. See docs/Example_config.json
for a complete example.
Configuration File Location
- Windows:
%LOCALAPPDATA%\slPhantomRemote\config.json
- Typical Path:
C:\Users\[username]\AppData\Local\slPhantomRemote\config.json
Configuration Properties
Property |
Type |
Description |
Default |
DeviceNames |
Dictionary<string, string> |
Maps device IPs to friendly names |
{} |
FavoriteDevices |
List<string> |
IP addresses of favorite devices (shown with star) |
[] |
HiddenDevices |
List<string> |
IP addresses of hidden devices |
[] |
DeviceSettings |
Dictionary<string, object> |
Per-device custom settings (reserved for future use) |
{} |
DeviceInfoCache |
Dictionary<string, DeviceInfoCache> |
Cached device information including GUIDs |
{} |
SourceFriendlyNames |
Dictionary<string, string> |
Maps source IDs to friendly names |
{} |
HiddenSources |
List<string> |
Source IDs to hide from the UI |
[] |
SourceIdentifiers |
Dictionary<string, object> |
Source identification mapping (reserved) |
{} |
PreferredNamespace |
int (enum) |
0=Devices, 1=Systems, 2=Groups |
2 |
PollingIntervalSeconds |
int |
Device status polling interval |
20 |
ConnectionTimeoutSeconds |
int |
HTTP request timeout |
3 |
MainWindow |
WindowPosition |
Main window position and size |
System default |
LogWindow |
WindowPosition |
Log window position and size |
System default |
EqualizerWindow |
WindowPosition |
Equalizer window position and size |
System default |
MinimumLogLevel |
LogLevel (enum) |
Logging verbosity level: Verbose, Debug, Info, Warning, Error, Critical |
Info |
MaxLogFileSizeMB |
int |
Maximum log file size before rotation |
10 |
MaxLogFileAgeDays |
int |
Days to keep old log files |
7 |
Theme |
int (enum) |
0=System, 1=Light, 2=Dark |
0 |
UseCustomColors |
bool |
Enable custom color themes |
false |
CustomLightColors |
ThemeColors |
Custom light theme colors |
Default light theme |
CustomDarkColors |
ThemeColors |
Custom dark theme colors |
Default dark theme |
EnableAutoSave |
bool |
Enable automatic configuration saving |
true |
AutoSaveIntervalSeconds |
int |
Auto-save interval |
30 |
DeviceInfoCache Structure
{
"192.168.0.31": {
"DeviceId": "e6e97c6f-0ac8-5a35-b68d-52f70cef57af",
"SystemId": "256b186f-76bc-5ca2-ab74-076795765bc7",
"GroupId": "9131a5fd-0afc-40b0-bb5c-3032377d1d11",
"Model": "Phantom I Gold",
"Serial": "N07P000734U10",
"FirmwareVersion": "2.18.3",
"LastUpdated": "2025-07-26T20:12:12.7228997-07:00"
}
}
WindowPosition Structure
{
"Left": -329,
"Top": -837,
"Width": 512,
"Height": 383
}
ThemeColors Structure
{
"BackgroundColor": "White",
"ForegroundColor": "Black",
"PanelColor": "WhiteSmoke",
"AccentColor": "0, 120, 212",
"AccentLightColor": "16, 110, 190",
"AccentDarkColor": "0, 90, 158",
"MutedColor": "138, 138, 138",
"ErrorColor": "209, 52, 56",
"SuccessColor": "16, 124, 16",
"WarningColor": "255, 185, 0",
"LinkColor": "0, 120, 212"
}
Logging Configuration
The application includes a logging system accessible via the F12 key. Log verbosity is controlled by the MinimumLogLevel
setting in config.json.
Available Log Levels
Level |
Description |
Use Case |
0 (Verbose) |
Everything including detailed debug traces |
Deep troubleshooting, API call details |
1 (Debug) |
Debug information and above |
Development and debugging |
2 (Info) |
Informational messages and above (default) |
Normal operation monitoring |
3 (Warning) |
Warnings and above |
Important notices, recoverable errors |
4 (Error) |
Errors and critical issues only |
Failure tracking |
5 (Critical) |
Only critical issues |
Application-breaking problems |
Changing Log Level
- Press Ctrl+O to open config.json
- Modify the
MinimumLogLevel
value to desired integer (0-5)
- Save the file and restart the application
- Press F12 to open the log window
Note: Log files are stored in the same directory as config.json (%LocalAppData%\slPhantomRemote\
) and are automatically rotated based on size (MaxLogFileSizeMB) and age (MaxLogFileAgeDays) settings.
Testing Strategy
10.1 Testing Approach
Testing Methodology:
- Manual Testing - Comprehensive test cases covering all features and UI components
- API Simulation - Mock API responses for testing edge cases and error handling
- Real Device Testing - Validation on physical Devialet speakers across all supported models
- Performance Testing - Memory usage, CPU utilization, and network efficiency analysis
- Usability Testing - User workflow validation with common scenarios
- Configuration Testing - File format validation, corruption recovery, and import/export testing
- Resilience Testing - Network interruption, reconnection scenarios, and API error simulation
10.2 Test Cases
Category |
Test Cases |
Coverage |
Device Discovery |
- mDNS discovery on all supported service types
- Manual device entry with IP validation
- Duplicate device detection and merging
- Device filtering and categorization
- Recovery from network changes
|
100% |
Device Control |
- Connection establishment and error handling
- Namespace auto-detection and switching
- Playback controls with state preservation
- Volume control with throttling verification
- Source switching and persistence
- Reconnection with state recovery
|
100% |
Configuration Management |
- Persistence across application restarts
- External file change detection
- Import/export validation
- Migration from legacy formats
- Error recovery and rollback
|
100% |
UI Validation |
- Dual-mode UI transition
- Theme application and switching
- Layout adaptation on window resize
- Keyboard shortcut functionality
- Context menu behavior
- Status feedback and visual indicators
|
100% |
Advanced Audio Features |
- Equalizer preset application
- Night Mode toggling and state
- Stream Sensing activation and mode switching
- Custom equalizer settings persistence
- Performance impact of audio processing
|
100% |
Error Handling |
- Network connectivity loss recovery
- API error classification and handling
- Configuration corruption recovery
- Unexpected exception handling
- User feedback for all error conditions
|
100% |
10.3 Test Environment
Test Matrix:
- Operating Systems: Windows 10 (21H2), Windows 10 (22H2), Windows 11 (22H2), Windows 11 (23H2)
- Devices: Phantom I, Phantom II, Dione, Classic Phantom, Phantom S
- DOS Versions: 2.1.0, 2.2.0, 3.0.0, 3.1.0
- Network Configurations: LAN (Wired), WiFi (2.4GHz), WiFi (5GHz), Mixed, VLANs
- Screen Resolutions: 1366x768, 1920x1080, 2560x1440, 3840x2160
- DPI Settings: 100%, 125%, 150%, 200%
- Input Methods: Mouse, Keyboard, Touch, Remote Desktop
11. Deployment & Distribution
14.1 Installation Options
Distribution Methods:
- Standalone Executable: Single-file deployment with no installation required
Prerequisites
- .NET 8.0 Runtime: Required for application execution
- Windows 10/11: Minimum OS version requirement
Installation Steps
Standalone Installation:
- Download
slPhantomRemote.exe
from official distribution channel
-
Place in desired location
- Get .net 8 if needed from Download .NET 8 from Microsoft
- Create desktop shortcut or pin it to your taskbar (optional)
- First run will generate
config.json
in same directory
To uninstall
- go to where you put
slPhantomRemote.exe
and delete it along with the config.json
file
Update Mechanism
NONE! - ET NO PHONE HOME.
Deployment Considerations
You will need .net 8 on the machine, its not part of the disto but you can get it from Microsoft.
Download .NET 8 from Microsoft
Security Considerations:
- Code signing with trusted certificate for tamper protection
- SmartScreen validation for Microsoft Store and standalone distribution
- No collection of personal data or telemetry
- Minimal local permission requirements
Future Enhancement Ideas
The following enhancements have been considered but are currently outside the scope of the initial implementation. They are documented here for potential future development:
PRIMARY DIRECTIVE ABOVE ALL ELSE - First LAW
- Above all dont break or regress functionality , dont leave things half done or half baked
- always use #solution
- 1 Follow Clean Code principles
- 2 Flag long functions, deep nesting, and magic numbers
- 3 Use clear, descriptive names
- 4 Avoid comments when the code is self-explanatory
Multi-Room Management:
- Group creation and management interface for controlling multiple speakers systems in groups
- This is not implemented by the Devialet API so blocked dont try
- as a workaround a user can create and configure a group using the devialet app THEN use it with slPhantomRemote
TO-DO Cross Platform Maui APP:
- Cross-platform mobile control app (win/macos/nix/android/ios)
Recent Updates (Version 1.0)
This section documents the latest enhancements and features added to slPhantomRemote:
Version 1.0.0.813 RC (Build 813) - Release Candidate
- UI Improvements & Bug Fixes:
- Settings UI redesigned: Auto-resize now uses checkbox instead of radio buttons for better UX
- Minimum height field is now always editable regardless of auto-resize setting
- Auto-resize logic enhanced to properly account for hidden sources
- Auto-resize now always respects minimum height setting as a floor value
- Removed border from device list for cleaner, more modern appearance
- Threading & Stability Fixes:
- Fixed cross-thread operation errors in Sources Management dialog
- All UI operations now properly marshalled to UI thread for thread safety
- Global hotkeys initialization improved to avoid conflicts and ensure reliable startup
- Threading issues resolved across all dialog operations
- AnimatedTooltip Component: New animated tooltip system with 4 animation modes:
- Bounce - Spring-like bouncing animation
- Wave - Smooth wave motion
- Police Lights - Alternating color flashing
- Honk - Attention-grabbing pulse effect
- Settings Dialog: Comprehensive configuration interface with volume step size, theme options, and advanced settings
- Enhanced System Tray: Improved minimize to system tray with full control access and notifications
- Smart Volume Acceleration: Intelligent volume control with 1 step default, accelerating to 5 steps when rapid-pressing (3+ times within 1 second)
- Hide Source Context Menu: Quick source management directly from Now Playing view for streamlined workflow
- Enhanced Device Discovery: Fixed device discovery list layout with proper 3-column display and star icon alignment
- Cross-Thread Safety: Resolved cross-thread operation errors when using keyboard arrows for volume control
- UI Polish: Enhanced Device Management form with visible Close button and consistent button layout
- Fallback Device Names: Smart fallback logic displays IP address when device name is unavailable
- Extended Icon Library: Expanded to 42 icons including Gold, Silver, and Gold Stereo Phantom models for enhanced customization
- About Box Enhancements: Animated taglines with smooth transitions and dynamic content
Bluetooth Support
- Bluetooth Advertising: Activate Bluetooth pairing mode directly from the application using the Devialet API
- Device Name Display: Shows the Phantom device name in Bluetooth pairing dialogs for easy identification (e.g., "Living Room Speaker" instead of just "Phantom")
- Peer Device Information: When connected via Bluetooth, displays the connected device name (e.g., "Peer: Pixel 9 Pro XL") next to the source label
- Quick Access: Bluetooth icon in the main UI for instant pairing activation (Ctrl+B shortcut)
- Integration Points: Bluetooth pairing available from device context menu, More Options menu, and Device Management form
- Enhanced Metadata Sync: Additional polling for Bluetooth sources to handle delayed metadata updates
UI Enhancements
- Source Icon Fallback: When no album art is available, displays appropriate source type icons from resources
- Improved Theme Support: Enhanced light mode with professional grey color scheme for better visibility
- Device Visibility Contrast: Hidden devices in Device Manager now show with:
- Strikethrough text for clear distinction
- Emoji indicators (🚫 for hidden, ✅ for visible)
- Different background shading
- Muted foreground colors
- Active Source Highlighting: Currently playing source is clearly highlighted in the available sources list
- F5 Refresh Enhancement: F5 now properly refreshes the now playing information during playback
Configuration Management
- Polling Interval Setting: Configurable polling interval (1-300 seconds) accessible from Device Management dialog
- Enhanced Settings Persistence: All new settings including polling interval are properly saved to and loaded from config.json
- Source Icon Customization: Full icon picker implementation allowing users to select custom icons for sources from built-in library
- Custom Icon Persistence: Selected source icons are saved to configuration (SourceCustomIcons dictionary) and persist across sessions
- Icon Highlighting: Selected icon is visually highlighted in the picker dialog with background color and bold text
- Configuration File Watcher Fix: Improved FileSystemWatcher to ignore app's own saves using timestamp tracking
Technical Improvements
- Thread Safety: Enhanced thread-safe UI updates using proper InvokeRequired patterns
- Error Handling: Improved null reference handling throughout the codebase
- API Integration: Full support for Bluetooth advertising endpoint (/bluetooth/advertise)
- Logging Enhancements: Comprehensive logging for Bluetooth operations and peer device tracking
Configuration Schema Updates:
PollingIntervalSeconds
: Now user-configurable (default: 20)
- Device info cache includes peer device information for Bluetooth connections
- All settings automatically persist to config.json with FileSystemWatcher monitoring
Summary
slPhantomRemote represents an implementation of the Devialet IP Control API specification in a .NET 8.0 WinForms application. The application provides device discovery, connectivity, control interfaces, and audio features while maintaining performance and reliability.
Important: This specification reflects the current implementation of slPhantomRemote as of August 2025.
Credits & Acknowledgments
Open Source Dependencies
slPhantomRemote is built with the following open-source libraries:
- Zeroconf (v3.7.16) by Oren Novotny
- Cross-platform mDNS/DNS-SD implementation
- Enables automatic device discovery on local networks
- GitHub: novotnyllc/Zeroconf
- License: MIT
- Newtonsoft.Json (v13.0.3) by James Newton-King
- High-performance JSON framework for .NET
- Used for API communication and configuration persistence
- Website: newtonsoft.com/json
- License: MIT
- .NET 8.0 by Microsoft
- Modern, cross-platform framework
- Windows Forms for desktop UI
- Website: dotnet.microsoft.com
- License: MIT
Acknowledgments
- Devialet engineering team for their IP Control API documentation
- The Devialet community for feedback, testing, and feature suggestions
- Contributors to the open-source libraries that make this project possible
Devialet IP Control - REFERENCE API DOCUMENTATION - Revision 1 - December 2021
Devialet IP Control - REFERENCE API DOCUMENTATION - Revision 1 - December 2021
Document history
Implementation Notes - slPhantomRemote V3
Technical Implementation Details
- Framework: .NET 8.0 Windows Forms (upgraded from .NET Framework)
- JSON Parsing: Newtonsoft.Json for flexible response handling
- HTTP Client Management: Static factory pattern to prevent resource exhaustion
- Logging: Custom LoggingService with file and UI output, structured properties support
- Configuration: JSON-based with automatic saving on changes
- Threading: Async/await pattern throughout for responsive UI
- Error Handling: Comprehensive try-catch with detailed logging at all API boundaries
Version: This documentation reflects the V3 implementation as of the latest codebase update.