FFmpegSource

From Avisynth wiki
(Difference between revisions)
Jump to: navigation, search
m (1 revision)
m (update to coincide with v2.20)
Line 1: Line 1:
−
Opens files using FFmpeg and nothing else. May be frame accurate on good days. The source is MIT licensed and can be obtained from [http://code.google.com/p/ffmpegsource/source/checkout code.google.com/p/ffmpegsource/source/checkout]. The precompiled binary is GPL3 licensed.  
+
{{FilterCat|External_filters|Source_filters|Plugins}}
 +
{{Filter3
 +
| {{Author/Myrsloik}}
 +
| v2.20
 +
| [http://github.com/FFMS/ffms2/releases FFMS2 v2.20]
 +
| Source filters
 +
| [http://opensource.org/licenses/MIT MIT] / binary is [http://www.gnu.org/licenses/gpl.txt GPLv3]
 +
|6=[http://forum.doom9.org/showthread.php?t=127037 Doom9 Thread]}}
 +
<br>
 +
== 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 http://github.com/FFMS/ffms2/. The precompiled binary is GPL3 licensed.
 +
<br>
  
−
==Source for this page==
+
== Requirements ==
−
This page is a copy of the [http://ffmpegsource.googlecode.com/svn/trunk/doc/ffms2-avisynth.html original FFMS2 documentation]. It may or may not be outdated. If you want to be sure you're reading the latest version, use the original documentation.
+
:- AviSynth 2.5.8 Alpha5] or later
 +
:- Supported color formats: [[RGB24]], [[RGB32]], [[YUY2]], [[YV12]]
 +
<br>
 +
== Limitations ==
 +
*Requires [http://haali.su/mkv/ Haali's Media Splitter] if you want to seek in OGM or MPEG PS/TS. Trying to do non-linear access in those containers without it will end in tears.
  
−
==Limitations==
+
*Haali's splitter requires transport streams to but cut at packed boundaries. Use [http://forum.doom9.org/showthread.php?t=125447 TsRemux] to fix the stream if you get an error message complaining about this.
  
−
* Requires [http://haali.su/mkv/ Haali's Media Splitter] if you want to seek in OGM or MPEG PS/TS. Trying to do non-linear access in those containers without it will end in tears.
+
*Because of LAVF's demuxer, most raw streams (such as elementary h264 and other mpeg video streams) will fail to work properly.
−
* Haali's splitter requires transport streams to be cut at packet boundaries. Use [http://forum.doom9.org/showthread.php?t=125447 TsRemux] to fix the stream before trying to open it.
+
−
* Because of LAVF's demuxer most raw streams will fail to work properly such as elementary h264 and other mpeg video streams.
+
−
* FFAudioSource() will have to remake any index implicitly created by FFVideoSource() and therefore code like
+
  
−
AudioDub(FFVideoSource(X), FFAudioSource(X))
+
*FFAudioSource() will have to remake any index implicitly created by FFVideoSource() and therefore code like
−
 
+
:<pre style="width: 50%">AudioDub(FFVideoSource(X), FFAudioSource(X))</pre>
−
will require two indexing passes. Apart from the time consumed this is harmless. To work around it open the audio first
+
will require two indexing passes. Apart from the time consumed this is harmless. To work around it open the audio first:
−
 
+
:<pre style="width: 50%">A = FFAudioSource(X) V = FFVideoSource(X) AudioDub(V, A)</pre>
−
A = FFAudioSource(X)
+
or use FFIndex(), like so:  
−
V = FFVideoSource(X)
+
:<pre style="width: 50%">FFIndex(X) AudioDub(FFVideoSource(X), FFAudioSource(X))</pre>
−
AudioDub(V, A)
+
<br>
−
 
+
== Known Issues ==
−
or use FFIndex():
+
−
FFIndex(X)  
+
−
AudioDub(FFVideoSource(X), FFAudioSource(X))
+
−
 
+
−
==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.
 
* 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.
  
 
* Decoding some M2TS files using Haali's splitter will cause massive blocking and other corruption issues. You can work around the issue either by remuxing the file to MKV (using GDSMux (make sure you untick "minimize output file size" in the Global settings tab) or eac3to), or (if you will be doing linear decoding only) by setting <tt>demuxer="lavf"</tt> in <tt>FFIndex</tt> and using <tt>seekmode=0</tt> with <tt>FFVideoSource</tt>. The cause of this issue is unknown but being investigated.
 
* Decoding some M2TS files using Haali's splitter will cause massive blocking and other corruption issues. You can work around the issue either by remuxing the file to MKV (using GDSMux (make sure you untick "minimize output file size" in the Global settings tab) or eac3to), or (if you will be doing linear decoding only) by setting <tt>demuxer="lavf"</tt> in <tt>FFIndex</tt> and using <tt>seekmode=0</tt> with <tt>FFVideoSource</tt>. The cause of this issue is unknown but being investigated.
 +
<br>
 +
== Compatibility ==
  
−
==Compatibility==
 
 
===Video===
 
===Video===
−
* AVI, MKV, MP4, FLV: Frame accurate
+
 
−
* WMV: Frame accurate(?) but avformat seems to pick keyframes relatively far away
+
*AVI, MKV, MP4, FLV: Frame accurate
−
* OGM: Frame accurate(?)
+
*WMV: Frame accurate(?) but avformat seems to pick keyframes relatively far away
−
* VOB, MPG: Seeking seems to be off by one or two frames now and then
+
*OGM: Frame accurate(?)
−
* M2TS, TS: Seeking seems to be off a few frames here and there
+
*VOB, MPG: Seeking seems to be off by one or two frames now and then
−
* Image files: Most formats can be opened if seekmode=-1 is set, no animation support
+
*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===
 
===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 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.
  
 
Decoding linearly will almost always work correctly.
 
Decoding linearly will almost always work correctly.
−
 
+
<br>
−
== Indexing and You==
+
<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 <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.
  
−
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> 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 ffmsindex.exe commandline program.
−
 
+
<br>
−
== Function reference==
+
<br>
−
 
+
== Function Reference ==
−
===FFIndex===
+
{{PluginFilterTable2}}
−
 
+
{{PluginFilterRow|FFmpegSource|FFIndex|
−
'''FFIndex(string source, string cachefile = source + ".ffindex", int indexmask = -1, int dumpmask = 0, string audiofile = "%sourcefile%.%trackzn%.w64", int errorhandling = 3,  bool overwrite = false, bool utf8 = false, string demuxer = "default")'''
+
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 <tt>FFVideoSource</tt> or <tt>FFAudioSource</tt>.
−
 
+
|
−
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 <tt>FFVideoSource</tt> or <tt>FFAudioSource</tt>. Normally you do not need to call this function manually; it's invoked automatically if necessary by <tt>FFVideoSource</tt>/<tt>FFAudioSource</tt>. It does, however, give you more control over how indexing is done and it can also dump audio tracks to WAVE64 files while indexing is in progress.
+
}}  
−
 
+
{{PluginFilterRow|FFmpegSource|FFAudioSource|
−
Note that this function returns an integer, not a clip (since it doesn't open video, nor audio). The return value isn't particularly interesting, but for the record it's 0 if the index file already exists (and is valid) and overwrite was not enabled, 1 if the index file was created and no previous index existed, and 2 if the index file was created by overwriting an existing, valid index file.
+
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.  
−
 
+
|
−
====Arguments====
+
}}
−
{{Par|source|string|filename}}
+
{{PluginFilterRow|FFmpegSource|FFVideoSource|
−
The source file to index.
+
−
 
+
−
{{Par|cachefile|string|source + ".ffindex"}}
+
−
The filename of the index file (where the indexing data is saved). Defaults to <tt>sourcefilename.ffindex</tt>.
+
−
 
+
−
{{Par|indexmask|int|-1}}
+
−
A binary mask representing what audio tracks should be indexed (all video tracks are always indexed; you have no choice in the matter). The mask is constructed by bitshifting 1 left by the track number; if multiple tracks are desired, bitwise OR each value so created together to get the full mask. In other words, the mask is a bit field where each bit is a track number (the least significant bit is track number 0). Since Avisynth doesn't have any bitwise operators at all, constructing the mask inside an Avisynth script is a rather annoying task.
+
−
 
+
−
Since the mask works like it does, and FFMS2 is designed to run on a machine that uses two's complement integers, -1 means index all tracks (the default) and 0 means index none.<br />
+
−
Note that FFMS2's idea about what track has what number may be completely different from what any other application might think.
+
−
 
+
−
{{Par|dumpmask|int|0}}
+
−
The same as indexmask, but the tracks flagged by this mask are dumped to disk as decompressed Wave64 files. This mask overrides indexmask if set to nonzero (more specifically, they are bitwise OR'ed together), since dumping a track indexes it at the same time.
+
−
 
+
−
{{Par|audiofile|string|"%sourcefile%.%trackzn%.w64"}}
+
−
A string representing a filename template that determines where the audio tracks set to be dumped by the <tt>dumpmask</tt> will be written. You can use a number of variables here; make sure you include a track number variable if you're dumping multiple tracks, or you'll get really weird results when FFMS2 tries to write multiple tracks to the same file. Available variables:
+
−
 
+
−
:'''%sourcefile%''' - same as the source argument, i.e. the file the audio is decoded from
+
−
:'''%trackn%''' - the track number
+
−
:'''%trackzn%''' - the track number, zero padded to two digits
+
−
:'''%samplerate%''' - sample rate in Hertz
+
−
:'''%channels%''' - number of channels
+
−
:'''%bps%''' - bits per sample
+
−
:'''%delay%''' - delay, or more exactly the first timestamp encountered in the audio stream
+
−
 
+
−
 
+
−
{{Par|errorhandling|int|3}}
+
−
Controls what happens if an audio decoding error is encountered during indexing. Possible values are:
+
−
 
+
−
:'''0:''' Raise an error and abort indexing. No index file is written.
+
−
:'''1:''' Clear the affected track (effectively making it silent) and continue.
+
−
:'''2:''' Stop indexing the track but keep all the index entries so far, effectively ending the track where the error occured.
+
−
:'''3:''' Pretend it's raining and continue anyway. This is the default; if you encounter odd noises in the audio, try mode 0 instead and see if it's FFMS2's fault.
+
−
 
+
−
{{Par|overwrite|bool|false}}
+
−
If set to true, <tt>FFIndex()</tt> 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.
+
−
 
+
−
{{Par|utf8|bool|false}}
+
−
If set to true, FFMS 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 funny filenames that otherwise would not be openable. You only need to set this parameter on the first FFMS2 function you call in a script; subsequent uses will have no further effect.<br />
+
−
'''NOTE:''' You must make sure you save the file without a BOM (byte-order marker) or Avisynth will refuse to open it. Notepad will write a BOM, so use something else.<br />
+
−
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.
+
−
 
+
−
{{Par|demuxer|string|"default"}}
+
−
Forces FFMS to use a given demuxer, namely one of:
+
−
 
+
−
:'''default''': probe for the best source module, i.e. choose automatically. This is the default (duh).
+
−
:'''lavf''': use libavformat.
+
−
:'''matroska''': use Haali's Matroska parser. Obviously only works for Matroska and WebM files.
+
−
:'''haalimpeg''': use Haali's DirectShow MPEG TS/PS parser. Only works if Haali Media Splitter is installed and only on MPEG TS/PS files (.ts/.m2ts/.mpg/.mpeg).
+
−
:'''haaliogg:''' use Haali's DirectShow Ogg parser. As above, only works if Haali Media Splitter is installed, and only on Ogg files (.ogg/.ogm).
+
−
 
+
−
You should only use this parameter if you know exactly what you're doing and exactly why you want to force another demuxer.
+
−
 
+
−
 
+
−
===FFVideoSource===
+
−
'''FFVideoSource(string source, int track = -1, bool cache = true, string cachefile = source + ".ffindex", int fpsnum = -1, int fpsden = 1, string pp = "", int threads = -1, string timecodes = "", int seekmode = 1, int rffmode = 0, int width = -1, int height = -1, string resizer = "BICUBIC", string colorspace = "", bool utf8 = false, string varprefix = "")'''
+
−
 
+
 
Opens video. Will invoke indexing of all video tracks (but no audio tracks) if no valid index file is found.
 
Opens video. Will invoke indexing of all video tracks (but no audio tracks) if no valid index file is found.
−
 
+
| [[RGB24]], [[RGB32]], [[YUY2]], [[YV12]]
−
====Arguments====
+
}}
−
{{Par|source|string|filename}}
+
{{PluginFilterRow|FFmpegSource|SWScale|
−
The source file to open.
+
An image resizing and colorspace conversion filter. Does nothing special; it's almost always a better idea to just use Avisynth's builtins instead.
−
 
+
| [[RGB24]], [[RGB32]], [[YUY2]], [[YV12]]
−
{{Par|track|int|-1}}
+
}}
−
The video track number to open, as seen by the relevant demuxer. Track numbers start from zero, and are guaranteed to be countinous (i.e. there must be a track 1 if there is a track 0 and a track 2). -1 means open the first video track. Note that FFMS2's idea about what track has what number may (or may not) be completely different from what some other application might think. Trying to open an audio track with <tt>FFVideoSource</tt> will naturally fail.</dd>
+
{{PluginFilterRow|FFmpegSource|FFSetLogLevel|
−
 
+
Sets the FFmpeg logging level, i.e. how much diagnostic spam it prints to STDERR.
−
{{Par|cache|bool|true}}
+
|
−
If set to true (the default), <tt>FFVideoSource</tt> will first check if the <tt>cachefile</tt> 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 <tt>cachefile</tt> afterwards. If set to false, <tt>FFVideoSource</tt> 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.
+
}}
−
 
+
{{PluginFilterRow|FFmpegSource|FFGetLogLevel|
−
{{Par|cachefile|string|source + ".ffindex"}}
+
Returns the current log level, as an integer.
−
The filename of the index file (where the indexing data is saved). Defaults to <tt>sourcefilename.ffindex</tt>. Note that if you didn't change this parameter from its default value and <tt>FFVideoSource</tt> encounters an index file that doesn't seem to match the file it's trying to open, it will automatically reindex and then overwrite the old index file. On the other hand, if you <em>do</em> change it, <tt>FFVideoSource</tt> will assume you have your reasons and throw an error instead if the index doesn't match the file.
+
|
−
 
+
}}
−
{{Par|fpsnum|int|-1}}
+
{{PluginFilterRow|FFmpegSource|FFGetVersion|
−
{{Par|fpsden|int|1}}
+
Returns the FFMS2 version, as a string.
−
Forces a given (constant) framerate, expressed as a rational number where <tt>fpsnum</tt> is the numerator and <tt>fpsden</tt> is the denominator. Used for VFR to CFR conversion, as it will make <tt>FFVideoSource</tt> drop or duplicate frames to convert VFR to CFR if <tt>fpsnum</tt> is greater than 0. Setting <tt>fpsnum</tt> to a number less than or equal to zero means no frames will be dropped or duplicated.
+
|
−
 
+
}}
−
{{Par|pp|string|"" [DEPRECATED]}}
+
{{PluginFilterRowNote|
−
Sets a chain of postprocessing filters, expressed as a string (see the "PP string format" section below). Mostly useful to do quantizer-based deblocking/deringing, but can also do simple deinterlacing and a few other odd things.
+
'''Note''': the following functions are provided by <tt>FFMS2.avsi</tt> and are not available unless that script has been imported or autoloaded.
−
 
+
}}
−
{{Par|threads|int|-1}}
+
{{PluginFilterRow|FFmpegSource|FFmpegSource2|
−
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 CPU's reported by Windows. Note that this setting might be completely ignored by libavcodec under a number of conditions; most commonly because a lot of decoders actually do not support multithreading. You may also have a libavcodec without threading support compiled in at all.
+
A convenience function that combines the functionality of <tt>FFVideoSource</tt> and <tt>FFAudioSource</tt>.
−
 
+
| [[RGB24]], [[RGB32]], [[YUY2]], [[YV12]]
−
{{Par|timecodes|string|""}}
+
}}
−
Filename to write Matroska v2 timecodes for the opened video track to. If the file exists, it will be truncated and overwritten. Set to the empty string to disable timecodes writing (this is the default).
+
{{PluginFilterRow|FFmpegSource|FFImageSource|
−
 
+
−
{{ParR|seekmode|int|1|1-3}}
+
−
Controls how seeking is done. Mostly useful for getting uncooperative files to work. Only has an effect on files opened with the libavformat demuxer; on other files the equivalent of mode 1 is always used. 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 <tt>n</tt> without having requested frames 0 to <tt>n-1</tt> in order first, all frames from 0 to <tt>n</tt> will have to be decoded before <tt>n</tt> can be delivered). The definition of slow, but should make some formats "usable".
+
−
: '''1:''' Safe normal. 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.
+
−
 
+
−
{{ParR|rffmode|int|0|0-2}}
+
−
Controls how RFF flags in the video stream are treated; 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 <tt>FFVideoSource</tt> 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. <tt>FFPICT_TYPE</tt> will also not be set as the output is a combination of several frames. Other subtle behavior changes may also exist.<br />
+
−
Also note that "force film" is mostly useless and only here for completeness' sake, since if your source really is safe to force film on, using mode 0 will have the exact same effect while being considerably more efficient.
+
−
 
+
−
{{Par|width|int|-1}}
+
−
{{Par|height|int|-1}}
+
−
Sets the resolution of the output video, in pixels. Setting either dimension to less than or equal to zero 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.
+
−
 
+
−
{{Par|resizer|string|"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 <tt>FAST_BILINEAR</tt>, <tt>BILINEAR</tt>, <tt>BICUBIC</tt> (default), <tt>X</tt>, <tt>POINT</tt>, <tt>AREA</tt>, <tt>BICUBLIN</tt>, <tt>GAUSS</tt>, <tt>SINC</tt>, <tt>LANCZOS</tt> and <tt>SPLINE</tt>. Note that <tt>SPLINE</tt> is completely different from Avisynth's builtin Spline resizers.
+
−
 
+
−
{{Par|colorspace|string|""}}
+
−
Convert the output from whatever it was to the given colorspace, which can be one of <tt>YV12</tt>, <tt>YUY2</tt>, <tt>RGB24</tt> or <tt>RGB32</tt>. Setting this to an empty string (the default) means keeping the same colorspace as the input.
+
−
 
+
−
{{Par|utf8|bool|false}}
+
−
Does the same thing as in <tt>FFIndex()</tt>; see that function for details.
+
−
 
+
−
{{Par|varprefix|string|""}}
+
−
A string that is added as a prefix to all exported Avisynth variables. This makes it possible to differentiate between variables from different clips. For convenience the last used FFMS function in a script sets the global variable <tt>FFVAR_PREFIX</tt> to its own variable prefix so that <tt>FFInfo()</tt> can default to it.
+
−
 
+
−
 
+
−
===FFAudioSource===
+
−
'''FFAudioSource(string source, int track = -1, bool cache = true, string cachefile = source + ".ffindex", int adjustdelay = -1, bool utf8 = false, string varprefix = "")'''
+
−
 
+
−
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.
+
−
 
+
−
====Arguments====
+
−
 
+
−
Are exactly the same as to <tt>FFVideoSource</tt>, with one exception:
+
−
 
+
−
{{Par|adjustdelay|int|-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 &gt;= 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.
+
−
 
+
−
===FFmpegSource2===
+
−
'''FFmpegSource2(string source, int vtrack = -1, int atrack = -2, bool cache = true,    string cachefile = source + ".ffindex", int fpsnum = -1, int fpsden = 1,    string pp = "", int threads = -1, string timecodes = "", int seekmode = 1,    bool overwrite = false, int width = -1, int height = -1,    string resizer = "BICUBIC", string colorspace = "", int rffmode = 0,    int adjustdelay = -1, bool utf8 = false, string varprefix = "")'''
+
−
 
+
−
 
+
−
A convenience function that combines the functionality of <tt>FFVideoSource</tt> and <tt>FFAudioSource</tt>. The arguments do the same thing as in <tt>FFVideoSource</tt> and <tt>FFAudioSource</tt>; see those functions for details. <tt>vtrack</tt> and <tt>atrack</tt> are the video and audio track to open, respectively; setting <tt>atrack</tt> &lt;= -2 means audio is disabled.
+
−
 
+
−
'''Note:''' this function is provided by <tt>FFMS2.avsi</tt> and is not available unless that script has been imported or autoloaded.
+
−
 
+
−
===FFImageSource===
+
−
'''FFImageSource(string source, int width = -1, int height = -1, string resizer = "BICUBIC", string colorspace = "", bool utf8 = false)'''
+
−
 
+
 
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 <tt>FFVideoSource</tt>, with the options set optimally for using it as an image reader. Disables caching and seeking for maximum compatiblity.
−
 
+
| [[RGB24]], [[RGB32]], [[YUY2]], [[YV12]]
−
'''Note:''' this function is provided by <tt>FFMS2.avsi</tt> and is not available unless that script has been imported or autoloaded.
+
}}
−
 
+
{{PluginFilterRow|FFmpegSource|FFFormatTime|
−
===FFPP [DEPRECATED]===
+
−
'''FFPP(clip, string pp)'''
+
−
 
+
−
A postprocessing filter. See the <tt>pp</tt> argument to <tt>FFVideoSource</tt> and the "PP string format" section below. In general, using <tt>FFVideoSource</tt>'s <tt>pp</tt> argument instead of this function is recommended (if possible), since if it's used there it has access to video quantizers and can adapt better to the video, particularly when doing deblocking/deringing.
+
−
 
+
−
Postprocessing support is deprecated and will be removed in a future version of FFMS2.
+
−
 
+
−
===SWScale===
+
−
'''SWScale(clip, int width = -1, int height = -1, string resizer = "BICUBIC", string colorspace = "")'''
+
−
 
+
−
An image resizing and colorspace conversion filter. Does nothing special; it's almost always a better idea to just use Avisynth's builtins instead. Might potentially be useful for testing or odd experiments just because it does things in a different way from Avisynth. See the relevant arguments to <tt>FFVideoSource</tt> for details.
+
−
 
+
−
===FFFormatTime===
+
−
'''FFFormatTime(int ms)'''
+
−
 
+
 
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 <tt>FFInfo</tt>.
 +
|
 +
}}
 +
{{PluginFilterRow|FFmpegSource|FFInfo|
 +
A helper function similar to Avisynth's internal [[Info|Info()]] function; shows general information about the current frame.
 +
|
 +
}}
 +
|}
 +
<br>
 +
== 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.
 +
<br>
 +
<br>
 +
<code>'''FFSAR_NUM, FFSAR_DEN, FFSAR'''</code>
  
−
'''Note:''' this function is provided by <tt>FFMS2.avsi</tt> and is not available unless that script has been imported or autoloaded.
+
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).
 +
<br>
 +
<br>
  
−
===FFInfo===
+
<code>'''FFCROP_LEFT, FFCROP_RIGHT, FFCROP_TOP, FFCROP_BOTTOM'''</code>
−
'''FFInfo(clip c, bool framenum = true, bool frametype = true, bool cfrtime = true, bool vfrtime = true, string varprefix = "")'''
+
  
−
A helper function similar to Avisynth's internal <tt>Info()</tt> function; shows general information about the current frame. Note that not all values are exported in all source modes, so some information may not always be shown. The arguments can be used to disable the drawing of certain information if so desired. Use the varprefix argument to determine which clip you want information about.
+
The on-playback cropping specified by the container.
 +
<br>
 +
<br>
  
−
'''Note:''' this function is provided by <tt>FFMS2.avsi</tt> and is not available unless that script has been imported or autoloaded.
+
<code>'''FFCOLOR_SPACE'''</code>
  
−
===FFSetLogLevel===
+
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.
−
'''FFSetLogLevel(int Level = -8)'''
+
  
−
Sets the FFmpeg logging level, i.e. how much diagnostic spam it prints to STDERR. Since most applications that open Avisynth scripts do not provide a way to display things printed to STDERR, and since it's rather hard to make any sense of the printed messages unless you're quite familiar with FFmpeg internals, the usefulness of this function is rather limited for end users. It's mostly intended for debugging. Defaults to quiet (no messages printed); a list of meaningful values can be found in <tt>libavutil/log.h</tt>.
+
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:
  
−
===FFGetLogLevel===
+
0: RGB (usually indicates the stream isn't actually YUV, but RGB flagged as YUV)
−
'''FFGetLogLevel()'''
+
1: ITU-R Rec.709
 +
2: Unknown or unspecified
 +
5 and 6: ITU-R Rec.601
 +
<br>
 +
<code>'''FFCOLOR_RANGE'''</code>
  
−
Returns the current log level, as an integer.
+
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.
  
−
==Exported Avisynth variables==
+
Note that using SWScale() or the width/height/colorspace parameters to FFVideoSource may under some circumstances change the output color range.
  
−
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.
+
0: Unknown/unspecified
 +
1: Limited range (usually 16-235)
 +
2: Full range (0-255)
 +
<br>
 +
<code>'''FFPICT_TYPE'''</code>
  
−
'''FFSAR_NUM, FFSAR_DEN, FFSAR:'''
+
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:
−
The playback aspect ratio specified by the container. FFSAR_NUM and FFSAR_DEN make up the rational number of the ratio and FFSAR is only provided for convenience and may not be set in case it cannot be calculated (FFSAR_DEN=0).
+
  
−
'''FFCROP_LEFT, FFCROP_RIGHT, FFCROP_TOP, FFCROP_BOTTOM:'''
+
I: Intra
−
The on playback cropping specified by the container.
+
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
 +
<br>
 +
<code>'''FFVFR_TIME'''</code>
  
−
'''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.<br />
 
−
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:<br />
 
−
:'''0:''' RGB (usually indicates the stream isn't actually YUV, but RGB flagged as YUV)<br />
 
−
:'''1:''' ITU-R Rec.709<br />
 
−
:'''2:''' Unknown or unspecified<br />
 
−
:'''5 and 6:''' ITU-R Rec.601<br />
 
−
 
−
'''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.<br />
 
−
Note that using SWScale() or the width/height/colorspace parameters to FFVideoSource may under some circumstances change the output color range.<br />
 
−
:'''0:''' Unknown/unspecified<br />
 
−
:'''1:''' Limited-range (usually 16-235)<br />
 
−
:'''2:''' Full-range (0-255)<br />
 
−
 
−
'''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).
 
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
  
−
'''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 <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.
−
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 the <tt>WAVEFORMATEXTENSIBLE</tt> is or what the <tt>dwChannelMask</tt> does, don't worry about it.
+
<br>
 +
<br>
 +
<code>'''FFVAR_PREFIX'''</code>
  
−
'''FFVAR_PREFIX:'''
 
 
The variable prefix of the last called FFMS source function. Note that this is a global variable.
 
The variable prefix of the last called FFMS source function. Note that this is a global variable.
 +
<br>
 +
<br>
 +
== External Links ==
 +
*[http://forum.doom9.org/showthread.php?t=127037 Doom9 Forum] - FFmpegSource discussion.
 +
*[http://github.com/FFMS/ffms2 GitHub] - Source code repository.
  
−
==PP string format==
+
<br>
−
 
+
<br>
−
Available postprocessing filters:
+
<br>
−
{| class="wikitable" style="margin:auto; background:#FFFFFF;"
+
-----------------------------------------------
−
|-
+
'''Back to [[External_filters#Source_Filters|External Filters]] &larr;'''
−
!colspan="2"| Filters!!colspan="2" |Options!!rowspan="2"|Description
+
−
|-
+
−
! short !! long name !! short !!width="100"| long option
+
−
|-
+
−
| *  || *              ||a ||  autoq          || CPU power dependent enabler
+
−
|-
+
−
|    ||                ||c ||  chrom          || chrominance filtering enabled
+
−
|-
+
−
|    ||                ||y ||  nochrom        || chrominance filtering disabled
+
−
|-
+
−
|    ||                ||n ||  noluma        || luma filtering disabled
+
−
|-
+
−
| hb || hdeblock      || ||(2 threshold)      || horizontal deblocking filter; 1. difference factor: default=32, higher -&gt; more deblocking; 2. flatness threshold: default=39, lower -&gt; more deblocking the h &amp; v deblocking filters share these so you can't set different thresholds for h / v
+
−
|-
+
−
| vb || vdeblock      || ||(2 threshold)      || vertical deblocking filter
+
−
|-
+
−
| ha || hadeblock      || ||(2 threshold)      || horizontal deblocking filter
+
−
|-
+
−
| va || vadeblock      || ||(2 threshold)      || vertical deblocking filter
+
−
|-
+
−
| h1 || x1hdeblock    || ||                  || experimental h deblock filter 1
+
−
|-
+
−
| v1 || x1vdeblock    || ||                  || experimental v deblock filter 1
+
−
|-
+
−
| dr || dering        || ||                  || deringing filter
+
−
|-
+
−
| al || autolevels    || ||                  || automatic brightness / contrast
+
−
|-
+
−
| f  || fullyrange    || ||                  || stretch luminance to (0..255)
+
−
|-
+
−
| lb || linblenddeint  || ||                  || linear blend deinterlacer
+
−
|-
+
−
| li || linipoldeint  || ||                  || linear interpolating deinterlace
+
−
|-
+
−
| ci || cubicipoldeint || ||                  || cubic interpolating deinterlacer
+
−
|-
+
−
| md || mediandeint    || ||                  || median deinterlacer
+
−
|-
+
−
| fd || ffmpegdeint    || ||                  || ffmpeg deinterlacer
+
−
|-
+
−
| l5 || lowpass5      || ||                  || FIR lowpass deinterlacer
+
−
|-
+
−
| de || default        || ||                  || hb:a,vb:a,dr:a
+
−
|-
+
−
| fa || fast          || ||                  || h1:a,v1:a,dr:a
+
−
|-
+
−
| ac ||                || ||                  || ha:a:128:7,va:a,dr:a
+
−
|-
+
−
| tn || tmpnoise      || ||(3 threshold)      || temporal noise reducer 1. &lt;= 2. &lt;= 3. larger -&gt; stronger filtering
+
−
|-
+
−
| fq || forceQuant    || ||&lt;quantizer&gt;  || force quantizer
+
−
|-
+
−
|}
+
−
 
+
−
===Usage===
+
−
 
+
−
<nowiki><filterName>[:<option>[:<option>...]][[,|/][-]<filterName>[:<option>...]]... </nowiki>
+
−
 
+
−
long form example:
+
−
vdeblock:autoq/hdeblock:autoq/linblenddeint    default,-vdeblock
+
−
short form example:
+
−
vb:a/hb:a/lb                                  de,-vb
+
−
more examples:
+
−
tn:64:128:256
+
−
 
+
−
[[Category:Plugins]]
+

Revision as of 17:09, 19 July 2014

Abstract
Author Myrsloik
Version v2.20
Download FFMS2 v2.20
Category Source filters
License MIT / binary is GPLv3
Discussion Doom9 Thread


Contents

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 http://github.com/FFMS/ffms2/. The precompiled binary is GPL3 licensed.


Requirements

- AviSynth 2.5.8 Alpha5] or later
- Supported color formats: RGB24, RGB32, YUY2, YV12


Limitations

  • Requires Haali's Media Splitter if you want to seek in OGM or MPEG PS/TS. Trying to do non-linear access in those containers without it will end in tears.
  • Haali's splitter requires transport streams to but cut at packed boundaries. Use TsRemux to fix the stream if you get an error message complaining about this.
  • 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)

or use FFIndex(), like so: 

FFIndex(X) AudioDub(FFVideoSource(X), FFAudioSource(X))


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 fpsnum and fpsden so that the framerate is halved (may or may not work). This issue is caused by libavcodec.
  • Decoding some M2TS files using Haali's splitter will cause massive blocking and other corruption issues. You can work around the issue either by remuxing the file to MKV (using GDSMux (make sure you untick "minimize output file size" in the Global settings tab) or eac3to), or (if you will be doing linear decoding only) by setting demuxer="lavf" in FFIndex and using seekmode=0 with FFVideoSource. The cause of this issue is unknown but being investigated.


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

Decoding linearly will almost always work correctly.

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

Function Reference

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, YV12
SWScale

An image resizing and colorspace conversion filter. Does nothing special; it's almost always a better idea to just use Avisynth's builtins instead.

RGB24, RGB32, YUY2, YV12
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.

FFmpegSource2

A convenience function that combines the functionality of FFVideoSource and FFAudioSource.

RGB24, RGB32, YUY2, YV12
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, YV12
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.

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.

External Links




Back to External Filters ←

Retrieved from "http://avisynth.nl/index.php?title=FFmpegSource&oldid=3584"
Personal tools