The IDLffVideoWrite object creates a video file with an optional soundtrack. If you need to write animated GIF files, use the WRITE_GIF procedure instead.

The process for creating a video file is:

IDLffVideoWrite is not available with the IDL Virtual Machine or IDL Runtime distributions.

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

Superclasses


None.

Creation


See IDLffVideoWrite::Init.

Methods


This class has the following methods:

IDLffVideoWrite::Init

IDLffVideoWrite::AddVideoStream

IDLffVideoWrite::AddAudioStream

IDLffVideoWrite::GetCodecs

IDLffVideoWrite::GetFormats

IDLffVideoWrite::GetStreams

IDLffVideoWrite::Put

IDLffVideoWrite::SetMetadata

IDLffVideoWrite::Cleanup

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

Examples


This example creates an MP4 video of a rotating surface graphic, and includes an audio track.

PRO surfaceVideo_ex
  file        = 'surface.mp4'
  width       = 500
  height      = 500
  frames      = 180
  fps         = 30
  speed       = 2
  samplerate  = 22050L
 
  ; Create object and initialize video/audio streams
  oVid = IDLffVideoWrite(file)
  vidStream = oVid.AddVideoStream(width, height, fps)
  audStream = oVid.AddAudioStream(samplerate)
 
  ; Generate some audio
  audio  = FINDGEN(samplerate * frames / fps)
  audio = SIN(audio * 2 * !PI / samplerate) * samplerate / 22
  audio  = SIN(audio * 2 * !PI / samplerate * 1000)
  audio  = FIX(30000 * audio)
  time = oVid.Put(audStream, audio)
 
  ; Generate video frames
  surf = SURFACE(/TEST, DIMENSIONS=[width,height])
  FOR i = 0, frames-1 DO BEGIN
    time = oVid.Put(vidStream, surf.CopyWindow())
    surf.Rotate, speed
  ENDFOR
  surf.Close
   
  ; Close the file
  oVid = 0
END

IDLffVideoWrite::Init


Initializes the object and creates the video file.

Syntax


Result = IDLffVideoWrite( Filename [, FORMAT=string])

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

A string that specifies the full path and name of the video file (container format) to create. If the file 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: For a list of all available file types, call IDLffVideoWrite::GetFormats.

Keywords


FORMAT

Set this keyword to a string that specifies the file type (container format) to create. You can also 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

Note: For a list of all available file types, call IDLffVideoWrite::GetFormats.

IDLffVideoWrite::AddVideoStream


This function method adds a new video stream to the file.

Syntax


Result = Obj.[IDLffVideoWrite::]AddVideoStream( Width, Height, Fps [, BIT_RATE=Value] [, CODEC=string] [, PRESET=string] [, PROFILE=string] [, TUNE=string] )

Return Value


Returns the index of the new stream.

Arguments


Width

The frame width in pixels.

Height

The frame height in pixels.

Fps

The frames per second at which the video file is meant to be played back.

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.

Keywords


BIT_RATE

The target output data rate of the video encoder, in bits per second. Larger values produce higher quality video, but larger files, up to the maximum bit rate. Actual results may be slightly larger or smaller.

Note: The maximum bit rate depends upon the codec, frame size, and frames-per-second. Setting bit rates higher than the maximum is harmless but will not result in a higher-quality video.

CODEC

Set this keyword to the codec to use for encoding the data. For a video stream in an AVI or MP4-format file, the default value is 'MP4'.

Note: For a list of all available codecs, call IDLffVideoWrite::GetCodecs.

PRESET

Set this keyword to a string that selects one of the built-in encoding presets for the H.264 video codec. Because the version of FFmpeg included with IDL does not support H.264, this argument is useful only if you have replaced the FFmpeg version. See Replacing the FFmpeg Version.

This argument is equivalent to the -vpre argument to the command-line FFmpeg utility. Valid values are:

ultrafast

slower

superfast

veryslow

veryfast

max

faster

placebo

fast

lossless_ultrafast

normal

lossless_fast

default

lossless_medium

medium

lossless_slow

hq

lossless_slower

slow

lossless_max

The 'lossless' presets will guarantee perfect video quality with a tradeoff between encoding speed and file size. All other values have a tradeoff between encoding speed and video quality, with fairly constant file size.

Note: Not all players that support H.264 can play lossless video.

PROFILE

Set this keyword to a string that selects one of the built-in profile presets for the H.264 video codec. Because the version of FFmpeg included with IDL does not support H.264, this argument is useful only if you have replaced the FFmpeg version. See Replacing the FFmpeg Version.

This argument is equivalent to the -profile argument to the command-line FFmpeg utility. Valid values are:

baseline

high10

main

high422

high

high444

Note: Usage of profile is not compatible with lossless encoding.

Note: Certain devices may only support certain profiles.

TUNE

Set this keyword to a string that selects one of the built-in tuning presets for the H.264 video codec. Because the version of FFmpeg included with IDL does not support H.264, this argument is useful only if you have replaced the FFmpeg version. See Replacing the FFmpeg Version.

This argument is equivalent to the -tune argument to the command-line FFmpeg utility. Valid values are:

film

psnr

animation

ssim

grain

fastdecode

stillimage

zerolatency

IDLffVideoWrite::AddAudioStream


This function method adds a new audio stream to the file.

Interlacing Video and Audio


Nearly all video formats require audio (if any) to be interlaced in the file with video frames, but IDLffVideoWrite does not require the user to output audio and video data this way. To permit this behavior, video and audio data is kept in memory until it can be interlaced and written out to a file.

The key to minimizing memory use is to keep all of the streams in the video synchronized--alternately write out a frame of video and some fraction of a second of audio. If you must do all of one and then the other, outputting audio first requires less memory.

Syntax


Result = Obj.[IDLffVideoWrite::]AddAudioStream(Rate [, BIT_RATE=value] [, CHANNELS=value] [, CODEC=string])

Return Value


Returns the index of the new stream.

Arguments


Rate

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.

Keywords


BIT_RATE

The target output data rate of the audio encoder, in bits per second. Larger values produce higher quality audio, but larger files. Actual results may be slightly larger or smaller.

CHANNELS

Set this keyword to the number of audio channels in the stream. For example, 1 = mono, 2 = stereo.

CODEC

Set this keyword to the codec to use for encoding the data. For an audio stream in an AVI or MP4-format file, the default value is 'MP2'.

Note: If you add only audio streams to an IDLffVideoWrite object, you can only use the MPEG-4 container format (file type).

Note: For a list of all available codecs, call IDLffVideoWrite::GetCodecs.

IDLffVideoWrite::GetCodecs


This function method returns the list of codecs you may use to encode a video or audio stream.

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

print, IDLffVideoWrite.GetCodecs()

Syntax


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

or, calling as a static method:

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

Return Value


Returns the available codecs as an array of strings. These strings are the same names accepted by the CODEC keyword of the AddVideoStream and AddAudioStream methods (unless the LONG_NAMES keyword is set).

Arguments


None

Keywords


AUDIO

Set this keyword to return only available audio codecs.

LONG_NAMES

Set this keyword to return longer, more descriptive names.

VIDEO

Set this keyword to return only available video codecs.

IDLffVideoWrite::GetFormats


This function method returns the video file types (container formats) you can create.

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

print, IDLffVideoWrite.GetFormats()

Syntax


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

or, calling as a static method:

Result = IDLffVideoWrite.GetFormats(/LONG_NAMES)

Return Value


Returns a list of available file formats as an array of strings. These strings are the same names accepted by the FORMAT keyword of the Init method (unless the LONG_NAMES keyword is set).

Arguments


None

Keywords


LONG_NAMES

Set this keyword to return longer, more descriptive format names.

IDLffVideoWrite::Put


This function method writes data into the stream identified by Index.

Syntax


Result = Obj.[IDLffVideoWrite::]Put(Index, Data)

Return Value


A floating-point value giving the point in the timeline (in seconds) that was assigned to the given data.

Arguments


Index

The data stream index returned by the AddVideoStream or AddAudioStream methods.

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.

IDLffVideoWrite::GetStreams


This function method returns an array of structures describing each of the streams contained in the video file.

Syntax


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

Return Value


Returns an array of structures describing each of the streams contained in the video 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
}

IDLffVideoWrite::SetMetadata


This method embeds a metadata string in the video file.

Note: You can not call the SetMetadata method after you call the Put method.

Syntax


Obj.[IDLffVideoWrite::]SetMetadata, Key, Value

Arguments


Key

A case-insensitive string value. Keys unsupported by the file format are ignored.

The following table lists the 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

Value

A string value.

Keywords


None

Example


oVid.SetMetadata, 'title', 'Yeti photographed by wildlife cam'

IDLffVideoWrite::Cleanup


This method finalizes and closes the file, and then destroys the object. The file is not playable until the object is destroyed.

Note: The Cleanup method will automatically be called when the object is destroyed (either using OBJ_DESTROY or Automatic Garbage Collection). You only need to call ::Cleanup if you are creating a custom subclass and you override the Cleanup method.

Syntax


Obj.[IDLffVideoWrite::]Cleanup

See Also


Creating Video, IDLffVideoRead, QUERY_VIDEO, READ_VIDEO, WRITE_VIDEO

Version History


8.1

Introduced

8.2

Added PRESET keyword to ::AddVideoStream method.

8.3

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