matplotlib.animation.Animation#

class matplotlib.animation.Animation(fig, event_source=None, blit=False)[source]#

A base class for Animations.

This class is not usable as is, and should be subclassed to provide needed behavior.

Note

You must store the created Animation in a variable that lives as long as the animation should run. Otherwise, the Animation object will be garbage-collected and the animation stops.

Parameters:

figFigure

The figure object used to get needed events, such as draw or resize.

event_sourceobject, optional

A class that can run a callback when desired events are generated, as well as be stopped and started.

Examples include timers (see TimedAnimation) and file system notifications.

blitbool, default: False

Whether blitting is used to optimize drawing.

See also

FuncAnimation, ArtistAnimation

__init__(fig, event_source=None, blit=False)[source]#

Methods

`__init__`(fig[, event_source, blit])
`new_frame_seq`()	Return a new sequence of frame information.
`new_saved_frame_seq`()	Return a new sequence of saved/cached frame information.
`pause`()	Pause the animation.
`resume`()	Resume the animation.
`save`(filename[, writer, fps, dpi, codec, ...])	Save the animation as a movie file by drawing every frame.
`to_html5_video`([embed_limit])	Convert the animation to an HTML5 `<video>` tag.
`to_jshtml`([fps, embed_frames, default_mode])	Generate HTML representation of the animation.

new_frame_seq()[source]#: Return a new sequence of frame information.

new_saved_frame_seq()[source]#: Return a new sequence of saved/cached frame information.

pause()[source]#: Pause the animation.

resume()[source]#: Resume the animation.

save(filename, writer=None, fps=None, dpi=None, codec=None, bitrate=None, extra_args=None, metadata=None, extra_anim=None, savefig_kwargs=None, *, progress_callback=None)[source]#

Save the animation as a movie file by drawing every frame.

Parameters:

filenamestr

The output filename, e.g., mymovie.mp4.

writerMovieWriter or str, default: rcParams["animation.writer"] (default: 'ffmpeg')

A MovieWriter instance to use or a key that identifies a class to use, such as 'ffmpeg'.

fpsint, optional

Movie frame rate (per second). If not set, the frame rate from the animation's frame interval.

dpifloat, default: rcParams["savefig.dpi"] (default: 'figure')

Controls the dots per inch for the movie frames. Together with the figure's size in inches, this controls the size of the movie.

codecstr, default: rcParams["animation.codec"] (default: 'h264').

The video codec to use. Not all codecs are supported by a given MovieWriter.

bitrateint, default: rcParams["animation.bitrate"] (default: -1)

The bitrate of the movie, in kilobits per second. Higher values means higher quality movies, but increase the file size. A value of -1 lets the underlying movie encoder select the bitrate.

extra_argslist of str or None, optional

Extra command-line arguments passed to the underlying movie encoder. The default, None, means to use rcParams["animation.[name-of-encoder]_args"] for the builtin writers.

metadatadict[str, str], default: {}

Dictionary of keys and values for metadata to include in the output file. Some keys that may be of use include: title, artist, genre, subject, copyright, srcform, comment.

extra_animlist, default: []

Additional Animation objects that should be included in the saved movie file. These need to be from the same matplotlib.figure.Figure instance. Also, animation frames will just be simply combined, so there should be a 1:1 correspondence between the frames from the different animations.

savefig_kwargsdict, default: {}

Keyword arguments passed to each savefig call used to save the individual frames.

progress_callbackfunction, optional

A callback function that will be called for every frame to notify the saving progress. It must have the signature

def func(current_frame: int, total_frames: int) -> Any

where current_frame is the current frame number and total_frames is the total number of frames to be saved. total_frames is set to None, if the total number of frames can not be determined. Return values may exist but are ignored.

Example code to write the progress to stdout:

progress_callback =                    lambda i, n: print(f'Saving frame {i} of {n}')

Notes

fps, codec, bitrate, extra_args and metadata are used to construct a MovieWriter instance and can only be passed if writer is a string. If they are passed as non-None and writer is a MovieWriter, a RuntimeError will be raised.

to_html5_video(embed_limit=None)[source]#

Convert the animation to an HTML5 <video> tag.

This saves the animation as an h264 video, encoded in base64 directly into the HTML5 video tag. This respects rcParams["animation.writer"] (default: 'ffmpeg') and rcParams["animation.bitrate"] (default: -1). This also makes use of the interval to control the speed, and uses the repeat parameter to decide whether to loop.

Parameters:

embed_limitfloat, optional: Limit, in MB, of the returned animation. No animation is created if the limit is exceeded. Defaults to rcParams["animation.embed_limit"] (default: 20.0) = 20.0.

Returns:

str: An HTML5 video tag with the animation embedded as base64 encoded h264 video. If the embed_limit is exceeded, this returns the string "Video too large to embed."

to_jshtml(fps=None, embed_frames=True, default_mode=None)[source]#

Generate HTML representation of the animation.

Parameters:

fpsint, optional: Movie frame rate (per second). If not set, the frame rate from the animation's frame interval.
embed_framesbool, optional
default_modestr, optional: What to do when the animation ends. Must be one of {'loop', 'once', 'reflect'}. Defaults to 'loop' if self.repeat is True, otherwise 'once'.