From 4386b5ce3b6568df3c9b801763471be6173db3fc Mon Sep 17 00:00:00 2001
From: Alexander Refsum Jensenius <arjensenius@gmail.com>
Date: Mon, 13 Apr 2026 22:29:40 +0200
Subject: [PATCH 1/3] Stabilize ffprobe-based utils tests across platforms

---
 tests/test_utils.py | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/tests/test_utils.py b/tests/test_utils.py
index ad4ff04..ced7bf8 100644
--- a/tests/test_utils.py
+++ b/tests/test_utils.py
@@ -633,7 +633,8 @@ def test_length(self, tmp_path):
             musicalgestures.examples.dance, 3, 4, target_name=target_name)
         fps = get_fps(musicalgestures.examples.dance)
         result_framecount = get_framecount(result)
-        assert fps - 1 <= result_framecount <= fps + 1
+        # ffmpeg/ffprobe frame rounding can vary slightly across platforms.
+        assert abs(result_framecount - round(fps)) <= 2
 
     def test_start_later_than_end(self, tmp_path, testvideo_avi):
         target_name = str(tmp_path).replace(
@@ -902,19 +903,19 @@ class Test_get_length:
     def test_video(self):
         result = get_length(musicalgestures.examples.dance)
         assert type(result) == float
-        assert result == 62.84
+        assert abs(result - 62.84) <= 0.1
 
     def test_audio(self, testaudio):
         result = get_length(testaudio)
         assert type(result) == float
-        assert result == 62.86
+        assert abs(result - 62.86) <= 0.1
 
 
 class Test_get_framecount:
     def test_get_framecount(self):
         result = get_framecount(musicalgestures.examples.dance)
         assert type(result) == int
-        assert result == 1571
+        assert abs(result - 1571) <= 1
 
 
 class Test_get_fps:

From 1e90d2cb6d469bf9ab7933ae4b536ad41aa54003 Mon Sep 17 00:00:00 2001
From: alexarje <114316+alexarje@users.noreply.github.com>
Date: Tue, 14 Apr 2026 04:14:59 +0000
Subject: [PATCH 2/3] Update documentation

---
 docs/musicalgestures/_centerface.md     |  14 +-
 docs/musicalgestures/_cropvideo.md      |   6 +-
 docs/musicalgestures/_flow.md           |   8 +-
 docs/musicalgestures/_pose.md           |  44 ++++--
 docs/musicalgestures/_pose_estimator.md |  20 +--
 docs/musicalgestures/_utils.md          | 169 ++++++++++++++----------
 docs/musicalgestures/index.md           |   2 +-
 7 files changed, 156 insertions(+), 107 deletions(-)

diff --git a/docs/musicalgestures/_centerface.md b/docs/musicalgestures/_centerface.md
index ad6ab0e..82bc165 100644
--- a/docs/musicalgestures/_centerface.md
+++ b/docs/musicalgestures/_centerface.md
@@ -12,16 +12,16 @@
 
 ## CenterFace
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_centerface.py#L7)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_centerface.py#L8)
 
 ```python
 class CenterFace(object):
-    def __init__(landmarks=True):
+    def __init__(landmarks=True, use_gpu=False):
 ```
 
 ### CenterFace().decode
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_centerface.py#L53)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_centerface.py#L62)
 
 ```python
 def decode(heatmap, scale, offset, landmark, size, threshold=0.1):
@@ -29,7 +29,7 @@ def decode(heatmap, scale, offset, landmark, size, threshold=0.1):
 
 ### CenterFace().inference_opencv
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_centerface.py#L21)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_centerface.py#L30)
 
 ```python
 def inference_opencv(img, threshold):
@@ -37,7 +37,7 @@ def inference_opencv(img, threshold):
 
 ### CenterFace().nms
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_centerface.py#L87)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_centerface.py#L96)
 
 ```python
 def nms(boxes, scores, nms_thresh):
@@ -45,7 +45,7 @@ def nms(boxes, scores, nms_thresh):
 
 ### CenterFace().postprocess
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_centerface.py#L35)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_centerface.py#L44)
 
 ```python
 def postprocess(heatmap, lms, offset, scale, threshold):
@@ -53,7 +53,7 @@ def postprocess(heatmap, lms, offset, scale, threshold):
 
 ### CenterFace().transform
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_centerface.py#L30)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_centerface.py#L39)
 
 ```python
 def transform(h, w):
diff --git a/docs/musicalgestures/_cropvideo.md b/docs/musicalgestures/_cropvideo.md
index 86aa1ff..36457c1 100644
--- a/docs/musicalgestures/_cropvideo.md
+++ b/docs/musicalgestures/_cropvideo.md
@@ -12,7 +12,7 @@
 
 ## async_subprocess
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_cropvideo.py#L239)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_cropvideo.py#L243)
 
 ```python
 async def async_subprocess(command):
@@ -59,7 +59,7 @@ Helper function to find the area of motion in a video, using ffmpeg.
 
 ## manual_text_input
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_cropvideo.py#L282)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_cropvideo.py#L286)
 
 ```python
 def manual_text_input():
@@ -104,7 +104,7 @@ Crops the video using ffmpeg.
 
 ## run_cropping_window
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_cropvideo.py#L258)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_cropvideo.py#L262)
 
 ```python
 def run_cropping_window(imgpath, scale_ratio, scaled_width, scaled_height):
diff --git a/docs/musicalgestures/_flow.md b/docs/musicalgestures/_flow.md
index cfcf866..31fbbb8 100644
--- a/docs/musicalgestures/_flow.md
+++ b/docs/musicalgestures/_flow.md
@@ -77,7 +77,7 @@ Renders a dense optical flow video of the input video file using `cv2.calcOptica
 
 ### Flow().get_acceleration
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_flow.py#L252)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_flow.py#L288)
 
 ```python
 def get_acceleration(velocity, fps):
@@ -85,7 +85,7 @@ def get_acceleration(velocity, fps):
 
 ### Flow().get_velocity
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_flow.py#L262)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_flow.py#L298)
 
 ```python
 def get_velocity(
@@ -101,7 +101,7 @@ def get_velocity(
 
 ### Flow().sparse
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_flow.py#L277)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_flow.py#L313)
 
 ```python
 def sparse(
@@ -141,7 +141,7 @@ Renders a sparse optical flow video of the input video file using `cv2.calcOptic
 
 ### Flow().velocity_meters_per_second
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_flow.py#L270)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_flow.py#L306)
 
 ```python
 def velocity_meters_per_second(
diff --git a/docs/musicalgestures/_pose.md b/docs/musicalgestures/_pose.md
index 200dcc0..eb0dd5f 100644
--- a/docs/musicalgestures/_pose.md
+++ b/docs/musicalgestures/_pose.md
@@ -6,9 +6,13 @@
     - [download_model](#download_model)
     - [pose](#pose)
 
+#### Attributes
+
+- `MEDIAPIPE_POSE_CONNECTIONS` - MediaPipe Pose skeleton connections (pairs of landmark indices): `[(0, 1), (1, 2), (2, 3), (3, 7), (0, 4), (4, 5)...`
+
 ## download_model
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_pose.py#L370)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_pose.py#L582)
 
 ```python
 def download_model(modeltype):
@@ -42,21 +46,37 @@ Outputs the predictions in a text file containing the normalized x and y coordin
 
 Supports two backends:
 
-- **MediaPipe** (`model='mediapipe'`): Uses Google's MediaPipe Pose which detects 33 landmarks entirely on CPU. Requires the optional `mediapipe` package (`pip install musicalgestures[pose]`). The model file (~8–28 MB) is auto-downloaded on first use and cached in `musicalgestures/models/`.
-- **OpenPose** (`model='body_25'`, `'coco'`, or `'mpi'`): Uses Caffe-based OpenPose models. Model weights (~200 MB) are downloaded on first use.
+* **MediaPipe** (``model='mediapipe'``): Uses Google's MediaPipe Pose which detects 33
+  landmarks entirely on CPU.  Requires the optional ``mediapipe`` package
+  (``pip install musicalgestures[pose]``).  On first use, the model file
+  (~8–28 MB) is downloaded automatically and cached in ``musicalgestures/models/``.
+* **OpenPose** (``model='body_25'``, ``'coco'``, or ``'mpi'``): Uses Caffe-based OpenPose
+  models.  Model weights (~200 MB) are downloaded on first use.
 
 #### Arguments
 
-- `model` *str, optional* - Pose model to use. `'mediapipe'` uses MediaPipe Pose (33 landmarks, model auto-downloaded on first use). `'body_25'` loads the OpenPose BODY_25 model (25 keypoints), `'mpi'` loads the MPII model (15 keypoints), `'coco'` loads the COCO model (18 keypoints). Defaults to 'body_25'.
-- `device` *str, optional* - Sets the backend to use for the neural network ('cpu' or 'gpu'). Ignored when `model='mediapipe'` (MediaPipe always runs on CPU). Defaults to 'gpu'.
-- `threshold` *float, optional* - The normalized confidence threshold that decides whether we keep or discard a predicted point. Discarded points get substituted with (0, 0) in the output data. Defaults to 0.1.
-- `downsampling_factor` *int, optional* - Decides how much we downsample the video before we pass it to the neural network. Ignored when `model='mediapipe'`. Defaults to 2.
+- `model` *str, optional* - Pose model to use. ``'mediapipe'`` uses MediaPipe Pose (33
+    landmarks, model auto-downloaded on first use). ``'body_25'`` loads the OpenPose BODY_25 model
+    (25 keypoints), ``'mpi'`` loads the MPII model (15 keypoints), ``'coco'`` loads
+    the COCO model (18 keypoints). Defaults to 'body_25'.
+- `device` *str, optional* - Sets the backend to use for the neural network ('cpu' or 'gpu').
+    Ignored when ``model='mediapipe'`` (MediaPipe always runs on CPU). Defaults to 'gpu'.
+- `threshold` *float, optional* - The normalized confidence threshold that decides whether we
+    keep or discard a predicted point. Discarded points get substituted with (0, 0) in the
+    output data. Defaults to 0.1.
+- `downsampling_factor` *int, optional* - Decides how much we downsample the video before we
+    pass it to the neural network. Ignored when ``model='mediapipe'``. Defaults to 2.
 - `save_data` *bool, optional* - Whether we save the predicted pose data to a file. Defaults to True.
-- `data_format` *str, optional* - Specifies format of pose-data. Accepted values are 'csv', 'tsv' and 'txt'. For multiple output formats, use list, eg. ['csv', 'txt']. Defaults to 'csv'.
-- `save_video` *bool, optional* - Whether we save the video with the estimated pose overlaid on it. Defaults to True.
-- `target_name_video` *str, optional* - Target output name for the video. Defaults to None (which assumes that the input filename with the suffix "_pose" should be used).
-- `target_name_data` *str, optional* - Target output name for the data. Defaults to None (which assumes that the input filename with the suffix "_pose" should be used).
-- `overwrite` *bool, optional* - Whether to allow overwriting existing files or to automatically increment target filenames to avoid overwriting. Defaults to False.
+- `data_format` *str, optional* - Specifies format of pose-data. Accepted values are 'csv', 'tsv'
+    and 'txt'. For multiple output formats, use list, eg. ['csv', 'txt']. Defaults to 'csv'.
+- `save_video` *bool, optional* - Whether we save the video with the estimated pose overlaid on it.
+    Defaults to True.
+- `target_name_video` *str, optional* - Target output name for the video. Defaults to None (which
+    assumes that the input filename with the suffix "_pose" should be used).
+- `target_name_data` *str, optional* - Target output name for the data. Defaults to None (which
+    assumes that the input filename with the suffix "_pose" should be used).
+- `overwrite` *bool, optional* - Whether to allow overwriting existing files or to automatically
+    increment target filenames to avoid overwriting. Defaults to False.
 
 #### Returns
 
diff --git a/docs/musicalgestures/_pose_estimator.md b/docs/musicalgestures/_pose_estimator.md
index 50b6b37..05763ed 100644
--- a/docs/musicalgestures/_pose_estimator.md
+++ b/docs/musicalgestures/_pose_estimator.md
@@ -26,7 +26,7 @@ This module provides:
 * class `PoseEstimator` – an abstract base class (ABC) defining the common
   interface that all pose backends must implement.
 * class `MediaPipePoseEstimator` – a concrete backend powered by Google
-  MediaPipe Pose (33 landmarks, CPU-friendly, auto-downloads model on first use).
+  MediaPipe Pose (33 landmarks, CPU-friendly, zero model download).
 * class `OpenPosePoseEstimator` – a thin wrapper around the legacy OpenPose /
   Caffe-model implementation already present in :mod:[Pose](_pose.md#pose).
 
@@ -68,8 +68,8 @@ pip install musicalgestures[pose]
 ```
 
 The first time you use a given complexity level the corresponding
-`.task` model file (~8–28 MB) is downloaded from Google's model
-storage and cached in `musicalgestures/models/`.
+``.task`` model file (~8–28 MB) is downloaded from Google's model
+storage and cached in ``musicalgestures/models/``.
 
 Parameters
 ----------
@@ -97,7 +97,7 @@ Examples
 
 ### MediaPipePoseEstimator().close
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_pose_estimator.py#L290)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_pose_estimator.py#L360)
 
 ```python
 def close() -> None:
@@ -107,7 +107,7 @@ Release MediaPipe resources.
 
 ### MediaPipePoseEstimator().landmark_names
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_pose_estimator.py#L255)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_pose_estimator.py#L323)
 
 ```python
 @property
@@ -116,7 +116,7 @@ def landmark_names() -> list[str]:
 
 ### MediaPipePoseEstimator().predict_frame
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_pose_estimator.py#L259)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_pose_estimator.py#L327)
 
 ```python
 def predict_frame(frame: np.ndarray) -> PoseEstimatorResult:
@@ -140,7 +140,7 @@ PoseEstimatorResult
 
 ## OpenPosePoseEstimator
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_pose_estimator.py#L303)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_pose_estimator.py#L373)
 
 ```python
 class OpenPosePoseEstimator(PoseEstimator):
@@ -172,7 +172,7 @@ threshold:
 
 ### OpenPosePoseEstimator().landmark_names
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_pose_estimator.py#L330)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_pose_estimator.py#L400)
 
 ```python
 @property
@@ -181,7 +181,7 @@ def landmark_names() -> list[str]:
 
 ### OpenPosePoseEstimator().predict_frame
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_pose_estimator.py#L335)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_pose_estimator.py#L405)
 
 ```python
 def predict_frame(frame: np.ndarray) -> PoseEstimatorResult:
@@ -341,7 +341,7 @@ Return a plain dict representation.
 
 ## get_pose_estimator
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_pose_estimator.py#L348)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_pose_estimator.py#L418)
 
 ```python
 def get_pose_estimator(
diff --git a/docs/musicalgestures/_utils.md b/docs/musicalgestures/_utils.md
index 8ee8f28..81107f6 100644
--- a/docs/musicalgestures/_utils.md
+++ b/docs/musicalgestures/_utils.md
@@ -36,12 +36,12 @@
     - [framediff_ffmpeg](#framediff_ffmpeg)
     - [generate_outfilename](#generate_outfilename)
     - [get_box_video_ratio](#get_box_video_ratio)
+    - [get_cuda_device_count](#get_cuda_device_count)
     - [get_first_frame_as_image](#get_first_frame_as_image)
     - [get_fps](#get_fps)
     - [get_frame_planecount](#get_frame_planecount)
     - [get_framecount](#get_framecount)
     - [get_length](#get_length)
-    - [get_cuda_device_count](#get_cuda_device_count)
     - [get_widthheight](#get_widthheight)
     - [has_audio](#has_audio)
     - [in_colab](#in_colab)
@@ -56,6 +56,7 @@
     - [roundup](#roundup)
     - [scale_array](#scale_array)
     - [scale_num](#scale_num)
+    - [show_progress](#show_progress)
     - [str2sec](#str2sec)
     - [threshold_ffmpeg](#threshold_ffmpeg)
     - [unwrap_str](#unwrap_str)
@@ -63,7 +64,7 @@
 
 ## FFmpegError
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1472)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1502)
 
 ```python
 class FFmpegError(Exception):
@@ -72,7 +73,7 @@ class FFmpegError(Exception):
 
 ## FFprobeError
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1077)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1107)
 
 ```python
 class FFprobeError(Exception):
@@ -81,7 +82,7 @@ class FFprobeError(Exception):
 
 ## FilesNotMatchError
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1654)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1698)
 
 ```python
 class FilesNotMatchError(Exception):
@@ -90,7 +91,7 @@ class FilesNotMatchError(Exception):
 
 ## MgFigure
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L220)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L250)
 
 ```python
 class MgFigure():
@@ -107,7 +108,7 @@ Class for working with figures and plots within the Musical Gestures Toolbox.
 
 ### MgFigure().show
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L245)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L275)
 
 ```python
 def show():
@@ -117,7 +118,7 @@ Shows the internal matplotlib.pyplot.figure.
 
 ## MgImage
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L177)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L207)
 
 ```python
 class MgImage():
@@ -128,7 +129,7 @@ Class for handling images in the Musical Gestures Toolbox.
 
 ## MgProgressbar
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L3)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L29)
 
 ```python
 class MgProgressbar():
@@ -147,7 +148,7 @@ Calls in a loop to create terminal progress bar.
 
 ### MgProgressbar().adjust_printlength
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L64)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L90)
 
 ```python
 def adjust_printlength():
@@ -155,7 +156,7 @@ def adjust_printlength():
 
 ### MgProgressbar().get_now
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L44)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L70)
 
 ```python
 def get_now():
@@ -169,7 +170,7 @@ Gets the current time.
 
 ### MgProgressbar().over_time_limit
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L54)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L80)
 
 ```python
 def over_time_limit():
@@ -183,7 +184,7 @@ Checks if we should redraw the progress bar at this moment.
 
 ### MgProgressbar().progress
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L126)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L152)
 
 ```python
 def progress(iteration):
@@ -197,7 +198,7 @@ Progresses the progress bar to the next step.
 
 ## NoDurationError
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1086)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1116)
 
 ```python
 class NoDurationError(FFprobeError):
@@ -209,7 +210,7 @@ class NoDurationError(FFprobeError):
 
 ## NoStreamError
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1082)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1112)
 
 ```python
 class NoStreamError(FFprobeError):
@@ -221,7 +222,7 @@ class NoStreamError(FFprobeError):
 
 ## WrongContainer
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L444)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L474)
 
 ```python
 class WrongContainer(Exception):
@@ -230,7 +231,7 @@ class WrongContainer(Exception):
 
 ## audio_dilate
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1402)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1432)
 
 ```python
 def audio_dilate(
@@ -256,7 +257,7 @@ Time-stretches or -shrinks (dilates) an audio file using ffmpeg.
 
 ## cast_into_avi
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L598)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L628)
 
 ```python
 def cast_into_avi(filename, target_name=None, overwrite=False):
@@ -278,7 +279,7 @@ but does not always work well with cv2 or built-in video players.
 
 ## clamp
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L297)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L327)
 
 ```python
 def clamp(num, min_value, max_value):
@@ -298,7 +299,7 @@ Clamps a number between a minimum and maximum value.
 
 ## convert
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L483)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L513)
 
 ```python
 def convert(filename, target_name, overwrite=False):
@@ -318,7 +319,7 @@ Converts a video to another format/container using ffmpeg.
 
 ## convert_to_avi
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L511)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L541)
 
 ```python
 def convert_to_avi(filename, target_name=None, overwrite=False):
@@ -338,7 +339,7 @@ Converts a video to one with .avi extension using ffmpeg.
 
 ## convert_to_grayscale
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L772)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L802)
 
 ```python
 def convert_to_grayscale(filename, target_name=None, overwrite=False):
@@ -358,7 +359,7 @@ Converts a video to grayscale using ffmpeg.
 
 ## convert_to_mp4
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L540)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L570)
 
 ```python
 def convert_to_mp4(filename, target_name=None, overwrite=False):
@@ -378,7 +379,7 @@ Converts a video to one with .mp4 extension using ffmpeg.
 
 ## convert_to_webm
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L569)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L599)
 
 ```python
 def convert_to_webm(filename, target_name=None, overwrite=False):
@@ -398,7 +399,7 @@ Converts a video to one with .webm extension using ffmpeg.
 
 ## crop_ffmpeg
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1009)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1039)
 
 ```python
 def crop_ffmpeg(filename, w, h, x, y, target_name=None, overwrite=False):
@@ -422,7 +423,7 @@ Crops a video using ffmpeg.
 
 ## embed_audio_in_video
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1432)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1462)
 
 ```python
 def embed_audio_in_video(source_audio, destination_video, dilation_ratio=1):
@@ -438,7 +439,7 @@ Embeds an audio file as the audio channel of a video file using ffmpeg.
 
 ## extract_frame
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L625)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L655)
 
 ```python
 def extract_frame(
@@ -462,7 +463,7 @@ time (Union[str, float]): The time in HH:MM:ss.ms where to extract the frame fro
 
 ## extract_subclip
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L681)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L711)
 
 ```python
 def extract_subclip(filename, t1, t2, target_name=None, overwrite=False):
@@ -484,7 +485,7 @@ Extracts a section of the video using ffmpeg.
 
 ## extract_wav
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1045)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1075)
 
 ```python
 def extract_wav(filename, target_name=None, overwrite=False):
@@ -504,7 +505,7 @@ Extracts audio from video into a .wav file via ffmpeg.
 
 ## ffmpeg_cmd
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1477)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1507)
 
 ```python
 def ffmpeg_cmd(
@@ -535,7 +536,7 @@ Run an ffmpeg command in a subprocess and show progress using an MgProgressbar.
 
 ## ffprobe
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1089)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1119)
 
 ```python
 def ffprobe(filename):
@@ -553,7 +554,7 @@ Returns info about video/audio file using FFprobe.
 
 ## frame2ms
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L429)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L459)
 
 ```python
 def frame2ms(frame, fps):
@@ -572,7 +573,7 @@ Converts frames to milliseconds.
 
 ## framediff_ffmpeg
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L800)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L830)
 
 ```python
 def framediff_ffmpeg(filename, target_name=None, color=True, overwrite=False):
@@ -593,7 +594,7 @@ Renders a frame difference video from the input using ffmpeg.
 
 ## generate_outfilename
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L350)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L380)
 
 ```python
 def generate_outfilename(requested_name):
@@ -612,7 +613,7 @@ filename if necessary by appending an integer, like "_0" or "_1", etc to the fil
 
 ## get_box_video_ratio
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1327)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1357)
 
 ```python
 def get_box_video_ratio(filename, box_width=800, box_height=600):
@@ -630,9 +631,24 @@ Gets the box-to-video ratio between an arbitrarily defind box and the video dime
 
 - `int` - The smallest ratio (ie. the one to use for scaling the video window to fit into the box).
 
+## get_cuda_device_count
+
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1649)
+
+```python
+def get_cuda_device_count():
+```
+
+Returns the number of CUDA-capable GPU devices visible to OpenCV.
+
+#### Returns
+
+- `int` - Number of available CUDA devices, or 0 if the OpenCV CUDA
+     module is unavailable or no devices are detected.
+
 ## get_first_frame_as_image
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1295)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1325)
 
 ```python
 def get_first_frame_as_image(
@@ -658,7 +674,7 @@ Extracts the first frame of a video and saves it as an image using ffmpeg.
 
 ## get_fps
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1262)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1292)
 
 ```python
 def get_fps(filename):
@@ -676,7 +692,7 @@ Gets the FPS (frames per second) value of a video using FFprobe.
 
 ## get_frame_planecount
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L414)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L444)
 
 ```python
 def get_frame_planecount(frame):
@@ -694,7 +710,7 @@ frame (numpy array): A frame extracted by `cv2.VideoCapture().read()`.
 
 ## get_framecount
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1212)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1242)
 
 ```python
 def get_framecount(filename, fast=True):
@@ -712,7 +728,7 @@ Returns the number of frames in a video using FFprobe.
 
 ## get_length
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1184)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1214)
 
 ```python
 def get_length(filename: str) -> float:
@@ -728,23 +744,9 @@ Gets the length (in seconds) of a video using FFprobe.
 
 - `float` - The length of the input video file in seconds.
 
-## get_cuda_device_count
-
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1649)
-
-```python
-def get_cuda_device_count():
-```
-
-Returns the number of CUDA-capable GPU devices visible to OpenCV.
-
-#### Returns
-
-- `int` - Number of available CUDA devices, or 0 if the OpenCV CUDA module is unavailable or no devices are detected.
-
 ## get_widthheight
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1117)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1147)
 
 ```python
 def get_widthheight(filename: str) -> Tuple[int, int]:
@@ -763,7 +765,7 @@ Gets the width and height of a video using FFprobe.
 
 ## has_audio
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1158)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1188)
 
 ```python
 def has_audio(filename):
@@ -795,7 +797,7 @@ Check's if the environment is a Google Colab document.
 
 ## in_ipynb
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1634)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1678)
 
 ```python
 def in_ipynb():
@@ -810,7 +812,7 @@ Taken from https://stackoverflow.com/questions/15411967/how-can-i-check-if-code-
 
 ## merge_videos
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1659)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1703)
 
 ```python
 def merge_videos(
@@ -835,7 +837,7 @@ Merges a list of video files into a single video file using ffmpeg.
 
 ## motiongrams_ffmpeg
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L933)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L963)
 
 ```python
 def motiongrams_ffmpeg(
@@ -876,7 +878,7 @@ Renders horizontal and vertical motiongrams using ffmpeg.
 
 ## motionvideo_ffmpeg
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L877)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L907)
 
 ```python
 def motionvideo_ffmpeg(
@@ -914,7 +916,7 @@ Renders a motion video using ffmpeg.
 
 ## pass_if_container_is
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L467)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L497)
 
 ```python
 def pass_if_container_is(container, file):
@@ -933,7 +935,7 @@ Checks if a file's extension matches a desired one. Passes if so, raises WrongCo
 
 ## pass_if_containers_match
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L449)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L479)
 
 ```python
 def pass_if_containers_match(file_1, file_2):
@@ -952,7 +954,7 @@ Checks if file extensions match between two files. If they do it passes, is they
 
 ## quality_metrics
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1353)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1383)
 
 ```python
 def quality_metrics(original, processed, metric=None):
@@ -976,7 +978,7 @@ Possible to compute three major video quality metrics used for objective evaluat
 
 ## rotate_video
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L734)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L764)
 
 ```python
 def rotate_video(filename, angle, target_name=None, overwrite=False):
@@ -997,7 +999,7 @@ Rotates a video by an `angle` using ffmpeg.
 
 ## roundup
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L282)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L312)
 
 ```python
 def roundup(num, modulo_num):
@@ -1016,7 +1018,7 @@ Rounds up a number to the next integer multiple of another.
 
 ## scale_array
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L330)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L360)
 
 ```python
 def scale_array(array, out_low, out_high):
@@ -1036,7 +1038,7 @@ Scales an array linearly.
 
 ## scale_num
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L312)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L342)
 
 ```python
 def scale_num(val, in_low, in_high, out_low, out_high):
@@ -1056,9 +1058,36 @@ Scales a number linearly.
 
 - `float` - The scaled number.
 
+## show_progress
+
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L8)
+
+```python
+def show_progress(enabled: bool) -> None:
+```
+
+Enable or disable the MGT progress bars globally.
+
+Disabling the progress bars is useful when running batch processing jobs or
+when the output is captured by a logging framework where the repeated
+``\r`` updates would clutter the log.
+
+#### Arguments
+
+- `enabled` *bool* - Pass ``True`` to show progress bars (default behaviour)
+    or ``False`` to suppress them.
+
+#### Examples
+
+```python
+>>> import musicalgestures as mg
+>>> mg.show_progress(False)  # suppress all progress bars
+>>> # … batch processing …
+>>> mg.show_progress(True)   # re-enable for interactive use
+
 ## str2sec
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1566)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1596)
 
 ```python
 def str2sec(time_string):
@@ -1076,7 +1105,7 @@ Converts a time code string into seconds.
 
 ## threshold_ffmpeg
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L833)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L863)
 
 ```python
 def threshold_ffmpeg(
@@ -1104,7 +1133,7 @@ Renders a pixel-thresholded video from the input using ffmpeg.
 
 ## unwrap_str
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1601)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1631)
 
 ```python
 def unwrap_str(string):
@@ -1122,7 +1151,7 @@ Unwraps a string from quotes.
 
 ## wrap_str
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1580)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1610)
 
 ```python
 def wrap_str(string, matchers=[' ', '(', ')']):
diff --git a/docs/musicalgestures/index.md b/docs/musicalgestures/index.md
index 55a5628..f991469 100644
--- a/docs/musicalgestures/index.md
+++ b/docs/musicalgestures/index.md
@@ -50,7 +50,7 @@
 
 ## Examples
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/__init__.py#L21)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/__init__.py#L23)
 
 ```python
 class Examples():

From ff2119e0ed8025333013c828929ffff5ae9b087f Mon Sep 17 00:00:00 2001
From: Alexander Refsum Jensenius <arjensenius@gmail.com>
Date: Tue, 14 Apr 2026 07:11:32 +0200
Subject: [PATCH 3/3] fixing reference

---
 docs/index.md                                | 19 +++++++++++--------
 musicalgestures/MusicalGesturesToolbox.ipynb |  2 +-
 2 files changed, 12 insertions(+), 9 deletions(-)

diff --git a/docs/index.md b/docs/index.md
index 02f7348..cdbc480 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -5,7 +5,7 @@
 [![CI](https://github.com/fourMs/MGT-python/actions/workflows/ci.yml/badge.svg)](https://github.com/fourMs/MGT-python/actions/workflows/ci.yml)
 [![Documentation](https://github.com/fourMs/MGT-python/actions/workflows/docs.yml/badge.svg)](https://fourms.github.io/MGT-python/)
 
-The **Musical Gestures Toolbox for Python** is a comprehensive collection of tools for visualization and analysis of audio and video, with a focus on motion capture and musical gesture analysis.
+The **Musical Gestures Toolbox for Python** is a collection of tools for visualization and analysis of audio and video, with a focus on motion capture and musical gesture analysis.
 
 ![MGT python demo](https://raw.githubusercontent.com/fourMs/MGT-python/master/musicalgestures/documentation/figures/promo/ipython_example.gif)
 
@@ -117,15 +117,18 @@ This toolbox builds upon years of research in musical gesture analysis:
 
 ## Citation
 
-If you use MGT-python in your research, please cite:
+If you use MGT-python in your research, please cite this article:
+
+- Laczkó, B., & Jensenius, A. R. (2021). [Reflections on the Development of the Musical Gestures Toolbox for Python](http://urn.nb.no/URN:NBN:no-91935). *Proceedings of the Nordic Sound and Music Computing Conference*, Copenhagen.
 
 ```bibtex
-@software{mgt_python,
-  title={Musical Gestures Toolbox for Python},
-  author={University of Oslo fourMs Lab},
-  url={https://fourms.github.io/MGT-python/},
-  version={1.3.2},
-  year={2024}
+@inproceedings{laczkoReflectionsDevelopmentMusical2021,
+    title = {Reflections on the Development of the Musical Gestures Toolbox for Python},
+    author = {Laczkó, Bálint and Jensenius, Alexander Refsum},
+    booktitle = {Proceedings of the Nordic Sound and Music Computing Conference},
+    year = {2021},
+    address = {Copenhagen},
+    url = {http://urn.nb.no/URN:NBN:no-91935}
 }
 ```
 
diff --git a/musicalgestures/MusicalGesturesToolbox.ipynb b/musicalgestures/MusicalGesturesToolbox.ipynb
index 17b5d1c..76aaef5 100644
--- a/musicalgestures/MusicalGesturesToolbox.ipynb
+++ b/musicalgestures/MusicalGesturesToolbox.ipynb
@@ -5524,7 +5524,7 @@
    "provenance": []
   },
   "kernelspec": {
-   "display_name": ".venv",
+   "display_name": ".venv (3.12.3)",
    "language": "python",
    "name": "python3"
   },