3 ‐ Preprocessing

For complete documentation see Preprocessing on the docs site.

---

Most recordings contain more than the part you want to study: setup before the dancing, talk after it, a camera slightly tilted, a room around the body. Preprocessing is the cropping and trimming you would do to a photograph before framing it, applied once when the video is loaded, so that every analysis afterwards sees only the material that matters.

All preprocessing is applied at load time via MgVideo constructor arguments. Steps execute in this order: trim → skip → fix → rotate → contrast/brightness → crop → grayscale.

import musicalgestures as mg

mv = mg.MgVideo('/path/to/video.avi', starttime=5, endtime=15, skip=3,
                rotate=90, contrast=100, brightness=20, crop='auto', color=False)

Key parameters

Parameter	Default	Description
starttime, endtime	0, 0	Trim to a time range in seconds
skip	0	Discard n frames before keeping one, so skip=3 keeps every 4th frame
frames	0	Fix total frame count (−1 for keyframes only)
rotate	0	Rotation angle in degrees
contrast, brightness	0, 0	Percentage adjustment, −100 to 100
crop	'None'	'auto' (motion-based) or 'manual' (draw rectangle)
color	True	False for grayscale mode
keep_all	False	Keep intermediate files from each step

A few of these deserve a closer look.

Trimming and skipping

starttime and endtime, both in seconds, cut the video down to the part you want to study before anything else happens. skip thins the frames that remain: skip=2 keeps every 3rd frame, which shortens processing time at the cost of temporal detail.

Fixing a frame count

frames extracts a fixed number of frames regardless of how long the file is, which is useful for batch processing files of different lengths:

mv = mg.MgVideo('/path/to/video.avi', frames=1000)
mv = mg.MgVideo('/path/to/video.avi', frames=-1)    # keyframes only

Rotation

rotate accepts any angle in degrees, not only right angles. A small fractional value such as rotate=5.31 straightens a slightly tilted camera:

mv = mg.MgVideo('/path/to/video.avi', rotate=5.31)

Contrast and brightness

Both are percentages in the range −100 to 100, and 0 leaves the video unchanged. Raising the contrast can help motion analysis separate a mover from a dim background.

Cropping

crop='auto' detects the region of motion and crops to it, which is often all you need. crop='manual' opens a window where you draw the crop rectangle yourself, then press c to confirm or r to reset and draw again.

Grayscale

color=False converts the video to grayscale and keeps all subsequent processes in grayscale mode, which can reduce processing time.

Keeping intermediate files

By default only the final preprocessed video is kept. With keep_all=True the result of each step is retained, producing files like video_trim.avi, video_trim_skip.avi and video_trim_skip_rot.avi, so you can inspect what each step did.

Resampling (frame rate, speed, frame decimation)

resample() is a method on an already-loaded MgVideo. It returns a new MgVideo and leaves the original untouched, so you can branch off a re-timed copy:

mv = mg.MgVideo('/path/to/video.avi')

mv25 = mv.resample(fps=25)        # retime to 25 fps (duration-preserving)
fast = mv.resample(speed=2.0)     # 2× faster — video + audio retimed in sync
slow = mv.resample(speed=0.5)     # 2× slower / longer
dec  = mv.resample(skip=2)        # discard 2 frames for every one kept

• fps—duration-preserving frame-rate change (FFmpeg fps filter), for example 30 → 25 fps
• speed—playback-speed factor (>1 faster/shorter, <1 slower/longer); retimes video + audio in sync
• skip—integer frame decimation (also speeds up), matching the loader's skip parameter

When combined, they are applied in order skip → speed/fps. The output name defaults to the input name + _resampled; target_name and overwrite work as they do everywhere else, described on File Naming.

The next chapter, Video-based Processes, turns the preprocessed video into motion videos, motiongrams and other visualisations.