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
oVid = IDLffVideoWrite(file)
vidStream = oVid.AddVideoStream(width, height, fps)
audStream = oVid.AddAudioStream(samplerate)
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)
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
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,
type,
rate,
width,
height,
channels,
codec,
length,
}
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.
|