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.

Things to note about READ_VIDEO:

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.
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.
READ_VIDEO is not available with the IDL Virtual Machine.

Examples

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', $

   SUBDIRECTORY=['examples','data'])

; Read a subset of the original video file.

myVid = READ_VIDEO(file, TIME_START=5, TIME_END=15)

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

Syntax

data = READ_VIDEO(Filename [, Stream_Index] [, /ALL] [, /CLOSE] [, HANDLE=variable] [, FRAME_END=value] [, FRAME_OUT=variable] [, FRAME_START=value] [, /NODATA] [, SUB_RECT=[x₀, y₀, x¹, y₁] [, 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.

Arguments

Filename

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).

Stream_Index

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.

Keywords

ALL

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.

CLOSE

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.

HANDLE

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.

NODATA

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 [x₀, y₀, x₁, y₁] denoting two corners of the sub-rectangle you wish to capture.

TIME_END

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.

TIME_OUT

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.

TIME_START

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

8.2.3

Introduced

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:

https://www.nasa.gov/multimedia/videogallery/index.html?media_id=160387251

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

https://www.nasa.gov/mission_pages/sdo/news/coronal-rain.html