motion-reference-prep 0.1.0__py3-none-any.whl

motion_reference_prep/__init__.py

@@ -0,0 +1,6 @@
+"""Local utilities for preparing motion-reference video clips."""
+
+from .core import VideoError, prepare, preview, probe
+
+__version__ = "0.1.0"
+__all__ = ["VideoError", "prepare", "preview", "probe"]

motion_reference_prep/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

motion_reference_prep/cli.py

@@ -0,0 +1,45 @@
+"""Command-line interface."""
+
+import argparse
+import json
+import sys
+
+from . import __version__
+from .core import VideoError, prepare, preview, probe
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description="Prepare local motion-reference videos with FFmpeg.")
+    parser.add_argument("--version", action="version", version=__version__)
+    commands = parser.add_subparsers(dest="command", required=True)
+    inspect = commands.add_parser("inspect", help="Print ffprobe metadata as JSON")
+    inspect.add_argument("source")
+    convert = commands.add_parser("prepare", help="Trim and encode an H.264/AAC MP4")
+    convert.add_argument("source")
+    convert.add_argument("destination")
+    convert.add_argument("--start", type=float, default=0.0)
+    convert.add_argument("--duration", type=float, default=10.0)
+    convert.add_argument("--width", type=int, default=720)
+    convert.add_argument("--height", type=int, default=1280)
+    convert.add_argument("--fps", type=int, default=30)
+    convert.add_argument("--fit", choices=("pad", "crop"), default="pad")
+    convert.add_argument("--mute", action="store_true")
+    convert.add_argument("--overwrite", action="store_true")
+    frame = commands.add_parser("preview", help="Save a PNG frame")
+    frame.add_argument("source")
+    frame.add_argument("destination")
+    frame.add_argument("--at", type=float, default=0.0)
+    frame.add_argument("--overwrite", action="store_true")
+    args = vars(parser.parse_args(argv))
+    command = args.pop("command")
+    try:
+        if command == "inspect":
+            print(json.dumps(probe(**{"path": args["source"]}), indent=2))
+        elif command == "prepare":
+            print(prepare(**args))
+        else:
+            print(preview(**args))
+    except (VideoError, OSError, ValueError) as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 1
+    return 0

motion_reference_prep/core.py

@@ -0,0 +1,139 @@
+"""FFmpeg wrappers for local files; no network client or Python dependencies."""
+
+import json
+import math
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import tempfile
+
+
+class VideoError(RuntimeError):
+    """An input, dependency, or media-processing error."""
+
+
+def _run(tool, args):
+    executable = shutil.which(tool)
+    if not executable:
+        raise VideoError(f"{tool} is required. Install FFmpeg and add it to PATH.")
+    result = subprocess.run(
+        [executable, *args], capture_output=True, text=True, check=False,
+    )
+    if result.returncode:
+        raise VideoError(result.stderr.strip()[-2000:] or f"{tool} failed")
+    return result.stdout
+
+
+def _source(path):
+    source = Path(path).expanduser().resolve()
+    if not source.is_file():
+        raise VideoError(f"Input is not a local file: {source}")
+    return source
+
+
+def _number(value, label, minimum=0, strict=False):
+    if not math.isfinite(value) or value < minimum or (strict and value == minimum):
+        comparison = "greater than" if strict else "at least"
+        raise VideoError(f"{label} must be finite and {comparison} {minimum}")
+
+
+def probe(path):
+    """Return ffprobe JSON for a local file containing a video stream."""
+    source = _source(path)
+    data = json.loads(_run("ffprobe", [
+        "-v", "error", "-show_format", "-show_streams", "-of", "json", str(source),
+    ]))
+    if not any(s.get("codec_type") == "video" and not s.get("disposition", {}).get("attached_pic")
+               for s in data.get("streams", [])):
+        raise VideoError("Input has no video stream")
+    return data
+
+
+def _duration(data):
+    for stream in data.get("streams", []):
+        if stream.get("codec_type") == "video" and not stream.get("disposition", {}).get("attached_pic"):
+            value = stream.get("duration", data.get("format", {}).get("duration"))
+            try:
+                duration = float(value)
+                if math.isfinite(duration) and duration > 0:
+                    return duration
+            except (TypeError, ValueError):
+                pass
+    raise VideoError("Cannot determine video duration")
+
+
+def _export(source, destination, args, overwrite, suffix):
+    target = Path(destination).expanduser().absolute()
+    if target.resolve() == source or (target.exists() and os.path.samefile(source, target)):
+        raise VideoError("Output must be different from input")
+    if target.exists() and not overwrite:
+        raise VideoError(f"Output already exists: {target}; use overwrite=True or --overwrite")
+    if not target.parent.is_dir():
+        raise VideoError(f"Output directory does not exist: {target.parent}")
+    # Encode beside the destination, then publish only a complete result.
+    with tempfile.TemporaryDirectory(prefix=".motion-reference-", dir=target.parent) as folder:
+        temporary = Path(folder) / ("result" + suffix)
+        _run("ffmpeg", ["-hide_banner", "-loglevel", "error", "-nostdin", *args, str(temporary)])
+        if not temporary.is_file() or not temporary.stat().st_size:
+            raise VideoError("FFmpeg produced no output")
+        if overwrite:
+            os.replace(temporary, target)
+        else:
+            try:
+                os.link(temporary, target)
+            except FileExistsError as error:
+                raise VideoError(f"Output already exists: {target}") from error
+    return target
+
+
+def prepare(source, destination, *, start=0.0, duration=10.0, width=720,
+            height=1280, fps=30, fit="pad", mute=False, overwrite=False):
+    """Trim and encode an H.264/AAC MP4. Pad preserves the whole source frame.
+
+    The requested interval must fit inside the source. Existing files are
+    protected unless overwrite=True; input files are never overwritten.
+    """
+    source = _source(source)
+    _number(start, "start")
+    _number(duration, "duration", strict=True)
+    for value, label in ((width, "width"), (height, "height")):
+        if not isinstance(value, int) or value < 2 or value > 7680 or value % 2:
+            raise VideoError(f"{label} must be an even integer between 2 and 7680")
+    if not isinstance(fps, int) or not 1 <= fps <= 120:
+        raise VideoError("fps must be an integer between 1 and 120")
+    if fit not in ("pad", "crop"):
+        raise VideoError("fit must be 'pad' or 'crop'")
+    if Path(destination).suffix.lower() != ".mp4":
+        raise VideoError("Prepared video output must have an .mp4 extension")
+    total = _duration(probe(source))
+    if start + duration > total + 0.001:
+        raise VideoError(f"Requested interval ends at {start + duration:g}s; video is {total:g}s")
+    # Normalize sample aspect ratio before fitting the display dimensions.
+    normalize = "scale=trunc(iw*sar/2)*2:ih,setsar=1"
+    if fit == "pad":
+        scale = f"scale={width}:{height}:force_original_aspect_ratio=decrease:force_divisible_by=2"
+        frame = f"pad={width}:{height}:(ow-iw)/2:(oh-ih)/2:color=black"
+    else:
+        scale = f"scale={width}:{height}:force_original_aspect_ratio=increase:force_divisible_by=2"
+        frame = f"crop={width}:{height}"
+    args = ["-ss", str(start), "-i", str(source), "-t", str(duration),
+            "-map", "0:V:0", "-vf", f"{normalize},{scale},{frame},setsar=1,fps={fps}",
+            "-c:v", "libx264", "-preset", "medium", "-crf", "22", "-pix_fmt", "yuv420p"]
+    args += ["-an"] if mute else ["-map", "0:a:0?", "-c:a", "aac", "-b:a", "128k"]
+    args += ["-map_metadata", "-1", "-map_chapters", "-1", "-movflags", "+faststart"]
+    return _export(source, destination, args, overwrite, ".mp4")
+
+
+def preview(source, destination, *, at=0.0, overwrite=False):
+    """Export one PNG frame at a timestamp in seconds."""
+    source = _source(source)
+    _number(at, "at")
+    if Path(destination).suffix.lower() != ".png":
+        raise VideoError("Preview output must have a .png extension")
+    if at >= _duration(probe(source)):
+        raise VideoError("Preview timestamp must be before the end of the video")
+    return _export(source, destination, [
+        "-ss", str(at), "-i", str(source), "-map", "0:V:0", "-frames:v", "1",
+        "-vf", "scale=trunc(iw*sar/2)*2:ih,setsar=1", "-update", "1",
+    ], overwrite, ".png")

motion_reference_prep-0.1.0.dist-info/METADATA

@@ -0,0 +1,109 @@
+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.

motion_reference_prep-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+motion_reference_prep/__init__.py,sha256=4wzHQmj76CTIv82Fs7pz_UtDT63IDLEbjMHD2lpLbag,200
+motion_reference_prep/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+motion_reference_prep/cli.py,sha256=DXBbQGYNRbH8n6HA2GUEyAHFbMYu2c6eoljQAW-dJzs,1894
+motion_reference_prep/core.py,sha256=rTYKf02ZcsoxKXjIZO8Yejz01U1PjKrqOfyWx7_kLg8,6223
+motion_reference_prep-0.1.0.dist-info/METADATA,sha256=_4CD5rCF6KEAckPQwic4SkF8B8iCT0UntQru39pROBs,4262
+motion_reference_prep-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+motion_reference_prep-0.1.0.dist-info/entry_points.txt,sha256=_tEYrqIEgawUiOV3m0R_sSmhnLOzHGNirYuLmEdegoA,73
+motion_reference_prep-0.1.0.dist-info/licenses/LICENSE,sha256=jckisRUnCwq8Fy1gepTC9YBTX_wNoEwXo8SkQ8lo-zU,1091
+motion_reference_prep-0.1.0.dist-info/RECORD,,

motion_reference_prep-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

motion_reference_prep-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+motion-reference-prep = motion_reference_prep.cli:main

motion_reference_prep-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 motion-reference-prep contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.