AviSynth FilterSDK

Note: May not fully up-to-date

AviSynth external Filter SDK is a package for developers to create your own filters (plugins and console applications) for AviSynth.

The package consists of:

  • these documentation text files (in HTML or Wiki format);

  • the header file 'avisynth.h' (recent version) with all declarations to include in plugin source code;

  • several plugin and console application source codes;

  • some extra files in 'Extra' folder.

Necessary software

You must have some necessary software.

Writing a plugin

We will start by writing some simple plugins to show you the basics.

Processing video

  • InvertNeg produces a photo-negative of the input clip.

  • SimpleSample has some very simple examples covering development of a filter that draws a variable sized square, in the middle of the screen. It does so for all color formats.

One thing not covered in SimpleSample, is how to change frame size in a filter.

Processing audio

  • xxx

Also have a look at Getting started with Audio.

Runtime functions

See Non-clip sample how to create runtime AviSynth functions.

Source filters

  • GradientMask creates a simple Gradient. The example explains a few things how source filters work.

Speeding up your plugin using assembler

todo: having SIMD intrinsic widespread this topic is a bit outdated: You can also browse various topic on Assembler Optimizing.

Making dual plugins

This old topic once was about making dual 2.5 and 2.6 plugins. Now in 2020 it is still important to give support earlier (now it's the 2.6) interface which is used by earlier Avisynth+ and classic Avisynth 2.6.

One of the features of AviSynth+ is that 2.6 plugins (plugins compiled with plugin api v6) can still be used in AviSynth+. Avisynth+ evolved from classic Avisynth 2.6 so this is no wonder. There are differences though since AviSynth+ introduced high bit depth video handling and there came new support functions. AviSynth+'s avisynth.h is responsible for the compatibility, functions which did not exist in classic Avisynth (such as BitsPerComponent() for VideoInfo) return a compatible value (8 in this case since Avisynth 2.6 handled only 8 bit videos)

Beginning with the v8 (v8.1 for C interface due to early bugs) interface - frame property support - dual interfaces became important again. Plugins have to be able to detect the availability of v8 interface and behave accordingly.

(todo: They are described here).

Writing console applications that access AviSynth

When writing console applications (commandline programs) it is possible to access AviSynth in two ways.

The first one is to use the VfW api (using the AVIFile library) like is done in avs2avi (see [1] or [2]), avs2yuv (using the C api, or using the C++ api), or avs2wav for example. See also here to get you going.

The second one is to call AviSynth directly like is done in avs2pipe for example (it uses the C api). It's a tool to output y4m video or wav audio to stdout. The way to do this is importing avisynth.dll via loadlibrary() and getprocaddress(). Then creating a scriptenvironment and importing a script using invoke(). At that point you will have a clip from which you can call getframe() to access the video and getaudio() to access the audio.

For C api clients see the examples (ffmpeg, x265, x264, avs2yuv) here: Introducing to C API.

Below are some examples that have a script as input and raw video or audio as output:

  • avs2yuv reads a script and outputs raw video.

  • avs2pcm reads a script and outputs raw audio.

Compiling plugins and console applications that access AviSynth

How to compile plugins and console applications that access AviSynth is described here.

Debugging plugins and console applications that access AviSynth

How to debug plugins and console applications that access AviSynth is described here.

AviSynth and its plugin api's

AviSynth exists as an instance of the ScriptEnvironment class, that implements the IScriptEnvironment interface. The IScriptEnvironment interface is defined in avisynth.h (and avisynth_c.h) and it is the only way for plugins and external applications to communicate with AviSynth. A pointer to ScriptEnvironment object is passed along to all plugins, so that they can use AviSynth facilities. Plugins are forbidden from storing this pointer. AviSynth creates one ScriptEnvironment object when Windows attempts to use AviSynth to open a script via AVIFile API.

When ScriptEnvironment is created, it checks for CPU extensions (to provide this information to filters that are able to use CPU extensions), sets up memory limits for itself and performs pre-scanning of all plugins.

AviSynth has the capability to load third-party libraries that include their own video and audio filters. It comes with two language interfaces (or plugin api's):

  • C++ API (through avisynth.h) - The classes and miscellaneous constants are described in here.

  • C API (through avisynth_c.h) - The classes and miscellaneous constants are described in here.

The built-in filters use the C++ API. This Filter SDK (or Source Development Kit) describes how to create plugins using both interfaces.

Although not included in AviSynth itself, several people wrote other language interfaces in Delphi, Purebasic, NET and Java. They can be found here. (comment from 2025: update needed)

...

There are several different Colorspaces in AviSynth. See more information about Color Spaces and Working With Images.

What's new in the 2.6 api

  • C++ API (AVISYNTH_INTERFACE_VERSION = 6):

    • Plugin api v3 and older contained baked code meaning code that is "baked" into all and every plugin instead being called from avisynth.dll. Starting from 2.6 the version 2.5 plugins are supported directly (with current baked code; meaning that plugins compiled for 2.5 can be loaded when using 2.6) and all the baked code from 2.6+ plugins is removed and the plugins are still source compatible. Note that the baked code is moved to interface.cpp, where also the structure AVS_Linkage is defined.

    • The IScriptEnvironment interface has several new members:

      • ApplyMessage writes text on a frame.

      • DeleteScriptEnvironment provides a method to delete the ScriptEnvironment which is created with CreateScriptEnvironment.

      • GetAVSLinkage returns the AVSLinkage.

      • GetVarDef can be used to access AviSynth variables. It will not throw an error if the variable doesn't exist.

    • Avisynth+ header still uses integer for things that are memory sizes (e.g. pitch) This only affects x64 versions. (Although Avisynth 2.6 defined them as size_t, AviSynth+ developers have left it as integer. AviSynth 2.6 had never reached a widespread x64 version so AviSynth+ variant "won")

    • New colorformats are added: Y8, YV411, YV16 and YV24. AviSynth+ extended these formats with 10, 12, 14, 16 bit integer and 32 bit floating point formats. Aside from 411, all other 4:2:0, 4:2:2 and 4:4:4 formats are available at higher bit depths. AviSynth+ introduced planar RGB formats for all the above mentioned bit depths. RGB48 and RGB64 is available as the 16 bit variants of RGB24 and RGB32 packed RGB formats. Alpha plane option was added for YUV (YUVA) and planar RGB formats (Planar RGBA).

    • VideoInfo has several new constants and functions (the ones relating to the new colorformats, the chroma placement constants, GetPlaneHeightSubsampling, GetPlaneWidthSubsampling). And in AviSynth+: BitsPerComponent, NumComponents, ComponentSize IsRGB48, IsRGB64, Is420, Is422, Is444, IsY, IsYUVA, IsPlanarRGB, IsPlanarRGBA

    • Some new cache and cpu constants for GetCPUFlags (the v5/v6 ones). In AviSynth+: CPU constants up to AVX512F, AVX512BW and on.

    • SetCacheHints changed from void to int.

    • AviSynth+: SetCacheHints constants helping automatic MT mode registration for plugins

  • C API (AVISYNTH_INTERFACE_VERSION = 6):

    • The following functions are added to the interface: avs_is_yv24, avs_is_yv16, avs_is_yv12, avs_is_yv411, avs_is_y8, avs_is_color_space, avs_get_plane_width_subsampling, avs_get_plane_height_subsampling, avs_bits_per_pixel, avs_bytes_from_pixels, avs_row_size, avs_bmp_size, avs_get_row_size_p, avs_get_height_p and avs_delete_script_environment.

    • And in AviSynth+: avs_is_rgb48, avs_is_rgb64, avs_is_444, avs_is_422, avs_is_420, avs_is_y, avs_is_yuva, avs_is_planar_rgb, avs_is_planar_rgba avs_num_components, avs_component_size and avs_bits_per_component (and others which are not mentioned because they are deprecated)

What's new in the api V8

  • C++ API (AVISYNTH_INTERFACE_VERSION = 8):
  • C API (AVISYNTH_INTERFACE_VERSION = 8):

    • mostly the same functions as provided in C++ interface. Naming convention is kept. E.g. propSetFloat in C++ is prop_set_float in C

    • Important note: frame property access in V8 is broken. Safely available since V8.1. or check simply for V9 like ffmpeg does.

  • C API (AVISYNTH_INTERFACE_VERSION = 8, AVISYNTH_INTERFACE_BUGFIX = 1):

    • working frame property access (see v9 comments for fixes)

What's new in the API V9

  • C and C++ API (AVISYNTH_INTERFACE_VERSION = 9):

    • MakePropertyWritable like MakeWritable but for frame properties only.

    • IsPropertyWritable like IsWritable but for frame properties only.

    • C interface equivalents: avs_make_property_writable and avs_is_property_writable

  • C API (AVISYNTH_INTERFACE_VERSION = 9, AVISYNTH_INTERFACE_BUGFIX = 1):

    • Fix: C interface crash when using avs_new_video_frame_p(_a)

    • Fix: C interface avs_prop_get_data behave like C++ counterpart.

  • C API (AVISYNTH_INTERFACE_VERSION = 9, AVISYNTH_INTERFACE_BUGFIX = 2):

    • Fix: C API undefined behavior when upstream throw runtime error

What's new in the API V10

  • C and C++ API (AVISYNTH_INTERFACE_VERSION = 10):

    • Technical fix: made VideoFrameBuffer destructor public like in other classes of the public API to prevent compiler errors downstream when calling non-const member functions

    • New: VideoFrame (c++) and AVS_VideoFrame (c) now have its own pixel_type field. Before, there was no reliable way of knowing it on a frame from propGetFrame.

    • New: VideoFrame::GetPixelType (avs_video_frame_get_pixel_type) returns the video format of a VideoFrame, ideally kept in sync with VideoInfo::pixel_type.

    • New: VideoFrame::AmendPixelType (avs_video_frame_amend_pixel_type) changes the pixel_type field of a VideoFrame (special cases)

      C interface equivalents: avs_video_frame_get_pixel_type and avs_video_frame_amend_pixel_type

    • New: AVSValue::GetType returns the underlying type directly

    • Added AvsValueType enum for the above case to avisynth.h

    • Added DEFAULT_PLANE and AVS_DEFAULT_PLANE to plane enum (avisynth.h, avisynth_c.h)

    • Gave all enums of public C++ API a name (avisynth.h): AvsVersion, AvsSampleType, AvsPlane, AvsColorFormat, AvsImageTypeFlags, AvsChromaPlacement

    • prop_src argument of NewVideoFrameP (c++) and of 'avs_new_video_frame_p' (c) is now const

    • New: VideoInfo::GetChannelMask (c++) and 'avs_get_channel_mask' (c) Audio channel layout support. returns the channel mask stored in VideoInfo struct

    • New: VideoInfo::SetChannelMask (c++) and 'avs_set_channel_mask' Audio channel layout support. sets the validity and the layout mask value into VideoInfo

    • New: VideoInfo::IsChannelMaskKnown (c++) and 'avs_is_channel_mask_known' (c) Audio channel layout support. Returns if clip has valid channel mask in its VideoInfo

What's new in the API V11

  • C and C++ API (AVISYNTH_INTERFACE_VERSION = 11):

    • General: support 64 bit data types in AVSValue/AVS_Value: double and long (int64_t), also for 32 bit Avisynth!

    • C++ interface

      • changed: AVSValue::IsFloat true for any 32/64 bit floating point or integer types

      • changed: AVSValue::IsInt true for any 32/64 bit integer types

      • new: AVSValue::IsFloatfStrict : returns true only if AVSValue is stricly 32 bit float

      • new: AVSValue::IsLongStrict : returns true only if AVSValue is stricly 64 bit integer

      • new: AVSValue::AsLong : returns int64_t

      • new: AVSValue::AsLong(int64_t def)

      • No change: since AsFloat return type was double --> no change, it retrieves double values as well

      • new AVSValue constructors for 64 bit types

      • new: IScriptInterface::propGetIntSaturated and IScriptInterface::propGetFloatSaturated

      • new: IScriptInterface::propGetDataTypeHint and IScriptInterface::propSetDataH

      • New enum AVSPropDataTypeHint: DATATYPEHINT_UNKNOWN, DATATYPEHINT_BINARY and DATATYPEHINT_UTF8.

    • C interface

      • New getter API calls: avs_get_as_long, avs_get_as_int, avs_get_as_float and the rest: avs_get_as_bool, avs_get_as_string, avs_get_as_error, avs_get_as_array

      • New API call for array size query: avs_get_array_size

      • New API call for array (or array-like value) content: avs_get_array_elt

      • Modified INLINE typecheck and getter helpers for 64-bit data type awareness:

        • avs_is_int, avs_is_float

        • avs_as_int, avs_as_float

      • New INLINE type check helpers:

        • avs_is_long_strict, avs_is_floatf_strict

      • New INLINE getter helpers for 64-bit data (prefer using API calls):

        • avs_as_long, avs_as_float

      • New setter API calls:

        • avs_set_to_double, avs_set_to_long

        • avs_set_to_array (deep arrays, deep copy, standard in AviSynth+) (Note: avs_release_value and avs_copy_value are required for destruct or copy arrays)

      • API version of existing INLINE value setters (new_value_xxx) for the rest value types, to make the world round:

        • avs_set_to_error, avs_set_to_bool, avs_set_to_int, avs_set_to_float, avs_set_to_string

      • new API function for assign a 'v'oid undefined value to AVS_Value

        • avs_set_to_void

      • API version of existing INLINE type checks

        • avs_val_defined, avs_val_is_error, avs_val_is_bool, avs_val_is_int, avs_val_is_string, avs_val_is_float, avs_val_is_floatf_strict, avs_val_is_long_strict, avs_val_is_array

      • New optional plugin entry point: avisynth_c_plugin_init2

        • A C plugin signals to AviSynth that it is V11 interface (64-bit data) ready by implementing avisynth_c_plugin_init2 as well.

        • avisynth_c_plugin_init2 has the same signature as avisynth_c_plugin_init and can simply call forward to the old avisynth_c_plugin_init entry point. Both entry points can be implemented; AviSynth+ will first check avisynth_c_plugin_init2, then avisynth_c_plugin_init. Don't forget to add a new

          avisynth_c_plugin_init2@4 = _avisynth_c_plugin_init2@4

          line to your existing .def file on Win32.

      • New avs_prop_get_int_saturated and avs_prop_get_float_saturated

      • New avs_prop_get_data_type_hint and avs_prop_set_data_h

      • New constants AVS_PROPDATATYPEHINT_UNKNOWN, AVS_PROPDATATYPEHINT_BINARY and AVS_PROPDATATYPEHINT_UTF8

      • New alternative avs_add_function_r and APPLYFUNCR functions for cases where the callback cannot return AVS_Value struct (functions/filters written Python / ctypes)

      • Deprecated inline helper functions.

        • avs_get_pitch => avs_get_pitch_p(p, AVS_DEFAULT_PLANE)

        • avs_get_row_size => avs_get_row_size_p(p, AVS_DEFAULT_PLANE)

        • avs_get_height => avs_get_height_p(p, AVS_DEFAULT_PLANE)

        • avs_get_read_ptr => avs_get_read_ptr_p(p, AVS_DEFAULT_PLANE)

        • avs_get_write_ptr => avs_get_write_ptr_p(p, AVS_DEFAULT_PLANE)

        • avs_release_frame => avs_release_video_frame

        • avs_copy_frame => avs_copy_video_frame

        • Use #define AVSC_ALLOW_DEPRECATED before including avisynth_c.h if they still need for you, but better fix your code: use the recommended replacements.

      • Add missing AVS_MT_xxxx mode constants to avisynth_c.h (similar to c++ avisynth.h header enum MtMode)

Some history

Ben's AviSynth Docs is the documentation written for AviSynth 1.0 by Ben Rudiak-Gould, in its original form.

See more about the modifications for AviSynth 2.5 in the AviSynth Two-Five SDK.

Please read AviSynth SDK History. ---

Other sources ???

Once you've got the basics down on AVS development (Ben's text is quite good), the [SDK] for VirtualDub is also a good read. Good news is you won't have to worry about writing [function pointers] and [raw Win32]; meanwhile, Avery knows his stuff when it comes to video & CPU optimization techniques, so you better pay attention.

Some video related ebooks (PDF) can be downloaded freely from [Snell & Wilcox]. edit - this???

License terms

Note: Avisynth Filter SDK parts are under specific SDK license terms.

$Date: 2025/02/03 11:11:11 $

Latest online Avisynth+ version is at https://avisynthplus.readthedocs.io/en/latest/avisynthdoc/FilterSDK/FilterSDK.html This one is maintained properly.

Latest online mediaWiki version is at http://avisynth.nl/index.php/Filter_SDK