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. The latest stable version of Python is recommended.

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 visualisation

Computer Vision & Media Processing

• opencv-python - Computer vision algorithms
• scikit-image - Image processing
• librosa - Audio analysis
• micromotion - Shared quantity-of-motion, posturography, physiology, and mocap cores
• tqdm - Progress bars

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

1. Download FFmpeg from https://ffmpeg.org/download.html
2. Extract and add to your system PATH
3. 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, including 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

Which backends you can use depends on your OpenCV:

• With musicalgestures[pose], the default MediaPipe backend is used, which is recommended: faster on CPU, 33 landmarks, and no CUDA-enabled OpenCV build needed. It carries its own weights and never touches cv2.dnn, so it works on any OpenCV.
• On OpenCV 4, if MediaPipe is not installed, pose() falls back to the OpenPose body_25 backend. This uses OpenCV's DNN module and auto-downloads ~200 MB of Caffe weights on first use.
• On OpenCV 5, the OpenPose backends cannot run at all. OpenCV removed its Caffe importer in 5.0, and body_25, coco and mpi are Caffe models. From 1.11.0 pose() says so with an MgDependencyError before looking for weights, instead of failing deep in the run after offering a download the environment could never use. Install MediaPipe, or install OpenCV 4 (pip install 'opencv-python<5') if you need the OpenPose skeletons. They are not interchangeable: 33 landmarks against BODY_25's 25 is a different skeleton.

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), musicalgestures[cli] (the musicalgestures command-line tool), and musicalgestures[soundscape] (the ambiscape bridge) are also available; musicalgestures[full] installs pose, c3d, ml, cli, and soundscape 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 the installed version
from importlib.metadata import version
print(version('musicalgestures'))

# 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, either 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:

1. Check the GitHub Issues for known problems
2. Create a new issue with:
3. Your operating system and version
4. Python version (python --version)
5. Complete error message
6. 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 Optimisation

For Large Video Files

Consider installing additional optimised 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