# FFmpegSource2 User Manual

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. The precompiled binary is GPL3 licensed. If you are religious you may consider this the second coming.

## Donate

Donate if you like this software. Collecting weird clips from the internet and making them play takes more time than you'd think.

## Limitations

- Requires Haali's Media Splitter if ogm or mpeg ps/ts is to be opened.
- Haali's splitter requires transport streams to be cut at packet boundaries. Use 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))

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

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

## Known issues

- There will appear decoding artifacts on h264 in transport streams.
- FFIndex() will silently ignore fatal decoding errors when indexing. This means that indexing a specific track may have failed even if FFIndex() succeeds.

## Compatibility

- 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

## Functions in FFMS2.dll

FFIndex(string source, string cachefile = source + ".ffindex", int indexmask = -1, int dumpmask = 0, string audiofile = "%sourcefile%.%trackzn%.w64", int errorhandling = 3, bool overwrite = false)
Used to invoke indexing separately with a few additional options and to write audio tracks to disk as wave64 files. It can be useful to use to avoid remaking the index twice or if some audio tracks are unsupported/broken and cannot be indexed properly.

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, int rffmode = 0, int width = -1, int height = -1, string resizer = "BICUBIC", string colorspace = "")
Opens video, will invoke indexing of all video tracks if no usable index is found.

FFAudioSource(string source, int track, bool cache = true, string cachefile = source + ".ffindex", int adjustdelay = -1)
Opens audio, will invoke indexing of all tracks if no index exists or the requested track is not present in the index.

FFPP(clip, string pp)
Separate postprocessing which also seems to include a few simple deinterlacers. Use the pp argument in FFVideoSource whenever possible as it will also have access to the video quantizers and thus adapt better to the video.

SWScale(clip, int width = -1, int height = -1, string resizer = "BICUBIC", string colorspace = "")
A resizing/colorspace conversion filter that does nothing special at all. May be useful in some cases just because it does not do things exactly like avisynth.

FFSetLogLevel(int Level = -8)
Sets the log FFmpeg logging level. Defaults to quiet (-8) and the FFmpeg default is 16. All possible different values can be found in avutil/log.h.

FFGetLogLevel()
Returns the current level of logging as an int.

## Functions in FFMS2.avsi

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)
Approximates the syntax later versions of the 1.x series. Can be convenient to use with atrack=-1 to load both audio and video at the same time. Note that the adjustdelay parameter may need to be specified for the expected behavior if a video track other than the first is selected.

FFImageSource(string source, int width = -1, int height = -1, string resizer = "BICUBIC", string colorspace = "")
Another alias for FFVideoSource with the options set optimally for using it as an image reader. Disables caching and seeking for maximum compatiblity.

FFFormatTime(int ms)
A helper function to format time given in milliseconds into a h:mm:ss.ttt string.

FFInfo(clip c, bool framenum = true, bool frametype = true, bool cfrtime = true, bool vfrtime = true)
A helper function to show general information about the current frame. Note that not all values are exported in all source modes and will therefore not always be shown.

## Function arguments

source: Source file.

indexmask & dumpmask: 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.

audiofile: The filename to use for dumped audio tracks. Make sure to include a track number variable to avoid multiple file access errors. The variables are case sensitive. The available variables are:
%sourcefile% - same as the source argument, the file the audio is decoded from
%trackn% - the track number
%trackzn% - the track number zero padded to 2 digits
%samplerate% - self explanatory
%channels% - self explanatory
%bps% - bits per sample
%delay% - delay, or more exactly the first timestamp encountered in the audio stream

overwrite: Forces reindexing even if a valid index already exists. May be useful for trackmask changes or testing.

track: Track number as seen by the relevant demuxer. Starts from 0, -1 means it will pick the first suitable track. This may however NOT be the first video/audio track found if it is not indexed but a later one is.

fpsnum & fpsden: For VFR -> CFR conversion. Setting fpsnum <= 0 means a 1:1 relation with the encoded frames.

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

cache: Write indexing information to a file for later use. This setting controls both loading of existing indices and the writing of new ones.

cachefile Where to write the cache information.

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.

threads: Sets the number of decoder threads used. Defaults to the number of logical cpus reported by windows. Ignored by lavc if the used decoder doesn't implement it.

seekmode: Control how seeking is handled, has no effect on matroska or haali splitter opened 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

rffmode: Controls how RFF flags in the video stream is treated.
0: Ignore all flags
1: Honor all pulldown flags
2: Equivalent to force film
Note that setting rffmode > 0 will throw an error if the video stream has no RFF flags at all. When engaged it will also make the output be assumed as CFR, disallow vertical scaling and setting the output colorspace. FFPICT_TYPE will also not be set as the output is a combination of several frames. Other subtle behavior changes may also exist.

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.

errorhandling: Controls what happens when an audio decoding error is encountered.
0: Abort indexing
1: Clear the affected track and continue
2: Stop indexing the track but keep all the index entries so far
3: Continue anyway

adjustdelay: Try to apply a suitable delay to the audio track. -1 is the default mode and should produce correct results in most cases
-3: No delay adjustment
-2: Adjust relative to time 0
-1: Adjust relative to the first video track, adjusts the delay relative to time 0 if no video track is present
Any valid track number: Adjust relative to the specified track

## Exported Avisynth variables

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 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: The on playback cropping specified by the container.

FFCOLOR_SPACE: The output colorimetry. Matches the values used by ColorMatrix() as input.

FFCOLOR_RANGE: The range used by the output.
0: Unknown/unspecified
1: Limited-range
2: Full-range

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

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