forked from mia/Aegisub
347 lines
16 KiB
HTML
347 lines
16 KiB
HTML
<html>
|
|
<head>
|
|
<title>
|
|
FFmpegSource2 Documentation
|
|
</title>
|
|
</head>
|
|
<body>
|
|
<h1>FFmpegSource2 Documentation</h1>
|
|
<p>
|
|
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://svn.aegisub.net/trunk/aegisub/FFmpegSource2/". The precompiled binary is GPL licensed. If you are religious you may consider this the second coming.
|
|
</p>
|
|
|
|
<h2>Known issues</h2>
|
|
<ul>
|
|
<li>FFAudioSource() will have to remake any index implicitly created by FFVideoSource() and therefore code like
|
|
<pre>
|
|
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
|
|
<pre>
|
|
A = FFAudioSource(X)
|
|
V = FFVideoSource(X)
|
|
AudioDub(V, A)
|
|
</pre>
|
|
or use FFIndex().
|
|
<pre>
|
|
FFIndex(X)
|
|
AudioDub(FFVideoSource(X), FFAudioSource(X))
|
|
</pre>
|
|
</li>
|
|
<li>FFIndex() will silently ignore fatal decoding errors when indexing. This means that indexing a specific track may have failed even if FFIndex() succeeds.</li>
|
|
<li>Requires <a href='http://haali.cs.msu.ru/mkv/'>Haali's Media Splitter</a> if ogm or mpeg ps/ts is to be opened.</li>
|
|
<li>Avi files with NVOPs (sometimes occurs in xvid and such) will desync when these frames are encountered. Remux to mkv/mp4 before opening to solve it for now.</li>
|
|
<li>There are still some issues with FFAudioSource but it should be good enough for actual use in many cases now.</li>
|
|
</ul>
|
|
|
|
<h2>Compatibility - Video</h2>
|
|
<ul>
|
|
<li>AVI, MKV, MP4, FLV: Frame accurate</li>
|
|
<li>WMV: Frame accurate(?) but avformat seems to pick keyframes relatively far away</li>
|
|
<li>OGM: Frame accurate(?)</li>
|
|
<li>VOB: No rff flags applied</li>
|
|
<li>MPG: Seeking seems to be off by one or two frames now and then</li>
|
|
<li>M2TS, TS: Seeking seems to be off a few frames here and there</li>
|
|
<li>Image files: Most formats can be opened if seekmode=-1 is set, no animation support</li>
|
|
</ul>
|
|
|
|
<h2>Compatibility - Audio</h2>
|
|
<ul>
|
|
<li>All formats are written to separate wave64 files</li>
|
|
<li>No wave64 reader is provided</li>
|
|
</ul>
|
|
|
|
<h2>Usage</h2>
|
|
<p>
|
|
<b>FFIndex(string source, string cachefile = source + ".ffindex", int indexmask = -1, int dumpmask = 0, string audiofile = source, bool overwrite = false)</b><br />
|
|
Used to invoke indexing separately and to write audio tracks to disk as wave64 files
|
|
</p>
|
|
|
|
<p>
|
|
<b>FFVideoSource(string source, int track, bool cache = true, string cachefile = source + ".ffindex", int fpsnum = -1, int fpsden = 1, string pp, int threads = -1, string timecodes, int seekmode = 1)</b><br />
|
|
Opens video, will invoke indexing with the defaults if no preexisting index is found
|
|
</p>
|
|
|
|
<p>
|
|
<b>FFAudioSource(string source, int track, bool cache = true, string cachefile = source + ".ffindex")</b><br />
|
|
Opens audio, <b>if an index already exists it needs to contain a suitable audio index or empty audio will be returned</b>, will invoke indexing with the defaults if no preexisting index is found
|
|
</p>
|
|
|
|
<p>
|
|
<b>FFPP(clip, string pp)</b><br />
|
|
Separate postprocessing which also seems to include a few simple deinterlacers
|
|
</p>
|
|
|
|
<p>
|
|
<b>SWScale(clip, width = -1, height = -1, resizer = "BICUBIC", colorspace = "")</b><br />
|
|
Separate postprocessing which also seems to include a few simple deinterlacers
|
|
</p>
|
|
|
|
<b>FFSetLogLevel(int Level)</b><br />
|
|
Sets the log FFmpeg logging level, defaults to quiet (-8) and the FFmpeg default is 16, all different values can be found in avutil/log.h
|
|
</p>
|
|
|
|
<b>FFGetLogLevel()</b><br />
|
|
Returns the current level of logging as an int
|
|
</p>
|
|
|
|
<p>
|
|
<b>source:</b>
|
|
Source file.
|
|
</p>
|
|
|
|
<p>
|
|
<b>indexmask & dumpmask:</b>
|
|
Which audio tracks to index/write to disk. Dumping a track also implies indexing since the same work has to be done anyway. It is a binary mask meaning that 7 corresponds to writing tracks 1-3. Non-audio tracks are ignored. -1 writes all tracks.
|
|
</p>
|
|
|
|
<p>
|
|
<b>audiofile:</b>
|
|
The base name to use for the decoded audio. Track number and delay is appended.
|
|
</p>
|
|
|
|
<p>
|
|
<b>overwrite:</b>
|
|
Forces reindexing even if a valid index already exists. May be useful for trackmask changes or testing.
|
|
</p>
|
|
|
|
<p>
|
|
<b>track:</b>
|
|
Track number as seen by the relevant demuxer, starts from 0, -1 means it will pick the first suitable track.
|
|
</p>
|
|
|
|
<p>
|
|
<b>fpsnum & fpsden:</b>
|
|
For VFR -> CFR conversion. Setting fpsnum <= 0 means a 1:1 relation with the encoded frames.
|
|
</p>
|
|
|
|
<p>
|
|
<b>timecodes:</b>
|
|
File to output timecodes to, if the file exists it will be overwritten.
|
|
</p>
|
|
|
|
<p>
|
|
<b>cache:</b>
|
|
Write indexing information to a file for later use. This setting does not control if the video index is loaded which it always is if it exists.
|
|
</p>
|
|
|
|
<p>
|
|
<b>cachefile</b>
|
|
Where to write the cache information.
|
|
</p>
|
|
|
|
<p>
|
|
<b>pp:</b>
|
|
See the table below for a full description, an empty string means no processing. It is recommended to avoid the autoq option since it's currently unknown what effect it will have on the processing.
|
|
</p>
|
|
|
|
<p>
|
|
<b>threads:</b>
|
|
Sets the number of decoder threads used. Defaults to the number of cpus reported by windows. Ignored by lavc if the used decoder doesn't implement it.
|
|
</p>
|
|
|
|
<p>
|
|
<b>seekmode:</b>
|
|
Force how seeking is handled, has no effect on matroska files which always use the equivalent of seekmode=1<br />
|
|
<b>-1:</b> linear access without rewind, 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<br />
|
|
<b>0:</b> linear access, the definition of slow but should make some formats "usable"<br />
|
|
<b>1:</b> safe normal, bases seeking decisions on the reported keyframe positions<br />
|
|
<b>2:</b> unsafe normal, same as 1 but no error will be thrown if the exact destination has to be guessed<br />
|
|
<b>3:</b> aggressive, seek in the forward direction even if no closer keyframe is known to exist, only useful for testing and containers where avformat doesn't report keyframes properly
|
|
</p>
|
|
|
|
<p>
|
|
<b>width & height:</b>
|
|
Width and height to resize to. Value below or equal to 0 is the same as specifying the input dimensions.
|
|
</p>
|
|
|
|
<p>
|
|
<b>resizer:</b>
|
|
Selects the resizer used for resampling the chroma planes and normal resizing. The available methods are: FAST_BILINEAR, BILINEAR, BICUBIC, X, POINT, AREA, BICUBLIN, GAUSS, SINC, LANCZOS and SPLINE.
|
|
</p>
|
|
|
|
<p>
|
|
<b>colorspace:</b>
|
|
The colorspace to convert to. The names are YV12, YUY2, RGB24, RGB32 and the empty string for same as input.
|
|
</p>
|
|
|
|
<h2>Exported Avisynth variables</h2>
|
|
<p>
|
|
<b>FFSAR_NUM, FFSAR_DEN, FFSAR:</b>
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
<b>FFCROP_LEFT, FFCROP_RIGHT, FFCROP_TOP, FFCROP_BOTTOM:</b>
|
|
The on playback cropping specified by the container.
|
|
</p>
|
|
|
|
<p>
|
|
<b>FFPICT_TYPE:</b>
|
|
The picture type of the most recently requested frame. Use after_frame=true in Avisynth's conditional scripting for proper results. The FFmpeg source definition of the numbers:
|
|
<pre>
|
|
FF_I_TYPE 1 ///< Intra
|
|
FF_P_TYPE 2 ///< Predicted
|
|
FF_B_TYPE 3 ///< Bi-dir predicted
|
|
FF_S_TYPE 4 ///< S(GMC)-VOP MPEG4
|
|
FF_SI_TYPE 5 ///< Switching Intra
|
|
FF_SP_TYPE 6 ///< Switching Predicted
|
|
FF_BI_TYPE 7
|
|
</pre>
|
|
</p>
|
|
|
|
|
|
<h2>PP string format</h2>
|
|
<pre>
|
|
Available postprocessing filters:
|
|
Filters Options
|
|
short long name short long option Description
|
|
* * 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 -> more deblocking
|
|
2. flatness threshold: default=39, lower -> more deblocking
|
|
the h & 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. <= 2. <= 3. larger -> stronger filtering
|
|
fq forceQuant <quantizer> force quantizer
|
|
Usage:
|
|
<filterName>[:<option>[:<option>...]][[,|/][-]<filterName>[:<option>...]]...
|
|
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
|
|
</pre>
|
|
|
|
<h2>Compiling</h2>
|
|
|
|
<p><b>zlib</b> from http://www.zlib.net/</p>
|
|
|
|
<p><b>FFmpeg svn</b> from http://ffmpeg.mplayerhq.hu/</p>
|
|
|
|
<p><b>pthreads</b> only required for FFmpeg-mt compiles</p>
|
|
|
|
<p><b>Required FFmpeg Configuration:</b>
|
|
./configure --enable-memalign-hack --enable-gpl --enable-postproc
|
|
|
|
<p><b>Suggested Additional Options:</b>
|
|
--enable-w32threads --disable-encoders --disable-muxers --disable-network --disable-debug --enable-libfaad --disable-decoder=aac</p>
|
|
|
|
<p>
|
|
Note that --enable-w32threads or --enable-pthreads is required for multithreaded decoding to work. For FFmpeg-mt only --enable-pthreads will work.
|
|
</p>
|
|
|
|
<h2>Changes</h2>
|
|
<ul>
|
|
<li>2.00 beta 9<ul>
|
|
<li>Dumping audio now actually implies indexing too in FFIndex, previously nothing would be done if the index mask wasn't set as well</li>
|
|
<li>FFAudioSource will now first load the index and returns the first indexed audio track with track=-1, if no audio tracks are indexed or the chosen track isn't indexed the equivalent of FFIndex(indexmask = -1, overwrite = cache) is executed first</li>
|
|
<li>Codec lookup for non-lavf opened files now to a large part use the same lookup tables as lavf, this should improve the number of properly recognized codecs</li>
|
|
<li>Now uses the average framerate for files opened with Haali's splitters, before it was always reported as 30 fps</li>
|
|
<li>Implemented audio decoding using Haali's splitters, FFAudioSource now works on ts, ps and ogm</li>
|
|
<li>Can now be compiled with ICL 10.1 (probably other versions too)</li>
|
|
<li>How indexing works has been split internally so the track numbers and types are reported, this makes it possible to create an interactive GUI or ask which audio tracks are to be indexed</li>
|
|
<li>Now has stricter index checking to detect when different FFmpeg versions were used to create an index of the same version</li>
|
|
<li>Fixed memory leaks when audio sources were destroyed and when errors happened during indexing</li>
|
|
<li>Fixed access violations occurring when a track of the wrong type was specified or didn't exist in FFVideoSource and FFAudioSource</li>
|
|
<li>Fixed access violations occurring when unindexed or empty audio tracks in matroska/lavf read files were opened</li>
|
|
<li>Less type conversion/signedness warnings</li>
|
|
<li>When audio track dumping is performed a custom callback can now be supplied to name the tracks</li>
|
|
<li>The audio track delay is now exposed in the API in the same way as video tracks</li>
|
|
<li>A big type and argument name cleanup in the API, many things have been renamed to be clearer and ffms.h should be completely C friendly now</li>
|
|
<li>Removed FFNoLog and replaced it with FFSetLogLevel and FFGetLogLevel, the default logging is now also set to quiet, the magical numbers to supply it can be found in avutil/log.h</li>
|
|
<li>Updated FFmpeg to rev 18972 (now with faad2 again by popular demand, updated to GCC 4.4.0 for compiling all libraries)</li>
|
|
</ul></li>
|
|
|
|
<li>2.00 beta 8<ul>
|
|
<li>Improved the audio decoding quality a lot by adding a simple cache, no more seeking is done when playing a file linearly and pops and other artifacts should be much more uncommon</li>
|
|
<li>Fixed a bug that would most of the time drop frame 0 and sometimes frame 1</li>
|
|
<li>Updated Haali's matroska parser code to the latest version</li>
|
|
<li>Updated FFmpeg to rev 18774</li>
|
|
</ul></li>
|
|
|
|
|
|
<li>2.00 beta 7<ul>
|
|
<li>Using ffms2 as a library no longer requires an installed pixfmt.h from libavutil, it is however still required to compile ffms2 and the avisynth plugin part</li>
|
|
<li>Fix a crash bug at the end of files with b-frames in beta 6 caused by uninitialized null packets</li>
|
|
<li>Includes TheFluff's wrapper function for 1.21 style syntax</li>
|
|
<li>Added a simple regression test application to the source</li>
|
|
<li>Removed a few pointless functions from the API</li>
|
|
<li>Fixed the accessing of codecprivate data with Haali's splitters</li>
|
|
<li>Timecode output should be fixed to include decimals AND not be in scientific format</li>
|
|
<li>Fixed a memory leak when using Haali's splitters</li>
|
|
<li>Updated FFmpeg to rev 18717</li>
|
|
</ul></li>
|
|
|
|
<li>2.00 beta 6<ul>
|
|
<li>Haali's splitters have been improved for video and now have audio dumping during indexing implemented</li>
|
|
<li>SeekMode=1 has improved logic which will make it go back and decode more frames if necessary to figure out where it is, in theory SeekMode=0 should now be mostly obsolete</li>
|
|
<li>Haali's splitters are now used to open mpeg ps and ogm in addition to mpeg ts, only ogm is frame accurate at this time</li>
|
|
<li>Negative timecodes and other bugs caused by an integer overflow fixed</li>
|
|
<li>Updated FFmpeg to rev 18442 (once again compilation fixes for the changes)</li>
|
|
</ul></li>
|
|
|
|
<li>2.00 beta 5<ul>
|
|
<li>FFMSIndex should now print the progress properly when another application reads its output</li>
|
|
<li>Added missing variables and explanations to the manual</li>
|
|
<li>Can now directly be compiled as a library for use in *nix</li>
|
|
<li>Fixed the missing decimals in saved timecode files</li>
|
|
</ul></li>
|
|
|
|
<li>2.00 beta 4<ul>
|
|
<li>Added the function FFNoLog which suppresses all messages from ffmpeg</li>
|
|
<li>Experimental new TS parsing using Haali's splitter (with bugs)</li>
|
|
<li>Everything is now compiled with VS2008 and GCC 4.3.2</li>
|
|
<li>Updated FFmpeg to rev 16383 (no libfaad2 this time)</li>
|
|
</ul></li>
|
|
|
|
<li>2.00 beta 3<ul>
|
|
<li>Compiled with libfaad2 again (has anyone seen a single aac file lavc can open right now?)</li>
|
|
<li>More API changes (and even more are likely to come)</li>
|
|
<li>Several access violations and memory leaks on opening and indexing files fixed</li>
|
|
<li>Added a VFR to CFR mode</li>
|
|
<li>Readded FFAudioSource support for other containers (glitches still present now and then but no separate raw cache is required and possibly less buggy)</li>
|
|
<li>Renamed the dll to FFMS2.dll, FFMS2 is now the official short name of the project</li>
|
|
<li>Updated FFmpeg to rev 15522</li>
|
|
</ul></li>
|
|
|
|
<li>2.00 beta 2<ul>
|
|
<li>More API changes (and more are likely to come)</li>
|
|
<li>Includes a simple CLI indexing application</li>
|
|
<li>FFIndex now takes a few more arguments</li>
|
|
<li>Readded FFAudioSource (only matroska supported for now)</li>
|
|
<li>Updated FFmpeg to rev 15396</li>
|
|
</ul></li>
|
|
|
|
<li>2.00 beta 1<ul>
|
|
<li>Can now be used as a stand alone library for making indices and retrieving frames</li>
|
|
<li>Rewrote most things</li>
|
|
<li>Updated FFmpeg to rev 15301</li>
|
|
</ul></li>
|
|
|
|
</ul>
|
|
|
|
</body>
|
|
</html>
|