The IDLffVideoRead class can be used to open video files in a variety of formats and read out frames of video, samples of audio, and packets of data.

The process for reading a video file is:

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

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

Superclasses

None.

Creation

See IDLffVideoRead::Init

Methods

This class has the following methods:

IDLffVideoRead::Init

IDLffVideoRead::GetCodecs

IDLffVideoRead::GetNext

IDLffVideoRead::GetFormats

IDLffVideoRead::GetMetadata

IDLffVideoRead::GetStreams

IDLffVideoRead::Seek

IDLffVideoRead::Cleanup

In addition, this class inherits the methods of its superclasses (if any).

Examples

The following example uses a NASA video displaying the coronal mass ejection (CME) event of Aug. 31, 2012, located in the \examples\data directory of your IDL installation.

CME.mp4 video courtesy NASA's Solar Dynamics Observatory (SDO)and Solar Heliospheric Observatory (SOHO). 

PRO video_read_example2
 
  file = FILEPATH('CME.mp4', SUBDIRECTORY=['examples','data'])
  oVid = IDLffVideoRead(file)
   
  ; Open up an image window, with no data for now
  img = IMAGE(BYTARR(2,2), /NODATA)       
   
          ; Get the next packet of data from the file,
  REPEAT BEGIN
     data = oVid->GetNext(TYPE=type) 
   
         ; If we got a frame of video, display it.
     IF type EQ 1 THEN img.SetData, data 
   
                    ; Keep going until we reach the end of the file.
  ; Note: End of file is where TYPE=-1.
  ENDREP UNTIL type EQ -1                   
   
  img.CLOSE
END

IDLffVideoRead::Init

Initializes the video read object.

Syntax

Result = IDLffVideoRead([Filename], /VERBOSE )

or

Result = OBJ_NEW('IDLffVideoRead' [, Filename], /VERBOSE )

 

Return Value

When this method is called indirectly, as in the previous syntax, the return value is an object reference to the newly-created object.

When called directly within a subclass Init method, the return value is 1 if initialization was successful, or zero otherwise.

Arguments

Filename

An optional string that specifies the full path and name of the video file (container format) to read. If you do not specify a filename, IDL will still create the object which can be used with the ::GetCodecs or ::GetFormats methods.

Keywords

VERBOSE

By default, if the video file contains any video or audio codecs that are not supported, then IDL will quietly ignore these codecs and continue to open the file. Set the VERBOSE keyword to force IDL to issue informational messages when it encounters any unsupported codecs.

IDLffVideoRead::GetCodecs

This method returns the list of codecs supported by IDLffVideoRead.

Tip: You can call IDLffVideoRead::GetCodecs as a static method, without needing to create an IDLffVideoRead object. For example:

print, IDLffVideoRead.GetCodecs()

Syntax

Result = Obj.[IDLffVideoRead::]GetCodecs([/LONG_NAMES] [, /AUDIO,] [, /VIDEO])

or, calling as a static method:

Result = IDLffVideoRead.GetCodecs([/LONG_NAMES] [, /AUDIO,] [, /VIDEO])

Return Value

Returns an array of strings listing the supported video formats.

Arguments

None

Keywords

LONG_NAMES

Set this keyword to return longer, more descriptive names.

AUDIO

Set this keyword to output only audio codecs.

VIDEO

Set this keyword to output only video codecs.

IDLffVideoRead::GetNext

Continue to decode the video file until one of the decoders yields a result.

Syntax

Result = Obj.[IDLffVideoRead::]GetNext(/AUDIO, /DATA, ONLY_STREAM=value, STREAM=variable, TYPE=variable, TIME=variable, /VERBOSE, /VIDEO)

Return Value

Returns the decoded data: a [3, w, h] array of bytes for a frame of video (with w width and h height in pixels); a [c, n] array of integers for audio (with c channels and n samples); or an array of bytes for streamed data.

Arguments

None

Keywords

AUDIO

Set this keyword to indicate that only audio data should be returned.

DATA

Set this keyword to indicate that only auxiliary data should be returned.

ONLY_STREAM

Set this keyword to the index value of the stream of interest so that IDL returns only that stream.

STREAM

Set this keyword to a named variable to specify the index value of the data stream you want to retrieve (see the ::GetStreams method for information on retrieving streams indices).

TYPE

Set this keyword to a named variable to capture an integer value representing the data type: 0=unknown, 1=video, 2=audio, 3=data, -1=EOF (end of file).

TIME

Set this keyword to a named variable to capture the data's place in the file, in seconds from the beginning.

VERBOSE

By default, any warnings or non-fatal errors will be quietly ignored. Set the VERBOSE keyword to issue informational messages for these warnings.

VIDEO

Set this keyword to indicate that only video data should be returned.

Note: One, two, or more of DATA, AUDIO, and VIDEO may be set to filter on those types. If none are set, all are assumed.

IDLffVideoRead::GetFormats

This method returns the list of formats supported by IDLffVideoRead.

Tip: You can call IDLffVideoRead::GetFormats as a static method, without needing to create an IDLffVideoRead object. For example:

print, IDLffVideoRead.GetFormats()

Syntax

Result = Obj.[IDLffVideoRead::]GetFormats([/LONG_NAMES])

or, calling as a static method:

Result = IDLffVideoRead.GetFormats([/LONG_NAMES])

Return Value

Returns an array of strings listing every supported format.

Arguments

None

Keywords

LONG_NAMES

Set this keyword to return longer, more descriptive names.

IDLffVideoRead::GetMetadata

Retrieves metadata values corresponding to the given key, such as 'title', 'copyright', 'author', etc.

Syntax

Result = Obj.[IDLffVideoRead::]GetMetadata([Key] [, /KEYS])

Return Value

Returns an array of strings listing the metadata for the key specified.

Arguments

Key

Set "Key" to a string value indicating the key for which you wish to retrieve metadata.

The following table lists the typpical metadata keys recognized by the IDL-supported video file formats. Other formats may have their own list of recognized metadata keys.

Key

album

artist

comment

copyright

genre

title

Either the Key argument or the /KEYS keyword must be specified when calling ::GetMetadata.

::GetMetadata will error if the "key" you specify is not present in the file.

Keywords

KEYS

Set this keyword to return an array of all available metadata keys.

IDLffVideoRead::GetStreams

The ::GetStreams() method returns an array of structures describing the streams in the current file.

These structures are of the following format:

{
PID,      ; Program ID - The internal identifier for the stream
TYPE,     ; 0=unknown, 1=video, 2=audio, 3=data
RATE,     ; Rate in Hertz.  For example, 25 FPS for video, or 44100 Hz for audio
WIDTH,    ; Video only.  Width in pixels
HEIGHT,   ; Video only.  Height in pixels
CHANNELS, ; Audio only. Number of audio channels
CODEC,    ; String identifying the codec used
LENGTH,   ; Stream length in seconds
COUNT     ; Number of frames of that stream in the file
}

Note: Animated GIF files do not contain header information on the frame rate, duration, or the number of frames. These values are estimated from other header information and may be incorrect.

Note: The LENGTH, COUNT, and RATE fields are best guess approximations given by the FFMPEG library. This is due to the reported RATE of some files being slightly different than the actual RATE. For example, an NTSC file might have a reported RATE of 30 but an actual RATE of 29.97. These differences vary by formats and codecs.

Syntax

Result = Obj.[IDLffVideoRead::]GetStreams()

Return Value

Returns an array of structures describing the current file's streams.

Arguments

None.

Keywords

None.

IDLffVideoRead::Seek

Repositions the current location in the file to as close as possible to the input time.

Syntax

Obj.[IDLffVideoRead::]Seek, Time

Return Value

None.

Arguments

Time

Desired position in the file, in seconds from the beginning.

Keywords

None.

IDLffVideoRead::Cleanup

This method closes the file and destroys the object.

Syntax

Obj.[IDLffVideoRead::]Cleanup

or

OBJ_DESTROY, Obj

Additional Example

Read in the same file as in our original example, above, and show the use of the ::GetMetadata method.

; Specify the file and create an IDLffVideoRead object
; to hold the file.
oVid = OBJ_NEW('IDLffVideoRead', 'CME.mp4')
 
; Obtain array of all available metadata for the file.
meta = oVid.GetMetadata(/KEYS)
 
HELP, meta
PRINT, meta
 

IDL displays:

 
META               STRING    = Array[5]
major_brand minor_version  compatible_brands creation_time encoder
 
; Get and display some metadata based on the results above.
brand = oVid.GetMetadata("major_brand")
PRINT, brand
 

IDL displays:

mp42

Version History

8.2.3

Introduced

8.3

Allow ::GetCodecs and ::GetFormats to be called as static methods.

8.4

Added VERBOSE keyword to ::Init

See Also

Creating Video, IDLffVideoWrite, OBJ_DESTROY, OBJ_NEW, QUERY_VIDEO, READ_VIDEO, WRITE_VIDEO