Contributing to Piper

Contributions are welcome! This guide provides instructions on how to set up a development environment, build the project from source, and run tests.

1. Setting Up a Development Environment

First, you will need to install the required system packages. For Debian-based systems like Ubuntu, run:

sudo apt-get update
sudo apt-get install build-essential cmake ninja-build git

Next, clone the repository and set up a Python virtual environment:

git clone https://github.com/OHF-voice/piper1-gpl.git
cd piper1-gpl
python3 -m venv .venv
source .venv/bin/activate

Now, install the project in editable mode with its development dependencies. This is specified under the [dev] extra in setup.py.

pip install -e '.[dev]'

This command installs tools like black, flake8, mypy, pylint, and pytest.

2. Building the Project

Piper uses scikit-build-core and cmake to build a Python module that embeds espeak-ng. This allows for a self-contained package with no runtime dependency on a system-installed espeak-ng.

The build process is managed by setup.py and CMakeLists.txt.

To build the C extension in place for development, run the following command from the root of the repository:

python3 setup.py build_ext --inplace

Alternatively, you can use the provided helper script, which is also used in the CI pipeline:

./script/dev_build

After a successful build, you should have a file named espeakbridge.cpython-*.so (on Linux) or similar inside the src/piper/ directory. You can now run Piper directly from the source tree:

python3 -m piper --help

3. Running Tests

Piper uses pytest for its test suite. The GitHub Actions workflow defined in .github/workflows/test.yml provides a reference for the testing process.

To run the tests locally, first make sure you have built the project as described above. Then, execute the test script:

./script/test

This will run the test suite and report any failures.

4. Building Wheels

If you need to build distributable wheel packages, you can use the build package:

python3 -m build

This command will create Python wheels (.whl) in the dist/ directory, which can then be installed with pip.

The GitHub Actions workflow in .github/workflows/wheels.yml uses cibuildwheel to create wheels for multiple platforms and Python versions.