Routines (alphabetical) > Object Classes > File Format Object Classes > IDLffVideoWrite

# IDLffVideoWrite

The IDLffVideoWrite object creates a video file with an optional soundtrack. The process for creating a video file is:

- Create the object and associated video file with IDLffVideoWrite::Init.
- Open a video stream with IDLffVideoWrite::AddVideoStream.
- Open an (optional) audio stream with IDLffVideoWrite::AddAudioStream.
- Write the video and audio data to the individual streams with IDLffVideoWrite::Put. Video data is written one frame at a time, (each frame consisting of an array of pixels). Audio data is written as an array of integers.
- Destroy the object and close the file with IDLffVideoWrite::Cleanup.

Note: IDLffVideoWrite is not available with the IDL Virtual Machine.

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. Actual results may be slightly larger or smaller.

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