Installation Details

Installing Python

The easiest way to install Python on your system is via Anaconda. To check if the system has a Python distribution installed, open a terminal window and run:

python --version

or for Python 3 specifically:

python3 --version

Opening a Terminal Window

On Windows, press the Windows key and search for “PowerShell”. On macOS, press Cmd + Space and search for “Terminal”.

Creating a Virtual Environment

If Python was installed via Anaconda, a virtual environment can be created via the Terminal with conda:

conda create -n mexca-venv 'Python<3.10'

Then, activate the environment with:

conda activate mexca-venv

Alternatively, you can create a virtual environment with venv:

python -m venv mexca-venv

On Windows, the venv environment can be activated with:

mexca-venv\Scripts\activate

On macOS and Linux, run:

source mexca-venv/bin/activate

Installation

Before installing mexca, make sure, all other Requirements are installed.

After creating and activating the virtual environment, run pip install mexca in the Terminal to install the mexca base package from PyPI. This will only install the dependencies of the base package. The pipeline components can still be run as Docker containers.

Note

This setup requires that Docker is installed on your system.

To run the components without containers, their additional dependencies must be installed via:

pip install mexca[vid,spe,voi,tra,sen]

The abbreviations indicate:

  • vid: FaceExtractor

  • spe: SpeakerIdentifier

  • voi: VoiceExtractor

  • tra: AudioTranscriber

  • sen: SentimentExtractor

All five components can be installed via:

pip install mexca[all]

Note

It is also possible to run some pipeline components with containers and others without. For example, the requirements for only the FaceExtractor can be installed via pip install mexca[vid]

Installing the Development Version

For the latest features and bug fixes, the development version of mexca can be installed from GitHub (requires Git) via:

pip install git+https://github.com/mexca/mexca.git

This command will install the latest developments of mexca on the main branch.

Running Example Notebooks

The mexca GitHub repository contains Jupyter notebooks with examples. This requires that Jupyter is installed, which can be done via:

pip install notebook

To run notebooks in your virtual environment, ipykernel also needs to be installed:

pip install ipykernel

Clone the repository with Git:

git clone https://github.com/mexca/mexca.git
cd mexca # go to package directory

To start Jupyter, run:

jupyter notebook

Select an example notebook in the examples/ folder.

Installation with CUDA

To run mexca on a GPU, PyTorch needs to be installed with CUDA. Note that this does not work with containerized components. If not already installed, download and install the appropriate CUDA toolkit for your operating system. Then, install PyTorch with CUDA support:

pip install torch==2.0.1 torchvision==0.15.2 torchaudio==2.0.2 --index-url https://download.pytorch.org/whl/cu118

It is important that the installed version of the CUDA toolkit matches supported version by PyTorch. In this example, both versions point to CUDA 11.8. If a different CUDA version is installed on your system, you need to install the matches PyTorch version. See this link to find the correct version.

Troubleshooting

This section mentions some reoccuring issues and how to solve them.

Install pypiwin32 package

When running mexca on Windows and depending on the Python distribution, this error can occur when running containerized components for the first time:

docker.errors.DockerException: Install pypiwin32 package to enable npipe:// support

A solution to this problem is running the pypiwin32 postinstall script manually. When mexca was installed in a virtual environment, this can be done via:

python mexca-venv\Scripts\pywin32_postinstall.py -install

Otherwise, search for the location of the script and run it from there.