Skip to content

installation.md

Latest commit

 

History

History
301 lines (216 loc) · 8.61 KB

installation.md

File metadata and controls

301 lines (216 loc) · 8.61 KB
Raw

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

  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 — 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:

  1. Check the GitHub Issues for known problems
  2. 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:

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