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

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.9
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.9
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.length:.2f} seconds")

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 may download OpenPose weights on first use. 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, pose estimation falls back to CPU execution.

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:

• 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

# For GPU acceleration (if available)
pip install opencv-contrib-python

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