Version 1.0 - Release Notes

Overview

BotOfTheSpecter OBS Connector v1.0 is the initial release that bridges BotOfTheSpecter and OBS Studio through WebSocket connections, enabling seamless automation and event-driven workflows.

Core Features

1. BotOfTheSpecter Integration

• WebSocket Connection: Establishes real-time connection to BotOfTheSpecter’s WebSocket server
• API Key Authentication: Validates user credentials via BotOfTheSpecter API key
• Auto-Reconnection: Implements intelligent reconnection logic with 60-second intervals and jitter to handle connection failures gracefully
• Session Management: Tracks connection status and handles registration with the Specter server
• Event Registration: Registers with Specter as “OBS Connector” for proper identification

2. OBS WebSocket Integration

• OBS Connection Management: Establishes secure WebSocket connection to OBS Studio
• Configurable Settings: Support for custom host, port, and password configuration
• Connection Status Monitoring: Real-time status updates for OBS connection state
• Source Name Caching: Pre-caches source names and item IDs from all scenes for efficient lookups

3. Event Handling & Logging

OBS Events Captured:

• Scene Management: Scene changes, creation, and deletion
• Source Management: Source creation/removal, visibility changes
• Streaming: Stream started/stopped events
• Recording: Recording started/stopped events
• Transitions: Transition start and end events
• Smart Formatting: User-friendly emoji-based messages for events

BotOfTheSpecter Events Supported:

• OBS_REQUEST: Commands from Specter to control OBS
• OBS_EVENT_RECEIVED: Acknowledgments and responses
• Generic event handling with automatic retrying

4. Action Execution

Supports execution of OBS actions via BotOfTheSpecter commands:

• Scene Switching: set_current_program_scene - Changes the active program scene
• Source Visibility: set_scene_item_enabled - Toggle source visibility in scenes

Action format:

{
  "action": "set_current_program_scene",
  "scene": "Scene Name"
}

or

{
  "action": "set_scene_item_enabled",
  "scene": "Scene Name",
  "item_id": 1,
  "enabled": true/false
}

5. Configuration Management

• Persistent Storage: Saves all settings to AppData (user-specific)
• Configuration File: Stores API key, OBS settings, and UI preferences
• Auto-Connection: Automatically connects if credentials are stored
• Log Preferences: Remembers event log expansion state

Configuration Location: %APPDATA%\BotOfTheSpecter\OBSConnector\

Files:

• config.json - All application settings
• app.log - Application logs
• botofthespecter.png - Downloaded application icon

6. User Interface (PyQt6)

• Clean Layout: Organized sections for BotOfTheSpecter and OBS settings
• Real-time Status: Live connection status indicators for both services
• Event Log: Collapsible event log with emoji indicators for different event types
• Password Fields: Secure input fields for API keys and OBS passwords
• One-Click Connection: Simple connect/disconnect buttons for both services
• API Validation: Built-in API key validation with feedback
• Auto-download Icon: Automatically fetches and displays BotOfTheSpecter logo

7. Logging & Debugging

• File & Console Logging: Dual output to both log file and console
• Detailed Event Tracking: Comprehensive logging of all WebSocket events
• Error Reporting: Clear error messages for connection issues
• Session Information: Logs session IDs and transport methods
• Sensitive Data Redaction: Masks API keys in logs for security

8. Error Handling

• Connection Failure Recovery: Automatic reconnection with exponential backoff
• User-Friendly Error Messages: Clear, actionable error descriptions
• Timeout Protection: 30-second timeout for connection establishment
• Action Failure Feedback: Notifies user when OBS actions fail
• Graceful Degradation: Continues operation even if pre-caching fails

Technical Specifications

Dependencies

• PyQt6: GUI framework
• python-socketio: WebSocket client for BotOfTheSpecter connection
• obswebsocket-py: WebSocket client for OBS Studio connection
• aiohttp: HTTP client for async operations
• requests: HTTP library for icon download
• Pillow: Image processing (optional, for icon handling)

System Requirements

• Python: 3.7 or higher
• OBS Studio: 28.0 or higher (with WebSocket Server plugin enabled)
• BotOfTheSpecter: Active account with valid API key
• Windows: Application designed for Windows (AppData storage)

Architecture

• Multi-threaded: Separate threads for BotOfTheSpecter and OBS connections
• Async Operations: Uses asyncio for non-blocking WebSocket operations
• Signal-Slot Pattern: PyQt signals for thread-safe GUI updates
• Singleton Pattern: Global configuration and logging setup

Known Limitations

• Windows-specific implementation (AppData paths)
• Requires manual WebSocket password configuration
• Icon download depends on internet connectivity
• No built-in OBS scene/source management UI (planned for future versions)

Future Enhancements

• OBS scene and source browser
• Custom action triggers
• Event filtering and routing
• Chatbot integration with more complex workflows
• Performance metrics and analytics

Version History

1.0 - Initial release (November 8, 2025)

• Core BotOfTheSpecter to OBS integration
• Change of scene/source management commands
• Real-time event monitoring
• Persistent configuration storage