Contributing to TorchCodec

You can contribute to this project by writing code, fixing issues or simply by using the library and reporting your feedback.

Below are instructions to build TorchCodec from source, as well as the usual contribution guidelines (code formatting, testing, etc). To submit a PR, please follow the official GitHub guidelines.

Building TorchCodec from source

Installing dependencies

The instructions below assume you are using a conda environment, but the steps are easily adaptable to other kind of virtual environments. To build, run and test locally you will need the following dependencies:

• A C++ compiler+linker. This is typically available on a baseline Linux installation already.
• cmake
• pkg-config
• pybind11
• FFmpeg
• PyTorch nightly

Start by installing the nightly build of PyTorch following the official instructions.

Then, the easiest way to install the rest of the dependencies is to run:

conda install cmake pkg-config pybind11 "ffmpeg" -c conda-forge

Clone and build

To clone and install the repo, run:

git clone git@github.com:pytorch/torchcodec.git
# Or, using https instead of ssh: git clone https://github.com/pytorch/torchcodec.git
cd torchcodec

# Optional, but recommended: define a persistent build directory which speeds-up
# subsequent builds.
export TORCHCODEC_CMAKE_BUILD_DIR="${PWD}/build"

pip install -e ".[dev]" --no-build-isolation -vv
# Or, for cuda support: ENABLE_CUDA=1 pip install -e ".[dev]" --no-build-isolation -vv

Running unit tests

To run python tests run:

pytest

Some tests are marked as 'slow' and aren't run by default. You can use pytest -m slow to run those, or pytest -m "" to run all tests, slow or not.

To run the C++ tests run:

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTS=1 -DCMAKE_PREFIX_PATH=$(python3 -c 'import torch;print(torch.utils.cmake_prefix_path)') ..
cmake --build . -- VERBOSE=1
ctest --rerun-failed --output-on-failure

Code formatting and type checking

We use pre-commit to enforce code formatting and mypy for type checking. Install both with

pip install pre-commit mypy

To run pre-commit hooks before each commit, run pre-commit install. You may prefer to run these checks manually, in which case you can just use pre-commit run --all-files.

For mypy we recommend the following command:

mypy --install-types --non-interactive --config-file mypy.ini

Building the docs

First install from source, then install the doc dependencies:

cd docs
pip install -r requirements.txt

Then, still from within the docs directory:

make html

The built docs will be in build/html. Open in your browser to view them.

To avoid building the examples (which execute python code and can take time) you can use make html-noplot. To build a subset of specific examples instead of all of them, you can use a regex like EXAMPLES_PATTERN="plot_the_best_example*" make html.

Run make clean from time to time if you encounter issues.

Serving docs locally (if building from a GPU env)

If you're developing locally, you can just open the generated index.htmlfile in your browser.

If instead you're using a remote machine, you can use a combination of a simple python HTTP server and port forwarding to serve the docs locally. This allows you to iterate on the documentation much more quickly than relying on PR previews.

To do so, after following the above doc build steps, run the following from the docs/build/html folder:

python -m http.server 8000 # or any free port

This will open up a simple HTTP server serving the files in the build directory. If this is done on a remote machine, you can set up port forwarding from your local machine to access the server, for example:

ssh -L 9000:localhost:8000 $REMOTE_DEV_HOST

Now, you can navigate to localhost:9000 on your local machine to view the rendered documentation.

License

By contributing to TorchCodec, you agree that your contributions will be licensed under the LICENSE file in the root directory of this source tree.

Contributors are also required to sign our Contributor License Agreement.