Main Content

VideoWriter

Create object to write video files

expand all in page

Description

Use a VideoWriter object to create a video file from an array or MATLAB® movie. The object contains information about the video and the properties that control the output video. You can create a VideoWriter object using the VideoWriter function, specify its properties, and then write the video using object functions.

Creation

Syntax

v = VideoWriter(filename)
v = VideoWriter(filename,profile)

Description

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

example

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

example

Input Arguments

expand all

Filename, specified as a character vector or string scalar. VideoWriter creates the file.

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 macOS 10.7 and later)

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

Example: 'myFile.avi'

Example: '../dir/videos/myFile.mj2'

File type, specified as one of these.

Value of profileDescription

'Archival'

Motion JPEG 2000 file with lossless compression

'Motion JPEG AVI'

AVI file using Motion JPEG encoding

'Motion JPEG 2000'

Motion JPEG 2000 file

'MPEG-4'

MPEG-4 file with H.264 encoding (systems with Windows 7 or later, or macOS 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

profile sets default values for video properties, such as VideoCompressionMethod.

Properties

expand all

The VideoWriter object contains properties that control the output video. You can create a VideoWriter object with properties tailored to a specific format, such as 'Uncompressed AVI' or 'MPEG-4', by using the VideoWriter function with a predefined profile. For example, you can create a VideoWriter object with a Motion JPEG AVI profile and assign a value to the Quality property.

v = VideoWriter('newfile.avi','Motion JPEG AVI');
v.Quality = 95;

After you call the open function on the VideoWriter object, you cannot change the value of a property. Therefore, modify property values before opening the video file for writing.

This property is read-only.

Number of color channels in each output video frame, specified as a positive integer:

  • Uncompressed AVI, Motion JPEG AVI, and MPEG-4 files have three color channels.

  • Indexed and grayscale AVI files have one color channel.

  • For Motion JPEG 2000 files, the number of channels depends on the input data to the writeVideo function: one for monochrome data or three for color data.

Data Types: double

Color information for video file, specified as a numeric matrix with three columns and a maximum of 256 rows. Each row in the matrix defines one color using an RGB triplet. An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1].

You can set the colormap explicitly before the call to open, or by using the colormap field of a movie frame structure at the time of writing the first frame.

The Colormap property only applies to objects used for writing indexed AVI files.

Example: colormap(summer(256))

Data Types: double | uint8

Target compression ratio, specified as an integer greater than 1. The compression ratio is the ratio between the number of bytes in the input image and the number of bytes in the compressed image. The video data is compressed as much as possible, up to the specified target.

CompressionRatio is available only for objects used for writing Motion JPEG 2000 files. After you call open, you cannot change the CompressionRatio value. If you previously set LosslessCompression to true, then setting CompressionRatio generates an error.

Example: 5

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

This property is read-only.

Duration of the output file in seconds, specified as a scalar value.

Data Types: double

This property is read-only.

Type of file to write, specified as 'avi', 'mp4', or 'mj2'.

This property is read-only.

Name of file, specified as a character vector or string scalar.

This property is read-only.

Number of frames written to the video file, specified as an integer.

Data Types: double

Rate of video playback in frames per second, specified as a positive number.

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

Example: 10

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

This property is read-only.

Height of each video frame in pixels, specified as a scalar. The writeVideo method sets values for Height and Width based on the dimensions of the first frame.

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, then VideoWriter pads the frame with a row of black pixels at the bottom. For MPEG-4 files on Windows systems, the allowed value depends on the version of Windows.

Data Types: double

Lossless compression, specified as a numeric or logical 1 (true) or 0 (false). The LosslessCompression property is available only for objects used for writing Motion JPEG 2000 files.

If LosslessCompression is true, then:

  • The writeVideo function writes data 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.

By default, LosslessCompression is false for the 'Motion JPEG 2000' profile and true for the 'Archival' profile.

Bit depth for Motion JPEG 2000 files, specified as an integer in the range [1,16]. The bit depth is the number of least-significant bits in the input image data

MJ2BitDepth is available only for objects used for writing Motion JPEG 2000 files. If you do not specify a value before calling the open method, then 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, then MJ2BitDepth is 8.

Example: 8

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

This property is read-only.

Full path to the video file, specified as a character vector or string scalar.

Video quality, specified as an integer in the range, [0,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.

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

Example: 50

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

This property is read-only.

Number of bits per pixel in each output video frame, specified as a numeric scalar.

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

Indexed and grayscale AVI files have 8 bits per pixel.

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, then the default value of MJ2BitDepth is 16, and VideoBitsPerPixel is 48 (three times the bit depth).

Data Types: double

This property is read-only.

Type of video compression, specified as 'None', 'H.264', 'Motion JPEG', or 'Motion JPEG 2000'.

This property is read-only.

MATLAB representation of the video format, specified as a character vector or string scalar.

For file types other than Motion JPEG 2000 files, VideoWriter sets VideoFormat to one of the values in this table.

Video Format

Value of VideoFormat

Uncompressed AVI, Motion JPEG AVI, or MPEG-4 files

'RGB24'

AVI files with indexed video

'Indexed'

AVI files with grayscale video

'Grayscale'

For Motion JPEG 2000 files, VideoWriter sets the VideoFormat based 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, then VideoWriter sets the format as shown here.

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'

This property is read-only.

Width of each video frame in pixels, specified as a numeric scalar. The writeVideo function sets values for Height and Width based on the dimensions of the first frame.

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, then VideoWriter pads the frame with a column of black pixels along the right side. For MPEG-4 files on Windows systems, the allowed value depends on the version of Windows.

Data Types: double

Object Functions

openOpen file for writing video data
closeClose file after writing video data
writeVideoWrite video data to file
VideoWriter.getProfilesProfiles and file formats that VideoWriter supports

Examples

collapse all

Open Live Script

Write a video to a file by creating an array with random data, making a VideoWriter object for the output file, and then writing the array to the video.

Create a 300-by-300 matrix of data.

A = rand(300);

Create a VideoWriter object to write a Motion JPEG AVI file named newfile.avi and open the object for writing.

v = VideoWriter("newfile.avi");
open(v)

Write the matrix of data A to the video file.

writeVideo(v,A)

Close the VideoWriter object.

close(v)
Open Live Script

Create a video object with a specified profile, make an array containing an RGB image, and then write the array into a video file.

Create a VideoWriter object for a new uncompressed AVI file for RGB24 video.

v = VideoWriter("newfile.avi","Uncompressed AVI");

Open the file for writing.

open(v)

Create an array containing data from the sample still image, peppers.png. Write the image in A to the video file.

A = imread("peppers.png");
writeVideo(v,A)

Close the VideoWriter object.

close(v)
Open Live Script

Set up the axes and figure properties to generate frames for the video.

Z = peaks;
surf(Z);
axis tight manual

Figure contains an axes object. The axes object contains an object of type surface.

set(gca,"NextPlot","replacechildren")

Create a VideoWriter object for the output video file and open the object for writing.

v = VideoWriter("peaks.avi");
open(v)

Generate a set of frames, get each frame from the figure, and then write each frame to the file.

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

Figure contains an axes object. The axes object contains an object of type surface.

Close the VideoWriter object.

close(v)

Extended Capabilities

Version History

Introduced in R2010b

expand all

See Also

|