Installing keyed-extras

keyed-extras extends the keyed animation library by providing additional features and capabilities exclusively to GitHub sponsors .

1. Install System Dependencies

First, install the required (and optional) system dependencies for keyed-extras.

Dependency	Required for	Installation Priority
Cairo	Core rendering functionality	Required
FFmpeg	Faster video rendering	Recommended
Pango	Rich text formatting	Optional
librsvg	SVG rendering	Optional

Choose the method that works best for your system:

(Recommended) conda - Any Platform

Create an environment.yml file:

environment.yml

name: keyed-pypi
channels:
- conda-forge
- nodefaults
dependencies:
- python<3.13,>=3.11
- ffmpeg
- cairo
- pycairo
- pango>=1.56.0
- pygobject
- librsvg
- pip
- pip:
    - --extra-index-url https://dougmercer.github.io/keyed-extras-docs/pypi/simple # (1)!
    - keyed[previewer]
    - keyed-extras>=0.1.0

1. This requires setting up authentication for the keyed-extras package registry. Jump to those instructions then come back here.

   Otherwise, you can comment out this line and the keyed-extras line below if you want to use the direct download approach.

After creating your environment.yml file, run:

conda env create -f environment.yml
conda activate keyed

Ubuntu/Debian

sudo apt-get update && sudo apt-get install -y \
    # Required dependencies
    libcairo2-dev \
    pkg-config \
    python3-dev \
    gcc \
    # Optional but recommended dependencies
    ffmpeg \              # Enables faster ffmpeg-based rendering
    libpango1.0-dev \     # Enables the RichText object
    librsvg2-dev          # Enables the SVG object for rendering SVG files

macOS

brew install cairo ffmpeg pango librsvg

Fedora

sudo dnf install cairo-devel pkg-config python3-devel ffmpeg pango-devel librsvg2-devel

Arch Linux

sudo pacman -S cairo pkgconf ffmpeg pango librsvg

Windows

Windows support is entirely untested!

Until wonderful people like you contribute and test more robust installation instructions, I recommend using the conda installation instructions instead.

1. Install MSYS2

2. Open MSYS2 MinGW 64-bit terminal and run:

   pacman -S mingw-w64-x86_64-cairo mingw-w64-x86_64-pango mingw-w64-x86_64-gtk3 mingw-w64-x86_64-librsvg
   

3. Add the MSYS2 bin directory to your PATH (typically C:\msys64\mingw64\bin)

4. Download and install FFmpeg for Windows

After, proceed to step 2.

2. Install the keyed-extras Python Package

After installing system dependencies, you need to install the keyed-extras Python package. Choose one of these methods:

Option A: Package Registry with GitHub Authentication

We provide a simple Python package index at https://dougmercer.github.io/keyed-extras-docs/pypi/simple.

This will allow you to use pip to install the latest version keyed-extras, like

pip install keyed-extras --extra-index-url https://dougmercer.github.io/keyed-extras-docs/pypi/simple

Authentication Setup

Before running this command, you need to set up authentication:

1. Ensure you're an active sponsor of keyed on GitHub
2. Create a GitHub Personal Access Token with:
3. Resource Owner: dougmercer-yt
4. Repository access: "Only select repositories" (dougmercer-yt/keyed-extras)
5. Permissions: "Contents" (Read-only)
6. Create a .netrc file in your home directory with:

   machine github.com
   login YOUR_GITHUB_USERNAME
   password YOUR_GITHUB_TOKEN
   

and give it permissions

chmod 600 ~/.netrc

Troubleshooting Package Registry Issues

• "Repository not found": Verify you're an active sponsor and have access to dougmercer-yt/keyed-extras when logged into GitHub
• "401 Unauthorized": Check your GitHub token permissions and .netrc file format
• If problems persist, try the Direct Download method instead

Option B: Direct Download

Each release is available as a Python wheel on the keyed-extras releases page.

1. Log into GitHub with your sponsor account
2. Visit the releases page
3. Download the latest .whl file

4. Install using pip:

   # Note (replace with the actual version number and file path):
   pip install keyed_extras-0.1.0-py3-none-any.whl
   

Advantages of Direct Download

• Simpler authentication (just log into GitHub in your browser)
• No need to set up .netrc
• Save a local copy of the package

Limitations of Direct Download

• Must manually download new versions
• Can't use pip install --upgrade for updates