WSDashboard

Real-time streaming monitoring and session control for your media server

WSDashboard - What’s Streaming Dashboard

What’s Streaming Dashboard (WSD) is a powerful, real-time monitoring and control system for Emby and Jellyfin media servers, exclusively available on QuickBox Pro. Monitor active streaming sessions, track bandwidth usage, view detailed media information, control playback, and manage user sessions—all through a beautiful, responsive dashboard that works seamlessly on desktop, tablet, and mobile devices.

What is WSD?

WSD (What’s Streaming Dashboard) is a comprehensive monitoring and control platform that integrates directly into your QuickBox Pro dashboard. Built with a modern, modular architecture, WSD provides complete visibility into your media server’s streaming activity with powerful management capabilities.

Installation

Prerequisites

Before installing WSD, ensure you have:

Install WSD

Install What’s Streaming Dashboard for a specific user:

qb install wsdashboard -u username

Automatic Installation Process

The QuickBox installer handles everything automatically:

1. 🔍 Detection - Automatically identifies Emby or Jellyfin installation
2. 📦 Dependencies - Installs Node.js (v24.6.0) and Python 3 virtual environments
3. 🗄️ Database - Creates SQLite database for session tracking and configuration
4. 🔐 API Integration - Configures API keys and connection settings
5. 🔒 Security - Sets up sandboxed systemd services with resource limits
6. 🌐 Nginx - Configures reverse proxy with SSL support
7. 💾 Service Files - Installs main daemon and log server services
8. 🎨 Web Interface - Integrates dashboard into QuickBox UI

CLI Commands

Basic Operations

Usage Examples

Install WSD:

qb install wsdashboard -u myuser

Update WSD with automatic backup:

qb update wsdashboard -u myuser

Reinstall (fix corrupted installation while preserving data):

qb reinstall wsdashboard -u myuser

Remove WSD and clean up:

qb remove wsdashboard -u myuser

Maintenance & Health Checks

WSD includes standalone maintenance scripts for diagnostics and repairs:

Run detailed health check:

/opt/quickbox/bin/qbwsd-health-check.sh --verbose

Auto-fix common issues:

/opt/quickbox/bin/qbwsd-health-check.sh --fix

View help for health check options:

/opt/quickbox/bin/qbwsd-health-check.sh --help

Enhanced Features

WSD on QuickBox Pro includes production-grade enhancements not found in standalone installations:

System Architecture

WSD utilizes a dual-service architecture for reliability:

Main Service (qbwsd.service)

• Node.js daemon for session monitoring and transcode cleanup
• Runs with forking type and PID file management
• Configurable polling interval (default: 2000ms)
• Automatic restart with exponential backoff

Log Server (qbwsd-log-server.service)

• Dedicated WebSocket server for real-time log streaming
• Independent service ensures logging availability even during main service restarts
• Systemd journal integration with supplementary groups for log access
• Automatic port configuration via environment variables

Service Management

WSD operates through two systemd services for maximum reliability:

Main WSD Service

Check service status:

systemctl status qbwsd.service

Restart main service:

systemctl restart qbwsd.service

View live logs:

journalctl -u qbwsd.service -f

Enable/disable service:

systemctl enable qbwsd.service   # Start on boot
systemctl disable qbwsd.service  # Prevent auto-start

Log Server Service

Check log server status:

systemctl status qbwsd-log-server.service

Restart log server:

systemctl restart qbwsd-log-server.service

View log server logs:

journalctl -u qbwsd-log-server.service -f

Health Check Commands

The integrated health check script provides comprehensive diagnostics:

Run detailed health check:

/opt/quickbox/bin/qbwsd-health-check.sh --verbose

Auto-fix common issues:

/opt/quickbox/bin/qbwsd-health-check.sh --fix

Display help:

/opt/quickbox/bin/qbwsd-health-check.sh --help

Service Configuration Override

Advanced users can customize service behavior without modifying the main service file:

# Edit override configuration
nano /etc/systemd/system/qbwsd.service.d/override.conf
 
# After changes, reload and restart
systemctl daemon-reload
systemctl restart qbwsd.service

Example overrides:

[Service]
# Increase memory limit
MemoryMax=1G
 
# Adjust CPU quota
CPUQuota=75%
 
# Change daemon polling interval
Environment=DAEMON_INTERVAL=5000

Configuration

Getting Your Media Server API Key

For Emby:

1. Open Emby web interface
2. Navigate to Settings → Advanced → API Keys
3. Look for qb_token or create a new API key
4. Click New API Key (if creating new)
5. Enter name: WSD Dashboard
6. Copy the generated key

For Jellyfin:

1. Open Jellyfin web interface
2. Navigate to Dashboard → Advanced → API Keys
3. Look for qb_token or click the + button to create new
4. Enter app name: WSD Dashboard
5. Copy the generated key

Environment Configuration

WSD uses a comprehensive environment configuration file that’s automatically created during installation:

nano /srv/quickbox/assets/plugins/wsd/env.conf

Configuration breakdown:

# ============================================
# Application Configuration
# ============================================
APPLICATION_NAME=jellyfin          # or 'emby'
APPLICATION_PORT=8096              # Media server port
APPLICATION_USERNAME=john_doe      # QuickBox username

# URL Structure:
# Emby:     http://localhost:${APPLICATION_PORT}
# Jellyfin: http://localhost:${APPLICATION_PORT}/${APPLICATION_USERNAME}/${APPLICATION_NAME}
APPLICATION_URL=http://localhost:8096/john_doe/jellyfin

# ============================================
# Node.js Configuration
# ============================================
NODE_TLS_REJECT_UNAUTHORIZED=0     # Disable TLS verification (localhost)
USE_LOCALHOST_HTTPS=true           # Use HTTPS for media server connections
NODE_ENV=production                # Production environment

# ============================================
# Daemon Configuration
# ============================================
DAEMON_INTERVAL=2000               # Polling interval in milliseconds
                                   # Lower = more real-time, higher load
                                   # Recommended: 2000-5000ms

# ============================================
# Database Configuration
# ============================================
QB_WSD_DB_PATH=/srv/quickbox/db/WSDashboard.db
QB_WSD_USER_GEOIP_DB_PATH=/srv/quickbox/db/WSDUserGeoIpMap.db
NODE_PATH=/srv/quickbox/assets/plugins/wsd/nodejs/.venv/lib/node_modules

# ============================================
# Logging Configuration
# ============================================
LOG_SERVER_PORT=3001               # WebSocket log server port
LOG_LEVEL=info                     # trace, debug, info, warn, error, fatal
LOG_CONSOLE=true                   # Enable console output
LOG_FILE=true                      # Enable file logging
LOG_DIR=/srv/quickbox/assets/plugins/wsd/logs
LOG_MAX_FILE_SIZE=10485760         # 10MB per log file
LOG_MAX_FILES=5                    # Keep 5 rotated files
LOG_TIMESTAMP_FORMAT=HH:mm:ss
LOG_INCLUDE_TIMESTAMP=true

# ============================================
# Frontend Logging Configuration
# ============================================
WSD_FRONTEND_LOG_LEVEL=warn        # none, error, warn, info, debug
WSD_FRONTEND_DEBUG=false           # Enable debug mode
WSD_FRONTEND_LOG_MAX_RECORDS=1000  # Max in-memory log entries
WSD_FRONTEND_LOG_TTL_MS=900000     # 15 minutes TTL
WSD_FRONTEND_LOG_SAMPLE=0.0        # Sampling rate (0.0-1.0)

# ============================================
# Log Rotation Configuration
# ============================================
LOG_ROTATION_CHECK_INTERVAL=60000  # Check every minute
LOG_MIDNIGHT_OFFSET=0              # Midnight rotation offset
LOG_DAILY_RETENTION=7              # Keep 7 days of logs
LOG_DAILY_ROTATION=true            # Enable daily rotation
WSD_ENABLE_POST_ROTATION_RESTART=true  # Restart after rotation

Accessing WSD Dashboard

After installation, access the dashboard through multiple methods:

Access Methods

Primary Access (QuickBox Dashboard):

https://your-server-ip/whats-streaming.php

Via QuickBox Navigation:

• Navigate to QuickBox Pro dashboard
• Look for What’s Streaming Dashboard in the navigation menu
• Click to access the monitoring interface

Via Service Control Panel:

• Open the main QuickBox dashboard
• Locate the Service Control Panel
• Find your media server (Emby/Jellyfin)
• Click the WSD icon or link

Dashboard Overview

The WSD interface provides comprehensive streaming insights:

Interactive Features

Session Management:

• Play/Pause Control - Remote playback control for any session
• Stop Session - Immediately terminate streaming sessions
• Seek Control - Jump to specific timestamps in media
• Send Messages - Push notifications to specific users or all active sessions
• Kick Users - Force disconnect with optional custom message

Data Visualization:

• Real-Time Updates - Live session data without page refreshes
• Sortable Tables - Click column headers to sort by any metric
• Search & Filter - Quickly find specific sessions or users
• Responsive Layout - Optimized for desktop, tablet, and mobile viewing

Advanced Log Panel Features

WSD includes a sophisticated log viewing system accessible directly from the dashboard:

Accessing the Log Panel

1. Navigate to the WSD dashboard
2. Click the settings dropdown for Emby or Jellyfin
3. Select “View WSD Logs”
4. Log panel opens in a modal with real-time streaming

Log Panel Capabilities

Log Panel Controls

Mode Toggle:

• Live Mode - Real-time WebSocket streaming from log server
• Static Mode - Historical logs with pagination

Search & Filter:

• Enter keywords to filter log entries in real-time
• Case-insensitive search across all log fields
• Results highlighted for easy identification

Tag Filters:

• Click tag buttons to show/hide specific log categories
• Multiple tags can be toggled simultaneously
• Visual indicators show active/inactive tags

Additional Controls:

• Clear Logs - Remove all entries from current buffer
• Connection Status - Visual indicator of WebSocket connection health
• Auto-Scroll Toggle - Enable/disable automatic scrolling

Directory Structure

Understanding WSD’s file organization:

Troubleshooting

Common Issues

WSD not connecting to media server:

# Check if media server is running
systemctl status jellyfin@username  # or emby-server@username
 
# Verify API key is correct
/opt/quickbox/bin/qbwsd-health-check.sh --verbose
 
# Check WSD logs
journalctl -u qbwsd.service -n 50
 
# Test media server API manually
curl -H "X-Emby-Token: YOUR_API_KEY" http://localhost:8096/Sessions

Dashboard not loading:

# Restart WSD service
systemctl restart qbwsd.service
 
# Check nginx configuration
nginx -t
systemctl reload nginx
 
# Verify PHP-FPM is running
systemctl status php8.1-fpm
systemctl restart php8.1-fpm
 
# Check file permissions
ls -la /srv/quickbox/assets/plugins/wsd/

No sessions showing in dashboard:

# Verify API key has proper permissions
# Check env.conf configuration
cat /srv/quickbox/assets/plugins/wsd/env.conf | grep APPLICATION
 
# Check database connectivity
sqlite3 /srv/quickbox/db/WSDashboard.db "SELECT * FROM media_api;"
 
# Ensure users are actively streaming
# Check media server's native dashboard for active sessions

Log panel not working:

# Check log server service
systemctl status qbwsd-log-server.service
systemctl restart qbwsd-log-server.service
 
# Verify WebSocket port configuration
grep LOG_SERVER_PORT /srv/quickbox/assets/plugins/wsd/env.conf
 
# Check nginx WebSocket proxy
grep -A 10 "wsd-logs/ws" /etc/nginx/software/wsd.conf
 
# Test WebSocket connection
curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" \
  http://localhost:3001/ws

Permission errors:

# Run comprehensive auto-fix
/opt/quickbox/bin/qbwsd-health-check.sh --fix
 
# Fix file ownership
chown -R www-data:www-data /srv/quickbox/assets/plugins/wsd
chown www-data:www-data /srv/quickbox/db/WSDashboard.db
 
# Verify www-data group memberships
id www-data
# Should show emby/jellyfin in supplementary groups
 
# Reinstall if issues persist
qb reinstall wsdashboard -u username

High resource usage:

# Check resource consumption
systemctl status qbwsd.service
top -p $(pgrep -f wsd-daemon)
 
# Adjust polling interval (increase DAEMON_INTERVAL)
nano /srv/quickbox/assets/plugins/wsd/env.conf
# Change DAEMON_INTERVAL=2000 to 5000 or higher
 
# Restart after changes
systemctl restart qbwsd.service
 
# Monitor resource limits
systemctl show qbwsd.service | grep -E "Memory|CPU"

Use Cases

Server Capacity Planning

Monitor concurrent streams to ensure optimal server performance:

User Activity Monitoring

Gain insights into viewing patterns and content popularity:

• 📊 Popular Content - Identify most-streamed movies, shows, and media
• ⏰ Peak Hours - Determine when server load is highest
• 👥 User Patterns - Track individual viewing habits and preferences
• 🌍 Geographic Distribution - See where your users stream from
• 📱 Device Analytics - Understand client types and player capabilities

Performance Troubleshooting

Diagnose and resolve playback issues in real-time:

• 🐌 Buffering Streams - Identify bandwidth bottlenecks or network issues
• ⚙️ Transcoding Load - Monitor CPU/GPU usage for transcoding operations
• 🎬 Direct Play vs Transcode - Optimize media formats for direct streaming
• 🔍 Session Diagnostics - View detailed codec, bitrate, and quality metrics
• 📝 Live Logs - Real-time troubleshooting with WebSocket log streaming

Administrative Control

Manage streaming sessions and enforce server policies:

• 🎮 Remote Control - Play, pause, or stop sessions remotely
• 💬 User Communication - Send messages or notifications to active users
• 🚫 Session Termination - Disconnect problematic or unauthorized sessions
• 📊 Resource Management - Monitor and limit bandwidth-intensive streams
• 🔐 Access Control - Track and manage user access patterns

Best Practices

Additional Resources

Related Applications

WSD works seamlessly with these QuickBox Pro applications: