Python MoviePy Video Editing — Core Concepts

Learn MoviePy's clip-based architecture, compositing model, audio handling, and effects system for programmatic video editing in Python.

What MoviePy does

MoviePy is a Python library for video editing — cutting, concatenating, compositing, and applying effects — all from code. It wraps FFmpeg for I/O and uses NumPy arrays to represent individual frames, giving you pixel-level control without dealing with codec details directly.

Install with pip install moviepy. FFmpeg must be available on the system path.

The clip model

Everything in MoviePy is a clip — an object with a duration that produces frames over time:

VideoFileClip — loads a video file (MP4, AVI, MOV, etc.)
AudioFileClip — loads an audio file (MP3, WAV, OGG)
ImageClip — a still image shown for a set duration
TextClip — rendered text (requires ImageMagick)
ColorClip — a solid color rectangle

Clips are immutable-style: methods like .subclip(), .resize(), and .fx() return new clip objects rather than modifying the original.

Cutting and concatenating

Extract a segment with .subclip(start, end) where times can be seconds or "MM:SS" strings. Join clips end-to-end with concatenate_videoclips():

from moviepy.editor import VideoFileClip, concatenate_videoclips

clip = VideoFileClip("raw.mp4")
intro = clip.subclip(0, 5)
highlight = clip.subclip(30, 45)
final = concatenate_videoclips([intro, highlight])
final.write_videofile("output.mp4")

The method="compose" parameter handles clips of different sizes by centering them on a canvas.

Compositing

Stack clips on top of each other with CompositeVideoClip:

from moviepy.editor import CompositeVideoClip

background = VideoFileClip("main.mp4")
overlay = ImageClip("logo.png").set_duration(background.duration)
overlay = overlay.set_position(("right", "top")).resize(height=50)
result = CompositeVideoClip([background, overlay])

Position accepts pixel tuples, named locations like "center", or functions of time for moving overlays.

Effects

MoviePy includes built-in effects: speed changes, fades, color adjustments, mirroring, and rotation. Apply them with .fx():

from moviepy.video.fx.all import speedx, fadein, mirror_x

clip = VideoFileClip("input.mp4")
clip = clip.fx(speedx, 2)       # double speed
clip = clip.fx(fadein, 1.5)     # 1.5-second fade in
clip = clip.fx(mirror_x)        # horizontal flip

Custom effects are functions that take a clip and return a modified clip. Since frames are NumPy arrays, you can apply any pixel transformation — filters, overlays, chroma key, frame blending.

Audio handling

Every VideoFileClip has an .audio attribute. You can replace it, mix tracks, or adjust volume:

video = VideoFileClip("clip.mp4")
music = AudioFileClip("song.mp3").subclip(0, video.duration)
video = video.set_audio(music)

CompositeAudioClip mixes multiple audio tracks. Volume is adjustable with .volumex().

Writing output

write_videofile() encodes the final result. Key parameters:

fps — output frame rate (default matches source)
codec — video codec ("libx264" is default for MP4)
audio_codec — audio codec ("aac" for MP4)
bitrate — target bitrate string like "5000k"
threads — CPU threads for encoding

For GIFs, use write_gif(). For image sequences, use write_images_sequence().

Performance considerations

MoviePy loads frames on demand, but compositing many layers or applying heavy effects increases memory usage. For large files, process in chunks or use .resize() to work at lower resolution during development. The FFmpeg encoding step is usually the bottleneck — use hardware-accelerated codecs when available.

The one thing to remember: MoviePy models video editing as operations on clip objects — cut, stack, transform, and export — with NumPy arrays as the frame format and FFmpeg handling the codec work.

pythonmoviepyvideoediting