Martin McBride, 2020-07-27
Tags movie video
Categories generativepy generative art

The movie module contains utility functions of dealing with lazy sequences of frames.

By storing images in memory, we can set up an efficient processing pipeline to process the frames. We can then process the entire video by treating it as a lazy iterable that returns frames. The frames pass through the pipeline, one by one.

The final stage of this pipeline, saving the frames as a file sequence, can be done by the save_frames function below.

The module also includes a MovieBuilder class than can be used to create more complex movies based on separate scenes, and optionally including audio.


This function has been removed. Use make_image_frames from the generativepy.drawing module instead.


This function has been removed. Use make_image_frame from the generativepy.drawing module instead.


save_frames(outfile, frames)
Parameter Type Description
outfile String The path and base filename for the output PNG files. See below.
frames iterable An iterbale that returns frames.

Iterates through the sequence of frame NumPy arrays returned by the frames iterable, and save each one as a PNG file.

The outfile parameter should be a base filepath. For example:


In this case the files will be created in the folder C:/temp, and their names will be based on the base name "image":


Once the images have been created, you can use an external program to convert them into an animated GIF or movie.


save_frame(outfile, frame)
Parameter Type Description
outfile String The path and filename for the output PNG file. It should end in '.png'.
frame NumPy array An image array in memory.

Saves the frame as a PNG file.


duplicate_frame(frame, count)
Parameter Type Description
frame NumPy array An image array in memory.
count int Number of repeats.

Returns an iterable that consists of the frame, repeated count times.

This can be used for static frames, for example a title frame that is displayed unchanged for several seconds.

MovieBuilder class

The MoveBuilder class accepts one or more frame sources, and combines them to create a movie in MP4 format. This allows complex animations ot be split into individual "scenes" than can be developed separately then combined later.

A frame source is an iterable that returns a sequence of frames representing an animation. make_image_frames from the generativepy.drawing module is a good way to create each scene.

MovieBuilder also allows audio clips to be added to the final movie.


Parameter Type Description
frame_rate Number The movie frame rate, in frames per second.

Creates a MovieBuilder object, and sets the frame rate. Every scene must have this frame rate, and the final movie will have the same frame rate.


Adds a scene to the movie

add_scene(frame_source_duration, audio_file=None)
Parameter Type Description
frame_source_duration Tuple A tuple containing the frame source of the clip, and the clip duration in seconds
audio_file string Path of an MP3 file with audio for the scene

Adds a scene to a MovieBuilder object. The scene is represented by a tuple containing:

  • A frame source for the scene. This is an iterator that returns the individual frames for the movie, such as the iterator returned by make_image_frames.
  • A number indicating the length of the scene in second.

A movie can have one or more scenes. Each scene must have the same pixel width and height, and use the same frame rate.

A scene can optionally have an audio file (MP3 format) associated with it. The audio will be added as a sound track to the scene. However:

  • The audio must be at least as long as the duration of the frame source. It can be longer, but if it is it will be truncated to the length of the frame source.
  • Either all the frames should have audio, or none of them. If you wish to create a movie with some sound and some silent scenes, you should create a silent audio file for the silent scenes. Most audio editing software (for example Audacity, which is freeand open source) can do this.


Creates the final movie.

make_movie(video_out, source=None)
Parameter Type Description
video_out string File path for video output file.
source int Scene to render (default is all scenes)

This function creates the final movie. This includes the audio if supplied.

By default this function will join all the scenes to create the movie.

If a source value is supplied, the function will create a movie using just that single scene. This can be useful if you are building the movie scene by scene. You can use this function to preview each scene as you create it, then finally run the function again to create the full movie.

If you found this article useful, you might be interested in the book Computer Graphics in Python or other books by the same author.


Popular tags

2d arrays abstract data type alignment and angle animation arange arc array arrays behavioural pattern bezier curve built-in function callable object chain circle classes clipping close closure cmyk colour combinations comparison operator comprehension context context manager conversion count creational pattern data science data types design pattern device space dictionary drawing duck typing efficiency ellipse else encryption enumerate fill filter font font style for loop function function composition function plot functools game development generativepy tutorial generator geometry gif global variable gradient greyscale higher order function hsl html image image processing imagesurface immutable object in operator index inner function input installing iter iterable iterator itertools join l system lambda function len line linear gradient linspace list list comprehension logical operator lru_cache magic method mandelbrot mandelbrot set map matplotlib monad mutability named parameter numeric python numpy object open operator optimisation optional parameter or pandas partial application path pattern permutations polygon positional parameter print pure function python standard library radial gradient range recipes rectangle recursion reduce repeat rgb rotation roundrect scaling scipy sector segment sequence setup shape singleton slice slicing sound spirograph sprite square str stream string stroke structural pattern subpath symmetric encryption template text text metrics tinkerbell fractal transform translation transparency triangle truthy value tuple turtle unpacking user space vectorisation webserver website while loop zip