Fixed Error "Could not load the Qt platform plugin "xcb" mentioned in #101

CHANGELOG.md

@@ -1,7 +1,9 @@
 # 1.2.5 (Pre-release)
+- Fixed `Error "Could not load the Qt platform plugin "xcb"` error that occurred in some Linux distributions due to missing `libxcb-cursor0` library by conditionally loading the bundled library when the system version is unavailable, issue mentioned by @bmcgonag in #101.
 - Fixed the `No module named pip` error that occurred for users who installed Abogen via the [**uv**](https://github.com/astral-sh/uv) installer.
 - Fixed defaults for `replace_single_newlines` not being applied correctly in some cases.
 - Fixed `Save chapters separately for queued epubs is ignored`, issue mentioned by @dymas-cz in #109.
+- Improvements in code and documentation.
 
 # 1.2.4
 - **Subtitle generation is now available for all languages!** Abogen now supports subtitle generation for non-English languages using audio duration-based timing. Available modes include `Line`, `Sentence`, and `Sentence + Comma`. (Note: Word-level subtitle modes remain English-only due to Kokoro's timestamp token limitations.)

abogen/main.py

@@ -3,6 +3,8 @@ import sys
 import platform
 import atexit
 import signal
+from abogen.utils import get_resource_path, load_config, prevent_sleep_end
+
 
 # Fix PyTorch DLL loading issue ([WinError 1114]) on Windows before importing PyQt6
 if platform.system() == "Windows":
@@ -21,6 +23,7 @@ if platform.system() == "Windows":
     except Exception:
         pass
 
+
 # Qt platform plugin detection (fixes #59)
 try:
     from PyQt6.QtCore import QLibraryInfo
@@ -42,6 +45,28 @@ try:
 except ImportError:
     print("PyQt6 not installed.")
 
+
+# Pre-load "libxcb-cursor" on Linux (fixes #101)
+if platform.system() == "Linux":
+    arch = platform.machine().lower()
+    lib_filename = {"x86_64": "libxcb-cursor-amd64.so.0", "amd64": "libxcb-cursor-amd64.so.0", "aarch64": "libxcb-cursor-arm64.so.0", "arm64": "libxcb-cursor-arm64.so.0"}.get(arch)
+    if lib_filename:
+        import ctypes
+        try:
+            # Try to load the system libxcb-cursor.so.0 first
+            ctypes.CDLL('libxcb-cursor.so.0', mode=ctypes.RTLD_GLOBAL)
+        except OSError:
+            # System lib not available, load the bundled version
+            lib_path = get_resource_path('abogen.libs', lib_filename)
+            if lib_path:
+                try:
+                    ctypes.CDLL(lib_path, mode=ctypes.RTLD_GLOBAL)
+                except OSError:
+                    # If it fails (e.g. wrong glibc version on very old systems),
+                    # we simply ignore it and hope the system has the library.
+                    pass
+
+
 # Set application ID for Windows taskbar icon
 if platform.system() == "Windows":
     try:
@@ -64,8 +89,6 @@ from PyQt6.QtCore import (
 # Add the directory to Python path
 sys.path.insert(0, os.path.join(os.path.dirname(__file__)))
 
-from abogen.utils import get_resource_path, load_config, prevent_sleep_end
-
 # Set Hugging Face Hub environment variables
 os.environ["HF_HUB_DISABLE_TELEMETRY"] = "1"  # Disable Hugging Face telemetry
 os.environ["HF_HUB_ETAG_TIMEOUT"] = "10"  # Metadata request timeout (seconds)

pyproject.toml

@@ -65,9 +65,15 @@ exclude = [
     "WINDOWS_INSTALL.bat",
 ]
 
+[tool.hatch.build.targets.sdist.force-include]
+"abogen/libs" = "abogen/libs"
+
 [tool.hatch.build.targets.wheel]
 packages = ["abogen"]
 
+[tool.hatch.build.targets.wheel.force-include]
+"abogen/libs" = "abogen/libs"
+
 [tool.hatch.version]
 path = "abogen/VERSION"
 pattern = "^(?P<version>.+)$"