The easiest way to install MGT-python is via pip:
pip install musicalgesturesMGT-python requires Python 3.10 or higher. The latest stable version of Python is recommended.
python --version # Should be 3.10+MGT-python is cross-platform and supports:
- Linux (Ubuntu, CentOS, etc.)
- macOS (10.14+)
- Windows (10+)
MGT-python automatically installs the following core dependencies:
numpy- Numerical computingpandas- Data manipulation and analysisscipy- Scientific computingmatplotlib- Plotting and visualisation
opencv-python- Computer vision algorithmsscikit-image- Image processinglibrosa- Audio analysismicromotion- Shared quantity-of-motion, posturography, physiology, and mocap corestqdm- Progress bars
These dependencies are declared in the package metadata and are installed automatically with pip install musicalgestures.
ipython>=7.12- Enhanced Python shell
MGT-python relies on FFmpeg for video processing. Install it based on your operating system:
sudo apt update
sudo apt install ffmpegbrew install ffmpeg- Download FFmpeg from https://ffmpeg.org/download.html
- Extract and add to your system PATH
- Or use Chocolatey:
choco install ffmpeg
ffmpeg -versionOpenCV is typically installed automatically with opencv-python. If you encounter issues:
sudo apt install libgl1-mesa-glx libglib2.0-0The 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) |
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 touchescv2.dnn, so it works on any OpenCV. - On OpenCV 4, if MediaPipe is not installed,
pose()falls back to the OpenPosebody_25backend. 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,cocoandmpiare Caffe models. From 1.11.0pose()says so with anMgDependencyErrorbefore 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.
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.
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 missingThe 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.
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.
pip install musicalgesturesFor 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 .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 musicalgesturesUsing virtual environments prevents dependency conflicts:
# 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 musicalgesturesconda create -n mgt python=3.10
conda activate mgt
pip install musicalgesturesTest 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 countError: ffmpeg not found
Solution: Install FFmpeg following the instructions above.
ImportError: libGL.so.1: cannot open shared object file
Solution (Linux):
sudo apt install libgl1-mesa-glxPermissionError: [WinError 5] Access is denied
Solution: Run terminal as Administrator or use --user flag:
pip install --user musicalgesturesIf using in Jupyter notebooks, you might need:
pip install jupyter ipywidgetsThe 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).
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
Once installed successfully:
- Quick Start Guide - Your first steps with MGT-python
- Examples - Sample code and tutorials
- User Guide - Comprehensive documentation
Consider installing additional optimised libraries:
# For faster NumPy operations
pip install mklGPU acceleration is not provided by the PyPI
opencv-python/opencv-contrib-pythonwheels. They are CPU-only. The CUDA-accelerated paths (flow.dense(use_gpu=True),flow.sparse(use_gpu=True),blur_faces(use_gpu=True), OpenPosedevice='gpu') require an OpenCV built from source with CUDA. See GPU / CUDA acceleration.
For processing large videos, ensure adequate RAM and consider:
- Processing videos in chunks
- Using lower resolution for initial analysis
- Monitoring memory usage with
htopor Task Manager