EZPlayer Troubleshooting: Follow the Failed Stage

Begin with one symptom and one known sequence. Check whether the failure is in the files, the player, the network or the physical display before changing several settings together. Save the current error and the last arrangement that worked.

Reviewed October 29, 2026. The public stable release was 0.6.12. Record your installed version and the layout-management mode before following a version-specific fix.

Start with the status that matches the symptom

Use Player for current playback and upcoming items, Show Status for deeper diagnostics, Cloud for registration and downloads, and Controllers for device and configuration information. Write down the actual status and time rather than describing the whole system as offline.

Official EZPlayer Show Status screen with playback and controller diagnostic cards
Official EZPlayer manual example of diagnostic cards. The sample is stopped and reports no controllers online; those are example conditions, not a completed setup. Source and current instructions.

The official Show Status guide explains the diagnostic cards. Compare the same song after each change so a different sequence does not hide the result.

The player opens, but the expected show is missing

  1. On the desktop app, verify the active show-folder location. A similarly named folder can contain a different season or a test show.
  2. For a local layout, confirm the layout, network configuration and intended sequence files are in the working arrangement.
  3. If another EZPlayer instance holds the folder, close that instance normally. The documented folder lock prevents simultaneous writers and expires after its owner exits; deleting files is not the first recovery step.

See folder settings and the folder-lock description. Use backup and recovery before replacing the working folder.

A purchased or assigned cloud song is not in Songs

Confirm the player is registered to the intended account and cloud activity is running. In Cloud Content, locate that specific sequence. A pending render or unfinished download is different from an installed song.

Check that the sequence is assigned and active for the show, inspect any reported error, and check the allowed sync times. Use the correct content-sync button after correcting the cause. A song becomes playable after its actual sequence file is ready. Follow the missing-content checks and our cloud setup walkthrough.

The preview is wrong, or the preview works but the lights do not

If the preview is wrong: confirm the song and active layout, then inspect the model mapping. For cloud-managed layouts, make the correction in the maintained cloud workflow. For local layouts, check the working xLights arrangement. Continue with EZSequence mapping.

If the preview looks right: inspect the controller's destination, protocol, model assignment and actual cable route. Confirm the intended controller is enabled and reachable. A network reply proves reachability; it does not prove that the correct pixels receive the correct channels. Use controller and network setup.

EZPlayer's preview documentation treats preview as a visual check of show data. The support matrix concerns detailed status and controller actions; absence of a particular management action does not by itself establish failed DDP/E1.31 playback.

Lights flicker, go dark unexpectedly, or two programs disagree

Check which programs are sending to the controllers. Stop unintended xLights, player and test outputs while proving one source. Remember that EZPlayer normally sends blackout frames while idle. For a shared-controller arrangement, inspect Settings → Player → Blackout when idle; with it disabled, the last displayed frame can remain after playback ends. See Player settings and startup.

For stuttering, open Show Status → Stats and record missed/skipped frames, loading errors and the last error. Compare a short known sequence with the troublesome one. The statistics guide describes useful evidence, not a single counter that proves a cable or controller is defective.

Playback is moving but audio is absent or late

Verify the song's audio association, then check the actual output device, mute state and active volume rule. A browser's streamed preview audio is a different listening path from speakers or a transmitter attached to the player computer.

Resolve the wrong file or wrong device first. For a consistent small timing offset, the documented Audio Sync Adjust shifts audio earlier with a negative value and later with a positive value. See Audio settings and audio and show-night operations.

The show does not start or stop as planned

Check the computer's date and local time, the intended schedule occurrence, its playlist and the player state. Confirm the app actually launched after any restart. The Player timeline describes the plan; manual stops and jukebox activity can change what happens. Use Player controls and the scheduling guide to inspect the actual entry and ending policy.

For background effects, observe the version caveat: the official manual says 0.6 and earlier ignore the Overlay/Underlay choice and blend the schedules. A visible selector is not proof of those separate behaviors in 0.6.12. See Background schedule and version caveat.

A phone or remote browser cannot connect

For local access, open Show Status → HTTP Listener Status and use the actual listening port with the player computer's address. The usual port is 3000, but a conflict can cause a fallback. Confirm both devices can reach the intended LAN. Cloud remote access instead needs the registered player's cloud connection. Follow the LAN connection checks and remote access.

Prepare a support packet that shows the failure

Include the app version, operating system, controller model and firmware, layout mode, affected song or schedule, time of the failure and exact error. Explain whether preview, local controller testing and actual playback agree. Include only the relevant screenshots and a short test result.

Keep Player IDs, registration QR codes and private control links out of public posts. The privacy documentation explains why those links grant access. Preserve the working files while investigating; record one change and its result before moving to the next.

EZRGB & EZPlayer Learning Center · Planning tools and checklists

Official references and documentation

EZRGB & EZPlayer Guides · All Mattos learning resources