WRITE_VIDEO

WRITE_VIDEO is a wrapper for IDLffVideoWrite. This function provides a way to easily write video and/or audio streams to a video file.

Things to note about READ_VIDEO:

If you are writing both video and audio to the same file, you must define both streams before any data can be written.
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. You may provide these values but they will be quietly ignored.
WRITE_VIDEO is not available with the IDL Virtual Machine.

For more information on video, please see the Creating Video topic.

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 READ_VIDEO and QUERY_VIDEO topics for additional examples using this video.

; Define the file to read.

file = FILEPATH('CME.mp4', $

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

; Read a subset of the original video file, starting at

; 5 seconds and ending at 15 seconds.

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

; Write out the snippet stored in the myVid variable

; but using a frame rate of 20 fps instead of the original

; 29.97 fps, effectively slowing down playback.

WRITE_VIDEO, 'TestCME_MP4.mp4', myVid, VIDEO_FPS=20

You can now use your computer's default video player to view the snippet of video you just wrote.

Syntax

WRITE_VIDEO, Filename [, Data] [, AUDIO_CHANNELS=value] [, AUDIO_CODEC=value] [, AUDIO_RATE=value] [, BIT_RATE=value] [, /CLOSE] [, FORMAT=string] [, HANDLE=handle] [, METADATA=value] [, VIDEO_CODEC=value] [, VIDEO_DIMENSIONS=value] [, VIDEO_FPS=value]

Return Value

None.

Arguments

Filename

Set this required argument to a string denoting the full path to a video file to write. If a file with the same name already exists, it will be overwritten. You can specify the file type by including a filename extension or by setting the optional FORMAT keyword. The IDL-supported file type extensions are:

Extension	File Type
.avi	Audio Video Interleave
.mp4	MPEG-4

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

Data

Use this argument to specify the data to be written to the stream.

For video, the data must be represented as bytes in the format [3, w, h] with w and h matching the stream's original width and height.

For audio, the data must be represented as 16-bit integers and arranged in an array of the format [n, s] to write s samples (as many as desired) into n channels (n must match the number of channels in the stream). If you are writing one channel, [1, s] and [s] are functionally equivalent, and both formats are accepted.

Note: You may write to one video and one audio stream. Their order does not matter, and calls to WRITE_VIDEO may alternate between the two.

Keywords

AUDIO_CHANNELS

Set this keyword to the number of channels to use in the audio data. Values are either '1' for mono or '2' for stereo. This keyword is only used during the first call to WRITE_VIDEO and is ignored during any subsequent calls using a HANDLE. If you supply audio data, IDL will take the value from the data and this keyword is then not necessary.

AUDIO_CODEC

Set this keyword to the codec to use for encoding the audio data. For an audio stream in an MP4-format file, the default value is 'mp2'. For a list of all available codecs, see the CODECS* keywords in QUERY_VIDEO.

Note: This keyword is only used during the first call to WRITE_VIDEO and is ignored during any subsequent calls using a HANDLE.

AUDIO_RATE

Set this keyword to the audio sample rate in Hertz. Not all values are guaranteed to work, depending upon the codec used. Suggested values are 44100 (CD quality), 22050, and 11025. A value is required during the first time audio data is written, and will be ignored during any future calls to write audio data to the same file.

BIT_RATE

Set BIT_RATE to the target output data rate, in bits per second. Larger values produce higher quality audio/video, but the files will be larger. Actual results may be slightly larger or smaller. If not specified, IDL uses a reasonable value depending on the chosen CODEC.

CLOSE

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

CODEC

Set this keyword to a string value specifying the codec to use.

For a video stream in an MP4-format file, the default value is 'MP4'.
For an audio stream in an MP4-format file, the default value is 'MP2'.

For a list of all available codecs, see the CODEC_* keywords in QUERY_VIDEO. This is only used during the first call to WRITE_VIDEO and is ignored during any subsequent calls using a HANDLE.

FORMAT

Set this keyword to a string indicating the container format (file type) to write. Alternatively, you can specify the file type by including a filename extension when setting Filename. The IDL-supported strings are:

String	File Type
'avi'	Audio Video Interleave
'mp4'	MPEG-4

This keyword is only used during the first call to WRITE_VIDEO and is ignored during any subsequent calls using a HANDLE.

HANDLE

If set to a handle previously returned from a WRITE_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 a valid handle, IDL returns the handle for the current file in the variable and keeps the file open.

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

METADATA

Set this keyword to a [2, n] element string array denoting n [key, value] pairs of metadata to be written to the file.

Note: Metadata must be written before any video or audio data.

VIDEO_CODEC

Set this keyword to the codec to use for encoding the video data. For a video stream in an MP4-format file, the default value is 'mp4'. For a list of all available codecs, see the CODECS* keywords in QUERY_VIDEO. This keyword is only used during the first call to WRITE_VIDEO and is ignored during any subsequent calls using HANDLE.

VIDEO_DIMENSIONS

Set this keyword to a 2-element vector giving the size [width, height] of one frame of video data. This keyword is only used during the first call to WRITE_VIDEO and is ignored during any subsequent calls using HANDLE. If you supply video data, IDL will take the value from the data and this keyword is then not necessary.

VIDEO_FPS

Set this keyword to the frames per second at which the video file is meant to be played back. A value is required during the first time video data is written, and will be ignored during any future calls to write to the same file.

Note: Very low frame rates (<5 FPS) can be problematic for many codecs and players. Rather than setting FPS this low,we recommend that you set some multiple of the desired frame rate and output each frame several times. Because of the way most codecs encode video, the increase in file size is usually negligible.

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