motion-reference-prep

Prepare a short, consistently sized video before using it as a motion reference. This small Python library and CLI wraps FFmpeg to inspect local footage, trim a specific interval, export an H.264 MP4, and save a preview frame.

Install

Requires Python 3.10+ and FFmpeg 6+ with libx264. Install FFmpeg separately and make both ffmpeg and ffprobe available on your PATH.

pip install motion-reference-prep
ffmpeg -version
motion-reference-prep --help

Quick start

# Inspect duration, dimensions, codecs, and audio streams.
motion-reference-prep inspect rehearsal.mov

# Keep ten seconds starting at second two; preserve the whole body with padding.
motion-reference-prep prepare rehearsal.mov reference.mp4 --start 2 --duration 10

# Inspect a frame before uploading your reference to another tool.
motion-reference-prep preview reference.mp4 preview.png --at 4

The default export is 720 × 1280 at 30 fps, H.264 video with AAC audio when an audio stream exists. --mute removes audio. --fit crop fills the canvas with a center crop; the default --fit pad preserves the whole frame with black borders. Use --width 1280 --height 720 for landscape output. Dimensions must be even.

Existing output files are protected unless you pass --overwrite. The source file cannot be used as the output. Failed encodes do not replace an existing destination. The selected interval must fit inside the source video.

Example: prepare a dance reference

For a photo-driven dance workflow such as the Bulin 47 AI video generator, first prepare a short reference in which the performer's full body stays visible:

motion-reference-prep prepare freestyle.mov dance-reference.mp4 --duration 10 --fit pad
motion-reference-prep preview dance-reference.mp4 framing.png --at 5

Review the framing, motion, file size, and audio before manually uploading the MP4. The linked service currently describes custom references of 3–15 seconds, up to 50 MB, with each side between 720 and 3840 pixels (checked October 12, 2026). Check its current requirements before uploading; this package does not enforce a service-specific size limit or guarantee acceptance. Use footage and portraits you have permission to use.

This is a local preprocessing utility, not an AI generator or an SDK for that service. It makes no API calls, uploads no files, and requires no account or API key. No affiliation with Bulin 47 or endorsement by any performer is implied.

Python API

from motion_reference_prep import prepare, preview, probe

metadata = probe("rehearsal.mov")
output = prepare("rehearsal.mov", "reference.mp4", start=2, duration=10)
preview(output, "preview.png", at=4)

Functions return output Path objects; probe returns an ffprobe dictionary. Catch VideoError for invalid inputs, missing FFmpeg, or encoder failures. No additional Python runtime dependencies are needed.

Limitations

• Resizing cannot recover detail missing from the source.
• Output size depends on the source and CRF encoding; no fixed size is promised.
• Padding does not detect or track a dancer. Inspect framing yourself.
• The first non-cover-art video stream and first audio stream are selected.
• Subtitles, additional audio tracks, chapters, and source metadata are omitted.
• Local inputs only. FFmpeg must support the source codec.

Development

python -m pip install -e . build twine
python -m unittest discover -s tests -v
python -m build
python -m twine check dist/*

Integration tests generate synthetic media locally. MIT licensed.