Welcome to MGT-python! This guide will get you up and running with the Musical Gestures Toolbox in just a few minutes.
Make sure you have MGT-python installed. If not, see the Installation Guide.
pip install musicalgesturesLet's start with a simple example using the built-in sample videos:
import musicalgestures as mg
# Access example videos
examples = mg.examples
print(f"Dance video: {examples.dance}")
print(f"Pianist video: {examples.pianist}")
# Load a video
mv = mg.MgVideo(examples.dance)
print(f"Loaded: {mv.filename}")
print(f"Duration: {mv.length:.2f} seconds")
print(f"Frame rate: {mv.fps} fps")The MgVideo class is your main interface for video analysis:
# Load your own video
mv = mg.MgVideo('path/to/your/video.mp4')
# Or use preprocessing options
mv = mg.MgVideo(
'path/to/video.mp4',
starttime=10, # Start at 10 seconds
endtime=30, # End at 30 seconds
color=False, # Convert to grayscale
filtertype='Regular', # Motion detection filter
threshold=0.1 # Motion threshold
)For audio-only analysis:
# Load audio from video or audio file
ma = mg.MgAudio('path/to/audio.wav')
# Or extract audio from video
mv = mg.MgVideo('video.mp4')
ma = mv.audio # Get the audio componentExtract motion information from your video:
mv = mg.MgVideo(examples.dance)
# Perform motion analysis — returns MgVideo pointing to the motion video
motion_video = mv.motion()
motion_video.show() # watch the motion video
mv.show(key='motion') # equivalent shorthand via source MgVideo
# Motion data (QoM, CoM, AoM per frame) is saved as a CSV alongside the video
import pandas as pd
import os
csv_path = os.path.splitext(motion_video.filename)[0].replace('_motion', '_motiondata') + '.csv'
data = pd.read_csv(csv_path)
print(data.head())Recent motion-analysis fixes ensure centroid-of-motion coordinates are computed as scalar values during motion() and motiondata() runs, which makes notebook and batch execution more robust.
Generate various visualizations:
mv = mg.MgVideo(examples.pianist)
# Motiongrams — returns MgList with [horizontal_mgram, vertical_mgram]
motiongrams = mv.motiongrams()
motiongrams[0].show() # horizontal motiongram
motiongrams[1].show() # vertical motiongram
mv.show(key='horizontal') # shorthand from source MgVideo
# Average image (blend of all frames)
average_img = mv.average()
average_img.show()
# Motion history
history = mv.history()
history.show()Face anonymization also returns a usable result object even when exporting face-coordinate data:
blurred = mv.blur_faces(save_data=True, data_format='csv')
blurred.show(mode='notebook')Analyze the audio component:
mv = mg.MgVideo(examples.pianist)
# Get audio object
audio = mv.audio
# Create waveform plot
waveform = audio.waveform()
print(f"Waveform plot: {waveform}")
# Generate spectrogram
spectrogram = audio.spectrogram()
print(f"Spectrogram: {spectrogram}")
# Extract audio descriptors
descriptors = audio.descriptors()
print(f"Descriptors: {descriptors}")mv = mg.MgVideo(examples.dance)
# pose() defaults to the MediaPipe backend: fast on plain CPU, no CUDA-enabled
# OpenCV build needed, 33 landmarks with depth + visibility (best for one person).
pose_video = mv.pose()
pose_video.show(mode='notebook')
# OpenPose models ('body_25', 'coco', 'mpi') support multi-person analysis but are
# slow without a CUDA-enabled OpenCV build:
pose_video = mv.pose(model='mpi', device='gpu', downsampling_factor=2)On first use, pose estimation downloads the requested model weights if they are not already present (MediaPipe weights by default).
mv = mg.MgVideo(examples.dance)
# CPU is the default for flow and blur_faces.
dense_cpu = mv.flow.dense()
blur_cpu = mv.blur_faces()
# Opt in to CUDA acceleration (falls back to CPU automatically).
dense_gpu = mv.flow.dense(use_gpu=True)
sparse_gpu = mv.flow.sparse(use_gpu=True)
blur_gpu = mv.blur_faces(use_gpu=True)
# Check CUDA availability reported by OpenCV.
print(mg.get_cuda_device_count())resample() returns a new MgVideo (the original is untouched) re-timed by frame rate, playback speed, or frame decimation:
mv = mg.MgVideo(examples.dance)
mv25 = mv.resample(fps=25) # retime to 25 fps (duration-preserving)
fast = mv.resample(speed=2.0) # 2× faster, video + audio in sync
mv25.show()pose_segments() draws a polar rose plot and circular statistics for each body segment (the bone between two joints):
mv = mg.MgVideo(examples.dance)
mv.pose_segments().show() # reuses cached pose keypoints if available
tempo_similarity() compares the audio tempo with the movement tempo and cross-correlates the two rhythms:
mv = mg.MgVideo(examples.dance)
ts = mv.tempo_similarity()
ts.show()
print(ts.data['audio_tempo_bpm'], ts.data['motion_tempo_bpm'])
See the dedicated Audio-Video Processing & Analysis page for the full suite (phase synchrony, structure comparison, body–audio and dynamics coupling).
MGT-python works with most common video formats:
- MP4, AVI, MOV, MKV
- Audio: WAV, MP3, FLAC, etc.
# 1. Load and preprocess
mv = mg.MgVideo(
'my_video.mp4',
starttime=5, # Skip first 5 seconds
endtime=60, # Use only first minute
color=False # Grayscale for motion analysis
)
# 2. Perform motion analysis
motion = mv.motion()
# 3. Create visualizations
motiongrams = mv.motiongrams()
average = mv.average()
# 4. Analyze audio
audio_analysis = mv.audio.spectrogram()
print("Analysis complete!")MGT-python creates several types of output files:
*_motion.avi- Motion detection video*_history.avi- Motion history visualization
*_average.png- Average of all frames*_mgh.png- Horizontal motiongram*_mgv.png- Vertical motiongram
*_motiondata.csv- Numerical motion data*_descriptors.csv- Audio feature data
By default, outputs are saved in the same directory as your input video. Use target_name on individual methods to control the output path for a specific result.
MGT-python works great in Jupyter notebooks:
import musicalgestures as mg
import matplotlib.pyplot as plt
# Load video
mv = mg.MgVideo(mg.examples.dance)
# Create motion analysis
motion = mv.motion()
# Display results inline
plt.figure(figsize=(12, 4))
mv.show() # Shows the video playerProcess multiple videos:
import glob
video_files = glob.glob('videos/*.mp4')
for video_file in video_files:
print(f"Processing: {video_file}")
mv = mg.MgVideo(video_file)
# Perform analysis
motion = mv.motion()
motiongrams = mv.motiongrams()
print(f"Completed: {video_file}")Now that you're familiar with the basics, explore more advanced features:
- Loading & Showing - How to load videos and display results
- Preprocessing - Trim, crop, rotate, and adjust videos
- Video Analysis - Motion analysis, optical flow, pose estimation
- Audio Analysis - Waveforms, spectrograms, and audio features
- Working with Results - MgFigure, MgImage, MgList, and chaining
- API Reference - Complete method documentation
# Check if file exists and is readable
import os
video_path = 'my_video.mp4'
if os.path.exists(video_path):
print(f"File found: {video_path}")
else:
print(f"File not found: {video_path}")If you get FFmpeg-related errors, ensure FFmpeg is installed:
ffmpeg -versionSee the Installation Guide for help with FFmpeg setup.
For large videos, consider:
# Process shorter segments
mv = mg.MgVideo('large_video.mp4', starttime=0, endtime=30)
# Or thin out the frames at load time (keep 1 of every skip+1 frames)
mv = mg.MgVideo('large_video.mp4', skip=2)
# Or re-time an already-loaded video to a lower frame rate
mv = mg.MgVideo('large_video.mp4').resample(fps=15)Ready to dive deeper? Check out our comprehensive User Guide!