# FFmpegSource Documentation

Opens files using ffmpeg and nothing else. May be frame accurate on good days. The source is BSD licensed and can be obtained from https://spaceboyz.net/svn/aegisub/trunk/FFmpegSource. The precompiled binary is GPL licensed.

## 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
- M2TS, TS: Linear access only (seekmode=-1)
- Image files: most formats can be opened if seekmode=-1 is set

## Compatibility - Audio

- Should be sample accurate in all containers with audio cache
- Can produce very bad distortions when caching is not used for certain formats like aac

## 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 acachefile2)

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

SWScale(clip, width = -1, height = -1, resizer = "BICUBIC", colorspace = "")
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 & acachefile2: 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. The second audio cache file is only required/created when not opening matroska files.

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. Defaults to the number of cpus reported by windows. Ignored by lavc 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

width & height: Width and height to resize to. Value below or equal to 0 is the same as specifying the input dimensions.

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

colorspace: The colorspace to convert to. The names are YV12, YUY2, RGB24, RGB32 and the empty string for same as input.

## 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:
    [:[:...]][[,|/][-][:...]]...
    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

## 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.19
  - Now automatically detects the number of cpus and uses it as the default for the number of decoding threads
  - Added SWScale filter which can perform colorspace conversions and resizing and has many different resizers to choose from
  - Now exports the stored cropping values in mkv files in the variables FFCROP_LEFT, FFCROP_RIGHT, FFCROP_TOP and FFCROP_BOTTOM
  - Updated FFmpeg to rev 13572
- 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