Appearance
Performance & Playback Troubleshooting ​
Use the DiagnosticsPanel (header toolbar → 📊 icon) to identify the bottleneck before following these steps.
Stuttering / Dropped Frames ​
Step 1 — Check Engine FPS ​
Open the DiagnosticsPanel. If Engine FPS is yellow or red:
| FPS range | Severity | Typical cause |
|---|---|---|
| 48–57 fps | Warning | Mild GPU or CPU load |
| 30–48 fps | Moderate | GPU or CPU overloaded |
| < 30 fps | Critical | Severe bottleneck — visible stuttering |
Step 2 — Check CPU Usage ​
If CPU > 75 %:
- Switch to hardware-decoded codecs. Replace H.264 files with HAP or HAP Q. HAP is GPU-decoded and has near-zero CPU cost.
- Reduce the number of simultaneous video streams. Each software-decoded clip consumes CPU.
- Enable Intel QuickSync. In the project settings, enable QuickSync for H.264 if an Intel GPU is present.
Step 2a — H.264 Performance Notes ​
H.264 playback performance depends heavily on decoder configuration. Exaplay applies the following optimisations automatically:
- Hardware decoder cascade: NVIDIA NVDEC → Intel QuickSync → AMD AMF → DXVA/D3D11 → software fallback.
- Native YUV pipeline: decoded frames stay in HDYC (packed YUV, 16 bpp) instead of being converted to RGB32 (32 bpp) on the CPU. The GPU fragment shader handles YUV→RGB conversion during rendering, halving the per-frame transfer and texture upload data volume.
- Multi-threaded software fallback: when hardware decode is unavailable (e.g. 4:4:4 chroma profiles), the FFmpeg fallback path uses frame-level and slice-level threading to utilise all CPU cores.
Advanced (non-critical environments only): for an additional ~10 % throughput gain you can set the Windows registry key HKCU\SOFTWARE\Medialooks\MFormats\MFReader\external_process to false. This runs the decoder in-process, eliminating IPC overhead — but removes crash isolation, so a corrupted file or codec bug can crash the entire application. Not recommended for live shows.
If H.264 clips still stutter, consider re-encoding with the following recommendations (see Medialooks H.264 encoding guide):
| Setting | Recommended value | Why |
|---|---|---|
| Profile | High (4:2:0) | Supported by all hardware decoders |
| Level | 4.1 (1080p) / 5.1 (4K) | Matches decoder capability |
| B-frames | 0–2 | Fewer B-frames reduce decode latency |
| Keyframe interval | 1–2 s | Faster seeking and buffer fill |
| Bitrate | CBR or capped VBR | Avoids storage throughput spikes |
For the highest performance, prefer HAP or HAP Q — these are GPU-decoded with near-zero CPU cost.
Step 3 — Check Buffer Health (Per-Media) ​
Expand the Per-Media Diagnostics section. If Buffer Health is yellow or red for a clip:
| Symptom | Cause | Fix |
|---|---|---|
| Buffer Health = 0 frames | Storage too slow | Move media to NVMe SSD; avoid network drives |
| Decode Time > 33 ms on 30 fps clip | Codec too demanding | Switch to HAP; enable QuickSync |
| Cycle FPS < target FPS | CPU saturated | Reduce clip count; switch codec |
Step 4 — Check VRAM ​
If VRAM is red:
- Reduce the number of simultaneously loaded clips.
- Switch to a lower-resolution working format (e.g. 1080p HAP instead of 4K HAP Q) if the output supports it.
- Close other GPU-using applications on the same machine.
FPS Fluctuation / Unstable Readout ​
The FPS display uses a 0.5-second rolling average to smooth out transient spikes. If you still see fluctuation:
- A spike every few seconds → likely storage hitching; check disk read speed.
- Gradual decline over time → possible memory leak; restart Exaplay; check the log.
- Sudden drops when a new clip starts → codec initialisation overhead; pre-load clips before they play.
High CPU on the UI Machine (Browser) ​
The Exaplay UI runs in a browser tab. If that tab is consuming significant CPU:
- Disable the Output Preview if active (it polls the engine continuously).
- Close the DiagnosticsPanel when not in use.
- Reduce the preview frame rate (2 fps is the lowest option).
The engine's rendering performance is not affected by browser CPU usage. The engine and the UI run in separate processes.
Performance Recommendations by Content Type ​
| Content | Recommended codec | Expected max streams (modern GPU) |
|---|---|---|
| 1080p 30 fps | HAP | 8–12 |
| 1080p 60 fps | HAP | 4–8 |
| 4K 30 fps | HAP Q | 3–6 |
| 4K 60 fps | HAP Q | 2–4 |
| 1080p 30 fps (with alpha) | HAP Alpha | 4–8 |
| 4K with alpha | NotchLC | 2–4 |
These are indicative figures. Actual performance depends on GPU model, VRAM, and system RAM.
Frame Blending Performance ​
Optical Flow frame blending is GPU-intensive. If it causes FPS drops:
- Switch to Mix mode (simpler 50/50 blend — much lower GPU cost).
- Or disable frame blending entirely for clips that do not benefit from it.
Warp/Blend Performance ​
Each enabled warp output adds one fragment shader pass per frame. On a rig with 6 warped projectors at 4K resolution, this is significant. Ensure the GPU has headroom for these extra passes in addition to media decode.
Rule of thumb: budget approximately 5–10 % of GPU frame time per warped output.