FFmpegSource Documentation

Loads video files without sucking

Compatibility - Video

AVI, MKV, MP4, FLV: Frame accurate
WMV: Frame accurate(?) but avformat seems to pick keyframes relatively far away
OGM: Messed up first frame and seeking produces smearing with seekmode=3, incredibly slow seeking without, remux to mkv or avi
VOB: No rff flags applied, frame accurate?
MPG: Seeking seems to be off by one or two frames now and then
TS: don't bother
Image files: most formats can be opened if seekmode=-1 is set

Compatibility - Audio

Should be sample accurate in all containers with audio cache

Usage

FFmpegSource(string source, int vtrack = -1, int atrack = -2, string timecodes, bool vcache = true, string vcachefile, string acachefile, string pp, int ppquality = 6, int threads = 1, int seekmode = 1)

Note that the audio cache will always be created when opening files with audio and that it will be huge since it stores all audio as raw signed 16/24/32 bit pcm, unsigned 8 bit pcm or as float, using flac to compress it is also possible to reduce the size by half.

FFAudioSource(string source, int atrack = -1, string acachefile, string ademuxedfile)

Experimental, may or may not be accurate enough for real usage.

FFPP(clip, string pp, int ppquality = 6)
Separate postprocessing which also seems to include a few simple deinterlacers

source: Source file.

atrack & vtrack: Track number as seen by the relevant demuxer, starts from 0, -1 means it will pick the first suitable track and -2 means it's disabled.

timecodes: File to output timecodes to, if the file exists it will be overwritten.

vcache: Write video 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.

vcachefile & acachefile: Specifies the file to store the index information or raw audio in, if nothing is specified (source).ffv(tracknumber)cache is used for video and (source).ffa(d if FFAudioSource is used)(tracknumber)cache for audio.

ademuxedfile: Specifies the file to store the demuxed audio stream in. Only used by FFAudioSource if the stream isn't matroska. If nothing is specified (source).ffasd(tracknumber)cache is used.

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

ppquality: The quality to use for the specified postprocessing. Valid values are 0-6 where 0 usually means that no actual processing is done.

threads: Sets the number of decoder threads used, ignored if the used decoder doesn't implement it.

seekmode: Force how seeking is handled, has no effect on matroska files which always use the equivalent of seekmode=1
-1: 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
0: linear access, the definition of slow but should make some formats "usable"
1: safe normal, bases seeking decisions on the reported keyframe positions
2: unsafe normal, same as 1 but no error will be thrown if the exact destination has to be guessed
3: 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

PP string format

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                   force quantizer
Usage:
[:

Compiling

zlib from http://www.zlib.net/

FFmpeg svn from http://ffmpeg.mplayerhq.hu/

Required FFmpeg Configuration: ./configure --enable-memalign-hack --enable-gpl --enable-swscale --enable-postproc

Suggested Additional Options: --enable-w32threads --disable-encoders --disable-muxers --enable-small --enable-libfaad --disable-debug

Note that --enable-w32threads is required for multithreaded decoding to work.

Changes

1.18
- Reverted error handling because it broke vc1
1.17
- Now sets the video SAR (if any) in the variables FFSAR, FFSAR_NUM and FFSAR_DEN when being invoked
- Changed error handling slightly in video decoding (most errors are still ignored)
- Fixed a bug where the last frame(s) wouldn't be returned properly in h264 with b-frames+pyramid
- Updated FFmpeg to rev 12685
1.16
- Added many new and missing matroska codec ids
- Added threads argument to set the number of decoding threads used
- Completely removed FLAC cache
- Updated FFmpeg to rev 12382
1.15
- Updated FFmpeg to rev 11518
1.14
- If the output colorspace is YV12 or YUY2 the width and height may be automatically cropped by one pixel to make it an even number
- FLAC cache is disabled because the static FLAC lib doesn't want to link
- Added the experimental FFAudioSource which doesn't need a huge uncompressed cache
- The plugin is now statically compiled
- Updated FFmpeg to rev 11413
1.13
- Now always sorts the output timecodes so native avc in mkv won't have out of order values
- Fixed the missing '# timecode format v2' line in saved timecode files
- Now properly handles video files where the output resolution isn't known until a frame has been decoded (seems to fix flv4)
- Now throws an error if the video decoder returns zero size video
- Added an avsi file for easy autoloading
- Updated libFLAC to 1.2.1
- Updated FFmpeg to rev 10671 + camtasia swapped colors fix
1.12
- Now caches the last fully decoded frame to increase the reliability of seekmode=-1 and possibly reduce seeking in other modes
- Video that needs to be converted to a suitable output format should now always have correct colors (was reversed in 1.11 and inconsistent in earlier versions)
- Added seekmode=-1 which is mostly useful for opening image files very carefully
- Now throws an error if the container is unseekable and seekmode=-1 isn't set
- Updated FFmpeg to rev 10492 + camtasia swapped colors fix
1.11
- Now officially uses the MIT license
- Much cleaner source
- Can be compiled without support for compressing the audio cache with FLAC
- Supports more audio formats in matroska
- RGB24 output no longer has swapped colors if the video is converted to it for output (there still seems to be some bugs lurking when conversion is done with libswscale)
- Fixed an access violation on close when no audio is opened (introduced in 1.10)
- Updated FFmpeg to rev 10423
1.10
- The audio cache compression level is now ignored if the source isn't 16bit and the raw format is used instead
- FLAC is now actually initialized properly so the cache actually works for files that aren't stereo (16bit limit still applies)
- Now uses proper callbacks for FLAC so it works with larger than 2GB files
- Doesn't (over)write the video cache with an empty one in certain cases when avformat is used for the source
1.9
- Added the possibility to compress the audio cache with FLAC (currently only works with 16bit audio)
- Added another planar YUV 4:2:0 format to the supported output formats (fixes certain mov files)
- Less memory is now allocated on the stack which makes av_find_stream_info() work for all files (fixes certain mov files)
- Updated FFmpeg to rev 10186
1.8
- Updated FFmpeg to rev 10141
1.7
- Updated FFmpeg
- Fixed error with mkv for codecs without codec private data and the first packet doesn't belong to them
1.6
- Fixed ac3 and other formats stored in mkv
- Skip unnecessary seeking when index information already exists (gif file opening only 3/4 broken now)
- Throws an error when the selected audio/video track has no frames/samples
1.5
- Fixed a bug that made avformat opened files only return audio if only the audio cache needed to be created
- Rejects more corrupt cache files
- Fixed crash when a 0 byte audio cache file is present
- Improved framerate guessing for avformat which now takes takes the duration of the first frame into account
- Fixed a bug introduced in 1.4 that would make the number of reported frames too high for files opened with avformat
- Fixed mpeg2 and probably some other formats stored in mkv
- Fixed issues with large mkv files and large audio cache files
- FFmpeg is now compiled with liba52 and faad2
1.4
- Uses the average framerate for mkv files
- Naming scheme of cache files changed to prevent confusion with the default names in files with multiple tracks of the same type
- Use mmx optimizations in swscaler when possible
- Now uses normal windows linebreaks in all files
- Removed FFAudioSource
- Merged FFVideoSource and FFAudioRefSource into FFmpegSource
- Added postprocessing with libpostproc in FFmpegSource and separately in FFPP
1.3
- Compiled against ffmpeg rev9620
- Added FFAudioRefSource
- Added FFAudioSource (has big issues)
- Renamed FFmpegSource to FFVideoSource
- Adjusted seeking in the forward direction to only be done if the requested frame is more than 10 frames away to reduce unnecessary seeking
- Now outputs the last frame properly when there are decoding delays
1.2
- Compiled against ffmpeg rev9451
- Somewhat cleaner source code
- Linear access in addition to a few other modes of seeking can now be forced
- Can now save the index information to a file which makes subsequent file opening fast
- No longer skips indexing for any format
1.1
- Skip indexing for avi
- Prefix all error messages with the plugin name
- Can write v2 timecodes to a file
- Fixed reported framerate