Welcome to the Harris Geospatial product documentation center. Here you will find reference guides, help documents, and product libraries.

  >  Docs Center  >  IDL Reference  >  I/O - Video Data Formats  >  READ_VIDEO



The READ_VIDEO function is a wrapper for IDLffVideoRead and provides a way to read video, audio, and/or data streams from a video file.

Note: Frame counts may vary slightly depending on the method used to obtain the count. Variabilities in timestamps and video standards, discontinuities in the videos themselves, or differences in the types of frames may influence the apparent frame count.

Note: Animated GIF files do not contain header information on the frame rate, duration, or the number of frames. Instead of retrieving frames using the time stamp, you should retrieve individual frames using the frame keywords.

Note: READ_VIDEO is not available with the IDL Virtual Machine.


The following example uses a NASA video displaying the Coronal Mass Ejection (CME) event of August, 2012. The video is available online (see Resources and References, below) or in the \examples\data directory of your IDL installation.

See the Examples in the QUERY_VIDEO topic for examples on obtaining information about the video file used in this example.

Copy the following to the IDL command line to read in the CME.mp4 file:

; Define the file to read.
file = FILEPATH('CME.mp4', $
; Read a subset of the original video file.

See WRITE_VIDEO for an example of writing this video snippet to another file.


data = READ_VIDEO(Filename [, Stream_Index] [, /ALL] [, /CLOSE] [, HANDLE=variable] [, FRAME_END=value] [, FRAME_OUT=variable] [, FRAME_START=value] [, /NODATA] [, SUB_RECT=[x0, y0, x1, y1] [, TIME_END=integer] [, TIME_OUT=variable] [, TIME_START=integer] )

Return Value

The type of data returned depends on the type of stream read.

  • For a video stream, the data returned will be an array with dimensions of [3, width, height, nFrames].
  • For an audio stream, the data returned will be an array with dimensions of [nChannels, packetLength].
  • For a data stream, the data returned will be a vector of byte data.



Set this required argument to a string denoting the full path to a video file to open.

Note: If you specify HANDLE, IDL ignores the Filename argument (although you must still supply it).


Set the Stream_Index argument to a scalar integer denoting the stream index from which to read the data. If not specified, IDL reads the first video stream in the file. See QUERY_VIDEO for a description of the streams available in a file.



If set, this keyword prompts IDL to read all of the data from the stream.

Note: Reading the entire contents of the video data could result in a very large array and may not be possible depending on your computer's available memory.


Set this keyword to close the file currently used in HANDLE.

FRAME_END (video only)

Set this keyword to the frame index value at which to stop reading. Note that if you specify only the FRAME_END, IDL will return all frames from the beginning up through the FRAME_END.

FRAME_OUT (video only)

If set to a named variable, this keyword returns a long array containing the frame index(es) of the frame(s) returned by READ_VIDEO.

FRAME_START (video only)

Set this keyword to the frame index value at which to start reading. If neither TIME_START or FRAME_START are set, IDL returns the first frame from the specified stream. If TIME_START is specified, FRAME_START is ignored.


Set this keyword to a named variable to create a reference to your video that allows for more efficient reading of multiple frames. When reading from a file multiple times (for example, frames 0 - 74 read via a loop structure), by default IDL opens, reads, and closes the file once for each frame. When using a handle, IDL opens the video, reads each of the 75 frames, then closes the file.

If set to a handle previously returned from a READ_VIDEO call, the file used in the handle will be used and the Filename argument will be ignored.

If set to a named variable that is currently not in use as a handle, the handle for the current file will be returned in the variable.

Note: If a HANDLE is used, make sure to close it by specifying the CLOSE keyword along with the handle.


If set, IDL does not return any data. Use this keyword to obtain all of the time stamps for a stream without having to allocate memory to read the entire data stream.

SUB_RECT (video only)

This keyword allows you to specify the dimensional area of the video frames you want returned. Set SUB_RECT to a four-element vector [x0, y0, x1, y1] denoting two corners of the sub-rectangle you wish to capture.


Set this keyword to indicate the time, in seconds, at which to stop reading. Note that if you specify only the TIME_END, IDL will return all video/audio/data from the beginning up through the TIME_END.


If set to a named variable, this keyword returns a float array containing the time stamp(s) from the file of the frame(s) or packet(s) of data returned.


Set to the time, in seconds, at which to start reading. If neither TIME_START nor FRAME_START are set, IDL returns the first frame or packet of data from the specified stream.

Version History



Resources and References

The NASA "CME.mp4" video used in the example is courtesy of the Solar Dynamics Observatory (SDO) and the Solar and Heliospheric Observatory (SOHO). The file is available for download here:



A longer, similar video that can be substituted in the example code, is available for download here:


See Also

Creating Video, IDLffVideoRead, IDLffVideoWrite, QUERY_VIDEO, WRITE_VIDEO

© 2018 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us