eSpeak NG Loader

Warnings

• breaking The `espeakng-loader` package *does not install* the eSpeak NG text-to-speech engine itself. Users *must* manually install the `espeak-ng` shared library and its data files on their operating system for this Python package to function. Failure to do so will result in `RuntimeError: espeak-ng library not found`.
  Fix: Install `espeak-ng` system-wide. For Debian/Ubuntu, `sudo apt-get install espeak-ng`. For Windows, download and run the installer from the official eSpeak NG GitHub releases page (https://github.com/espeak-ng/espeak-ng/releases). For macOS, you might need to build from source or use a package manager like Homebrew.
• gotcha The eSpeak NG library requires access to its data directory (e.g., containing `phontab` files). If `espeak-ng-data` is not found in a standard location, you might encounter errors like "Error processing file '/usr/local/share/espeak-ng-data/phontab': No such file or directory".
  Fix: Ensure the `espeak-ng-data` directory is in a location where the eSpeak NG library can find it. This might involve setting the `ESPEAK_DATA_PATH` environment variable to point to the correct directory or ensuring a proper system-wide installation.
• gotcha When integrating `espeakng-loader` with the `phonemizer` package, use `phonemizer-fork` instead of the official `phonemizer` package due to an unresolved issue (#191).
  Fix: Install `phonemizer-fork` instead of `phonemizer` if you plan to use it with `espeakng-loader`.
• gotcha On Linux, audio output issues (e.g., no sound) can occur if the underlying `espeak-ng` library has problems with `pcaudiolib` or `pulseaudio`.
  Fix: Ensure `libpulse-dev` is installed before compiling `espeak-ng` (if building from source), or troubleshoot `pulseaudio` configuration. Testing `espeak-ng` from the command line directly can help diagnose if the issue is with the Python loader or the underlying `espeak-ng` installation.

Install

• pip install espeakng-loader Install with pip

Imports

• get_library_path

  from espeakng_loader import get_library_path

• load_library

  from espeakng_loader import load_library

• make_library_available

  from espeakng_loader import make_library_available

Quickstart

This quickstart demonstrates how to retrieve the path to the eSpeak NG shared library using `get_library_path()` and how to load it directly into your Python process with `load_library()`. It also includes guidance on the essential prerequisite of having the eSpeak NG library installed on the system.

import os
from espeakng_loader import get_library_path, load_library, make_library_available

try:
    # Get the path to the loaded eSpeak NG shared library
    library_path = get_library_path()
    print(f"eSpeak NG library path: {library_path}")

    # Example: Directly load the library (returns a ctypes.CDLL object)
    # This is useful if you're writing a direct binding or need the CDLL object.
    espeak_ng_cdll = load_library()
    print(f"eSpeak NG library loaded directly: {espeak_ng_cdll}")
    
    # Example: Make the library available for other systems (e.g., via PATH on Windows/LD_LIBRARY_PATH on Linux)
    # This is typically handled implicitly or by other Python bindings.
    # make_library_available()
    # print("eSpeak NG library made available to system.")

    # Note: To actually use eSpeak NG to speak text, you would typically
    # use another Python package that provides bindings to the C library,
    # like 'espeakng' (pip install espeakng).

except RuntimeError as e:
    print(f"Error: {e}")
    print("Please ensure the eSpeak NG shared library is installed on your system.")
    print("On Ubuntu/Debian: sudo apt-get install espeak-ng")
    print("On Windows, download installer from https://github.com/espeak-ng/espeak-ng/releases")