Classes of Video Clips


class, ismask=False, duration=None)[source]

Bases: moviepy.Clip.Clip

Base class for video clips.

See VideofileClip, ImageClip etc. for more user-friendly classes.


ismask :

True if the clip is going to be used as a mask.


size The size of the clip, (width,heigth), in pixels.
w, h The width and height of the clip, in pixels.
ismask Boolean set to True if the clip is a mask.
make_frame A function t-> frame at time t where frame is a w*h*3 RGB array.
mask (default None)
VideoClip mask attached to this clip. If mask is None,
The video clip is fully opaque.
audio (default None) An AudioClip instance containing the audio of the video clip.
pos A function t->(x,y) where x,y is the position of the clip when it is composed with other clips. See VideoClip.set_pos for more details
relative_pos See variable pos.

Add a mask VideoClip to the VideoClip.

Returns a copy of the clip with a completely opaque mask (made of ones). This makes computations slower compared to having a None mask but can be useful in many cases. Choose

Set constant_size to False for clips with moving image size.

afx(fun, *a, **k)[source]

Transform the clip’s audio.

Return a new clip whose audio has been transformed by fun.

blit_on(picture, t)[source]

Returns the result of the blit of the clip’s frame at time t on the given picture, the position of the clip being given by the clip’s pos attribute. Meant for compositing.

fl_image(image_func, apply_to=[])[source]

Modifies the images of a clip by replacing the frame get_frame(t) by another frame, image_func(get_frame(t))

on_color(size=None, color=(0, 0, 0), pos=None, col_opacity=None)[source]

Place the clip on a colored background.

Returns a clip made of the current clip overlaid on a color clip of a possibly bigger size. Can serve to flatten transparent clips.


size :

Size (width, height) in pixels of the final clip. By default it will be the size of the current clip.

bg_color :

Background color of the final clip ([R,G,B]).

pos :

Position of the clip in the final clip. ‘center’ is the default

col_opacity :

Parameter in 0..1 indicating the opacity of the colored background.

save_frame(filename, t=0, withmask=True)[source]

Save a clip’s frame to an image file.

Saves the frame of clip corresponding to time t in ‘filename’. t can be expressed in seconds (15.35), in (min, sec), in (hour, min, sec), or as a string: ‘01:03:05.35’.

If withmask is True the mask is saved in the alpha layer of the picture (only works with PNGs).


Attach an AudioClip to the VideoClip.

Returns a copy of the VideoClip instance, with the audio attribute set to audio, hich must be an AudioClip instance.


Change the clip’s get_frame.

Returns a copy of the VideoClip instance, with the make_frame attribute set to mf.


Set the clip’s mask.

Returns a copy of the VideoClip with the mask attribute set to mask, which must be a greyscale (values in 0-1) VideoClip


Set the opacity/transparency level of the clip.

Returns a semi-transparent copy of the clip where the mask is multiplied by op (any float, normally between 0 and 1).

set_pos(*a, **kw)[source]

The function set_pos is deprecated and is kept temporarily for backwards compatibility. Please use the new name, set_position, instead.

set_position(pos, relative=False)

Set the clip’s position in compositions.

Sets the position that the clip will have when included in compositions. The argument pos can be either a couple (x,y) or a function t-> (x,y). x and y mark the location of the top left corner of the clip, and can be of several types.


>>> clip.set_pos((45,150)) # x=45, y=150
>>> # clip horizontally centered, at the top of the picture
>>> clip.set_pos(("center","top"))
>>> # clip is at 40% of the width, 70% of the height:
>>> clip.set_pos((0.4,0.7), relative=True)
>>> # clip's position is horizontally centered, and moving up !
>>> clip.set_pos(lambda t: ('center', 50+t) )
subfx(fx, ta=0, tb=None, **kwargs)[source]

Apply a transformation to a part of the clip.

Returns a new clip in which the function fun (clip->clip) has been applied to the subclip between times ta and tb (in seconds).


>>> # The scene between times t=3s and t=6s in ``clip`` will be
>>> # be played twice slower in ``newclip``
>>> newclip = clip.subapply(lambda c:c.speedx(0.5) , 3,6)
to_ImageClip(t=0, with_mask=True)[source]

Returns an ImageClip made out of the clip’s frame at time t, which can be expressed in seconds (15.35), in (min, sec), in (hour, min, sec), or as a string: ‘01:03:05.35’.


Returns a non-mask video clip made from the mask video clip.

to_gif(*a, **kw)[source]

The function to_gif is deprecated and is kept temporarily for backwards compatibility. Please use the new name, write_gif, instead.

to_images_sequence(*a, **kw)[source]

The function to_images_sequence is deprecated and is kept temporarily for backwards compatibility. Please use the new name, write_images_sequence, instead.


Returns a mask a video clip made from the clip.

to_videofile(*a, **kw)[source]

The function to_videofile is deprecated and is kept temporarily for backwards compatibility. Please use the new name, write_videofile, instead.


Remove the clip’s audio.

Return a copy of the clip with audio set to None.

write_gif(filename, fps=None, program='imageio', opt='wu', fuzz=1, verbose=True, loop=0, dispose=False, colors=None, tempfiles=False)

Write the VideoClip to a GIF file.

Converts a VideoClip into an animated GIF using ImageMagick or ffmpeg.


filename :

Name of the resulting gif file.

fps :

Number of frames per second (see note below). If it

isn’t provided, then the function will look for the clip’s fps attribute (VideoFileClip, for instance, have one).

program :

Software to use for the conversion, either ‘imageio’ (this will use the library FreeImage through ImageIO), or ‘ImageMagick’, or ‘ffmpeg’.

opt :

Optimalization to apply. If program=’imageio’, opt must be either ‘wu’ (Wu) or ‘nq’ (Neuquant). If program=’ImageMagick’, either ‘optimizeplus’ or ‘OptimizeTransparency’.

fuzz :

(ImageMagick only) Compresses the GIF by considering that the colors that are less than fuzz% different are in fact the same.


The gif will be playing the clip in real time (you can only change the frame rate). If you want the gif to be played slower than the clip you will use

>>> # slow down clip 50% and make it a gif
>>> myClip.speedx(0.5).to_gif('myClip.gif')
write_images_sequence(nameformat, fps=None, verbose=True, withmask=True)

Writes the videoclip to a sequence of image files.


nameformat :

A filename specifying the numerotation format and extension of the pictures. For instance “frame%03d.png” for filenames indexed with 3 digits and PNG format. Also possible: “some_folder/frame%04d.jpeg”, etc.

fps :

Number of frames per second to consider when writing the clip. If not specified, the clip’s fps attribute will be used if it has one.

withmask :

will save the clip’s mask (if any) as an alpha canal (PNGs only)

verbose :

Verbose output ?


names_list :

A list of all the files generated.


The resulting image sequence can be read using e.g. the class DirectoryClip.

write_videofile(filename, fps=None, codec=None, bitrate=None, audio=True, audio_fps=44100, preset='medium', audio_nbytes=4, audio_codec=None, audio_bitrate=None, audio_bufsize=2000, temp_audiofile=None, rewrite_audio=True, remove_temp=True, write_logfile=False, verbose=True, threads=None, ffmpeg_params=None)

Write the clip to a videofile.


filename :

Name of the video file to write in. The extension must correspond to the “codec” used (see below), or simply be ‘.avi’ (which will work with any codec).

fps :

Number of frames per second in the resulting video file. If None is provided, and the clip has an fps attribute, this fps will be used.

codec :

Codec to use for image encoding. Can be any codec supported by ffmpeg. If the filename is has extension ‘.mp4’, ‘.ogv’, ‘.webm’, the codec will be set accordingly, but you can still set it if you don’t like the default. For other extensions, the output filename must be set accordingly.

Some examples of codecs are:

'libx264' (default codec for file extension .mp4) makes well-compressed videos (quality tunable using ‘bitrate’).

'mpeg4' (other codec for extension .mp4) can be an alternative to 'libx264', and produces higher quality videos by default.

'rawvideo' (use file extension .avi) will produce a video of perfect quality, of possibly very huge size.

png (use file extension .avi) will produce a video of perfect quality, of smaller size than with rawvideo

'libvorbis' (use file extension .ogv) is a nice video format, which is completely free/ open source. However not everyone has the codecs installed by default on their machine.

'libvpx' (use file extension .webm) is tiny a video format well indicated for web videos (with HTML5). Open source.

audio :

Either True, False, or a file name. If True and the clip has an audio clip attached, this audio clip will be incorporated as a soundtrack in the movie. If audio is the name of an audio file, this audio file will be incorporated as a soundtrack in the movie.

audiofps :

frame rate to use when generating the sound.

temp_audiofile :

the name of the temporary audiofile to be generated and incorporated in the the movie, if any.

audio_codec :

Which audio codec should be used. Examples are ‘libmp3lame’ for ‘.mp3’, ‘libvorbis’ for ‘ogg’, ‘libfdk_aac’:’m4a’, ‘pcm_s16le’ for 16-bit wav and ‘pcm_s32le’ for 32-bit wav. Default is ‘libmp3lame’, unless the video extension is ‘ogv’ or ‘webm’, at which case the default is ‘libvorbis’.

audio_bitrate :

Audio bitrate, given as a string like ‘50k’, ‘500k’, ‘3000k’. Will determine the size/quality of audio in the output file. Note that it mainly an indicative goal, the bitrate won’t necessarily be the this in the final file.

preset :

Sets the time that FFMPEG will spend optimizing the compression. Choices are: ultrafast, superfast, fast, medium, slow, superslow. Note that this does not impact the quality of the video, only the size of the video file. So choose ultrafast when you are in a hurry and file size does not matter.

threads :

Number of threads to use for ffmpeg. Can speed up the writing of the video on multicore computers

ffmpeg_params :

Any additional ffmpeg parameters you would like to pass, as a list of terms, like [‘-option1’, ‘value1’, ‘-option2’, ‘value2’]

write_logfile :

If true, will write log files for the audio and the video. These will be files ending with ‘.log’ with the name of the output file in them.


>>> from moviepy.editor import VideoFileClip
>>> clip = VideoFileClip("myvideo.mp4").subclip(100,120)
>>> clip.write_videofile("my_new_video.mp4")


class, has_mask=False, audio=True, audio_buffersize=200000, audio_fps=44100, audio_nbytes=2, verbose=False)[source]


A video clip originating from a movie file. For instance:

>>> clip = VideofileClip("myHolidays.mp4")
>>> clip2 = VideofileClip("myMaskVideo.avi")

filename: :

The name of the video file. It can have any extension supported by ffmpeg: .ogv, .mp4, .mpeg, .avi, .mov etc.

has_mask: :

Set this to ‘True’ if there is a mask included in the videofile. Video files rarely contain masks, but some video codecs enable that. For istance if you have a MoviePy VideoClip with a mask you can save it to a videofile with a mask. (see also VideoClip.to_videofile for more details).

audio: :

Set to False if the clip doesn’t have any audio or if you do not wish to read the audio.


filename: Name of the original video file.
fps: Frames per second in the original file.


class, ismask=False, transparent=True, fromalpha=False, duration=None)[source]


Class for non-moving VideoClips.

A video clip originating from a picture. This clip will simply display the given picture at all times.


img :

Any picture file (png, tiff, jpeg, etc.) or any array representing an RGB image (for instance a frame from a VideoClip).

ismask :

Set this parameter to True if the clip is a mask.

transparent :

Set this parameter to True (default) if you want the alpha layer of the picture (if it exists) to be used as a mask.


>>> clip = ImageClip("myHouse.jpeg")
>>> clip = ImageClip( someArray ) # a Numpy array represent


img Array representing the image of the clip.
fl(fl, apply_to=[], keep_duration=True)[source]

General transformation filter.

Equivalent to VideoClip.fl . The result is no more an ImageClip, it has the class VideoClip (since it may be animated)

fl_image(image_func, apply_to=[])[source]

Image-transformation filter.

Does the same as VideoClip.fl_image, but for ImageClip the tranformed clip is computed once and for all at the beginning, and not for each ‘frame’.

fl_time(time_func, apply_to=['mask', 'audio'], keep_duration=False)[source]

Time-transformation filter.

Applies a transformation to the clip’s timeline (see Clip.fl_time).

This method does nothing for ImageClips (but it may affect their masks or their audios). The result is still an ImageClip.


class, col=(0, 0, 0), ismask=False, duration=None)[source]


An ImageClip showing just one color.


size :

Size (width, height) in pixels of the clip.

color :

If argument ismask is False, color indicates the color in RGB of the clip (default is black). If ismask` is True, color must be a float between 0 and 1 (default is 1)

ismask :

Set to true if the clip will be used as a mask.


class, filename=None, size=None, color='black', bg_color='transparent', fontsize=None, font='Courier', stroke_color=None, stroke_width=1, method='label', kerning=None, align='center', interline=None, tempfilename=None, temptxt=None, transparent=True, remove_temp=True, print_cmd=False)[source]


Class for autogenerated text clips.

Creates an ImageClip originating from a script-generated text image. Requires ImageMagick.


txt :

A string of the text to write. Can be replaced by argument filename.

filename :

The name of a file in which there is the text to write. Can be provided instead of argument txt

size :

Size of the picture in pixels. Can be auto-set if method=’label’, but mandatory if method=’caption’. the height can be None, it will then be auto-determined.

bg_color :

Color of the background. See TextClip.list('color') for a list of acceptable names.

color :

Color of the background. See TextClip.list('color') for a list of acceptable names.

font :

Name of the font to use. See TextClip.list('font') for the list of fonts you can use on your computer.

stroke_color :

Color of the stroke (=contour line) of the text. If None, there will be no stroke.

stroke_width :

Width of the stroke, in pixels. Can be a float, like 1.5.

method :

Either ‘label’ (default, the picture will be autosized so as to fit exactly the size) or ‘caption’ (the text will be drawn in a picture with fixed size provided with the size argument). If caption, the text will be wrapped automagically (sometimes it is buggy, not my fault, complain to the ImageMagick crew) and can be aligned or centered (see parameter align).

kerning :

Changes the default spacing between letters. For nstance kerning=-1 will make the letters 1 pixel nearer from ach other compared to the default spacing.

align :

center | East | West | South | North . Will only work if method is set to caption

transparent :

True (default) if you want to take into account the transparency in the image.

static list(arg)[source]

Returns the list of all valid entries for the argument of TextClip given (can be font, color, etc...)

static search(string, arg)

Returns the of all valid entries which contain string for the argument arg of TextClip, for instance

>>> # Find all the available fonts which contain "Courier"
>>> print ('Courier', 'font') )


class, size=None, bg_color=None, use_bgclip=False, ismask=False)[source]


A VideoClip made of other videoclips displayed together. This is the base class for most compositions.


The size (height x width) of the final clip.

A list of videoclips. Each clip of the list will be displayed below the clips appearing after it in the list. For each clip:

  • The attribute pos determines where the clip is placed.

    See VideoClip.set_pos

  • The mask of the clip determines which parts are visible.

Finally, if all the clips in the list have their duration attribute set, then the duration of the composite video clip is computed automatically

Color for the unmasked and unfilled regions. Set to None for these regions to be transparent (will be slower).

If all clips with a fps attribute have the same fps, it becomes the fps of the result.


Returns a list of the clips in the composite clips that are actually playing at the given time t.