.. _clips:

Creating and exporting video clips
===================================

Video au audio clips are the central objects of MoviePy. In this section we present the different sorts of clips, how to create them, and how to write them to a file. For informations on modifying a clip (cuts, effects, etc.), see :ref:`effects`. For how to put clips together see :ref:`CompositeVideoClips` and to see how to preview clips before writing a file, refer to :ref:`efficient`.

The following code summarizes the base clips that you can create with moviepy: ::
    
    # VIDEO CLIPS
    clip = VideoClip(make_frame, duration=4) # for custom animations (see below)
    clip = VideoFileClip("my_video_file.mp4") # or .avi, .webm, .gif ...
    clip = ImageClip("my_picture.png") # or .jpeg, .tiff, ...
    clip = TextClip("Hello !", font="Amiri-Bold", fontsize=70, color="black")
    clip = ColorClip(size=(460,380), color=[R,G,B])
    
    # AUDIO CLIPS
    clip = AudioFileClip("my_audiofile.mp3") # or .ogg, .wav... or a video !
    clip = AudioArrayClip(numpy_array, fps=44100) # from a numerical array
    clip = AudioClip(make_frame, duration=3) # uses a function make_frame(t) 



The best to understand these clips is to read the full documentation for each in the :ref:`reference_manual`. The next sections
In this section we see how to create clips, (for instance from video or audio files), how to mix them together, and how to write them to a file. 



Categories of video clips
~~~~~~~~~~~~~~~~~~~~~~~~~~

Video clips are the building blocks of longer videos. Technically, they are clips with a ``clip.get_frame(t)`` method which outputs a HxWx3 numpy array representing the frame of the clip at time *t*. There are two main categories: animated clips (made with ``VideoFileClip`` and ``VideoClip``) and unanimated clips which show the same picture for an a-priori infinite duration (``ImageClip``, ``TextClip``,``ColorClip``). There are also special video clips call masks, which belong to the categories above but output greyscale frames indicating which parts of another clip are visible or not. A video clip can carry around an audio clip (``clip.audio``) which is its *soundtrack*, and a mask clip. 

VideoClip
""""""""""

``VideoClip`` is the base class for all the other video clips in MoviePy. If all you want is to edit video files, you will never need it. This class is practical when you want to make animations from frames that are generated by another library. All you need is to define a function ``make_frame(t)`` which returns a HxWx3 numpy array (of 8-bits integers) representing the frame at time t. Here is an example with the graphics library Gizeh: ::

    import gizeh
    import moviepy.editor as mpy

    def make_frame(t):
        surface = gizeh.Surface(128,128) # width, height
        radius = W*(1+ (t*(2-t))**2 )/6 # the radius varies over time
        circle = gizeh.circle(radius, xy = (64,64), fill=(1,0,0))
        circle.draw(surface)
        return surface.get_npimage() # returns a 8-bit RGB array

    clip = mpy.VideoClip(make_frame, duration=2) # 2 seconds
    clip.write_gif("circle.gif",fps=15)

.. image:: circle.gif
   :width: 128 px
   :align: center

Note: three next sections are in construction

VideoFileClip
"""""""""""""""
See :py:class:`~moviepy.video.io.VideoFileClip.VideoFileClip`.

ImageClip
""""""""""
See :py:class:`~moviepy.video.VideoClip.ImageClip`.

TextClip
"""""""""""""""
See :py:class:`~moviepy.video.VideoClip.TextClip`.


Mask clips
~~~~~~~~~~~~~~

A mask is a special video clip which indicates which pixels will be visible when a video clip carrying this mask will be composed with other video clips (see :ref:`CompositeVideoClips`).

The fundamental difference between masks and standard clips is that standard clips output frames with 3 components (R-G-B) per pixel, comprised between 0 and 255, while a mask has just one composant per pixel, between 0 and 1 (1 indicating a fully visible pixel and 0 a transparent pixel). Seen otherwise, a mask is always in greyscale.

When you create or load a clip that you will use as a mask you need to declare it: ::

    mclip = VideoClip(makeframe, duration=4, ismask=True)
    mclip = ImageClip("my_mask.jpeg", ismask=True)
    mclip = VideoClip("myvideo.mp4", ismask=True)
    
In the case of video and image files, if these are not already black and white they will be converted automatically.

Any video clip can be turned into a mask with ``clip.to_mask()``, and a mask can be turned to a standard RGB video clip with ``my_mask_clip.to_RGB()``.


Masks are treated differently by many methods (because their frames are different) but you can do with a mask pretty much everything you can do with a standard clip: you can cut it, edit it, preview it, write it to a video file, make snapshots, etc.

.. _renderingAClip:

Exporting video clips
~~~~~~~~~~~~~~~~~~~~~~~

Video files (.mp4, .webm, .ogv...)
""""""""""""""""""""""""""""""""""""

To write a clip as a video file, use ::
    
    my_clip.write_videofile("movie.mp4") # default codec: 'libx264', 24 fps
    my_clip.write_videofile("movie.mp4",fps=15)
    my_clip.write_videofile("movie.webm") # webm format
    my_clip.write_videofile("movie.webm",audio=False) # don't render audio.
    
MoviePy has default codec names for the most common file extensions. If you want to use exotic formats or if you are not happy with the defaults you can provide the codec with ``codec='mpeg4'`` for instance. There are many many options when you are writing a video (bitrate, parameters of the audio writing, file size optimization, number of processors to use, etc.). Please refer to :py:meth:`~moviepy.video.VideoClip.VideoClip.write_videofile` for more.


Sometimes it is impossible for MoviePy to guess the ``duration`` attribute of the clip (keep in mind that some clips, like ImageClips displaying a picture, have *a priori* an infinite duration). Then, the ``duration`` must be set manually with ``clip.set_duration``: ::

    # Make a video showing a flower for 5 seconds
    my_clip = Image("flower.jpeg") # has infinite duration
    my_clip.write_videofile("flower.mp4") # Will fail ! NO DURATION !
    my_clip.set_duration(5).write_videofile("flower.mp4") # works !


Animated GIFs
""""""""""""""

To write your video as an animated GIF, use ::

    my_clip.write_gif('test.gif', fps=12)

Note that this requires ImageMagick installed. Otherwise you can also create the GIF with ffmpeg by adding the option ``program='ffmpeg'``, it will be much faster but won't look as nice and won't be optimized.

There are many options to optimize the quality and size of a gif. Please refer to :py:meth:`~moviepy.video.VideoClip.VideoClip.write_gif`.

Note that for editing gifs the best way is to preview them in the notebook as explained here: :ref:`ipython_display`

See `this blog post <http://zulko.github.io/blog/2014/01/23/making-animated-gifs-from-video-files-with-python>`_ for informations on making GIFs from video files, and `this other post <http://zulko.github.io/blog/2014/09/20/vector-animations-with-python/>`_ for GIF animations with vector graphics.

.. _CCaudioClips:


