Performance Diagnostics - User Guide

Overview

The Performance Diagnostics panel helps operators understand and troubleshoot video playback issues in Exaplay 3. When a video stutters or has playback problems, this tool provides real-time information about what might be causing the issue.

Performance Guarantee: The diagnostics panel has ZERO performance impact when closed or minimized. No background processes run, no HTTP requests are made, and no resources are consumed.

Accessing the Diagnostics Panel

1. Toggle Button: Click the diagnostics icon in the top-right header toolbar (looks like a monitor with an activity graph)
2. On-Demand: The panel only appears when you click the toggle - it doesn't affect performance when hidden
3. Auto-Refresh: When visible and not minimized, diagnostics update every second automatically
4. Minimize to Pause: Click minimize to stop auto-refresh while keeping system metrics visible

Performance Impact

When Closed (Default State)

• ✅ Zero HTTP requests - No data fetched from the playback system
• ✅ Zero intervals running - No timers or background processes
• ✅ Zero CPU usage - Component not rendered
• ✅ Zero memory overhead - No data stored

When Minimized

• ✅ Zero HTTP requests - Auto-refresh automatically paused
• ✅ Zero intervals running - Timer stopped to save resources
• 📊 System metrics frozen - Shows last fetched data
• 💡 Quick glance mode - See RAM/VRAM at a glance without overhead

When Open and Active

• 📡 1 HTTP request per second - Fetches diagnostics data
• 💾 ~2KB per request - Minimal network usage
• 🔄 Auto-refresh active - Updates every second
• ⚡ <0.1% CPU overhead - Negligible impact on playback

What the Panel Shows

All system metrics (FPS, CPU, RAM, VRAM) are reported by the playback engine, not the browser. This ensures accurate readings even when the web UI runs on a separate machine.

System Resources

Engine FPS (Framerate)

• Large card display showing the current rendering framerate
• Color Coding:
  • Green: ≥ 57 fps (healthy)
  • Yellow: 48-57 fps (warning)
  • Red: < 48 fps (critical - may cause visible stuttering)

CPU Usage

• Large card display showing overall system CPU usage percentage
• Progress bar for visual indication
• Color Coding:
  • Green: < 75% (healthy)
  • Yellow: 75-90% (warning)
  • Red: > 90% (critical)

RAM (System Memory)

• Compact inline bar showing available / total with usage percentage
• Color Coding:
  • Green: < 75% usage (healthy)
  • Yellow: 75-90% usage (warning)
  • Red: > 90% usage (critical - may cause stuttering)

GPU VRAM (Graphics Memory)

• Only shown on NVIDIA GPUs with driver support
• Compact inline bar showing available / total with usage percentage
• Color Coding: Same as RAM

Media Status

Shows the current count of active media items:

• Videos: Number of video files currently loaded/playing
• Images: Number of image files currently loaded
• Live Inputs: Number of live input sources available

Per-Media Diagnostics (Collapsible)

For each playing media item, the panel shows buffer health, decode times, FPS, and timing information with automatic issue detection. Click the section header to expand or collapse the per-media details.

Common Issues and Solutions

Issue: Video Stuttering

Check these in order:

1. Engine FPS: If red/yellow - Rendering pipeline overloaded
2. CPU Usage: If red - System CPU saturated, consider reducing media load
3. Cycle FPS: If red/yellow - CPU overloaded or codec too demanding
4. Buffer Health: If red/yellow - Decoding too slow or storage speed issues
5. RAM Usage: If red - System running out of memory
6. Decode Time: If > 33ms for 30fps - Switch to HAP or hardware-accelerated codec

Panel Controls

• Minimize/Maximize: Click minimize icon to collapse to title bar
• Refresh: Manually refresh (auto-updates every second)
• Close: Hide panel (click toolbar icon to reopen)
• Draggable: Drag title bar to reposition