FFmpegSource

Revision as of 20:18, 16 April 2016

Abstract
Author	Myrsloik, et al.
Version	v2.22
Download	FFMS2 v2.22
Alt. Download	10bithack version
Documentation	User Manual
Category	Source filters
License	MIT / binary is GPLv3
Discussion	Doom9 Thread

Description

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.

Requirements

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)

Limitations

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

  AudioDub( FFVideoSource(X), FFAudioSource(X) )
will require two indexing passes. Apart from the time consumed this is harmless. To work around it open the audio first:
  A = FFAudioSource(X)
  V = FFVideoSource(X)
  AudioDub(V, A)
(FFmpegSource2 does this for you with a single function call) or use FFIndex, like so:
  FFIndex(X)
  AudioDub( FFVideoSource(X), FFAudioSource(X) ).

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.

Known Issues

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

Compatibility

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

Indexing and You

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.

Function Reference

For complete documentation see the FFMS2 GitHub page.

Filter	Description	Color format
FFIndex	Indexes a number of tracks in a given source file and writes the index file to disk, where it can be picked up and used by `FFVideoSource` or `FFAudioSource`.
FFAudioSource	Opens audio. Invokes indexing of all tracks if no valid index file is found, or if the requested track isn't present in the index.
FFVideoSource	Opens video. Will invoke indexing of all video tracks (but no audio tracks) if no valid index file is found.	RGB24, RGB32, YUY2, Y8, YV12, YV16, YV24, YV411
FFmpegSource2	A convenience function that combines the functionality of FFVideoSource and FFAudioSource.	RGB24, RGB32, YUY2, Y8, YV12, YV16, YV24, YV411
FFMS2	A shorter FFmpegSource2 alias, this feature was added in v2.22	RGB24, RGB32, YUY2, Y8, YV12, YV16, YV24, YV411
FFImageSource	A convenience alias for FFVideoSource, with the options set optimally for using it as an image reader. Disables caching and seeking for maximum compatiblity.	RGB24, RGB32, YUY2, Y8, YV12, YV16, YV24, YV411
FFSetLogLevel	Sets the FFmpeg logging level, i.e. how much diagnostic spam it prints to STDERR.
FFGetLogLevel	Returns the current log level, as an integer.
FFGetVersion	Returns the FFMS2 version, as a string.
Note: the following functions are provided by `FFMS2.avsi` and are not available unless that script has been imported or autoloaded.
FFFormatTime	A helper function used to format a time given in milliseconds into a h:mm:ss.ttt string. Used internally by FFInfo.
FFInfo	A helper function similar to Avisynth's internal Info() function; shows general information about the current frame.

Exported AviSynth variables

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 r1072+90

Note: C-plugins must be loaded using LoadCPlugin.

External Links

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

Back to External Filters ←

@@ Line 11: / Line 11: @@
 == Description ==
-Opens files using FFmpeg and (almost) nothing else. May be frame accurate on good days. The source is MIT licensed and can be obtained from the [http://github.com/FFMS/ffms2/ GitHub repository]. The precompiled binary is GPL3 licensed.
+Opens files using [http://www.ffmpeg.org/ FFmpeg] and nothing else. May be frame accurate on good days. The source is MIT licensed and can be obtained from the [http://github.com/FFMS/ffms2/ GitHub repository]. The precompiled binary is GPL3 licensed.
 <br>
 <br>
@@ Line 22: / Line 22: @@
 *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 <code>AudioDub(FFVideoSource(X), FFAudioSource(X))</code> will require two indexing passes.<br>Apart from the time consumed this is harmless. To work around it open the audio first: <code>A = FFAudioSource(X) V = FFVideoSource(X) AudioDub(V, A)</code> or use FFIndex(), like so: <code>FFIndex(X) AudioDub(FFVideoSource(X), FFAudioSource(X))</code>.
+*'''FFAudioSource''' will have to remake any index implicitly created by '''FFVideoSource''' and therefore code like
+<div {{ListItemContinue}} >
+&nbsp;&nbsp;<code>AudioDub( FFVideoSource(X), FFAudioSource(X) )</code> <br>
+will require two indexing passes. Apart from the time consumed this is harmless. To work around it open the audio first: <br>
+&nbsp;&nbsp;<code>A = FFAudioSource(X)</code><br>
+&nbsp;&nbsp;<code>V = FFVideoSource(X)</code><br>
+&nbsp;&nbsp;<code>AudioDub(V, A)</code> <br>
+('''FFmpegSource2''' does this for you with a single function call) or use '''FFIndex''', like so: <br>
+&nbsp;&nbsp;<code>FFIndex(X)</code><br>
+&nbsp;&nbsp;<code>AudioDub( FFVideoSource(X), FFAudioSource(X) )</code>.
+</div>
 *Interlaced H.264 mostly works these days, but seeking may occasionally result in corruption.
-*Transport Streams will not decode reliably without seekmode -1.
+*Transport Streams will not decode reliably without {{FuncArg|seekmode}} -1.
 *Open-GOP H.264 will sometimes produces corruption when seeking.
 <br>
 == Known Issues ==
-* 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 <tt>fpsnum</tt> and <tt>fpsden</tt> so that the framerate is halved (may or may not work). This issue is caused by libavcodec.
+(''NOTE this section does not appear in the [http://github.com/FFMS/ffms2/blob/master/doc/ffms2-avisynth.md 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 {{FuncArg|fpsnum}} and {{FuncArg|fpsden}} so that the framerate is halved (may or may not work). This issue is caused by libavcodec.
 <br>
 == Compatibility ==
@@ Line 43: / Line 54: @@
 ===Audio===
-Seeking should be sample-accurate with most codecs in AVI, MKV, MP4 and FLV with two notable exceptions, namely MP3 and AC3 where FFmpeg's decoders seem to be completely broken (with MP3 in particular you can feed the decoder the same encoded data three times in a row and get a different decoded result every time). Still, results should usually be "good enough" for most purposes.
+Seeking should be sample-accurate with most codecs in AVI, MKV, MP4 and FLV.
-Decoding linearly will almost always work correctly.
+Decoding linearly will almost always give correct results, and forward-seeks from trimming should result in at most a few hundred samples of corruption.
 <br>
 <br>
 == Indexing and You ==
-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 <tt>FFVideoSource()</tt> or <tt>FFAudioSource()</tt>, but if you want to you can invoke the indexing yourself by calling <tt>FFIndex()</tt>, or by running <tt>ffmsindex.exe</tt>. 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.
+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 <tt>ffmsindex.exe</tt>. 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 commandline program.
+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 <tt>ffmsindex.exe</tt> command line program.
 <br>
 <br>
@@ Line 70: / Line 81: @@
 }}
 {{PluginFilterRow|FFmpegSource|FFmpegSource2|
-A convenience function that combines the functionality of <tt>FFVideoSource</tt> and <tt>FFAudioSource</tt>.
+A convenience function that combines the functionality of '''FFVideoSource''' and '''FFAudioSource'''.
 | [[RGB24]], [[RGB32]], [[YUY2]], [[Y8]], [[YV12]], [[YV16]], [[YV24]], [[YV411]]
 }}
 {{PluginFilterRow|FFmpegSource|FFMS2|
-A shorter <tt>FFmpegSource2</tt> alias, this feature was added in v2.22
+A shorter '''FFmpegSource2''' alias, this feature was added in v2.22
 | [[RGB24]], [[RGB32]], [[YUY2]], [[Y8]], [[YV12]], [[YV16]], [[YV24]], [[YV411]]
 }}
 {{PluginFilterRow|FFmpegSource|FFImageSource|
-A convenience alias for <tt>FFVideoSource</tt>, with the options set optimally for using it as an image reader. Disables caching and seeking for maximum compatiblity.
+A convenience alias for '''FFVideoSource''', with the options set optimally for using it as an image reader. Disables caching and seeking for maximum compatiblity.
 | [[RGB24]], [[RGB32]], [[YUY2]], [[Y8]], [[YV12]], [[YV16]], [[YV24]], [[YV411]]
 }}
@@ Line 90: / Line 101: @@
 }}
 {{PluginFilterRow|FFmpegSource|FFGetVersion|
-Returns the FFMS2 version, as a string.
+Returns the '''FFMS2''' version, as a string.
 |
 }}
 {{PluginFilterRowNote|
-'''Note''': the following functions are provided by <tt>[http://raw.githubusercontent.com/FFMS/ffms2/master/etc/FFMS2.avsi FFMS2.avsi]</tt> and are not available unless that script has been imported or autoloaded.
+'''Note''': the following functions are provided by <tt>[http://raw.githubusercontent.com/FFMS/ffms2/master/etc/FFMS2.avsi FFMS2.avsi]</tt> and are not available unless that script has been imported or [[Plugins#Plugin_Autoload_and_Name_Precedence|autoloaded]].
 }}
 {{PluginFilterRow|FFmpegSource|FFFormatTime|
-A helper function used to format a time given in milliseconds into a h:mm:ss.ttt string. Used internally by <tt>FFInfo</tt>.
+A helper function used to format a time given in milliseconds into a h:mm:ss.ttt string. Used internally by '''FFInfo'''.
 |
 }}
@@ Line 108: / Line 119: @@
 == Exported AviSynth variables ==
-All variable names are prefixed by the <tt>varprefix</tt> argument to the respective <tt>FFVideoSource</tt> or <tt>FFAudioSource</tt> call that generated them.
+All variable names are prefixed by the {{FuncArg|varprefix}} argument to the respective '''FFVideoSource''' or '''FFAudioSource''' call that generated them.
+'''NOTE''': these exported variables are mostly [[Runtime_environment|Runtime variables]], requiring [[ScriptClip]] etc to read them.
 <br>
 <br>
@@ Line 128: / Line 141: @@
 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:
+<div {{BoxWidthIndent|56|1}} >
 : RGB (usually indicates the stream isn't actually YUV, but RGB flagged as YUV)
 : ITU-R Rec.709
 : Unknown or unspecified
 and 6: ITU-R Rec.601
-<br>
+</div>
 <code>'''FFCOLOR_RANGE'''</code>
 The color range the input video claims to be using. Much like <tt>FFCOLOR_SPACE</tt>, 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 <tt>SWScale</tt>() or the width/height/colorspace parameters to <tt>FFVideoSource</tt> may under some circumstances change the output color range.
+Note that using <tt>SWScale</tt>() or the width/height/colorspace parameters to '''FFVideoSource''' may under some circumstances change the output color range.
+<div {{BoxWidthIndent|56|1}} >
 : Unknown/unspecified
 : Limited range (usually 16-235)
 : Full range (0-255)
-<br>
+</div>
 <code>'''FFPICT_TYPE'''</code>
-The picture type of the most recently requested frame as the ASCII number of the character listed below. Use <tt>Chr</tt>() to convert it to an actual letter in AviSynth. Use <tt>after_frame=true</tt> in AviSynth's conditional scripting for proper results. Only set when <tt>rffmode=0</tt>. The FFmpeg source definition of the characters:
+The picture type of the most recently requested frame as the ASCII number of the character listed below. Use <tt>Chr</tt>() to convert it to an actual letter in AviSynth. Use {{FuncArg|after_frame}}<tt>=true</tt> in AviSynth's conditional scripting for proper results. Only set when {{FuncArg|rffmode}}<tt>=0</tt>. The FFmpeg source definition of the characters:
+<div {{BoxWidthIndent|56|1}} >
   I: Intra
   P: Predicted
@@ Line 156: / Line 169: @@
   b: FF_BI_TYPE (no good explanation available)
   ?: Unknown
-<br>
+</div>
 <code>'''FFVFR_TIME'''</code>
-The actual time of the source frame in milliseconds. Only set when no type of CFR conversion is being done (<tt>rffmode</tt> and <tt>fpsnum</tt> left at their defaults).
+The actual time of the source frame in milliseconds. Only set when no type of CFR conversion is being done ({{FuncArg|rffmode}} and {{FuncArg|fpsnum}} left at their defaults).
-FFCHANNEL_LAYOUT
+<br>
+<br>
+<code>'''FFCHANNEL_LAYOUT'''</code>
 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 <tt>dwChannelMask</tt> property of the Windows <tt>WAVEFORMATEXTENSIBLE</tt> struct. If you don't know what a <tt>WAVEFORMATEXTENSIBLE</tt> is or what the <tt>dwChannelMask</tt> does, don't worry about it.

FFmpegSource

Revision as of 20:18, 16 April 2016

Contents

Description

Requirements

Limitations

Known Issues

Compatibility

Video

Audio

Indexing and You

Function Reference

Exported AviSynth variables

C Plugin

External Links

Views

Personal tools

Navigation

community

in other languages

Search

Tools