Migrating from MoviePy

MovieLite is designed to be familiar to MoviePy users while offering significant performance improvements. This guide shows you how to migrate your existing MoviePy code to MovieLite.

Why Migrate?

MovieLite offers substantial performance improvements over MoviePy for common video editing tasks:

3.79x faster overall on standard workflows
Up to 4.61x faster on complex compositions
Up to 4.52x faster on text overlays
Up to 3.92x faster on alpha compositing

These improvements come from Numba JIT compilation, optimized compositing, and better memory management.

Philosophy Differences

MoviePy

Comprehensive feature set
Many codec/format options
GPU support (limited)
Larger ecosystem

MovieLite

Speed-focused for common tasks
MP4/H.264 output only
CPU-optimized with Numba
Cleaner, chainable API

Installation

pip install moviepy

Both require FFmpeg to be installed and available in your PATH.

Core API Comparison

Basic Video Loading and Export

from moviepy import VideoFileClip

clip = VideoFileClip("input.mp4")
clip.write_videofile(
    "output.mp4",
    codec='libx264',
    audio_codec='aac'
)
clip.close()

MovieLite uses a separate VideoWriter object for composition, making it easier to combine multiple clips.

Extracting Subclips

clip = VideoFileClip("video.mp4")
subclip = clip.subclipped(10, 20)
subclip.write_videofile("output.mp4")
clip.close()

Concatenating Videos

from moviepy import VideoFileClip, concatenate_videoclips

clip1 = VideoFileClip("intro.mp4")
clip2 = VideoFileClip("main.mp4")
clip3 = VideoFileClip("outro.mp4")

final = concatenate_videoclips([clip1, clip2, clip3])
final.write_videofile("output.mp4")

clip1.close()
clip2.close()
clip3.close()
final.close()

In MovieLite, you control timing explicitly using start parameters instead of relying on concatenation functions.

Transformations

Resizing

clip = VideoFileClip("video.mp4")
resized = clip.resized(width=1280, height=720)
resized.write_videofile("output.mp4")
clip.close()

Dynamic Scaling/Zoom

clip = VideoFileClip("video.mp4")

# Zoom from 1.0x to 1.5x
def zoom_scale(t):
    progress = min(t / clip.duration, 1.0)
    return 1.0 + 0.5 * progress

clip = clip.resized(zoom_scale)
clip.write_videofile("output.mp4")
clip.close()

Positioning

clip = VideoFileClip("video.mp4")
positioned = clip.with_position((100, 100))

# Or centered
centered = clip.with_position('center')

MovieLite currently doesn’t support string-based positioning like 'center'. You need to calculate positions manually. This is on the roadmap for future releases.

Opacity

clip = VideoFileClip("video.mp4")
clip = clip.with_opacity(0.5)
clip.write_videofile("output.mp4")

Speed Control

clip = VideoFileClip("video.mp4")
fast = clip.with_speed_scaled(2.0)  # 2x speed
slow = clip.with_speed_scaled(0.5)  # 0.5x speed (slow motion)

Visual Effects

Fade In/Out

from moviepy import VideoFileClip
from moviepy.video.fx import FadeIn, FadeOut

clip = VideoFileClip("video.mp4")
clip = clip.with_effects([FadeIn(1.0), FadeOut(1.5)])
clip.write_videofile("output.mp4")
clip.close()

Blur

from moviepy.video.fx import GaussianBlur

clip = VideoFileClip("video.mp4")
clip = clip.with_effects([GaussianBlur(5)])
clip.write_videofile("output.mp4")

Color Adjustments

from moviepy.video.fx import BlackAndWhite, Brightness

clip = VideoFileClip("video.mp4")
clip = clip.with_effects([
    Brightness(1.2),
    BlackAndWhite()
])
clip.write_videofile("output.mp4")

Text Overlays

from moviepy import VideoFileClip, TextClip, CompositeVideoClip

video = VideoFileClip("video.mp4")
text = TextClip(
    'arial.ttf',
    "Hello World",
    font_size=60,
    color='white'
)
text = text.with_duration(video.duration)
text = text.with_position(('center', 100))

final = CompositeVideoClip([video, text])
final.write_videofile("output.mp4")

video.close()
final.close()

MovieLite uses the pictex library for advanced text styling with gradients, shadows, and more.

Image Clips

from moviepy import ImageClip

img = ImageClip("image.png")
img = img.with_duration(5)
img.write_videofile("output.mp4", fps=30)

Compositing Multiple Clips

from moviepy import VideoFileClip, CompositeVideoClip

background = VideoFileClip("bg.mp4")
overlay = VideoFileClip("overlay.mp4")

overlay = overlay.with_opacity(0.5)
overlay = overlay.resized(width=320)
overlay = overlay.with_position((20, 20))

final = CompositeVideoClip([background, overlay])
final.write_videofile("output.mp4")

background.close()
overlay.close()
final.close()

Transitions

from moviepy import VideoFileClip, concatenate_videoclips
from moviepy.video.fx import CrossFadeIn

clip1 = VideoFileClip("scene1.mp4")
clip2 = VideoFileClip("scene2.mp4")

clip2 = clip2.with_effects([CrossFadeIn(1.0)])
final = concatenate_videoclips([clip1, clip2], padding=-1)

final.write_videofile("output.mp4")

Audio Handling

Adding Background Music

from moviepy import VideoFileClip, AudioFileClip

video = VideoFileClip("video.mp4")
music = AudioFileClip("music.mp3")

music = music.with_volume_scaled(0.5)
video = video.with_audio(music)
video.write_videofile("output.mp4")

video.close()
music.close()

Audio Fade Effects

from moviepy import AudioFileClip
from moviepy.audio.fx import AudioFadeIn, AudioFadeOut

audio = AudioFileClip("music.mp3")
audio = audio.with_effects([
    AudioFadeIn(2.0),
    AudioFadeOut(2.0)
])

Alpha/Transparency

from moviepy import VideoFileClip, CompositeVideoClip

main = VideoFileClip("main.mp4")
alpha_clip = VideoFileClip("transparent.mov", has_mask=True)

alpha_clip = alpha_clip.with_position('center')
final = CompositeVideoClip([main, alpha_clip])
final.write_videofile("output.mp4")

Use AlphaVideoClip instead of VideoClip when you need transparency support. It loads frames in BGRA format.

Custom Frame Transformations

import cv2
from moviepy import VideoFileClip

def sepia_effect(frame):
    kernel = np.array([
        [0.131, 0.534, 0.272],
        [0.168, 0.686, 0.349],
        [0.189, 0.769, 0.393]
    ])
    return cv2.transform(frame, kernel)

clip = VideoFileClip("video.mp4")
clip = clip.image_transform(sepia_effect)
clip.write_videofile("output.mp4")

In MovieLite, custom transforms receive both the frame and the current time t, allowing for time-based effects.

Parallel Rendering

clip = VideoFileClip("video.mp4")
clip.write_videofile(
    "output.mp4",
    threads=8  # Use 8 threads
)

Quality Settings

clip.write_videofile(
    "output.mp4",
    preset="slow",  # x264 preset
    ffmpeg_params=["-crf", "18"]  # CRF quality
)

MovieLite currently offers preset quality levels. Fine-grained FFmpeg parameter control is on the roadmap.

Migration Checklist

Update imports

Replace from moviepy import ... with from movielite import ...

Change clip loading

Replace VideoFileClip with VideoClip and AudioFileClip with AudioClip

Use VideoWriter for output

Replace clip.write_videofile() with VideoWriter + add_clip() + write()

Update method names

with_effects() → add_effect()
with_position() → set_position()
with_opacity() → set_opacity()
resized() → set_size() or set_scale()
subclipped() → subclip()

Handle compositing

Replace CompositeVideoClip with explicit timing using start parameters

Update text rendering

Replace MoviePy’s TextClip with MovieLite’s TextClip + pictex Canvas

Test and optimize

Run your code and measure the performance improvements!

Key Differences Summary

API Design

MoviePy uses immutable clips with .with_*() methods that return new clips
MovieLite uses mutable clips with .set_*() methods that modify and return self for chaining
MovieLite separates composition (VideoWriter) from clip manipulation

Output Formats

MoviePy supports many codecs and formats
MovieLite currently only supports MP4 with H.264 video and AAC audio
More format support is planned for future releases

Performance

MovieLite is 3-5x faster on common tasks due to Numba JIT compilation
MovieLite is CPU-optimized (GPU support planned)
MovieLite has better memory management for long videos

Text Rendering

MoviePy uses ImageMagick or PIL for text
MovieLite uses the pictex library for advanced styling
MovieLite text supports gradients, shadows, and complex layouts

Effects

Both libraries support chaining effects
MovieLite’s effects are JIT-compiled for better performance
Effect names and parameters are largely compatible

Common Pitfalls

Remember to close clips: Always call clip.close() when done to free resources, especially when working with multiple videos.

Manual position calculation: MovieLite doesn’t support string-based positioning like 'center' yet. Calculate positions manually.

Format limitations: MovieLite only outputs MP4 files. If you need other formats, use FFmpeg to convert the output.

Timing in concatenation: Instead of using concatenation functions, set explicit start times for each clip. This gives you more control.

Need Help?

If you encounter issues during migration:

Check the API Reference for detailed method documentation
Review the examples directory
Open an issue on GitHub

What’s Not Supported (Yet)

Some MoviePy features are not yet available in MovieLite:

GPU acceleration
Output formats other than MP4/H.264
String-based positioning ('center', 'top', etc.)
Some advanced effects (3D transforms, etc.)
Direct FFmpeg parameter control

These features are on the roadmap for future releases.

Additional

Migrating from MoviePy

Why Migrate?

Philosophy Differences

MoviePy

MovieLite

Installation

Core API Comparison

Basic Video Loading and Export

Extracting Subclips

Concatenating Videos

Transformations

Resizing

Dynamic Scaling/Zoom

Positioning

Opacity

Speed Control

Visual Effects

Fade In/Out

Blur

Color Adjustments

Text Overlays

Image Clips

Compositing Multiple Clips

Transitions

Audio Handling

Adding Background Music

Audio Fade Effects

Alpha/Transparency

Custom Frame Transformations

Parallel Rendering

Quality Settings

Migration Checklist

Key Differences Summary

Common Pitfalls

Need Help?

What’s Not Supported (Yet)

Build docs developers (and LLMs) love

Additional

​Why Migrate?

​Philosophy Differences

MoviePy

MovieLite

​Installation

​Core API Comparison

​Basic Video Loading and Export

​Extracting Subclips

​Concatenating Videos

​Transformations

​Resizing

​Dynamic Scaling/Zoom

​Positioning

​Opacity

​Speed Control

​Visual Effects

​Fade In/Out

​Blur

​Color Adjustments

​Text Overlays

​Image Clips

​Compositing Multiple Clips

​Transitions

​Audio Handling

​Adding Background Music

​Audio Fade Effects

​Alpha/Transparency

​Custom Frame Transformations

​Parallel Rendering

​Quality Settings

​Migration Checklist

​Key Differences Summary

​Common Pitfalls

​Need Help?

​What’s Not Supported (Yet)

Build docs developers (and LLMs) love

Why Migrate?

Philosophy Differences

Installation

Core API Comparison

Basic Video Loading and Export

Extracting Subclips

Concatenating Videos

Transformations

Resizing

Dynamic Scaling/Zoom

Positioning

Opacity

Speed Control

Visual Effects

Fade In/Out

Blur

Color Adjustments

Text Overlays

Image Clips

Compositing Multiple Clips

Transitions

Audio Handling

Adding Background Music

Audio Fade Effects

Alpha/Transparency

Custom Frame Transformations

Parallel Rendering

Quality Settings

Migration Checklist

Key Differences Summary

Common Pitfalls

Need Help?

What’s Not Supported (Yet)