AviSynth C Interface API Reference

Here is the complete ABI for the AviSynth C Interface.

The ABI closely mirrors the native Visual C++ ABI. It should provide all the functionally of the C++. The main differences from the C++ ABI are:

In the way a new filter is created since virtual functions can't be used
Error handling since exceptions can't be used
Memory management since smart pointers can't be used.

Be sure to also check out the Illustrated Example and the orignal AviSynth development documentation.

Basic Info

Everything is defined in "avisynth_c.h". Link with "avisynth_c.lib".

The macro "AVSC_CC" should always be used after the return type when defining call back functions. This macro stands for AviSynth C calling convention. Right now it expands to "__cdecl" but it is likely to change to "__stdcall" in a future version for better compatibility with languages such as Visual Basic.

Constants

AVISYNTH_INTERFACE_VERSION

Audio Sample information:

AVS_SAMPLE_INT8
AVS_SAMPLE_INT16
AVS_SAMPLE_INT24
AVS_SAMPLE_INT32
AVS_SAMPLE_FLOAT

AVS_PLANAR_Y
AVS_PLANAR_U
AVS_PLANAR_V
AVS_PLANAR_ALIGNED
AVS_PLANAR_Y_ALIGNED = AVS_PLANAR_Y|AVS_PLANAR_ALIGNED
AVS_PLANAR_U_ALIGNED = AVS_PLANAR_U|AVS_PLANAR_ALIGNED
AVS_PLANAR_V_ALIGNED = AVS_PLANAR_V|AVS_PLANAR_ALIGNED

Colorspace properties:

AVS_CS_BGR
AVS_CS_YUV
AVS_CS_INTERLEAVED
AVS_CS_PLANAR

Specific colorformats:

AVS_CS_UNKNOWN
AVS_CS_BGR24 = 1<<0 | AVS_CS_BGR | AVS_CS_INTERLEAVED,
AVS_CS_BGR32 = 1<<1 | AVS_CS_BGR | AVS_CS_INTERLEAVED,
AVS_CS_YUY2 = 1<<2 | AVS_CS_YUV | AVS_CS_INTERLEAVED,
AVS_CS_YV12 = 1<<3 | AVS_CS_YUV | AVS_CS_PLANAR - y-v-u, planar
AVS_CS_I420 = 1<<4 | AVS_CS_YUV | AVS_CS_PLANAR - y-u-v, planar
AVS_CS_IYUV = 1<<4 | AVS_CS_YUV | AVS_CS_PLANAR -same as above

Imagetype properties:

AVS_IT_BFF
AVS_IT_TFF
AVS_IT_FIELDBASED

AVS_FILTER_TYPE
AVS_FILTER_INPUT_COLORSPACE
AVS_FILTER_OUTPUT_TYPE
AVS_FILTER_NAME
AVS_FILTER_AUTHOR
AVS_FILTER_VERSION
AVS_FILTER_ARGS
AVS_FILTER_ARGS_INFO
AVS_FILTER_ARGS_DESCRIPTION
AVS_FILTER_DESCRIPTION

Subtypes:

AVS_FILTER_TYPE_AUDIO
AVS_FILTER_TYPE_VIDEO
AVS_FILTER_OUTPUT_TYPE_SAME
AVS_FILTER_OUTPUT_TYPE_DIFFERENT

AVS_CACHE_NOTHING
AVS_CACHE_RANGE

Constants for avs_get_cpu_flags. (These are backwards-compatible with those in VirtualDub.)

AVS_CPU_FORCE
AVS_CPU_FPU - 386/486DX
AVS_CPU_MMX - P55C, K6, PII
AVS_CPU_INTEGER_SSE - PIII, Athlon
AVS_CPU_SSE - PIII, Athlon XP/MP
AVS_CPU_SSE2 - PIV, Hammer
AVS_CPU_3DNOW - K6-2
AVS_CPU_3DNOW_EXT - Athlon
AVS_CPU_X86_64 - Hammer (note: equiv. to 3DNow + SSE2, which only Hammer will have anyway)

AVS_FRAME_ALIGN = 16

AVS_VideoInfo

typedef struct AVS_VideoInfo {
  int width, height;    // width=0 means no video
  unsigned fps_numerator, fps_denominator;
  int num_frames;

  int pixel_type;
  
  int audio_samples_per_second;   // 0 means no audio
  int sample_type;
  INT64 num_audio_samples;
  int nchannels;

  // Imagetype properties

  int image_type;
} AVS_VideoInfo;

Helper functions:

int avs_has_video(const AVS_VideoInfo * p)
int avs_has_audio(const AVS_VideoInfo * p)
int avs_is_rgb(const AVS_VideoInfo * p)
int avs_is_rgb24(const AVS_VideoInfo * p)
int avs_is_rgb32(const AVS_VideoInfo * p)
int avs_is_yuy(const AVS_VideoInfo * p)
int avs_is_yuy2(const AVS_VideoInfo * p)
int avs_is_yv12(const AVS_VideoInfo * p)
int avs_is_color_space(const AVS_VideoInfo * p, int c_space)
int avs_is_property(const AVS_VideoInfo * p, int property)
int avs_is_planar(const AVS_VideoInfo * p)
int avs_is_field_based(const AVS_VideoInfo * p)
int avs_is_parity_known(const AVS_VideoInfo * p)
int avs_is_bff(const AVS_VideoInfo * p)
int avs_is_tff(const AVS_VideoInfo * p)
int avs_bits_per_pixel(const AVS_VideoInfo * p)
int avs_bytes_from_pixels(const AVS_VideoInfo * p, int pixels)
int avs_row_size(const AVS_VideoInfo * p)
int avs_bmp_size(const AVS_VideoInfo * vi)
int avs_samples_per_second(const AVS_VideoInfo * p)
int avs_bytes_per_channel_sample(const AVS_VideoInfo * p)
int avs_bytes_per_audio_sample(const AVS_VideoInfo * p)
INT64 avs_audio_samples_from_frames(const AVS_VideoInfo * p, INT64 frames)
int avs_frames_from_audio_samples(const AVS_VideoInfo * p, INT64 samples)
INT64 avs_audio_samples_from_bytes(const AVS_VideoInfo * p, INT64 bytes)
INT64 avs_bytes_from_audio_samples(const AVS_VideoInfo * p, INT64 samples)
int avs_audio_channels(const AVS_VideoInfo * p)
int avs_sample_type(const AVS_VideoInfo * p)

Useful mutator:

void avs_set_property(AVS_VideoInfo * p, int property)
void avs_clear_property(AVS_VideoInfo * p, int property)
void avs_set_field_based(AVS_VideoInfo * p, int isfieldbased)
void avs_set_fps(AVS_VideoInfo * p, unsigned numerator, unsigned denominator)
int avs_is_same_colorspace(AVS_VideoInfo * x, AVS_VideoInfo * y)

AVS_VideoFrame

The "_p" suffex stands for planar.

int avs_get_pitch(const AVS_VideoFrame * p)
int avs_get_pitch_p(const AVS_VideoFrame * p, int plane)
int avs_get_row_size(const AVS_VideoFrame * p)
int avs_get_row_size_p(const AVS_VideoFrame * p, int plane)
int avs_get_height(const AVS_VideoFrame * p)
int avs_get_height_p(const AVS_VideoFrame * p, int plane) {
const BYTE * avs_get_read_ptr(const AVS_VideoFrame * p) {
const BYTE * avs_get_read_ptr_p(const AVS_VideoFrame * p, int plane)
int avs_is_writable(const AVS_VideoFrame * p) {
BYTE* avs_get_write_ptr(const AVS_VideoFrame * p)
BYTE* avs_get_write_ptr_p(const AVS_VideoFrame * p, int plane)

void avs_release_video_frame(AVS_VideoFrame *)
void avs_release_frame(AVS_VideoFrame * f) - alias for avs_release_video_frame
AVS_VideoFrame * avs_copy_video_frame(AVS_VideoFrame *) - makes a shallow copy of a video frame
AVS_VideoFrame * avs_copy_frame(AVS_VideoFrame * f) - alias for avs_copy_video_frame

AVS_Value

Treat AVS_Value as a fat pointer. That is use avs_copy_value and avs_release_value appropiaty as you would if AVS_Value was a pointer.

It is defined in the header file but to maintain source code compatibility with future versions of the avisynth_c API don't use the AVS_Value directly.

AVS_Value should be initilized with "avs_void". Should also set to avs_void after the value is released with avs_copy_value. Consider it the equalvent of setting a pointer to NULL

void avs_copy_value(AVS_Value * dest, AVS_Value src)
void avs_release_value(AVS_Value)
int avs_defined(AVS_Value v)
int avs_is_clip(AVS_Value v)
int avs_is_bool(AVS_Value v)
int avs_is_int(AVS_Value v)
int avs_is_float(AVS_Value v)
int avs_is_string(AVS_Value v)
int avs_is_array(AVS_Value v)
int avs_is_error(AVS_Value v)
AVS_Clip * avs_take_clip(AVS_Value, AVS_ScriptEnvironment *)
void avs_set_to_clip(AVS_Value *, AVS_Clip *)
int avs_as_bool(AVS_Value v)
int avs_as_int(AVS_Value v)
const char * avs_as_string(AVS_Value v)
double avs_as_float(AVS_Value v)
const char * avs_as_error(AVS_Value v)
const AVS_Value * avs_as_array(AVS_Value v)
int avs_array_size(AVS_Value v)
AVS_Value avs_array_elt(AVS_Value v, int index)
AVS_Value avs_new_value_bool(int v0)
AVS_Value avs_new_value_int(int v0)
AVS_Value avs_new_value_string(const char * v0)
AVS_Value avs_new_value_float(float v0)
AVS_Value avs_new_value_error(const char * v0)
AVS_Value avs_new_value_clip(AVS_Clip * v0)
AVS_Value avs_new_value_array(AVS_Value * v0, int size)

AVS_Clip

Functions for accessing an existing clip.

void avs_release_clip(AVS_Clip *)
AVS_Clip * avs_copy_clip(AVS_Clip *)
const char * avs_clip_get_error(AVS_Clip *) - return 0 if no error
const AVS_VideoInfo * avs_get_video_info(AVS_Clip *)
int avs_get_version(AVS_Clip *)
AVS_VideoFrame * avs_get_frame(AVS_Clip *, int n) - The returned video frame must be released with avs_release_video_frame
int avs_get_parity(AVS_Clip *, int n) - return field parity if field_based, else parity of first field in frame
int avs_get_audio(AVS_Clip *, void * buf, INT64 start, INT64 count) - start and count are in samples
avs_set_cache_hints(AVS_Clip *, int cachehints, int frame_range)

AVS_ScriptEnvironment

long avs_get_cpu_flags(AVS_ScriptEnvironment *)
int avs_check_version(AVS_ScriptEnvironment *, int version)
char * avs_save_string(AVS_ScriptEnvironment *, const char* s, int length)
char * avs_sprintf(AVS_ScriptEnvironment *, const char * fmt, ...)
char * avs_vsprintf(AVS_ScriptEnvironment *, const char * fmt, void* val) - val is really a va_list; I hope everyone typedefs va_list to a pointer
int avs_add_function - see Callbacks
int avs_function_exists(AVS_ScriptEnvironment *, const char * name)
AVS_Value avs_invoke(AVS_ScriptEnvironment *, const char * name, AVS_Value args, const char** arg_names) - The returned value must be be released with avs_release_value
AVS_Value avs_get_var(AVS_ScriptEnvironment *, const char* name) - The returned value must be be released with avs_release_value
int avs_set_var(AVS_ScriptEnvironment *, const char* name, AVS_Value val)
int avs_set_global_var(AVS_ScriptEnvironment *, const char* name, const AVS_Value val)
AVS_VideoFrame * avs_new_video_frame_a(AVS_ScriptEnvironment *, const AVS_VideoInfo * vi, int align) - align should be at least 16
AVS_VideoFrame * avs_new_video_frame(AVS_ScriptEnvironment * env, const AVS_VideoInfo * vi) = avs_new_video_frame_a(env,vi,AVS_FRAME_ALIGN)
AVS_VideoFrame * avs_new_frame(AVS_ScriptEnvironment * env, const AVS_VideoInfo * vi) - alias for avs_new_video_frame
int avs_make_writable(AVS_ScriptEnvironment *, AVS_VideoFrame * * pvf)
void avs_bit_blt(AVS_ScriptEnvironment *, BYTE* dstp, int dst_pitch, const BYTE* srcp, int src_pitch, int row_size, int height)
void avs_at_exit - see callbacks
AVS_VideoFrame * avs_subframe(AVS_ScriptEnvironment *, AVS_VideoFrame * src, int rel_offset, int new_pitch, int new_row_size, int new_height) - The returned video frame must be be released
int avs_set_memory_max(AVS_ScriptEnvironment *, int mem);
int avs_set_working_dir(AVS_ScriptEnvironment *, const char * newdir);

AVS_ScriptEnvironment * avs_create_script_environment(int version) - AviSynth exports this; it's a way to use it as a library, without writing an AVS script or without going through AVIFile.

Callbacks

typedef AVS_Value (AVSC_CC * AVS_ApplyFunc) (AVS_ScriptEnvironment *, AVS_Value args, void * user_data)
int avs_add_function(AVS_ScriptEnvironment *, const char * name, const char * params, AVS_ApplyFunc apply, void * user_data)

In order to create a new filter avs_add_function must be used to register a call back function of type AVS_ApplyFunc.

typedef struct AVS_FilterInfo
{
  // these members should not be modified outside of the AVS_ApplyFunc callback
  AVS_Clip * child;
  AVS_VideoInfo vi;
  AVS_ScriptEnvironment * env;
  AVS_VideoFrame * (AVSC_CC * get_frame)(AVS_FilterInfo *, int n);
  int (AVSC_CC * get_parity)(AVS_FilterInfo *, int n);
  int (AVSC_CC * get_audio)(AVS_FilterInfo *, void * buf, 
				  INT64 start, INT64 count);
  int (AVSC_CC * set_cache_hints)(AVS_FilterInfo *, int cachehints, 
					int frame_range);
  void (AVSC_CC * free_filter)(AVS_FilterInfo *);
  
  // Should be set when ever there is an error to report.
  // It is cleared before any of the above methods are called
  const char * error;
  // this is to store whatever and may be modified at will
  void * user_data;
} AVS_FilterInfo;

This is the structure that containts the essence of a filter. The AVS_ApplyFunc callback must manipulate it appropriately.

AVS_Clip * avs_new_c_filter(AVS_ScriptEnvironment * e, AVS_FilterInfo * * fi, AVS_Value child, int store_child)

avs_new_c_filter creates a new filter. It should be called inside the AVS_ApplyFunc call back. "fi" is set to point to the AVS_FilterInfo so that you can modify it once it is initilized. "store_child" should generally be set to true. If it is not set than ALL methods (the function pointers) must be defined. If it is set than you do not need to worry about freeing the child clip.

typedef void (AVSC_CC *AVS_ShutdownFunc)(void* user_data, AVS_ScriptEnvironment * env)
void avs_at_exit(AVS_ScriptEnvironment *, AVS_ShutdownFunc function, void * user_data)

const char * AVSC_CC avisynth_c_plugin_init(AVS_ScriptEnvironment* env)

"avisynth_c_plugin_init" is the entry point for the plugin and must be defined.

Copyright © 2004 Kevin Atkinson under the GPL GNU General Public License as published by the Free Software Foundation version 2.0.
Last Modified January 1, 2004.
Avisynth can be found at www.avisynth.org. The latest version of the C interface can be found at kevin.atkinson.dhs.org/avisynth_c/.