PyMotion

Code-first video generation for Python. Build motion graphics, animated explainers, data visualizations, and production videos entirely in code.

Install

Requires Python 3.12+ and FFmpeg.

# Install system dependencies
# macOS
brew install ffmpeg cairo pkg-config

# Ubuntu / Debian
sudo apt-get install ffmpeg libcairo2-dev pkg-config libfreetype6-dev

# Windows (chocolatey)
choco install ffmpeg cairo

# Install PyMotion
pip install pymotion-studio

# Optional extras
pip install "pymotion-studio[ai]"            # AI features (rembg, SAM, Real-ESRGAN, MusicGen)
pip install "pymotion-studio[3d-extras]"     # GLTF model loading
pip install "pymotion-studio[gpu-compute]"   # WGPU GPU compositing
pip install "pymotion-studio[dev]"           # Development tools

The Python import name is pymotion:

from pymotion import Composition, ColorClip, Track

Quick start

from pymotion import (
    Composition, ColorClip, TextClip, Track,
    GaussianBlur, Fade, animate
)

comp = Composition(1920, 1080, fps=30, duration=90)

# Dark background
bg_track = Track(name="bg")
bg = ColorClip(color="#1a1a2e")
bg.set_duration(90)
bg_track.add(bg)

# Colored card with a blur effect
content_track = Track(name="content")
card = ColorClip(color="#e94560")
card.set_duration(60).set_position(360.0, 240.0).set_scale(0.6)
card.add_effect(GaussianBlur(radius=2.0))
content_track.add(card)

# Title text
text_track = Track(name="text")
title = TextClip("Hello, PyMotion", font="Arial", size=64.0, color="#FFFFFF")
title.set_duration(90).set_position(560.0, 480.0)
text_track.add(title)

# Assemble and render
comp.add_track(bg_track)
comp.add_track(content_track)
comp.add_track(text_track)
comp.render("output.mp4", preset="h264_1080p")

What PyMotion can do

PyMotion started as a 2D rendering pipeline with Cairo, then grew into a full video production framework. The core gives you compositions, tracks, clips, keyframe animation with 30 easing functions, and an effect chain that processes BGRA frames through NumPy. Eight blend modes, a sparse bounding-box compositor, and FreeType+HarfBuzz typography are built in.

Video editing operations cover split, join, subclip, repeat, freeze frame, concatenate with transitions, speed control, speed ramp, reverse, and time remap with optical flow interpolation. Four keying effects (chroma, luma, color, difference) handle green screen and isolation work. Layout helpers arrange clips in picture-in-picture, grid, split screen, and stack configurations. Motion tracking and video stabilization use OpenCV under the hood, and a proxy workflow caches low-res versions for fast iteration.

The compositing layer adds nested compositions (pre-comps), adjustment layers, clip parenting with NullObject, a Bezier/gradient/track-matte/text mask system with boolean operations, Python expressions on any animatable property, and SVG path animation with draw-on strokes and path morphing.

Nine motion graphics components (LowerThird, LogoReveal, CallToAction, SocialHandle, Countdown, QuoteCard, Divider, TransitionTitle, Watermark), eight animated chart types, three device mockups, and a number counter and progress bar cover data visualization and overlay needs.

Professional audio includes 5.1 surround mixing with bus routing, twelve DSP effects, LUFS normalization, beat detection, audio-reactive visual effects, Whisper-powered auto-captions with four subtitle styles, and text-to-speech. The color science module provides an ACES 1.3 pipeline, HDR10 and HLG output, secondary color grading, four video scopes, and EDL/OTIO interchange export.

AI features are optional extras that add background removal, object segmentation, upscaling, denoising, face detection and blur, scene detection, content-aware cropping, and AI music and sound effect generation. GPU-accelerated compositing runs through WGPU compute shaders, and hardware encoding supports NVENC, QSV, AMF, and VideoToolbox with automatic detection and software fallback. Distributed rendering uses Ray or Dask backends with frame-level checkpointing.

Examples

Twelve production-ready scripts ship with the repo, each self-contained with generated assets:

python examples/download_assets.py
python examples/01_core_composition.py

Presets

Hardware presets are auto-detected. If the hardware encoder is unavailable, PyMotion falls back to the equivalent software preset.

System requirements

No GPU is required for CPU-path rendering. All GPU features detect hardware availability at runtime and fall back to CPU.

Run pymotion doctor to verify your environment.

License

PyMotion is released under the PyMotion Source Available License 1.0. You can use it in any project, including commercial products. You cannot redistribute, rebrand, or republish the library itself. Read the full LICENSE for details.