FFmpegSource

Opens files using FFmpeg and nothing else. May be frame accurate on good days. The source is MIT licensed and can be obtained from the GitHub repository. The precompiled binary is GPL3 licensed.

• AviSynth 2.6.0 or greater
• Supported color formats: RGB24, RGB32, YUY2, Y8, YV12, YV16, YV24, YV411
  

(10-bit formats are supported with the 10bithack version - see alternate download above)

• Because of LAVF's demuxer, most raw streams (such as elementary h264 and other mpeg video streams) will fail to work properly.

• FFAudioSource will have to remake any index implicitly created by FFVideoSource and therefore code like

• Interlaced H.264 mostly works these days, but seeking may occasionally result in corruption.
• Transport Streams will not decode reliably without seekmode -1.
• Open-GOP H.264 will sometimes produces corruption when seeking.

(NOTE this section does not appear in the latest documentation and may be obsolete)

• Interlaced H.264 is decoded in an odd way; each field gets its own full-height frame and the fieldrate is reported as the framerate, and furthermore one of the fields (odd or even) may "jump around". To get the correct behavior, you can try setting fpsnum and fpsden so that the framerate is halved (may or may not work). This issue is caused by libavcodec.

Video

• AVI, MKV, MP4, FLV: Frame accurate
• WMV: Frame accurate(?) but avformat seems to pick keyframes relatively far away
• OGM: Frame accurate(?)
• VOB, MPG: Seeking seems to be off by one or two frames now and then
• M2TS, TS: Seeking seems to be off a few frames here and there
  • As MP4 container supports MPEG2/4 video stream, when seeking is off, you can try copying the stream to MP4 container (maybe without audio.) With FFmpeg: ffmpeg -i file.m2ts -c:v copy -an file.mp4. You might have to specify -fflags +genpts before -i.
• Image files: Most formats can be opened if seekmode=-1 is set, no animation support

Audio

Seeking should be sample-accurate with most codecs in AVI, MKV, MP4 and FLV.

Decoding linearly will almost always give correct results, and forward-seeks from trimming should result in at most a few hundred samples of corruption.

Before FFMS2 can open a file, it must be indexed first so that keyframe/sample positions are known and seeking is easily accomplished. This is done automatically when using FFVideoSource or FFAudioSource, but if you want to you can invoke the indexing yourself by calling FFIndex, or by running ffmsindex.exe. By default the index is written to a file so it can be reused the next time you open the same file, but this behavior can be turned off if desired.

If you wonder why FFMS2 takes so long opening files, the indexing is the answer. If you want a progress report on the indexing, you can use the supplied ffmsindex.exe command line program.

FFmpegSource2

FFmpegSource2(string source [, int vtrack, int atrack ,
     bool cache, string cachefile, int fpsnum, int fpsden,
     int threads, string timecodes, int seekmode, bool overwrite,
     int width, int height, string resizer, string colorspace,
     int rffmode, int adjustdelay, bool utf8, string varprefix ] )

string  source = (required)

Path of the file to be opened.

int  vtrack = -1

The video track number to open, as seen by the relevant demuxer. Track numbers start from zero, and are guaranteed to be continous (i.e. there must be a track 1 if there is a track 0 and a track 2). vtrack=-1 (the default) means open the first video track. Note that this filter's idea about what track has what number may be completely different from what some other application might think.

int  atrack = -2

The audio track to open. atrack=-1 means select the first available track. atrack=-2 (the default) means audio is disabled.

bool  cache = true

If set to true (the default), this filter will first check if the cachefile contains a valid index, and if it does, that index will be used. If no index is found, all video tracks will be indexed, and the indexing data will be written to cachefile afterwards. If set to false, this filter will not look for an existing index file; instead all video tracks will be indexed when the script is opened, and the indexing data will be discarded after the script is closed; you will have to index again next time you open the script.

string  cachefile = source + ".ffindex"

The filename of the index file (where the indexing data is saved). Defaults to sourcefilename.ffindex.

int  fpsnum = -1

int  fpsden = 1

Controls the framerate of the output; used for VFR to CFR conversions. If fpsnum is less than or equal to zero (the default), the output will contain the same frames that the input did, and the frame rate reported to Avisynth will be set based on the input clip's average frame duration. If fpsnum is greater than zero, this filter will force a constant frame rate, expressed as a rational number where fpsnum is the numerator and fpsden is the denominator. This may naturally cause dropped or duplicated frames to achieve the desired frame rate, and the output is not guaranteed to have the same number of frames that the input did.

int  threads = -1

The number of decoding threads to request from libavcodec. Setting it to less than or equal to zero means it defaults to the number of logical CPUs as reported by Windows. Note that this setting might be completely ignored under a number of conditions; most commonly because a lot of decoders actually do not support multithreading. Default -1.

string  timecodes = ""

Filename to write Matroska v2 timecodes for the opened video track. If the file exists, it will be truncated and overwritten. Set to the empty string to disable timecodes writing (this is the default).

int  seekmode = 1

Controls how seeking is done. Mostly useful for getting uncooperative files to work. Valid modes are:

• -1: Linear access without rewind; i.e. will throw an error if each successive requested frame number isn't bigger than the last one. Only intended for opening images but might work on well with some obscure video format.
• 0: Linear access (i.e. if you request frame n without having requested all frames from 0 to n-1 in order first, all frames from 0 to n will have to be decoded before n can be delivered). The definition of slow, but should make some formats "usable".
• 1: Safe normal (the default). Bases seeking decisions on the keyframe positions reported by libavformat.
• 2: Unsafe normal. Same as mode 1, but no error will be thrown if the exact seek destination has to be guessed.
• 3: Aggressive. Seeks in the forward direction even if no closer keyframe is known to exist. Only useful for testing and containers where libavformat doesn't report keyframes properly.

bool  overwrite = false

If set to true, this filter will reindex the source file and overwrite the index file even if the index file already exists and is valid. Mostly useful for trackmask changes and testing.

int  width = -1

int  height = -1

Sets the resolution of the output video, in pixels. Setting either dimension to less than or equal to zero (which is the default) means the resolution of the first decoded video frame is used for that dimension. These parameters are mostly useful because FFMS2 supports video streams that change resolution mid-stream; since Avisynth does not, these parameters are used to set single resolution for the output.

string  resizer = "BICUBIC"

The resizing algorithm to use if rescaling the image is necessary. If the video uses subsampled chroma but your chosen output colorspace does not, the chosen resizer will be used to upscale the chroma planes, even if you did not request an image rescaling. The available choices are FAST_BILINEAR, BILINEAR, BICUBIC (default), X, POINT, AREA, BICUBLIN, GAUSS, SINC, LANCZOS and SPLINE. Note that SPLINE is completely different from Avisynth's builtin Spline resizers.

string  colorspace = ""

Convert the output from whatever it was to the given colorspace, which can be one of YV12, YUY2, RGB24 or RGB32. Setting this to an empty string (the default) means keeping the same colorspace as the input.

int  rffmode = 0

Controls how RFF flags in the video stream are treated (RFF = Repeat First Field; used in 3:2 pulldown^[1]). In other words, it's equivalent to the "field operation" mode switch in DVD2AVI/DGIndex. Valid modes are:

• 0: Ignore all flags (the default mode).
• 1: Honor all pulldown flags.
• 2: Equivalent to DVD2AVI's "force film" mode.

Note that using modes 1 or 2 will make FFMS2 throw an error if the video stream has no RFF flags at all. When using either of those modes, it will also make the output be assumed as CFR, disallow vertical scaling and disallow setting the output colorspace. FFPICT_TYPE will also not be set as the output is a combination of several frames. Other subtle behavior changes may also exist.

int  adjustdelay = -1

Controls how audio delay is handled, i.e. what happens if the first audio sample in the file doesn't have a timestamp of zero. The following arguments are valid:

• -3: No adjustment is made; the first decodable audio sample becomes the first sample in the output.
• -2: Samples are created (with silence) or discarded so that sample 0 in the decoded audio starts at time zero.
• -1: Samples are created (with silence) or discarded so that sample 0 in the decoded audio starts at the same time as frame 0 of the first video track. This is the default, and probably what most people want.
• Any integer >= 0: Same as -1, but adjust relative to the video track with the given track number instead. If the provided track number isn't a video track, an error is raised.

-2 obviously does the same thing as -1 if the first video frame of the first video track starts at time zero. In some containers this will always be the case, in others (most notably 188-byte MPEG TS) it will almost never happen.

bool  utf8 = false

If set to true, this filter will assume that the .avs script is encoded as UTF-8 and therefore interpret all filenames as UTF-8 encoded strings. This makes it possible to open files with odd filenames that otherwise would not be openable.

NOTE: You must make sure you save the .avs file without a BOM (byte-order marker) or Avisynth will refuse to open it. Notepad will write a BOM, so use something else.

You should also note that setting this parameter incorrectly will cause all file openings to fail unless your filenames are exclusively 7-bit ASCII compatible.

string  varprefix = ""

A string that is added as a prefix to all exported Avisynth variables. This makes it possible to differentiate between variables from different clips.

• Note, FFMS2 is a shorter name (added in v2.22) for FFmpegSource2. The syntax is the same for both.

Other Functions

For complete documentation see the FFMS2 GitHub page.

All variable names are prefixed by the varprefix argument to the respective FFVideoSource or FFAudioSource call that generated them.

NOTE: these exported variables are mostly Runtime variables, requiring ScriptClip etc to read them.

FFSAR_NUM, FFSAR_DEN, FFSAR

The playback aspect ratio specified by the container. FFSAR_NUM and FFSAR_DEN make up the rational number of the ratio; FFSAR is only provided for convenience and may not be set in case it cannot be calculated (i.e. if FFSAR_DEN is zero).

FFCROP_LEFT, FFCROP_RIGHT, FFCROP_TOP, FFCROP_BOTTOM

The on-playback cropping specified by the container.

FFCOLOR_SPACE

The colorimetry the input claims to be using. Only meaningful for YUV inputs. The source for this variable is a metadata flag that can arbitrarily be set or manipulated at will by incompetent users or buggy programs without changing the actual video content, so blindly trusting its correctness is not recommended.

The value is exported as a cryptic numerical constant that matches the values in the MPEG-2 specification. You can find the gory details in the FFMS2 API documentation, but the important ones are:

0: RGB (usually indicates the stream isn't actually YUV, but RGB flagged as YUV)
1: ITU-R Rec.709
2: Unknown or unspecified
5 and 6: ITU-R Rec.601

FFCOLOR_RANGE

The color range the input video claims to be using. Much like FFCOLOR_SPACE, the source for this variable is a metadata flag that can freely be set to arbitrary values, so trusting it blindly might not be a good idea.

Note that using SWScale() or the width/height/colorspace parameters to FFVideoSource may under some circumstances change the output color range.

0: Unknown/unspecified
1: Limited range (usually 16-235)
2: Full range (0-255)

FFPICT_TYPE

The picture type of the most recently requested frame as the ASCII number of the character listed below. Use Chr() to convert it to an actual letter in AviSynth. Use after_frame=true in AviSynth's conditional scripting for proper results. Only set when rffmode=0. The FFmpeg source definition of the characters:

I: Intra
P: Predicted
B: Bi-dir predicted
S: S(GMC)-VOP MPEG4
i: Switching Intra
p: Switching Predicted
b: FF_BI_TYPE (no good explanation available)
?: Unknown

FFVFR_TIME

The actual time of the source frame in milliseconds. Only set when no type of CFR conversion is being done (rffmode and fpsnum left at their defaults).

FFCHANNEL_LAYOUT

The audio channel layout of the audio stream. This is exported as a very cryptic integer that is constructed in the same way as the dwChannelMask property of the Windows WAVEFORMATEXTENSIBLE struct. If you don't know what a WAVEFORMATEXTENSIBLE is or what the dwChannelMask does, don't worry about it.

FFVAR_PREFIX

The variable prefix of the last called FFMS source function. Note that this is a global variable.

C Plugin

The C plugin supports the additional planar colorspaces in AviSynth 2.6. Also starting with r940+64 it removes the Matroska demuxer too. This means that the *only* demuxer this build of FFMS2 uses is LAVF. The test this time is whether VP8 (and maybe VP9) bearing WebM files can be used correctly with the LAVF demuxer.

• Discussion - Doom9 Thread

• Download - FFMS2 C-plugin r1293+111

Note: C-plugins must be loaded using LoadCPlugin.

• Doom9 Forum - FFmpegSource discussion.
• GitHub - Source code repository.