diff --git a/docs/FAQ.rst b/docs/FAQ.rst index f77e53f92..6eaadf980 100644 --- a/docs/FAQ.rst +++ b/docs/FAQ.rst @@ -25,7 +25,7 @@ I can't seem to read any video with MoviePy """""""""""""""""""""""""""""""""""""""""""""" Known reason: you have a deprecated version of FFMPEG, install a recent version from the -website, not from your OS's repositories ! (see :ref:`installation`). +website, not from your OS's repositories ! (see :ref:`install`). Previewing videos make them slower than they are """"""""""""""""""""""""""""""""""""""""""""""""" diff --git a/docs/conf.py b/docs/conf.py index d841bbecb..70c947f3c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -46,7 +46,7 @@ # General information about the project. project = u'MoviePy' -copyright = u'2014, Zulko' +copyright = u'2017, Zulko' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -55,7 +55,7 @@ # The short X.Y version. version = '0.2' # The full version, including alpha/beta/rc tags. -release = '0.2' +release = '0.2.3.1' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -263,7 +263,7 @@ epub_title = u'MoviePy' epub_author = u'Zulko' epub_publisher = u'Zulko' -epub_copyright = u'2013, Zulko' +epub_copyright = u'2017, Zulko' # The language of the text. It defaults to the language option # or en if the language is not set. diff --git a/docs/examples/examples.rst b/docs/examples/examples.rst index 9ae71d3df..98a9a5a5f 100644 --- a/docs/examples/examples.rst +++ b/docs/examples/examples.rst @@ -17,6 +17,10 @@ Here are a few example scripts to get you started. Most are quite old now and wi masked_credits painting_effect compo_from_image + logo + headblur + quick_recipes + several_characters the_end diff --git a/docs/examples/logo.rst b/docs/examples/logo.rst index a47f40026..2adf1ee7b 100644 --- a/docs/examples/logo.rst +++ b/docs/examples/logo.rst @@ -5,6 +5,4 @@ MoviePy logo with a moving shadow
-Here the logo is a picture, while the shadow is actually a black rectangle taking the whole screen, overlaid over the logo, but with a moving mask composed of a bi-gradient, such that only one (moving) part of the rectangle is visible. See :ref:`gradients` for the code of the function `biGradient`: :: - - +Here the logo is a picture, while the shadow is actually a black rectangle taking the whole screen, overlaid over the logo, but with a moving mask composed of a bi-gradient, such that only one (moving) part of the rectangle is visible. \ No newline at end of file diff --git a/docs/examples/masked_credits.rst b/docs/examples/masked_credits.rst index 838c7319a..145ce3b9a 100644 --- a/docs/examples/masked_credits.rst +++ b/docs/examples/masked_credits.rst @@ -7,7 +7,7 @@ Partially Hidden credits
-First, see in :ref:`autocredits` how to make credits automatically with MoviePy. Before seeing the code for this video, here is a tutorial video that explains the different steps (also made with MoviePy): +Before seeing the code for this video, here is a tutorial video that explains the different steps (also made with MoviePy): .. raw:: html diff --git a/docs/examples/severalCharacters.rst b/docs/examples/several_characters.rst similarity index 95% rename from docs/examples/severalCharacters.rst rename to docs/examples/several_characters.rst index 48f9e1975..0f3509a71 100644 --- a/docs/examples/severalCharacters.rst +++ b/docs/examples/several_characters.rst @@ -1,4 +1,4 @@ -.. charDuplication: +.. char_duplication: Character duplication in a video ----------------------------------- diff --git a/docs/examples/star_worms.rst b/docs/examples/star_worms.rst index 68a2d4c7e..5d1659e18 100644 --- a/docs/examples/star_worms.rst +++ b/docs/examples/star_worms.rst @@ -5,8 +5,6 @@ This is an approximate effect (the perspective would require some more complex t Warning: clip with sound. -.. raw:: html - Let us also have a look at this tutorial which shows the different steps: .. raw:: html diff --git a/docs/gallery.rst b/docs/gallery.rst index ea988bfd7..0081d6356 100644 --- a/docs/gallery.rst +++ b/docs/gallery.rst @@ -46,7 +46,7 @@ Animations edited with MoviePy GIFs made from videos ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This `tutorial +This `gifs tutorial `_ gives you the basics to make gifs from video files (cutting, croping, adding text...). The last example shows how to remove a (still) background to keep only the animated part of a video. @@ -58,7 +58,7 @@ This `tutorial Vector Animations ~~~~~~~~~~~~~~~~~~~ -This `tutorial `_ shows how to combine MoviePy with Gizeh to create animations: +This `vector animations tutorial `_ shows how to combine MoviePy with Gizeh to create animations: .. raw:: html @@ -72,7 +72,7 @@ It is also possible to combine MoviePy with other graphic librairies like matplo 3D animations ~~~~~~~~~~~~~~~~~~~ -This `tutorial `_ shows how to combine MoviePy with Vapory, a library to render 3D scenes using the free ray-tracer POV-Ray +This `3d animation tutorial `_ shows how to combine MoviePy with Vapory, a library to render 3D scenes using the free ray-tracer POV-Ray .. raw:: html @@ -114,7 +114,7 @@ Or use `this script `_ to ma Data animations ---------------- -This `tutorial `_ shows how to use MoviePy to animate the different Python vizualization libraries: Mayavi, Vispy, Scikit-image, Matplotlib, etc. +This `data animation tutorial `_ shows how to use MoviePy to animate the different Python vizualization libraries: Mayavi, Vispy, Scikit-image, Matplotlib, etc. Scientific or technological projects @@ -124,7 +124,7 @@ Scientific or technological projects Piano rolls transcription to sheet music ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This `blog post `_ explains how to transform a video of a piano roll performance into playable sheet music. MoviePy is used for the frame-by-frame analysis of the piano roll video. The last video is also edited with MoviePy: +This `transcribing piano rolls blog post `_ explains how to transform a video of a piano roll performance into playable sheet music. MoviePy is used for the frame-by-frame analysis of the piano roll video. The last video is also edited with MoviePy: .. raw:: html @@ -170,7 +170,7 @@ Here are `Videogrep's introductory blog post If you liked it, also have a look at these Videogrep-inspired projects: -This `blog post `_ attempts to cut a video precisely at the beginning and end of sentences or words: :: +This `Videogrep blog post `_ attempts to cut a video precisely at the beginning and end of sentences or words: :: words = ["Americans", "must", "develop", "open ", "source", " software", "for the", " rest ", "of the world", diff --git a/docs/getting_started/audio.rst b/docs/getting_started/audio.rst deleted file mode 100644 index 1dffa3ea0..000000000 --- a/docs/getting_started/audio.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. _audio: - -Audio in MoviePy ------------------ - -This section shows how to use MoviePy to create and edit audio clips. - -Note that when you cut, mix or concatenate video clips in MoviePy the audio is automatically handled and you need to worry about it. This section is of interest if you just want to edit audiofiles or you want custom audio clips for your videos. - -Creating a new audio clip -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Audio clips can be created from an audio file or from the soundtrack of a video file -:: - from moviepy.editor import * - audioclip = AudioFileClip("some_audiofile.mp3") - audioclip = AudioFileClip("some_video.avi") - -Alternatively you can get the audio track of an already created video clip: - - videoclip = VideoFileClip("some_video.avi") - audioclip = videoclip.audio - -You can also \ No newline at end of file diff --git a/docs/getting_started/audioclips.rst b/docs/getting_started/audioclips.rst index 3614ad4b7..df17e148b 100644 --- a/docs/getting_started/audioclips.rst +++ b/docs/getting_started/audioclips.rst @@ -1,6 +1,4 @@ -.. _audio: - - +.. _audioclips: Audio in MoviePy ----------------- @@ -9,7 +7,6 @@ This section shows how to use MoviePy to create and edit audio clips. Note that when you cut, mix or concatenate video clips in MoviePy the audio is automatically handled and you need to worry about it. This section is of interest if you just want to edit audiofiles or you want custom audio clips for your videos. - What audioclips are made of ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -19,31 +16,25 @@ AudioClips are very similar to video clips in moviepy: they have a length, can b Creating a new audio clip ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Audio clips can be created from an audio file or from the soundtrack of a video file -:: +Audio clips can be created from an audio file or from the soundtrack of a video file :: + from moviepy.editor import * audioclip = AudioFileClip("some_audiofile.mp3") audioclip = AudioFileClip("some_video.avi") -Alternatively you can get the audio track of an already created video clip: +for more, see :py:class:`~moviepy.audio.io.AudioFileClip.AudioFileClip`. + +Alternatively you can get the audio track of an already created video clip :: videoclip = VideoFileClip("some_video.avi") audioclip = videoclip.audio -You can also - Compositing audio clips ~~~~~~~~~~~~~~~~~~~~~~~~ - Exporting and previewing audio clips ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can export +You can also export assign an audio clip as the soundtrack of a video clip with :: -You can - -You can also export assign an audio clip as the soundtrack of a video clip with:: - videoclip2 = videoclip.set_audio(my_audioclip) - diff --git a/docs/getting_started/clips.rst b/docs/getting_started/clips.rst deleted file mode 100644 index 283812c04..000000000 --- a/docs/getting_started/clips.rst +++ /dev/null @@ -1,241 +0,0 @@ -.. _clips: - -Creating and exporting video clips -=================================== - -Video and 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 = ImageSequenceClip(['image_file1.jpeg', ...], fps=24) - 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 that clips make with a `make_frame` do not have an explicit frame rate, so you must provide a frame rate (``fps``, frames er second) for ``write_gif`` and ``write_videofile``, and more generally for any methods that requires iterating through the frames. - - -VideoFileClip -""""""""""""""" - -A VideoFileClip is a clip read from a video file (most formats are supported) or a GIF file. You load the video as follows: :: - - myclip = VideoFileClip("some_video.avi") - myclip = VideoFileClip("some_animation.gif") - -Note that these clips will have an ``fps`` (frame per second) attribute, which will be transmitted if you do small modifications of the clip, and will be used by default in ``write_videofile``, ``write_gif``, etc. For instance: :: - - myclip = VideoFileClip("some_video.avi") - print (myclip.fps) # prints for instance '30' - # Now cut the clip between t=10 and 25 secs. This conserves the fps. - myclip2 = myclip.subclip(10, 25) - myclip2.write_gif("test.gif") # the gif will have 30 fps - - -For more, see :py:class:`~moviepy.video.io.VideoFileClip.VideoFileClip`. - -ImageSequenceClip -"""""""""""""""""" - -This is a clip made from a series of images, you call it with :: - - clip = ImageSequenceClip(images_list, fps=25) - -where ``images_list`` can be either a list of image names (that will be *played*) in that order, a folder name (at which case all the image files in the folder will be played in alphanumerical order), or a list of frames (Numpy arrays), obtained for instance from other clips. - -When you provide a folder name or list of file names, you can choose ``load_images=True`` to specify that all images should be loaded into the RAM. This is only interesting if you have a small number of images that will be each used more than once (e.g. if the images form a looping animation). - - -ImageClip -"""""""""" - -An ImageClip is a video clip that always displays the same image. You can create one as follows: :: - - myclip = ImageClip("some_picture.jpeg") - myclip = ImageClip(somme_array) # a (height x width x 3) RGB numpy array - myclip = some_video_clip.to_ImageClip(t='01:00:00') # frame at t=1 hour. - -For more, see :py:class:`~moviepy.video.VideoClip.ImageClip`. - -Two examples of ImageClip shown below are the TextClip and ColorClip - - - -TextClip -""""""""""""""" - -Generating a TextClip requires to have ImageMagick installed and (for windows users) linked to MoviePy, see the installation instructions. - -Here is how you make a textclip (you won't need all these options all the time): :: - - myclip = TextClip("Hello", font='Amiri-Bold') - - -The font can be any font installed on your computer, but ImageMagick will have specific names for it. For instance the *normal* Amiri font will be called ``Amiri-Regular`` while the Impact font will be called ``Impact-Normal``. To get a list of the possible fonts, type ``TextClip.list('fonts')``. To find all the font names related to a given font, use for instance :: - - TextClip.search('Amiri', 'fonts') # Returns all font names containing Amiri - -Note also that the use of a stroke (or contour) will not work well on small letters, so if you need a small text with a contour, it is better to generate a big text, then downsize it: :: - - myclip = TextClip("Hello", fontsize=70, stroke_width=5).resize(height=15) - - -TextClips have many, many options: alignment, kerning (distance between the letters), stroke size, background, word wrapping, etc. see :py:class:`~moviepy.video.VideoClip.TextClip` for more. - - -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`). Masks are also used to define transparency when you export the clip as GIF file or as a PNG. - -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 will be used as a mask you need to declare it: :: - - maskclip = ImageClip("my_mask.jpeg", ismask=True) - maskclip = VideoFileClip("myvideo.mp4", ismask=True) - maskclip = VideoClip(makeframe_function, duration=4, ismask=True) - - -In the case of video and image files, if these are not already black and white they will be converted automatically. - -Then you attach this mask to a clip (which must have the same dimensions) with ``myclip.set_mask(maskclip)``. - -Some image formats like PNG support transparency with an *alpha layer*, which MoviePy will use as a mask: :: - - myclip = ImageClip("image.png", transparent=True) # True is the default - myclip.mask # <- the alpha layer of the picture. - -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. - -If the clip has a mask it will be used for transparency. - -There are many options to optimize the quality and size of a gif (see :py:meth:`~moviepy.video.VideoClip.VideoClip.write_gif`) - -Note that when editing gifs the best way to preview them is in the notebook as explained here: :ref:`ipython_display` - -For examples of use, see `this blog post `_ for informations on making GIFs from video files, and `this other post `_ for GIF animations with vector graphics. - -Export images -""""""""""""""" - -You can write a frame to an image file with :: - - myclip.save_frame("frame.png") # by default the first frame is extracted - myclip.save_frame("frame.jpeg", t='01:00:00') # frame at time t=1h - -If the clip has a mask it will be exported as the alpha layer of the image unless you specify ``withmask=False``. - -.. _CCaudioClips: - - -Audio clips -~~~~~~~~~~~~~ - -This section shows how to use MoviePy to create and edit audio clips. - -Note that when you import, cut, mix or concatenate video clips in MoviePy, their audio tracks are automatically handled and you don't need to worry about it. This section is of interest if you just want to edit audio files, or you want custom audio clips for your videos. - -What audioclips are made of -"""""""""""""""""""""""""""""" - -AudioClips are very similar to video clips in moviepy: they have a length, can be cut and composed the same way, etc. A notable difference is that their method ``myclip.get_frame(t)``, instead of returning a RGB picture array like for video clips, returns just a couple of values between -1 and 1 (e.g.``[-0.4, 0.2]``) representing the left-right stereo sound at time ``t`` (for mono sounds, only one value is returned) - -Creating a new audio clip -"""""""""""""""""""""""""""""" - -Audio clips can be created from an audio file or from the soundtrack of a video file -:: - from moviepy.editor import * - audioclip = AudioFileClip("some_audiofile.mp3") - audioclip = AudioFileClip("some_video.avi") - -for more, see :py:class:`~moviepy.audio.io.AudioFileClip.AudioFileClip`. - -Alternatively you can get the audio track of an already created video clip: - - videoclip = VideoFileClip("some_video.avi") - audioclip = videoclip.audio - -.. (next paragraphs still to be written) - -.. You can also create an audio clip from a numpy array. For more, see :py:class:`~moviepy.audio.AudioClip.AudioArrayClip` diff --git a/docs/getting_started/effects.rst b/docs/getting_started/effects.rst index d548dda6a..63c565421 100644 --- a/docs/getting_started/effects.rst +++ b/docs/getting_started/effects.rst @@ -1,7 +1,5 @@ .. _effects: -Warning: page in construction. - Clips transformations and effects =================================== diff --git a/docs/getting_started/getting_started.rst b/docs/getting_started/getting_started.rst index 456e56735..e2613d42b 100644 --- a/docs/getting_started/getting_started.rst +++ b/docs/getting_started/getting_started.rst @@ -12,7 +12,8 @@ These pages explain everything you need to start editing with MoviePy. To go fur :maxdepth: 1 quick_presentation - clips compositing effects - efficient_moviepy \ No newline at end of file + efficient_moviepy + audioclips + videoclips \ No newline at end of file diff --git a/docs/getting_started/quick_presentation.rst b/docs/getting_started/quick_presentation.rst index 6586f6467..54884da45 100644 --- a/docs/getting_started/quick_presentation.rst +++ b/docs/getting_started/quick_presentation.rst @@ -72,7 +72,7 @@ MoviePy uses the software ``ffmpeg`` to read and to export video and audio files Basic concepts ~~~~~~~~~~~~~~~ -The central objects of MoviePy are *clips*, which can be ``AudioClips`` or ``VideoClips``. They can be modified (cut, slowed down, darkened...) or put mixed with clips to form new clips, they can be previewed (using either PyGame or the IPython Notebook) and rendered to a file (as a MP4, a GIF, a MP3, etc.). ``VideoClips`` for instance can be created from a video file, an image, a text, or a custom animation. They can have an audio track (which is an ``AudioClip``) and a mask (a special ``VideoClip`` indicating which parts of the clip to hide when the clip is mixed with other clips). See :ref:`clips` and :ref:`CompositeVideoClips` for more details. +The central objects of MoviePy are *clips*, which can be ``AudioClips`` or ``VideoClips``. They can be modified (cut, slowed down, darkened...) or put mixed with clips to form new clips, they can be previewed (using either PyGame or the IPython Notebook) and rendered to a file (as a MP4, a GIF, a MP3, etc.). ``VideoClips`` for instance can be created from a video file, an image, a text, or a custom animation. They can have an audio track (which is an ``AudioClip``) and a mask (a special ``VideoClip`` indicating which parts of the clip to hide when the clip is mixed with other clips). See :ref:`videoclips` and :ref:`CompositeVideoClips` for more details. A clip can be modified using one of moviepy's numerous effects (like in ``clip.resize(width="360")``, ``clip.subclip(t1,t2)``, or ``clip.fx(vfx.black_white)``) or using a user-implemented effect. MoviePy implements many functions (like ``clip.fl``, ``clip.fx``, etc.) which make it very easy to code your own effect in a few lines. See :ref:`effects` for more. diff --git a/docs/getting_started/videoclips.rst b/docs/getting_started/videoclips.rst index 37f5b34a0..3bdd93f83 100644 --- a/docs/getting_started/videoclips.rst +++ b/docs/getting_started/videoclips.rst @@ -1,4 +1,4 @@ -.. _clips: +.. _videoclips: Creating and exporting video clips =================================== @@ -10,6 +10,7 @@ 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 = ImageSequenceClip(['image_file1.jpeg', ...], fps=24) 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]) @@ -53,36 +54,95 @@ VideoClip :width: 128 px :align: center -Note: three next sections are in construction +Note that clips make with a `make_frame` do not have an explicit frame rate, so you must provide a frame rate (``fps``, frames er second) for ``write_gif`` and ``write_videofile``, and more generally for any methods that requires iterating through the frames. VideoFileClip """"""""""""""" -See :py:class:`~moviepy.video.io.VideoFileClip.VideoFileClip`. + +A VideoFileClip is a clip read from a video file (most formats are supported) or a GIF file. You load the video as follows: :: + + myclip = VideoFileClip("some_video.avi") + myclip = VideoFileClip("some_animation.gif") + +Note that these clips will have an ``fps`` (frame per second) attribute, which will be transmitted if you do small modifications of the clip, and will be used by default in ``write_videofile``, ``write_gif``, etc. For instance: :: + + myclip = VideoFileClip("some_video.avi") + print (myclip.fps) # prints for instance '30' + # Now cut the clip between t=10 and 25 secs. This conserves the fps. + myclip2 = myclip.subclip(10, 25) + myclip2.write_gif("test.gif") # the gif will have 30 fps + + +For more, see :py:class:`~moviepy.video.io.VideoFileClip.VideoFileClip`. + +ImageSequenceClip +"""""""""""""""""" + +This is a clip made from a series of images, you call it with :: + + clip = ImageSequenceClip(images_list, fps=25) + +where ``images_list`` can be either a list of image names (that will be *played*) in that order, a folder name (at which case all the image files in the folder will be played in alphanumerical order), or a list of frames (Numpy arrays), obtained for instance from other clips. + +When you provide a folder name or list of file names, you can choose ``load_images=True`` to specify that all images should be loaded into the RAM. This is only interesting if you have a small number of images that will be each used more than once (e.g. if the images form a looping animation). ImageClip """""""""" -See :py:class:`~moviepy.video.VideoClip.ImageClip`. + +An ImageClip is a video clip that always displays the same image. You can create one as follows: :: + + myclip = ImageClip("some_picture.jpeg") + myclip = ImageClip(somme_array) # a (height x width x 3) RGB numpy array + myclip = some_video_clip.to_ImageClip(t='01:00:00') # frame at t=1 hour. + +For more, see :py:class:`~moviepy.video.VideoClip.ImageClip`. + +Two examples of ImageClip shown below are the TextClip and ColorClip TextClip """"""""""""""" -See :py:class:`~moviepy.video.VideoClip.TextClip`. + +Generating a TextClip requires to have ImageMagick installed and (for windows users) linked to MoviePy, see the installation instructions. + +Here is how you make a textclip (you won't need all these options all the time): :: + + myclip = TextClip("Hello", font='Amiri-Bold') + + +The font can be any font installed on your computer, but ImageMagick will have specific names for it. For instance the *normal* Amiri font will be called ``Amiri-Regular`` while the Impact font will be called ``Impact-Normal``. To get a list of the possible fonts, type ``TextClip.list('fonts')``. To find all the font names related to a given font, use for instance :: + + TextClip.search('Amiri', 'fonts') # Returns all font names containing Amiri + +Note also that the use of a stroke (or contour) will not work well on small letters, so if you need a small text with a contour, it is better to generate a big text, then downsize it: :: + + myclip = TextClip("Hello", fontsize=70, stroke_width=5).resize(height=15) + + +TextClips have many, many options: alignment, kerning (distance between the letters), stroke size, background, word wrapping, etc. see :py:class:`~moviepy.video.VideoClip.TextClip` for more. 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`). +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`). Masks are also used to define transparency when you export the clip as GIF file or as a PNG. 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) + maskclip = VideoClip(makeframe, duration=4, ismask=True) + maskclip = ImageClip("my_mask.jpeg", ismask=True) + maskclip = VideoFileClip("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. +Then you attach this mask to a clip (which must have the same dimensions) with ``myclip.set_mask(maskclip)``. + +Some image formats like PNG support transparency with an *alpha layer*, which MoviePy will use as a mask: :: + + myclip = ImageClip("image.png", transparent=True) # True is the default + myclip.mask # <- the alpha layer of the picture. + 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()``. @@ -127,8 +187,14 @@ There are many options to optimize the quality and size of a gif. Please refer t 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 `_ for informations on making GIFs from video files, and `this other post `_ for GIF animations with vector graphics. +For examples of use, see `this blog post `_ for informations on making GIFs from video files, and `this other post `_ for GIF animations with vector graphics. + +Export images +""""""""""""""" -.. _CCaudioClips: +You can write a frame to an image file with :: + myclip.save_frame("frame.png") # by default the first frame is extracted + myclip.save_frame("frame.jpeg", t='01:00:00') # frame at time t=1h +If the clip has a mask it will be exported as the alpha layer of the image unless you specify ``withmask=False``. diff --git a/docs/index.rst b/docs/index.rst index 3d6449549..1e8d21234 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -27,7 +27,9 @@ User Guide gallery examples/examples docker + opencv_instructions FAQ + advanced_tools/advanced_tools ref/ref Contribute ! diff --git a/docs/opencv_instructions.rst b/docs/opencv_instructions.rst index 888c1788e..de161762f 100644 --- a/docs/opencv_instructions.rst +++ b/docs/opencv_instructions.rst @@ -7,29 +7,29 @@ OpenCV is very optional, its installation is not always simple and I found it to The installation seems easy for Windows. On linux, here is what I found on the Internet: - Remove any other version of OpenCV if you installed it through a package manager. -- Unzip the source code of `OpenCV 2.4.6`_ in some folder. open a terminal in this folder. +- Unzip the source code of `OpenCV 2.4.6` in some folder. open a terminal in this folder. - Make a new directory and go into this directory: :: - + mkdir release cd release - + - Run ``cmake``. Here is the line I used: :: - + cmake -D WITH_TBB=ON -D BUILD_NEW_PYTHON_SUPPORT=ON -D WITH_V4L=OFF -D INSTALL_C_EXAMPLES=ON -D INSTALL_PYTHON_EXAMPLES=ON -D BUILD_EXAMPLES=ON .. - + - Run ``make``. This may take a few minutes (15 minutes on my computer). :: - + make - + - Finally, install. :: - + sudo make install - + And voilà ! You can check if it worked by opeing a Python console and typing :: - + import cv2 print cv2.__version__ -Advice: do not throw your ``release`` folder away. If later you have strange bugs with OpenCV involving ``.so`` files, just redo the ``sudo make install`` step. \ No newline at end of file +Advice: do not throw your ``release`` folder away. If later you have strange bugs with OpenCV involving ``.so`` files, just redo the ``sudo make install`` step. diff --git a/docs/ref/code_origanization.rst b/docs/ref/code_origanization.rst index df50c6ec5..ffdf189ab 100644 --- a/docs/ref/code_origanization.rst +++ b/docs/ref/code_origanization.rst @@ -5,7 +5,7 @@ Organization of MoviePy's code This reviews the folders and files in moviepy's code. It's very easy: -At the root of the project you have everything required for the packaging and installation of moviepy (README, setup.py, LICENCE) etc. Then you the ``docs/`` folder with the source code of the documentation (see :ref:`updating_docs`), a folder for some :ref:`examples`, and the main folder ``moviepy/`` for the source code of the library itself. +At the root of the project you have everything required for the packaging and installation of moviepy (README, setup.py, LICENCE) etc. Then you the ``docs/`` folder with the source code of the documentation, a folder for some :ref:`examples`, and the main folder ``moviepy/`` for the source code of the library itself. The folder ``moviepy/`` the classes and modules relative to the video and the audio are clearly separated into two subfolders ``video/`` and ``audio/``. In ``moviepy/`` you will find all the classes, functions and decorations which are useful to both submodules ``audio`` and ``video``: diff --git a/docs/ref/ref.rst b/docs/ref/ref.rst index ef2050531..c2541e3ce 100644 --- a/docs/ref/ref.rst +++ b/docs/ref/ref.rst @@ -20,4 +20,4 @@ If you want to hack into the code or locate a particular function, read :ref:`co audiotools ffmpeg decorators - + code_origanization diff --git a/docs/ref/videofx.rst b/docs/ref/videofx.rst index 6d96d7f6a..2bdf10c90 100644 --- a/docs/ref/videofx.rst +++ b/docs/ref/videofx.rst @@ -57,7 +57,7 @@ the module ``video.fx`` is loaded as ``vfx`` and you can use ``vfx.colorx``, ``v mirror_y painting resize - rotation + rotate scroll speedx supersample diff --git a/docs/ref/videofx/moviepy.video.fx.all.accel_decel.rst b/docs/ref/videofx/moviepy.video.fx.all.accel_decel.rst new file mode 100644 index 000000000..4e499db34 --- /dev/null +++ b/docs/ref/videofx/moviepy.video.fx.all.accel_decel.rst @@ -0,0 +1,6 @@ +moviepy\.video\.fx\.all\.accel\_decel +===================================== + +.. currentmodule:: moviepy.video.fx.all + +.. autofunction:: accel_decel \ No newline at end of file diff --git a/docs/ref/videofx/moviepy.video.fx.all.even_size.rst b/docs/ref/videofx/moviepy.video.fx.all.even_size.rst new file mode 100644 index 000000000..364bff043 --- /dev/null +++ b/docs/ref/videofx/moviepy.video.fx.all.even_size.rst @@ -0,0 +1,6 @@ +moviepy\.video\.fx\.all\.even\_size +=================================== + +.. currentmodule:: moviepy.video.fx.all + +.. autofunction:: even_size \ No newline at end of file diff --git a/docs/ref/videofx/moviepy.video.fx.all.freeze_region.rst b/docs/ref/videofx/moviepy.video.fx.all.freeze_region.rst new file mode 100644 index 000000000..b4466e31a --- /dev/null +++ b/docs/ref/videofx/moviepy.video.fx.all.freeze_region.rst @@ -0,0 +1,6 @@ +moviepy\.video\.fx\.all\.freeze\_region +======================================= + +.. currentmodule:: moviepy.video.fx.all + +.. autofunction:: freeze_region \ No newline at end of file diff --git a/docs/ref/videofx/moviepy.video.fx.all.invert_colors.rst b/docs/ref/videofx/moviepy.video.fx.all.invert_colors.rst new file mode 100644 index 000000000..dfee91802 --- /dev/null +++ b/docs/ref/videofx/moviepy.video.fx.all.invert_colors.rst @@ -0,0 +1,6 @@ +moviepy\.video\.fx\.all\.invert\_colors +======================================= + +.. currentmodule:: moviepy.video.fx.all + +.. autofunction:: invert_colors \ No newline at end of file diff --git a/docs/ref/videofx/moviepy.video.fx.all.freeze_at_end.rst b/docs/ref/videofx/moviepy.video.fx.all.mask_and.rst similarity index 53% rename from docs/ref/videofx/moviepy.video.fx.all.freeze_at_end.rst rename to docs/ref/videofx/moviepy.video.fx.all.mask_and.rst index df2dd94ea..ccb643ded 100644 --- a/docs/ref/videofx/moviepy.video.fx.all.freeze_at_end.rst +++ b/docs/ref/videofx/moviepy.video.fx.all.mask_and.rst @@ -1,6 +1,6 @@ -moviepy.video.fx.all.freeze_at_end +moviepy\.video\.fx\.all\.mask\_and ================================== .. currentmodule:: moviepy.video.fx.all -.. autofunction:: freeze_at_end \ No newline at end of file +.. autofunction:: mask_and \ No newline at end of file diff --git a/docs/ref/videofx/moviepy.video.fx.all.freeze_at_start.rst b/docs/ref/videofx/moviepy.video.fx.all.mask_color.rst similarity index 53% rename from docs/ref/videofx/moviepy.video.fx.all.freeze_at_start.rst rename to docs/ref/videofx/moviepy.video.fx.all.mask_color.rst index 1adc29cdc..c64b41801 100644 --- a/docs/ref/videofx/moviepy.video.fx.all.freeze_at_start.rst +++ b/docs/ref/videofx/moviepy.video.fx.all.mask_color.rst @@ -1,6 +1,6 @@ -moviepy.video.fx.all.freeze_at_start +moviepy\.video\.fx\.all\.mask\_color ==================================== .. currentmodule:: moviepy.video.fx.all -.. autofunction:: freeze_at_start \ No newline at end of file +.. autofunction:: mask_color \ No newline at end of file diff --git a/docs/ref/videofx/moviepy.video.fx.all.mask_or.rst b/docs/ref/videofx/moviepy.video.fx.all.mask_or.rst new file mode 100644 index 000000000..9351c96be --- /dev/null +++ b/docs/ref/videofx/moviepy.video.fx.all.mask_or.rst @@ -0,0 +1,6 @@ +moviepy\.video\.fx\.all\.mask\_or +================================= + +.. currentmodule:: moviepy.video.fx.all + +.. autofunction:: mask_or \ No newline at end of file diff --git a/docs/ref/videofx/moviepy.video.fx.all.rotation.rst b/docs/ref/videofx/moviepy.video.fx.all.rotate.rst similarity index 56% rename from docs/ref/videofx/moviepy.video.fx.all.rotation.rst rename to docs/ref/videofx/moviepy.video.fx.all.rotate.rst index 04762ca43..d68ce476e 100644 --- a/docs/ref/videofx/moviepy.video.fx.all.rotation.rst +++ b/docs/ref/videofx/moviepy.video.fx.all.rotate.rst @@ -1,6 +1,6 @@ -moviepy.video.fx.all.rotation +moviepy.video.fx.all.rotate ============================= .. currentmodule:: moviepy.video.fx.all -.. autofunction:: rotation \ No newline at end of file +.. autofunction:: rotate \ No newline at end of file diff --git a/docs/ref/videofx/moviepy.video.fx.all.supersample.rst b/docs/ref/videofx/moviepy.video.fx.all.supersample.rst new file mode 100644 index 000000000..0776fb575 --- /dev/null +++ b/docs/ref/videofx/moviepy.video.fx.all.supersample.rst @@ -0,0 +1,6 @@ +moviepy\.video\.fx\.all\.supersample +==================================== + +.. currentmodule:: moviepy.video.fx.all + +.. autofunction:: supersample \ No newline at end of file diff --git a/docs/ref/videofx/moviepy.video.fx.crop.rst b/docs/ref/videofx/moviepy.video.fx.crop.rst deleted file mode 100644 index fff5c7220..000000000 --- a/docs/ref/videofx/moviepy.video.fx.crop.rst +++ /dev/null @@ -1,6 +0,0 @@ -moviepy.video.fx.crop -===================== - -.. currentmodule:: moviepy.video.fx - -.. autofunction:: crop \ No newline at end of file diff --git a/requirements_docs.txt b/requirements_docs.txt index 026a1fd17..d0375d933 100644 --- a/requirements_docs.txt +++ b/requirements_docs.txt @@ -1,3 +1,6 @@ Sphinx>=1.5.2 sphinx_rtd_theme>=0.1.10b0 -numpydoc>=0.6.0 \ No newline at end of file +numpydoc>=0.6.0 +pygame==1.9.3 +scipy==0.19.0 +tqdm==4.11.2 \ No newline at end of file