psychopy.tools.movietools¶

Overview¶

Details¶

class psychopy.tools.movietools.MovieFileWriter(filename, size, fps, codec=None, pixelFormat='rgb24', encoderLib='ffpyplayer', encoderOpts=None)[source]¶

Create movies from a sequence of images.

This class allows for the creation of movies from a sequence of images using FFMPEG (via the ffpyplayer or cv2 libraries). Writing movies to disk is a slow process, so this class uses a separate thread to write the movie in the background. This means that you can continue to add images to the movie while frames are still being written to disk. Movie writers are closed automatically when the main thread exits. Any remaining frames are flushed to the file before the file is finalized.

Writing audio tracks is not supported. If you need to add audio to your movie, create the file with the video content first, then add the audio track to the file. The addAudioToMovie() function can be used to do this after the video and audio files have been saved to disk.

Parameters:

• filename (str) – The name (or path) of the file to write the movie to. The file extension determines the movie format if codec is None for some backends. Otherwise it must be explicitly specified.

• size (tuple or str) – The size of the movie in pixels (width, height). If a string is passed, it should be one of the keys in the VIDEO_RESOLUTIONS dictionary.

• fps (float) – The number of frames per second.

• codec (str or None) – The codec to use for encoding the movie. This may be a codec identifier (e.g., ‘libx264’) or a FourCC code. The value depends of the encoderLib in use. If None, the writer will select the codec based on the file extension of filename (if supported by the backend).

• pixelFormat (str) – Pixel format for frames being added to the movie. This should be either ‘rgb24’ or ‘rgba32’. The default is ‘rgb24’. When passing frames to addFrame() as a numpy array, the array should be in the format specified here.

• encoderLib (str) – The library to use to handle encoding and writing the movie to disk. The default is ‘ffpyplayer’.

• encoderOpts (dict or None) – A dictionary of options to pass to the encoder. These option can be used to control the quality of the movie, for example. The options depend on the encoderLib in use. If None, the writer will use the default options for the backend.

Examples

Create a movie from a sequence of generated noise images:

import psychopy.tools.movietools as movietools
import numpy as np

# create a movie writer
writer = movietools.MovieFileWriter(
    filename='myMovie.mp4',
    size=(640, 480),
    fps=30)

# open the movie for writing
writer.open()

# add some frames to the movie
for i in range(5 * writer.fps):  # 5 seconds of video
    # create a frame, just some random noise
    frame = np.random.randint(0, 255, (640, 480, 3), dtype=np.uint8)
    # add the frame to the movie
    writer.addFrame(frame)

# close the movie, this completes the writing process
writer.close()

Setting additional options for the movie encoder requires passing a dictionary of options to the encoderOpts parameter. The options depend on the encoder library in use. For example, to set the quality of the movie when using the ffpyplayer library, you can do the following:

ffmpegOpts = {'preset': 'medium', 'crf': 16}  # medium quality, crf=16
writer = movietools.MovieFileWriter(
    filename='myMovie.mp4',
    size='720p',
    fps=30,
    encoderLib='ffpyplayer',
    encoderOpts=ffmpegOpts)

The OpenCV backend specifies options differently. To set the quality of the movie when using the OpenCV library with a codec that support variable quality, you can do the following:

cvOpts = {'quality': 80}  # set the quality to 80 (0-100)
writer = movietools.MovieFileWriter(
    filename='myMovie.mp4',
    size='720p',
    fps=30,
    encoderLib='opencv',
    encoderOpts=cvOpts)

PIXEL_FORMAT_RGB24 = 'rgb24'¶

PIXEL_FORMAT_RGBA32 = 'rgb32'¶

_convertImage(image)[source]¶

Convert an image to a pixel format appropriate for the encoder.

This is used internally to convert an image (i.e. frame) to the native frame format which the encoder library can work with. At the very least, this function should accept a numpy.array as a valid type for image no matter what encoder library is being used.

Parameters:

image (Any) – The image to convert.

Returns:

The converted image. Resulting object type depends on the encoder library being used.

Return type:

Any

_openFFPyPlayer()[source]¶

Open a movie writer using FFPyPlayer.

This is called by open() if encoderLib is ‘ffpyplayer’. It will create a background thread to write the movie file. This method is not intended to be called directly.

_openOpenCV()[source]¶

Open a movie writer using OpenCV.

This is called by open() if encoderLib is ‘opencv’. It will create a background thread to write the movie file. This method is not intended to be called directly.

addFrame(image, pts=None)[source]¶

Add a frame to the movie.

This adds a frame to the movie. The frame will be added to a queue and written to disk by a background thread. This method will block until the frame is added to the queue.

Any color space conversion or resizing will be performed in the caller’s thread. This may be threaded too in the future.

Parameters:

• image (numpy.ndarray or ffpyplayer.pic.Image) – The image to add to the movie. The image must be in RGB format and have the same size as the movie. If the image is an Image instance, it must have the same size as the movie.

• pts (float or None) – The presentation timestamp for the frame. This is the time at which the frame should be displayed. The presentation timestamp is in seconds and should be monotonically increasing. If None, the presentation timestamp will be automatically generated based on the chosen frame rate for the output video. Not all encoder libraries support presentation timestamps, so this parameter may be ignored.

Returns:

Presentation timestamp assigned to the frame. Should match the value passed in as pts if provided, otherwise it will be the computed presentation timestamp.

Return type:

float

property bytesOut¶

Total number of bytes (int) saved to the movie file.

Use this to monitor how much disk space is occupied by the frames that have been written so far. This value is updated asynchronously, so it may not be accurate if you are adding frames to the movie file very quickly.

This value is retained after the movie file is closed. It is cleared when a new movie file is opened.

close()[source]¶

Close the movie file.

This shuts down the background thread and finalizes the movie file. Any frames still waiting in the queue will be written to disk before the movie file is closed. This will block the program until all frames are written, therefore, it is recommended for close() to be called outside any time-critical code.

property codec¶

The codec to use for encoding the movie (str).

This may be a codec identifier (e.g., ‘libx264’), or a FourCC code (e.g. ‘MPV4’). The value depends of the encoderLib in use. If None, the a codec determined by the file extension will be used.

property duration¶

The duration of the movie in seconds (float).

This is the total duration of the movie in seconds based on the number of frames that have been added to the movie and the frame rate. This does not represent the actual duration of the movie file on disk, which may be longer if frames are still being written to disk.

property encoderLib¶

The library to use for writing the movie (str).

Can only be set before the movie file is opened. The default is ‘ffpyplayer’.

property encoderOpts¶

Encoder options (dict).

These are passed directly to the encoder library. The default is an empty dictionary.

property filename¶

The name (path) of the movie file (str).

This cannot be changed after the writer has been opened.

flush()[source]¶

Flush waiting frames to the movie file.

This will cause all frames waiting in the queue to be written to disk before continuing the program i.e. the thread that called this method. This is useful for ensuring that all frames are written to disk before the program exits.

property fps¶

Output frames per second (float).

This is the number of frames per second that will be written to the movie file. The default is 30.

property frameInterval¶

The time interval between frames (float).

This is the time interval between frames in seconds. This is the reciprocal of the frame rate.

property frameRate¶

Output frames per second (float).

This is an alias for fps to synchronize naming with other video classes around PsychoPy.

property frameSize¶

The size (w, h) of the movie in pixels (tuple).

This is an alias for size to synchronize naming with other video classes around PsychoPy.

property framesOut¶

Total number of frames written to the movie file (int).

Use this to monitor the progress of the movie file writing. This value is updated asynchronously, so it may not be accurate if you are adding frames to the movie file very quickly.

This value is retained after the movie file is closed. It is cleared when a new movie file is opened.

property framesWaiting¶

The number of frames waiting to be written to disk (int).

This value increases when you call addFrame() and decreases when the frame is written to disk. This number can be reduced to zero by calling flush().

property isOpen¶

Whether the movie file is open (bool).

If True, the movie file is open and frames can be added to it. If False, the movie file is closed and no more frames can be added to it.

property lastVideoFile¶

The name of the last video file written to disk (str or None).

This is None if no video file has been written to disk yet. Only valid after the movie file has been closed (i.e. after calling close().)

open()[source]¶

Open the movie file for writing.

This creates a new thread that will write the movie file to disk in the background.

After calling this method, you can add frames to the movie using addFrame(). When you are done adding frames, call close() to finalize the movie file.

property pixelFormat¶

Pixel format for frames being added to the movie (str).

This should be either ‘rgb24’ or ‘rgba32’. The default is ‘rgb24’. When passing frames to addFrame() as a numpy array, the array should be in the format specified here.

property size¶

The size (w, h) of the movie in pixels (tuple or str).

If a string is passed, it should be one of the keys in the VIDEO_RESOLUTIONS dictionary.

This can not be changed after the writer has been opened.

property totalFrames¶

The total number of frames that will be written to the movie file (int).

This incudes frames that have already been written to disk and frames that are waiting to be written to disk.

psychopy.tools.movietools.closeAllMovieWriters()[source]¶

Signal all movie writers to close.

This function should only be called once at the end of the program. This can be registered atexit to ensure that all movie writers are closed when the program exits. If there are open file writers with frames still queued, this function will block until all frames remaining are written to disk.

Use caution when calling this function when file writers are being used in a multi-threaded environment. Threads that are writing movie frames must be stopped prior to calling this function. If not, the thread may continue to write frames to the queue during the flush operation and never exit.

psychopy.tools.movietools.addAudioToMovie(outputFile, videoFile, audioFile, useThreads=True, removeFiles=False, writerOpts=None)[source]¶

Add an audio track to a video file.

This function will add an audio track to a video file. If the video file already has an audio track, it will be replaced with the audio file provided. If no audio file is provided, the audio track will be removed from the video file.

The audio track should be exactly the same length as the video track.

Parameters:

• outputFile (str) – Path to the output video file where audio and video will be merged.

• videoFile (str) – Path to the input video file.

• audioFile (str or None) – Path to the audio file to add to the video file.

• codec (str) – The name of the audio codec to use. This should be a valid codec name for the encoder library being used. If None, the default codec for the encoder library will be used.

• useThreads (bool) – If True, the audio will be added in a separate thread. This allows the audio to be added in the background while the program continues to run. If False, the audio will be added in the main thread and the program will block until the audio is added. Defaults to True.

• removeFiles (bool) – If True, the input video (videoFile) and audio (audioFile) files will be removed (i.e. deleted from disk) after the audio has been added to the video. Defaults to False.

• writerOpts (dict or None) – Options to pass to the movie writer. This should be a dictionary of keyword arguments to pass to the movie writer. If None, the default options for the movie writer will be used. Defaults to None. See documentation for moviepy.video.io.VideoFileClip.write_videofile for possible values.

Examples

Combine a video file and an audio file into a single video file:

from psychopy.tools.movietools import addAudioToMovie
addAudioToMovie('output.mp4', 'video.mp4', 'audio.mp3')