Troubleshooting Common Issues in ZXTune-Qt: Tips & Fixes

Troubleshooting Common Issues in ZXTune-Qt — Quick Tips & Fixes

Symptom: message like “Could not load the Qt platform plugin ‘xcb’ / ‘windows’”.
Fixes to try (in order):
1. Reinstall zxtune-qt from the official package/bundle you used.
2. On Linux: install missing Qt system libs (example for Debian/Ubuntu):
  - sudo apt update && sudo apt install libxcb-cursor0 libxcb1 libx11-6
  - For Qt6 GUIs: sudo apt install qt6-qpa-plugins
3. If using a Python/conda environment, remove conflicting OpenCV Qt packages or reinstall OpenCV without binaries: pip uninstall opencv-python then pip install –no-binary opencv-python opencv-python (may compile).
4. Set QT_DEBUG_PLUGINS=1 and run the app to see why a plugin failed to load; use that output to identify missing libraries.

Check audio backend in Preferences → Sound. Switch between ALSA/PulseAudio/ALSA plug-ins or the system backend.
Ensure sample rate and buffer sizes match your sound card (Preferences → Mixer).
Disable heavy effects or software resampling; try lower CPU load (close other apps).

Use Add Files / Add Folder; zxtune-qt scans archives/disk images too.
If particular formats are missing, open Help → Components to see unsupported backends (missing codecs/libraries). Install required libs or rebuild with format support.
Re-scan the folder or remove and re-add the folder.

If conversion options are disabled, required external libraries are missing — check Help → Components.
For large conversions enable “Use multithread conversion” in the dialog (only on multi‑CPU systems).
Ensure target path has write permission and enough free space.

Reset layout via View / Layout or manually rearrange components and save layout.
Change interface language in Preferences → Interface and restart if needed.
Delete (or move) the cached settings file if corrupted (config path shown in Help → Components or OS-specific config dirs).