MoviePy

The moviepy.audio.io module provides tools for reading and writing audio files. Key components include:

• AudioFileClip: The primary class for loading an audio file as a clip.
• ffmpeg_audiowriter: A writer used to save audio clips to disk using FFmpeg.
• ffplay_audiopreview: A utility for previewing audio via FFplay.
• readers: A sub-module containing various audio reading implementations.

MoviePy is organized into several core modules that handle different aspects of video and audio manipulation. The primary modules available for use are:

• moviepy.Clip: Core classes for video and audio clips.
• moviepy.Effect: Tools for applying visual or auditory effects.
• moviepy.audio: Functions and classes specifically for audio processing.
• moviepy.video: Functions and classes specifically for video processing.
• moviepy.config: Configuration settings for MoviePy (e.g., paths to FFmpeg).
• moviepy.tools: Internal and utility functions.
• moviepy.decorators: Decorators used within the library.

The moviepy.audio module provides the core functionality for audio manipulation in MoviePy. It is organized into several submodules:

• moviepy.audio.AudioClip: Contains the base class and logic for audio clips.
• moviepy.audio.fx: Contains audio effects (e.g., volume changes, fading).
• moviepy.audio.io: Handles audio input/output operations (loading and saving audio files).
• moviepy.audio.tools: Provides internal utility functions for audio processing.

Most clip manipulation methods in MoviePy (often starting with with_) are out-of-place. This means they do not modify the original object but instead return a new modified copy. You must reassign the result to a variable to save the changes.

# INCORRECT: The original clip remains unchanged
clip.with_effects(some_effect)

# CORRECT: Reassign the returned copy
clip = clip.with_effects(some_effect)

MoviePy relies on several underlying technologies to handle media:

• FFmpeg: Used for reading and exporting video and audio files.
• FFplay: Optionally used for video previewing.
• Numpy: Used for the internal representation and manipulation of media via fast numerical arrays.
• Pillow: Used for advanced effects and enhancements.

MoviePy operates by importing media (video frames, images, sounds) and converting them into Python objects (specifically numpy arrays). This allows every pixel to be accessible for manipulation.

Users can define video or audio effects using these arrays or built-in functions. The library supports mixing clips through techniques like:

• Concatenation: Joining clips end-to-end.
• Compositing: Playing clips side-by-side or on top of each other with transparency.

Once editing is complete, the final clip is encoded back into standard formats like mp4, webm, or gif. Because of the heavy data import/export operations required to convert media to numpy arrays, MoviePy is more flexible and approachable than raw ffmpeg but generally slower.

The moviepy.video module is the primary namespace for video-related operations in MoviePy. It is organized into several submodules that handle different aspects of video processing:

• moviepy.video.VideoClip: The core class for representing video clips.
• moviepy.video.compositing: Tools and functions for layering and combining multiple clips.
• moviepy.video.fx: A collection of video effects (filters, transformations, etc.).
• moviepy.video.io: Input/Output operations specifically for video files.
• moviepy.video.tools: Internal or utility functions used for video processing.

MoviePy v2.0 has renamed most methods that modify a clip to start with with_. This indicates an 'out-of-place' operation: the method does not modify the original clip instance, but instead returns a new, modified copy.

When migrating from v1.x, check your Clip object method calls and replace .set_ style methods with their .with_ equivalents.

# Example of the pattern change
# Instead of clip.set_duration(10)
new_clip = clip.with_duration(10)

MoviePy uses out-of-place modification. When you modify a clip, the original object remains untouched; instead, MoviePy returns a new modified copy. This prevents accidental side effects but means you must always capture the returned object.

Memory and Performance: Modifications and effects are lazy. Applying an effect does not immediately process all frames. Computation only occurs during the final rendering (e.g., when writing to a file or previewing). This makes creating new clip objects very efficient in terms of both time and memory.