VideoWriter class

Write video files

Description

Use the VideoWriter object with the open, writeVideo, and close methods to create video files from figures, still images, or MATLAB® movies. VideoWriter can create uncompressed AVI and Motion JPEG 2000 compressed AVI files on all platforms, and MPEG-4 files on Windows® 7 or later and Mac OS X 10.7 and higher. VideoWriter supports files larger than 2 GB, which is the limit for avifile.

To set video properties, VideoWriter includes predefined profiles such as 'Uncompressed AVI' or 'MPEG-4'.

Construction

writerObj = VideoWriter(filename) constructs a VideoWriter object to write video data to an AVI file with Motion JPEG compression.

writerObj = VideoWriter(filename,profile) applies a set of properties tailored to a specific file format (such as 'MPEG-4' or 'Uncompressed AVI') to a VideoWriter object.

Input Arguments

filename

String enclosed in single quotation marks that specifies the name of the file to create.

VideoWriter supports these file extensions:

.avi

AVI file

.mj2

Motion JPEG 2000 file

.mp4 or .m4v

MPEG-4 file (systems with Windows 7 or later, or Mac OS X 10.7 and later)

If you do not specify a valid file extension, VideoWriter appends the extension .avi, .mj2 or .mp4, depending on the profile. If you do not specify a value for profile, then VideoWriter creates a Motion JPEG compressed AVI file with the extension .avi.

profile

String enclosed in single quotation marks that describes the type of file to create. Specifying a profile sets default values for video properties such as VideoCompressionMethod. Possible values:

'Archival'

Motion JPEG 2000 file with lossless compression

'Motion JPEG AVI'

Compressed AVI file using Motion JPEG codec

'Motion JPEG 2000'

Compressed Motion JPEG 2000 file

'MPEG-4'

Compressed MPEG-4 file with H.264 encoding (systems with Windows 7 or later, or Mac OS X 10.7 and later)

'Uncompressed AVI'

Uncompressed AVI file with RGB24 video

'Indexed AVI'

Uncompressed AVI file with indexed video

'Grayscale AVI'

Uncompressed AVI file with grayscale video

Default: 'Motion JPEG AVI'

Properties

ColorChannels

Number of color channels in each output video frame. (Read-only)

AVI and MPEG-4 files with RGB24 data have three color channels. Indexed and Grayscale AVI files have one color channel. The number of channels for Motion JPEG 2000 files depends on the input data to the writeVideo method: one for monochrome image data, three for color data.

Colormap

P-by-3 numeric matrix that contains color information about the video file. The colormap can have a maximum of 256 entries of type uint8 or double. The entries of the colormap must be integers. Each row of Colormap specifies the red, green, and blue components of a single color. The colormap can be set explicitly before the call to open, or using the colormap field of a movie frame structure at the time of writing the first frame.

Only applies to objects associated with Indexed AVI files.

After you call open, you cannot change the Colormap value.

Default: none

CompressionRatio

Number greater than 1 that specifies the target ratio between the number of bytes in the input image and the number of bytes in the compressed image. The data is compressed as much as possible, up to the specified target.

Only available for objects associated with Motion JPEG 2000 files. After you call open, you cannot change the CompressionRatio value. If you previously set LosslessCompression to true, setting CompressionRatio generates an error.

Default: 10

Duration

Scalar value specifying the duration of the file in seconds. (Read-only)

FileFormat

String specifying the type of file to write: 'avi', 'mp4', or 'mj2'. (Read-only)

Filename

String specifying the name of the file. (Read-only)

FrameCount

Number of frames written to the video file. (Read-only)

FrameRate

Rate of playback for the video in frames per second. After you call open, you cannot change the FrameRate value.

Default: 30

Height

Height of each video frame in pixels. The writeVideo method sets values for Height and Width based on the dimensions of the first frame. (Read-only)

MPEG-4 files require frame dimensions that are divisible by two. If the input frame height for an MPEG-4 file is not an even number, VideoWriter pads the frame with a row of black pixels at the bottom.

LosslessCompression

Boolean value (logical true or false) only available for objects associated with Motion JPEG 2000 files. If true:

  • The writeVideo method uses reversible mode so that the decompressed data is identical to the input data.

  • VideoWriter ignores any specified value for CompressionRatio.

After you call open, you cannot change the LosslessCompression value.

Default: false for the 'Motion JPEG 2000' profile, true for the 'Archival' profile

MJ2BitDepth

Number of least significant bits in the input image data, from 1 to 16.

Only available for objects associated with Motion JPEG 2000 files. If you do not specify a value before calling the open method, VideoWriter sets the bit depth based on the input data type. For example, if the input data to writeVideo is an array of uint8 or int8 values, MJ2BitDepth is 8.

Path

String specifying the fully qualified path. (Read-only)

Quality

Integer from 0 through 100. Higher quality numbers result in higher video quality and larger file sizes. Lower quality numbers result in lower video quality and smaller file sizes.

Only available for objects associated with the MPEG-4 or Motion JPEG AVI profile. After you call open, you cannot change the Quality value.

Default: 75

VideoBitsPerPixel

Number of bits per pixel in each output video frame. (Read-only)

AVI files with truecolor video and MPEG-4 files have 24 bits per pixel (8 bits for each of three color bands).

For Motion JPEG 2000 files, the number of bits per pixel depends on the value of MJ2BitDepth and the number of bands of image data. For example, if the input data to writeVideo is a three-dimensional array of uint16 or int16 values, the default value of MJ2BitDepth is 16, and VideoBitsPerPixel is 48 (three times the bit depth).

VideoCompressionMethod

String indicating the type of video compression: 'None', 'H.264', 'Motion JPEG', or 'Motion JPEG 2000'. (Read-only)

VideoFormat

String indicating the MATLAB representation of the video format. (Read-only)

Video Format

Value of VideoFormat

AVI or MPEG-4 files with RGB24 video

'RGB24'

AVI files with indexed video

'Indexed'

AVI files with grayscale video

'Grayscale'

For Motion JPEG 2000 files, VideoFormat depends on the value of MJ2BitDepth and the format of the input image data to the writeVideo method. For example, if you do not specify the MJ2BitDepth property, VideoWriter sets the format as shown in this table.

Format of Image Data

Value of VideoFormat

Single-band uint8'Mono8'
Single-band int8'Mono8 Signed'
Single-band uint16'Mono16'
Single-band int16'Mono16 Signed'
Three-banded uint8'RGB24'
Three-banded int8'RGB24 Signed'
Three-banded uint16'RGB48'
Three-banded int16'RGB48 Signed'

Width

Width of each video frame in pixels. The writeVideo method sets values for Height and Width based on the dimensions of the first frame. (Read-only)

MPEG-4 files require frame dimensions that are divisible by two. If the input frame width for an MPEG-4 file is not an even number, VideoWriter pads the frame with a column of black pixels along the right side.

Methods

closeClose file after writing video data
getProfilesList profiles and file formats supported by VideoWriter
openOpen file for writing video data
writeVideoWrite video data to file

Copy Semantics

Handle. To learn how handle classes affect copy operations, see Copying Objects in the MATLAB documentation.

Examples

expand all

View and Set Object Properties

Construct a VideoWriter object and view its properties.

writerObj = VideoWriter('newfile.avi')

Set the frame rate to 60 frames per second, using the FrameRate property.

writerObj.FrameRate = 60;

AVI File from Animation

Write a sequence of frames to a compressed AVI file, peaks.avi.

Prepare the new file.

writerObj = VideoWriter('peaks.avi');
open(writerObj);

Generate initial data and set axes and figure properties.

Z = peaks; surf(Z); 
axis tight
set(gca,'nextplot','replacechildren');
set(gcf,'Renderer','zbuffer');

Setting the Renderer property to zbuffer or Painters works around limitations of getframe with the OpenGL® renderer on some Windows systems.

Create a set of frames and write each frame to the file.

for k = 1:20 
   surf(sin(2*pi*k/20)*Z,Z)
   frame = getframe;
   writeVideo(writerObj,frame);
end

close(writerObj);
Was this topic helpful?