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 Performance Diagnostics panel. If Engine FPS is amber or red:
| FPS range | Severity | Typical cause |
|---|---|---|
| 57 fps and above | Good (green) | — |
| 48–57 fps | Warning (amber) | Mild GPU or CPU load |
| below 48 fps | Critical (red) | GPU or CPU overloaded — visible stuttering |
Step 2 — Check CPU Usage
If CPU > 75 %:
- Switch the heavy clips to HAP. Replace H.264/H.265 files with HAP or HAP Q. HAP is decoded on the GPU; the CPU only unpacks it, spread over several cores — the price is much bigger files, so plan fast storage (NVMe). Encode with several chunks (Exaplay's own encoder in the File Browser does this for you).
- Reduce the number of simultaneous video streams. Each H.264/H.265 stream needs decoding resources, and a software-decoded one costs CPU.
- Check that hardware decoding is on. Settings → Decode & GPU → Video decoding is Automatic (GPU) by default: Exaplay decodes on the GPU that drives the outputs where it can, else on the strongest GPU that can, else on the CPU (Software (CPU) forces the CPU everywhere). A single clip can be overridden in its Inspector (Decoder → Acceleration: Hardware, Software, NVIDIA GPU (NVDEC) or Intel GPU (QuickSync)). There is no project-wide QuickSync switch.
Step 2a — H.264 / H.265 Performance Notes
Exaplay picks the decoder automatically when a clip loads (details in Video Decoding):
- 8-bit 4:2:0 H.264/H.265 and H.265 Main10 are decoded by the GPU's video decoder, and the frames stay on the GPU all the way to the Output. That one decoder is shared by every H.264/H.265 layer on the card.
- If the hardware decoder cannot open a file, the same built-in decoder reopens it on the CPU; if it delivers no frame within about 3 seconds, the clip is reopened in software — shown as HW→SW in the Diagnostics panel.
- 8-bit 4:4:4 is decoded in software on all CPU cores; 4:4:4 above 8-bit is blocked with a message.
- 4:2:2, 10-bit H.264 (High 10), ProRes and DNxHD are the formats the built-in decoder does not take; they go through the compatibility decoder, on the GPU where the driver supports it, otherwise on the CPU. A clip's Force engine can send an H.264/H.265 file there too.
If H.264 clips still stutter, consider re-encoding with the following guidelines (see Medialooks H.264 encoding guide):
| Setting | Guideline | Why |
|---|---|---|
| Profile | High (8-bit 4:2:0) | Decoded by the GPU's video decoder |
| 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 — decoded on the GPU with the lightest load, at the price of much bigger files.
Step 3 — Check the Per-Clip Rows
Expand the Media section of the Diagnostics panel. Each playing clip shows its decoder, resolution and effective / nominal fps:
| Symptom | Cause | Fix |
|---|---|---|
| Effective fps in amber (below 90 % of the clip's rate) | The decoder cannot keep up — codec too demanding, too many layers, or storage too slow | Switch the clip to HAP; move media to an NVMe SSD, avoid network drives |
| HW→SW on a clip | The hardware decoder gave up and the clip was reopened in software | Transcode to 8-bit 4:2:0 H.264/H.265 or HAP |
| Decoder names software, high CPU, Video Decode near 0 % | Clips are decoded on the CPU | Check Settings → Decode & GPU → Video decoding is not Software; transcode the flagged files (Check Project) |
| ⚠ n climbing | Decode failures or empty frames | Re-export the file; check it plays in another player |
See Reading the Diagnostics panel.
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.
Outputs at Different Refresh Rates
Exaplay presents all of a machine's outputs from one window with one vertical sync, and one sync can follow only one display. On a rig where the outputs run at different rates — a 30 Hz projector wall beside 60 Hz projectors, or a 60 Hz control monitor beside a 25 Hz wall — the outputs on the other rate drop or repeat frames, and a driver setting such as NVIDIA's Vertical sync: Adaptive (half refresh rate) can halve the whole engine to 15 fps.
The engine log says so at start: one Display …: … @ 30 Hz line per output and a Mixed refresh rates: line naming the rates when they differ (also in the Diagnostics panel's render_clock block). Two ways out:
- Set every output to one refresh rate in Windows' display settings — the cleanest, whenever the projectors and cables allow it.
- Settings → Decode & GPU → Vertical sync: off, and Frame rate = the rate of the slowest output (30 for a 30 Hz wall). The engine then paces its own clock and each output shows it at its own rate, with nothing to set in the graphics driver.
FPS Fluctuation / Unstable Readout
The FPS display counts the frames of the last 1-second measuring window, which smooths 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 → decoder start-up. Timeline clips already open about 3 seconds before the playhead reaches them; for clips started by a cue, switching heavy clips to HAP reduces it.
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 (1 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 | Indicative 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, not measured limits. Actual performance depends on GPU model, VRAM, storage speed and system RAM — test your own content on the show machine.
Frame Blending Performance
Frame blending draws each clip twice and mixes the two frames, so it roughly doubles that clip's draw cost. It is off by default. If it is on and the frame rate drops, turn it off again for clips that do not benefit from it — see Fades & Transitions.
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.