Chapter 9

Troubleshooting

Outputs on the wrong display, mirrored displays, the playback health indicator, logs and the Learn watermark.

An output opens on the wrong display

  1. Select the output and open Display in the Inspector.
  2. Click the right display in the map (or choose it under Monitor).
  3. If the Inspector says Not connected: opens on …, the display the output remembers (by its name) is not plugged in or has another name. Pick the display again.

On a show machine, pixelwright-node --list-monitors prints the names, resolutions and positions of the connected displays.

Linux: under Wayland applications cannot place their windows, so the compositor decides where each output appears. Use an X11 session for shows.

Two displays show the same picture

The Inspector says Mirrored with …: the displays are in mirror (duplicate) mode and cannot carry different outputs. Turn mirroring off in the system:

  • macOS: System Settings → Displays, “Use as: Extended display”. Keep “Displays have separate Spaces” on (Desktop & Dock), it is the default.
  • Windows: Settings → Display, “Extend these displays”.
  • Linux: your desktop’s display settings, or xrandr.

A fullscreen output covers the studio

If you made an output fullscreen on the display where the studio is, it covers it and Esc does not close it. Turn the output’s Window off from another display, or use Output → Close all windows. The Inspector warns about this before it happens (The studio is on this display).

The playback health indicator is amber or red

The status bar watches playback all the time:

It says It means What to do
Playback OK (green) Every frame on time Nothing
dropped frames/s (amber) Frames shown late or skipped Usually the GPU or the display is overloaded: fewer or smaller layers, lower NDI/Syphon send rate, close other GPU apps
late frames/s (amber) Frames rendered late Same as above
Decoder behind (n layers) (amber) A video layer’s decoder has no frames ready The disk is too slow for the media: use a faster SSD, BPV (smaller than HAP), or fewer 4K layers
Damaged media (n/s skipped) (red) A file has damaged frames; they are skipped Re-encode or re-copy the file

The indicator settles a few seconds after you open a show or jump around; judge it during steady playback. For a real verdict, run a soak test on the show machine: pixelwright-node --project MyShow/MyShow.bp --soak 10.

A clip marked Not show-safe in the Media panel or Inspector is in a codec the engine will not play (H.264, ProRes…). Use To BPV (or HAP) to transcode it.

Logs

Every run of the studio or node writes a log:

  • Help → Open log folder opens the folder (the 50 most recent sessions are kept):
    • macOS: ~/Library/Application Support/PixelWright/logs
    • Windows: %APPDATA%\PixelWright\logs
    • Linux: ~/.config/pixelwright/logs
  • With a show open, the same lines also go to MyShow/logs/, so the log travels with the show.
  • Help → Show log, or the Log tab in the Live workspace, shows it inside the studio, with filters by level and text.

The log has the version, system, CPU and GPU, show open and save, imports and transcodes, every external control command with its origin, transport changes, playback health changes and media errors. A crash is written with its backtrace. Start with --verbose to also log every dropped frame.

When you ask for support, send the log of the session that failed.

The outputs say “PixelWright · Learn”

The machine runs in Learn mode: there is no valid licence. Open Help → License… to see why (for example: expired, issued for another machine) and activate it (see Install and first launch). Outputs that show NO LICENCE · LEARN: 1 OUTPUT are the extra outputs Learn does not render.

Activating takes effect at once. The other way round is deliberately slow: a licence that expires or is removed while a show runs only takes effect at the next start or show load, so it never stops a show.

A shortcut or edit does nothing

Check the top bar: a red LOCKED badge means Show Lock is on, and editing is read-only. Turn it off with Ctrl+Shift+L or Edit → Show Lock.