moviepy.video.tools.cuts.FramesMatches#

class moviepy.video.tools.cuts.FramesMatches(lst)[source]#

Frames matches inside a set of frames.

You can instantiate it passing a list of FramesMatch objects or using the class methods load and from_clip.

Parameters:

lst (list) -- Iterable of FramesMatch objects.

best(n=1, percent=None)[source]#

Returns a new instance of FramesMatches object or a FramesMatch from the current class instance given different conditions.

By default returns the first FramesMatch that the current instance stores.

Parameters:

  • n (int, optional) -- Number of matches to retrieve from the current FramesMatches object. Only has effect when percent=None.

  • percent (float, optional) -- Percent of the current match to retrieve.

Returns:

FramesMatch or FramesMatches -- greater than 1 returns a FramesMatches object, otherwise a FramesMatch.

Return type:

If the number of matches to retrieve is

filter(condition)[source]#

Return a FramesMatches object obtained by filtering out the FramesMatch which do not satistify a condition.

Parameters:

condition (func) -- Function which takes a FrameMatch object as parameter and returns a bool.

Examples

# Only keep the matches corresponding to (> 1 second) sequences.
new_matches = matches.filter(lambda match: match.time_span > 1)
static from_clip(clip, distance_threshold, max_duration, fps=None, logger='bar')[source]#

Finds all the frames that look alike in a clip, for instance to make a looping GIF.

Parameters:

  • clip (moviepy.video.VideoClip.VideoClip) -- A MoviePy video clip.

  • distance_threshold (float) -- Distance above which a match is rejected.

  • max_duration (float) -- Maximal duration (in seconds) between two matching frames.

  • fps (int, optional) -- Frames per second (default will be clip.fps).

  • logger (str, optional) -- Either "bar" for progress bar or None or any Proglog logger.

Returns:

All pairs of frames with end_time - start_time < max_duration and whose distance is under distance_threshold.

Return type:

FramesMatches

Examples

We find all matching frames in a given video and turn the best match with a duration of 1.5 seconds or more into a GIF:

from moviepy import VideoFileClip
from moviepy.video.tools.cuts import FramesMatches

clip = VideoFileClip("foo.mp4").resize(width=200)
matches = FramesMatches.from_clip(
    clip, distance_threshold=10, max_duration=3,  # will take time
)
best = matches.filter(lambda m: m.time_span > 1.5).best()
clip.subclipped(best.start_time, best.end_time).write_gif("foo.gif")
static load(filename)[source]#

Load a FramesMatches object from a file.

Parameters:

filename (str) -- Path to the file to use loading a FramesMatches object.

Examples

>>> matching_frames = FramesMatches.load("somefile")
save(filename)[source]#

Save a FramesMatches object to a file.

Parameters:

filename (str) -- Path to the file in which will be dumped the FramesMatches object data.

select_scenes(match_threshold, min_time_span, nomatch_threshold=None, time_distance=0)[source]#

Select the scenes at which a video clip can be reproduced as the smoothest possible way, mainly oriented for the creation of GIF images.

Parameters:

  • match_threshold (float) -- Maximum distance possible between frames. The smaller, the better-looping the GIFs are.

  • min_time_span (float) -- Minimum duration for a scene. Only matches with a duration longer than the value passed to this parameters will be extracted.

  • nomatch_threshold (float, optional) -- Minimum distance possible between frames. If is None, then it is chosen equal to match_threshold.

  • time_distance (float, optional) -- Minimum time offset possible between matches.

Returns:

FramesMatches

Return type:

New instance of the class with the selected scenes.

Examples

from pprint import pprint
from moviepy import *
from moviepy.video.tools.cuts import FramesMatches

ch_clip = VideoFileClip("media/chaplin.mp4").subclipped(1, 4)
mirror_and_clip = [ch_clip.with_effects([vfx.TimeMirror()]), ch_clip]
clip = concatenate_videoclips(mirror_and_clip)

result = FramesMatches.from_clip(clip, 10, 3).select_scenes(
    1, 2, nomatch_threshold=0,
)
print(result)
# [(1.0000, 4.0000, 0.0000, 0.0000),
#  (1.1600, 3.8400, 0.0000, 0.0000),
#  (1.2800, 3.7200, 0.0000, 0.0000),
#  (1.4000, 3.6000, 0.0000, 0.0000)]
write_gifs(clip, gifs_dir, **kwargs)[source]#

Extract the matching frames represented by the instance from a clip and write them as GIFs in a directory, one GIF for each matching frame.

Parameters:

  • clip (video.VideoClip.VideoClip) -- A video clip whose frames scenes you want to obtain as GIF images.

  • gif_dir (str) -- Directory in which the GIF images will be written.

  • kwargs -- Passed as clip.write_gif optional arguments.

Examples

import os
from pprint import pprint
from moviepy import *
from moviepy.video.tools.cuts import FramesMatches

ch_clip = VideoFileClip("media/chaplin.mp4").subclipped(1, 4)
clip = concatenate_videoclips([ch_clip.time_mirror(), ch_clip])

result = FramesMatches.from_clip(clip, 10, 3).select_scenes(
    1, 2, nomatch_threshold=0,
)

os.mkdir("foo")
result.write_gifs(clip, "foo")
# MoviePy - Building file foo/00000100_00000400.gif with imageio.
# MoviePy - Building file foo/00000115_00000384.gif with imageio.
# MoviePy - Building file foo/00000128_00000372.gif with imageio.
# MoviePy - Building file foo/00000140_00000360.gif with imageio.