Installation Guide¶

Quick Installation¶

The easiest way to install MGT-python is via pip:

pip install musicalgestures

System Requirements¶

Python Version¶

MGT-python requires Python 3.10 or higher. We recommend using the latest stable version of Python.

python --version  # Should be 3.10+

Operating Systems¶

MGT-python is cross-platform and supports:

Linux (Ubuntu, CentOS, etc.)
macOS (10.14+)
Windows (10+)

Dependencies¶

MGT-python automatically installs the following core dependencies:

Core Scientific Libraries¶

numpy - Numerical computing
pandas - Data manipulation and analysis
scipy - Scientific computing
matplotlib - Plotting and visualization

Computer Vision & Media Processing¶

opencv-python - Computer vision algorithms
scikit-image - Image processing
librosa - Audio analysis

These dependencies are declared in the package metadata and are installed automatically with pip install musicalgestures.

Interactive Computing¶

ipython>=7.12 - Enhanced Python shell

External Dependencies¶

FFmpeg (Required)¶

MGT-python relies on FFmpeg for video processing. Install it based on your operating system:

Ubuntu/Debian¶

sudo apt update
sudo apt install ffmpeg

macOS (with Homebrew)¶

brew install ffmpeg

Windows¶

Download FFmpeg from https://ffmpeg.org/download.html
Extract and add to your system PATH
Or use Chocolatey: choco install ffmpeg

Verify FFmpeg Installation¶

ffmpeg -version

OpenCV (Usually automatic)¶

OpenCV is typically installed automatically with opencv-python. If you encounter issues:

Linux additional packages¶

sudo apt install libgl1-mesa-glx libglib2.0-0

Optional Dependencies (Extras)¶

The core pip install musicalgestures already covers the large majority of features — motion analysis, motiongrams/videograms, average/blend, heatmap, space-time visualisations (stroboscope, silhouette waterfall, motion history), audio analysis (librosa), optical flow on the CPU, face blurring, and more. A few capabilities need an optional dependency or a specially-built OpenCV. Install only what you need:

Feature	Install / requirement
Everything in the table below	`pip install musicalgestures[full]`
Pose estimation — default backend (MediaPipe)	`pip install musicalgestures[pose]`
C3D motion-capture export (`pose(data_format='c3d')`)	`pip install musicalgestures[c3d]`
GPU acceleration (`flow.dense(use_gpu=True)`, `flow.sparse(use_gpu=True)`, `blur_faces(use_gpu=True)`, OpenPose `device='gpu'`)	OpenCV built with CUDA (see GPU / CUDA acceleration below)

Pose estimation¶

pose() works with or without an extra installed:

With musicalgestures[pose], the default MediaPipe backend is used — recommended: faster on CPU, 33 landmarks, and no CUDA-enabled OpenCV build needed.
If MediaPipe is not installed, pose() automatically falls back to the OpenPose body_25 backend. This uses the always-present OpenCV DNN module and auto-downloads ~200 MB of Caffe weights on first use — so pose estimation works either way.

Pose model weights are downloaded automatically on first use via Python's urllib (cross-platform, no wget or platform-specific download scripts) — nothing extra to install.

C3D export¶

pose(data_format='c3d') writes a .c3d motion-capture file and needs the optional c3d package (pip install musicalgestures[c3d]). All other data_format values ('csv', 'tsv', 'txt') work with the core install.

GPU / CUDA acceleration¶

flow.dense(use_gpu=True), flow.sparse(use_gpu=True), blur_faces(use_gpu=True), and the OpenPose backends with device='gpu' all require an OpenCV built with CUDA support (the standard pip opencv-python wheels are CPU-only). Every one of these calls falls back to the CPU automatically when CUDA is unavailable, so code stays portable. Check what your build offers:

import musicalgestures as mg

mg.cuda_build_available()    # True if OpenCV was compiled with CUDA
mg.get_cuda_device_count()   # number of CUDA devices visible to OpenCV
mg.cuda_unavailable_reason() # human-readable explanation when CUDA is missing

The MediaPipe pose backend is the exception: pose(model='mediapipe', device='gpu') can use a GPU through MediaPipe's own delegate with the standard pip OpenCV — no CUDA build required.

Other extras¶

musicalgestures[ml] (scikit-learn/torch) and musicalgestures[cli] (the musicalgestures command-line tool) are also available; musicalgestures[full] installs pose, c3d, ml, and cli together.

Installation Methods¶

1. Standard Installation (Recommended)¶

pip install musicalgestures

2. Development Installation¶

For contributing or using the latest features:

# Clone the repository
git clone https://github.com/fourMs/MGT-python.git
cd MGT-python

# Install in development mode
pip install -e .

3. Conda Installation¶

While not officially supported, you can use conda for dependency management:

# Create a new environment
conda create -n mgt python=3.10
conda activate mgt

# Install pip dependencies
pip install musicalgestures

Virtual Environments (Recommended)¶

Using virtual environments prevents dependency conflicts:

Using venv¶

# Create virtual environment
python -m venv mgt-env

# Activate (Linux/macOS)
source mgt-env/bin/activate

# Activate (Windows)
mgt-env\Scripts\activate

# Install MGT-python
pip install musicalgestures

Using conda¶

conda create -n mgt python=3.10
conda activate mgt
pip install musicalgestures

Verification¶

Test your installation:

import musicalgestures as mg

# Check version
print(mg.__version__)

# Load example data
examples = mg.examples
print(f"Dance video: {examples.dance}")
print(f"Pianist video: {examples.pianist}")

# Basic functionality test
mv = mg.MgVideo(examples.dance)
print(f"Video loaded: {mv.filename}")
print(f"Duration: {mv.duration:.2f} seconds")   # .duration is seconds; .length is the frame count

Troubleshooting¶

Common Issues¶

1. FFmpeg not found¶

Error: ffmpeg not found

Solution: Install FFmpeg following the instructions above.

2. OpenCV import errors¶

ImportError: libGL.so.1: cannot open shared object file

Solution (Linux):

sudo apt install libgl1-mesa-glx

3. Permission errors on Windows¶

PermissionError: [WinError 5] Access is denied

Solution: Run terminal as Administrator or use --user flag:

pip install --user musicalgestures

4. Jupyter Notebook integration¶

If using in Jupyter notebooks, you might need:

pip install jupyter ipywidgets

5. Pose estimation in notebooks¶

The pose() workflow downloads its model weights on first use — MediaPipe weights for the default backend, or the larger OpenPose Caffe weights when an OpenPose model ('body_25'/'coco'/'mpi') is selected. In non-interactive environments such as notebooks, the download is attempted automatically rather than prompting for input. If CUDA-backed OpenCV DNN support is unavailable, OpenPose models fall back to CPU execution (MediaPipe runs on plain CPU regardless).

Getting Help¶

If you encounter installation issues:

Check the GitHub Issues for known problems
Create a new issue with:
Your operating system and version
Python version (python --version)
Complete error message
Installation method used

Next Steps¶

Once installed successfully:

Quick Start Guide - Your first steps with MGT-python
Examples - Sample code and tutorials
User Guide - Comprehensive documentation

Performance Optimization¶

For Large Video Files¶

Consider installing additional optimized libraries:

# For faster NumPy operations
pip install mkl

GPU acceleration is not provided by the PyPI opencv-python/opencv-contrib-python wheels — they are CPU-only. The CUDA-accelerated paths (flow.dense(use_gpu=True), flow.sparse(use_gpu=True), blur_faces(use_gpu=True), OpenPose device='gpu') require an OpenCV built from source with CUDA. See GPU / CUDA acceleration.

Memory Management¶

For processing large videos, ensure adequate RAM and consider: - Processing videos in chunks - Using lower resolution for initial analysis - Monitoring memory usage with htop or Task Manager