Metadata-Version: 2.5
Name: motion-reference-prep
Version: 0.1.0
Summary: Prepare local dance and motion-reference clips with FFmpeg: trim, resize, inspect, and preview.
Project-URL: Example workflow, https://motioncontrolaifree.com/bulin-47-ai
License-Expression: MIT
License-File: LICENSE
Keywords: dance,ffmpeg,motion-reference,video
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Video :: Conversion
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 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`.

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

## Quick start

```bash
# 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](https://motioncontrolaifree.com/bulin-47-ai), first
prepare a short reference in which the performer's full body stays visible:

```bash
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

```python
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

```bash
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.
