# Performance & Playback

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 %:

1. **Switch to hardware-decoded codecs.** Replace H.264 files with HAP or HAP Q. HAP is GPU-decoded and has near-zero CPU cost.
2. **Reduce the number of simultaneous video streams.** Each software-decoded clip consumes CPU.
3. **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](https://support.medialooks.com/hc/en-us/articles/360000210192-H-264-encoding-options)):

| 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**:

1. Reduce the number of simultaneously loaded clips.
2. Switch to a lower-resolution working format (e.g. 1080p HAP instead of 4K HAP Q) if the output supports it.
3. 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 is a Vue 3 SPA running in a browser. If the browser tab is consuming significant CPU:

1. Disable the **Output Preview** if active (it polls the engine continuously).
2. Close the **DiagnosticsPanel** when not in use.
3. 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.exaplay.one/v3/troubleshooting/performance.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.