MGT-python

PyPi version Python GitHub license CI Documentation DOI

The Musical Gestures Toolbox for Python (musicalgestures) is a collection of tools for visualising and analysing motion in video recordings, along with the accompanying sound. It was developed for research on music-related body motion, but it works on any video or audio file.

MGT python

Installation

pip install musicalgestures

You also need FFmpeg on your system; everything else installs automatically. The installation guide covers optional extras such as pose estimation.

Quickstart

import musicalgestures as mg

v = mg.MgVideo(mg.examples.dance)   # or your own file: mg.MgVideo('dance.mp4')
v.motiongrams().show()

This draws motiongrams: images that trace where movement happens in the frame over time, like a spectrogram for the body. Analysis methods return result objects, and .show() displays them.

You can also try the toolbox in the browser, with no installation:

Open In Colab

Documentation

  • Documentation site — installation, quickstart, user guide, and full API reference
  • Wiki — worked examples and discussion of the methods
  • Contributing — how to report issues and submit changes

The four toolboxes

Four packages from the fourMs Lab at the University of Oslo, each released separately on PyPI. Which one you want is decided by what you have in hand rather than by what you want to know:

you have use it gives you
a video file, with or without its sound musicalgestures (this one) motiongrams, videograms, motion analysis from ordinary video
a motion time series from a body — optical markers, an accelerometer, a respiration belt, a force plate micromotion quantity of motion, posture, balance, and the band conventions the others follow
a recording of a place — mono, stereo, binaural or ambisonic ambiscape the sonic ambience of that place: level, spectrum, space, rhythm, sources
a folder of music, or a concert recording musiscape many tracks and albums compared at a glance

Where a measure appears in more than one package it has a single owner and a single implementation, so the answer does not depend on which package you called. This package owns everything that starts from pixels; micromotion owns filtering, lag estimation and circular statistics, and this package requires it, re-exporting its group_qom, bandpass and xcorr_lag rather than keeping its own. A test here checks the numbers against micromotion's and fails if they diverge.

One name is deliberately NOT shared. musicalgestures.dominant_frequency takes an FFT peak over 0.5–8.0 Hz, for locomotion and dance; micromotion.dominant_frequency takes a Welch peak over 0.3–4.0 Hz, for a body trying to stay still. They answer different questions and can disagree completely, so state which one produced any number you report.

Citing

If you use this toolbox in your research, please cite:

Laczkó, B., & Jensenius, A. R. (2021). Reflections on the Development of the Musical Gestures Toolbox for Python. Proceedings of the Nordic Sound and Music Computing Conference, Copenhagen.

If you want to cite the toolbox itself, use the Zenodo CONCEPT DOI, which always resolves to the newest version:

Jensenius, A. R., Laczkó, B., Poutaraud, J., Widmer, M., Furmyr, F., Guo, J., Clim, A., Upham, F., & von Arnim, H. A. (2026). Musical Gestures Toolbox for Python [Computer software]. Zenodo https://doi.org/10.5281/zenodo.21965729

Where the exact behaviour matters, cite the version you ran.

An older concept DOI, https://doi.org/10.5281/zenodo.21949007, is frozen at 1.11.1. It was created by a hand deposit made on 2026-08-15, before the Zenodo GitHub integration was archiving this repository; the integration began working the next day and every release since is under the DOI above. Zenodo cannot merge two concepts, so both records exist and only one of them advances. Cite the DOI above.

CITATION.cff in this repository carries the same information in machine-readable form.

Credits

This toolbox builds on the Musical Gestures Toolbox for Matlab, which again builds on the Musical Gestures Toolbox for Max. Many researchers and research assistants have helped its development (both directly and indirectly) over the years; see the contributor list on Zenodo for details.

The fourMs lab maintains the software at the RITMO Centre for Interdisciplinary Studies in Rhythm, Time and Motion, University of Oslo.

License

This toolbox is released under the GNU General Public License 3.0.

Project links

Data verified by PyPI on Aug 24, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.18.0)

2 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for fisheggg from gravatar.com fisheggg Avatar for fourMs from gravatar.com fourMs

Credits

Author: University of Oslo fourMs Lab

GitHub Statistics

Data verified by PyPI on Aug 24, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

GNU General Public License v3 (GPLv3) (GPL-3.0-or-later)

Requires

Python >=3.10

Provides Extra

pose c3d ml cli dev soundscape full

Tags

computer vision motion analysis musical gestures video analysis

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

musicalgestures-1.14.1.tar.gz (32.7 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

musicalgestures-1.14.1-py3-none-any.whl (32.6 MB view details)

Uploaded Python 3

File details

Details for the file musicalgestures-1.14.1.tar.gz.

File metadata

  • Download URL: musicalgestures-1.14.1.tar.gz
  • Upload date:
  • Size: 32.7 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for musicalgestures-1.14.1.tar.gz
Algorithm Hash digest
SHA256 adbdc0a98bde1f42e5e43c6aebeb5e9139045a246fed34a557bd1c62d8767ba9
MD5 70b908b056c6d8c5b53d538a723f2a7c
BLAKE2b-256 8cbedfaf49b58d07ca1faf6b673a60822167b5fd45b8cc501181b363bcb93633

See more details on using hashes here.

Provenance

The following attestation bundles were made for musicalgestures-1.14.1.tar.gz:

Publisher: pypi-publish.yml on fourMs/MGT-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file musicalgestures-1.14.1-py3-none-any.whl.

File metadata

File hashes

Hashes for musicalgestures-1.14.1-py3-none-any.whl
Algorithm Hash digest
SHA256 885fed6f8ab594b01f10cee300d2906b197f733c4d5ff1fdb56a208cb33d3dce
MD5 5f1094f20996c5cf924d93a27d3d6d72
BLAKE2b-256 824ad4898abbf3c255e96a2723e3c6b7a5a5dfaea20cc0c1dd264da567dc9abd

See more details on using hashes here.

Provenance

The following attestation bundles were made for musicalgestures-1.14.1-py3-none-any.whl:

Publisher: pypi-publish.yml on fourMs/MGT-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

1.18.0

2 files

1.17.0

2 files

1.16.0

2 files

1.15.0

2 files

1.14.2

2 files

This release

1.14.1 This release

2 files

1.14.0

2 files

1.13.0

2 files

1.12.1

2 files

1.12.0

2 files

1.11.4

2 files

1.11.3

2 files

1.11.2

2 files

1.11.1

2 files

1.11.0

2 files

1.10.0

2 files

1.9.2

2 files

1.9.1

2 files

1.9.0

2 files

1.8.0

2 files

1.7.1

2 files

1.7.0

2 files

1.6.9

2 files

1.6.8

2 files

1.6.7

2 files

1.6.6

2 files

1.6.5

2 files

1.6.4

2 files

1.6.3

2 files

1.6.2

2 files

1.6.1

2 files

1.6.0

2 files

1.5.0

2 files

1.4.9

2 files

1.4.8

2 files

1.4.7

2 files

1.4.6

2 files

1.4.5

2 files

1.4.4

2 files

1.4.3

2 files

1.4.2

2 files

1.4.0

2 files

1.3.3

2 files

1.3.2

2 files

1.3.0

2 files

1.2.9

2 files

1.2.8

2 files

1.2.7

2 files

1.2.6

2 files

1.2.5

2 files

1.2.4

2 files

1.2.3

2 files

1.2.2

2 files

1.2.1

2 files

1.2.0

2 files

1.1.9

2 files

1.1.7

2 files

1.1.6

2 files

1.1.5

2 files

1.1.4

2 files

1.1.3

2 files

1.1.1

2 files

1.1.0

2 files

1.0.999

2 files

1.0.6

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page