VapourSynth.h

Table of contents

Introduction

Macros

VS_CC

VS_EXTERNAL_API

VAPOURSYNTH_API_MAJOR

VAPOURSYNTH_API_MINOR

VAPOURSYNTH_API_VERSION

Enums

VSColorFamily

VSSampleType

VSPresetFormat

VSFilterMode

VSNodeFlags

VSPropTypes

VSGetPropErrors

VSPropAppendMode

VSActivationReason

VSMessageType

Structs

VSFrameRef

VSNodeRef

VSCore

VSPlugin

VSNode

VSFuncRef

VSMap

VSFrameContext

VSFormat

VSCoreInfo

VSVideoInfo

VSAPI

Functions

getVapourSynthAPI

Writing plugins

VSInitPlugin

VSFilterInit

VSFilterGetFrame

VSFilterFree

Introduction

This is VapourSynth’s main header file. Plugins and applications that use the library must include it.

VapourSynth’s public API is all C.

Macros

VapourSynth.h defines some preprocessor macros that make the programmer’s life easier. The relevant ones are described below.

VS_CC

The VS_CC macro expands to the calling convention used by VapourSynth. All functions meant to be called by VapourSynth must use this macro (a filter’s “init”, “getframe”, “free” functions, etc).

Example:

static void VS_CC fooInit(...) { ... }

VS_EXTERNAL_API

The VS_EXTERNAL_API macro expands to the platform-specific magic required for functions exported by shared libraries. It also takes care of adding extern "C" when needed, and VS_CC.

This macro must be used for a plugin’s entry point, like so:

VS_EXTERNAL_API(void) VapourSynthPluginInit(...) { ... }

VAPOURSYNTH_API_MAJOR

Major API version.

This macro was added in VapourSynth R26 (API R3).

VAPOURSYNTH_API_MINOR

Minor API version. It is bumped when new functions are added to VSAPI.

This macro was added in VapourSynth R26 (API R3).

VAPOURSYNTH_API_VERSION

API version. The high 16 bits are VAPOURSYNTH_API_MAJOR, the low 16 bits are VAPOURSYNTH_API_MINOR.

Prior to VapourSynth R26, the API version consisted of only the major component.

Enums

enum VSColorFamily

  • cmGray

  • cmRGB

  • cmYUV

  • cmYCoCg

  • cmCompat

enum VSSampleType

  • stInteger

  • stFloat

enum VSPresetFormat

The presets suffixed with H and S have floating point sample type. The H and S suffixes stand for half precision and single precision, respectively.

The compat formats are the only packed formats in VapourSynth. Everything else is planar. They exist for compatibility with Avisynth plugins. They are not to be implemented in native VapourSynth plugins.

  • pfNone

  • pfGray8

  • pfGray16

  • pfGrayH

  • pfGrayS

  • pfYUV420P8

  • pfYUV422P8

  • pfYUV444P8

  • pfYUV410P8

  • pfYUV411P8

  • pfYUV440P8

  • pfYUV420P9

  • pfYUV422P9

  • pfYUV444P9

  • pfYUV420P10

  • pfYUV422P10

  • pfYUV444P10

  • pfYUV420P12

  • pfYUV422P12

  • pfYUV444P12

  • pfYUV420P14

  • pfYUV422P14

  • pfYUV444P14

  • pfYUV420P16

  • pfYUV422P16

  • pfYUV444P16

  • pfYUV444PH

  • pfYUV444PS

  • pfRGB24

  • pfRGB27

  • pfRGB30

  • pfRGB48

  • pfRGBH

  • pfRGBS

  • pfCompatBGR32

  • pfCompatYUY2

enum VSFilterMode

Controls how a filter will be multithreaded, if at all.

  • fmParallel

    Completely parallel execution. Multiple threads will call a filter’s “getframe” function, to fetch several frames in parallel.

  • fmParallelRequests

    For filters that are serial in nature but can request in advance one or more frames they need. A filter’s “getframe” function will be called from multiple threads at a time with activation reason arInitial, but only one thread will call it with activation reason arAllFramesReady at a time.

  • fmUnordered

    Only one thread can call the filter’s “getframe” function at a time. Useful for filters that modify or examine their internal state to determine which frames to request.

    While the “getframe” function will only run in one thread at a time, the calls can happen in any order. For example, it can be called with reason arInitial for frame 0, then again with reason arInitial for frame 1, then with reason arAllFramesReady for frame 0.

  • fmSerial

    For compatibility with other filtering architectures. The filter’s “getframe” function only ever gets called from one thread at a time. Unlike fmUnordered, only one frame is processed at a time.

enum VSNodeFlags

  • nfNoCache

    This flag indicates that the frames returned by the filter should not be cached. “Fast” filters should set this to reduce cache bloat.

  • nfIsCache

    This flag must not be used in third-party filters. It is used to mark instances of the built-in Cache filter. Strange things may happen to your filter if you use this flag.

    This flag was introduced in VapourSynth R24 without bumping the API version (R3).

  • nfMakeLinear

    This flag should be used by filters which prefer linear access, like source filters, where seeking around can cause significant slowdowns. This flag only has any effect if the filter using it is immediately followed by an instance of the built-in Cache filter.

    This flag was introduced in API R3.3 (VapourSynth R30).

enum VSPropTypes

Types of properties that can be stored in a VSMap.

  • ptUnset

  • ptInt

  • ptFloat

  • ptData

  • ptNode

  • ptFrame

  • ptFunction

enum VSGetPropErrors

When a propGet* function fails, it returns one of these in the err parameter.

They are all non-zero.

  • peUnset

    The requested key was not found in the map.

  • peType

    The wrong function was used to retrieve the property. E.g. propGetInt() was used on a property of type ptFloat.

  • peIndex

    The requested index was out of bounds.

enum VSPropAppendMode

Controls the behaviour of propSetInt() and friends.

  • paReplace

    All existing values associated with the key will be replaced with the new value.

  • paAppend

    The new value will be appended to the list of existing values associated with the key.

  • paTouch

    If the key exists in the map, nothing happens. Otherwise, the key is added to the map, with no values associated.

enum VSActivationReason

See VSFilterGetFrame.

  • arInitial

  • arFrameReady

  • arAllFramesReady

  • arError

enum VSMessageType

See setMessageHandler().

  • mtDebug

  • mtWarning

  • mtCritical

  • mtFatal

Structs

Most structs are opaque and their contents can only be accessed using functions in the API.

struct VSFrameRef

A frame.

Each row of pixels in a frame is guaranteed to have an alignment of 32 bytes.

Two frames with the same width are guaranteed to have the same stride.

Any data can be attached to a frame, using a VSMap.

struct VSNodeRef

A reference to a node in the constructed filter graph. Its primary use is as an argument to other filter or to request frames from.

struct VSCore

The core represents one instance of VapourSynth. Every core individually loads plugins and keeps track of memory.

struct VSPlugin

A VapourSynth plugin. There are a few of these built into the core, and therefore available at all times: the basic filters (identifier com.vapoursynth.std, namespace std), the resizers (identifier com.vapoursynth.resize, namespace resize), and the Avisynth compatibility module, if running in Windows (identifier com.vapoursynth.avisynth, namespace avs).

The Function Reference describes how to load VapourSynth and Avisynth plugins.

A VSPlugin instance is constructed by the core when loading a plugin (.so / .dylib / .dll), and the pointer is passed to the plugin’s VapourSynthPluginInit() function.

A VapourSynth plugin can export any number of filters.

Plugins have a few attributes:

  • An identifier, which must be unique among all VapourSynth plugins in existence, because this is what the core uses to make sure a plugin only gets loaded once.

  • A namespace, also unique. The filters exported by a plugin end up in the plugin’s namespace.

  • A full name, which is used by the core in a few error messages.

  • The VapourSynth API version the plugin requires.

  • A file name.

Things you can do with a VSPlugin:

  • Get a list of all the filters it exports, using getFunctions().

  • Invoke one of its filters, using invoke().

  • Get its location in the file system, using getPluginPath().

A list of all loaded plugins (including built-in) can be obtained with getPlugins().

Once loaded, a plugin only gets unloaded when the VapourSynth core is freed.

struct VSNode

Not really interesting.

struct VSFuncRef

Holds a reference to a function that may be called. This type primarily exists so functions can be shared between the scripting layer and plugins in the core.

struct VSMap

VSMap is a container that stores (key,value) pairs. The keys are strings and the values can be (arrays of) integers, floating point numbers, arrays of bytes, VSNodeRef, VSFrameRef, or VSFuncRef.

The pairs in a VSMap are sorted by key.

In VapourSynth, VSMaps have several uses:

  • storing filters’ arguments and return values

  • storing user-defined functions’ arguments and return values

  • storing the properties attached to frames

Only alphanumeric characters and the underscore may be used in keys.

Creating and destroying a map can be done with createMap() and freeMap(), respectively.

A map’s contents can be retrieved and modified using a number of functions, all prefixed with “prop”.

A map’s contents can be erased with clearMap().

struct VSFrameContext

Not really interesting.

struct VSFormat

Describes the format of a clip.

Don’t create an instance of this struct manually (struct VSFormat moo;), but only through registerFormat(). Registered VSFormat instances will be valid as long as the VapourSynth core object lives. They can be retrieved with getFormatPreset() or registerFormat().

char name[32]

A nice, printable name, like “YUV444P10”.

int id

A number that uniquely identifies the VSFormat instance. One of VSPresetFormat, if it’s a built-in format.

int colorFamily

See VSColorFamily.

int sampleType

See VSSampleType.

int bitsPerSample

Number of significant bits.

int bytesPerSample

Number of bytes needed for a sample. This is always a power of 2 and the smallest possible that can fit the number of bits used per sample.

int subSamplingW
int subSamplingH

log2 subsampling factor, applied to second and third plane. Convenient numbers that can be used like so:

uv_width = y_width >> subSamplingW;
int numPlanes

Number of planes.

struct VSCoreInfo

Contains information about a VSCore instance.

const char *versionString

Printable string containing the name of the library, copyright notice, core and API versions.

int core

Version of the core.

int api

Version of the API.

int numThreads

Number of worker threads.

int64_t maxFramebufferSize

The framebuffer cache will be allowed to grow up to this size (bytes) before memory is aggressively reclaimed.

int64_t usedFramebufferSize

Current size of the framebuffer cache, in bytes.

struct VSVideoInfo

Contains information about a clip.

const VSFormat *format

Format of the clip. It will be NULL if the clip’s format can vary.

int64_t fpsNum

Numerator part of the clip’s frame rate. It will be 0 if the frame rate can vary. Should always be a reduced fraction.

int64_t fpsDen

Denominator part of the clip’s frame rate. It will be 0 if the frame rate can vary. Should always be a reduced fraction.

int width

Width of the clip. Both width and height will be 0 if the clip’s dimensions can vary.

int height

Height of the clip. Both width and height will be 0 if the clip’s dimensions can vary.

int numFrames

Length of the clip.

Since API R3.2 (VapourSynth R27) this is no longer allowed to be 0, i.e. clips with unknown length are not supported.

int flags

The flags passed to createFilter (either 0, or one or more of VSNodeFlags).

struct VSAPI

This giant struct is the way to access VapourSynth’s public API.

VSCore *createCore(int threads)

Creates the VapourSynth processing core and returns a pointer to it. It is legal to create multiple cores but in most cases it shouldn’t be needed.

threads

Number of desired worker threads. If 0 or lower, a suitable value is automatically chosen, based on the number of logical CPUs.

void freeCore(VSCore *core)

Frees a core. Should only be done after all frame requests have completed and all objects belonging to the core have been released.

const VSCoreInfo *getCoreInfo(VSCore *core)

Deprecated as of API 3.6 (VapourSynth R47)

Returns information about the VapourSynth core.

VapourSynth retains ownership of the returned pointer.

void getCoreInfo2(VSCore *core, VSCoreInfo *info)

Returns information about the VapourSynth core.

This function is thread-safe.

int64_t setMaxCacheSize(int64_t bytes, VSCore *core)

Sets the maximum size of the framebuffer cache. Returns the new maximum size.

void setMessageHandler(VSMessageHandler handler, void *userData)

Deprecated as of API 3.6 (VapourSynth R47)

Installs a custom handler for the various error messages VapourSynth emits. The message handler is currently global, i.e. per process, not per VSCore instance.

The default message handler simply sends the messages to the standard error stream.

This function is thread-safe.

handler

typedef void (VS_CC *VSMessageHandler)(int msgType, const char *msg, void *userdata)

Custom message handler. If this is NULL, the default message handler will be restored.

msgType

The type of message. One of VSMessageType.

If msgType is mtFatal, VapourSynth will call abort() after the message handler returns.

msg

The message.

userData

Pointer that gets passed to the message handler.

int addMessageHandler(VSMessageHandler handler, VSMessageHandlerFree free, void *userData)

Installs a custom handler for the various error messages VapourSynth emits. The message handler is currently global, i.e. per process, not per VSCore instance. Returns a unique id for the handler.

If no error handler is installed the messages are sent to the standard error stream.

This function is thread-safe.

handler

typedef void (VS_CC *VSMessageHandler)(int msgType, const char *msg, void *userdata)

Custom message handler. If this is NULL, the default message handler will be restored.

msgType

The type of message. One of VSMessageType.

If msgType is mtFatal, VapourSynth will call abort() after the message handler returns.

msg

The message.

free

typedef void (VS_CC *VSMessageHandlerFree)(void *userData)

Called when a handler is removed.

userData

Pointer that gets passed to the message handler.

This function was introduced in API R3.6 (VapourSynth R47).

int removeMessageHandler(int id)

Removes a custom handler. Return non-zero on success and zero if the handler id is invalid.

This function is thread-safe.

id

Message handler id obtained from addMessageHandler().

This function was introduced in API R3.6 (VapourSynth R47).

void logMessage(int msgType, const char *msg)

Send a message through VapourSynth’s logging framework. See setMessageHandler.

This function is thread-safe.

msgType

The type of message. One of VSMessageType.

If msgType is mtFatal, VapourSynth will call abort() after delivering the message.

msg

The message.

This function was introduced in API R3.4 (VapourSynth R30).

int setThreadCount(int threads, VSCore *core)

Sets the number of worker threads for the given core. If the requested number of threads is zero or lower, the number of hardware threads will be detected and used.

Returns the new thread count.

This function was introduced in VapourSynth R24 without bumping the API version (R3).

VSFrameRef *newVideoFrame(const VSFormat *format, int width, int height, const VSFrameRef *propSrc, VSCore *core)

Creates a new frame, optionally copying the properties attached to another frame. It is a fatal error to pass invalid arguments to this function.

The new frame contains uninitialised memory.

format

The desired colorspace format. Must not be NULL.

width

height

The desired dimensions of the frame, in pixels. Must be greater than 0 and have a suitable multiple for the subsampling in format.

propSrc

A frame from which properties will be copied. Can be NULL.

Returns a pointer to the created frame. Ownership of the new frame is transferred to the caller.

See also newVideoFrame2().

VSFrameRef *newVideoFrame2(const VSFormat *format, int width, int height, const VSFrameRef **planeSrc, const int *planes, const VSFrameRef *propSrc, VSCore *core)

Creates a new frame from the planes of existing frames, optionally copying the properties attached to another frame. It is a fatal error to pass invalid arguments to this function.

format

The desired colorspace format. Must not be NULL.

width

height

The desired dimensions of the frame, in pixels. Must be greater than 0 and have a suitable multiple for the subsampling in format.

planeSrc

Array of frames from which planes will be copied. If any elements of the array are NULL, the corresponding planes in the new frame will contain uninitialised memory.

planes

Array of plane numbers indicating which plane to copy from the corresponding source frame.

propSrc

A frame from which properties will be copied. Can be NULL.

Returns a pointer to the created frame. Ownership of the new frame is transferred to the caller.

Example (assume frameA, frameB, frameC are existing frames):

const VSFrameRef * frames[3] = { frameA, frameB, frameC };
const int planes[3] = { 1, 0, 2 };
VSFrameRef * newFrame = vsapi->newVideoFrame2(f, w, h, frames, planes, frameB, core);

The newFrame’s first plane is now a copy of frameA’s second plane, the second plane is a copy of frameB’s first plane, the third plane is a copy of frameC’s third plane and the properties have been copied from frameB.

VSFrameRef *copyFrame(const VSFrameRef *f, VSCore *core)

Duplicates the frame (not just the reference). As the frame buffer is shared in a copy-on-write fashion, the frame content is not really duplicated until a write operation occurs. This is transparent for the user.

Returns a pointer to the new frame. Ownership is transferred to the caller.

const VSFrameRef *cloneFrameRef(const VSFrameRef *f)

Duplicates a frame reference. This new reference has to be deleted with freeFrame() when it is no longer needed.

void freeFrame(const VSFrameRef *f)

Deletes a frame reference, releasing the caller’s ownership of the frame.

It is safe to pass NULL.

Don’t try to use the frame once the reference has been deleted.

int getStride(const VSFrameRef *f, int plane)

Returns the distance in bytes between two consecutive lines of a plane of a frame. The stride is always positive.

Passing an invalid plane number will cause a fatal error.

const uint8_t *getReadPtr(const VSFrameRef *f, int plane)

Returns a read-only pointer to a plane of a frame.

Passing an invalid plane number will cause a fatal error.

Note

Don’t assume all three planes of a frame are allocated in one contiguous chunk (they’re not).

uint8_t *getWritePtr(VSFrameRef *f, int plane)

Returns a read/write pointer to a plane of a frame.

Passing an invalid plane number will cause a fatal error.

Note

Don’t assume all three planes of a frame are allocated in one contiguous chunk (they’re not).

const VSFormat *getFrameFormat(const VSFrameRef *f)

Retrieves the format of a frame.

int getFrameWidth(const VSFrameRef *f, int plane)

Returns the width of a plane of a given frame, in pixels. The width depends on the plane number because of the possible chroma subsampling.

int getFrameHeight(const VSFrameRef *f, int plane)

Returns the height of a plane of a given frame, in pixels. The height depends on the plane number because of the possible chroma subsampling.

void copyFrameProps(const VSFrameRef *src, VSFrameRef *dst, VSCore *core)

Copies the property map of a frame to another frame, overwriting all existing properties.

const VSMap *getFramePropsRO(const VSFrameRef *f)

Returns a read-only pointer to a frame’s properties. The pointer is valid as long as the frame lives.

VSMap *getFramePropsRW(VSFrameRef *f)

Returns a read/write pointer to a frame’s properties. The pointer is valid as long as the frame lives.

VSNodeRef *cloneNodeRef(VSNodeRef *node)

Duplicates a node reference. This new reference has to be deleted with freeNode() when it is no longer needed.

void freeNode(VSNodeRef *node)

Deletes a node reference, releasing the caller’s ownership of the node.

It is safe to pass NULL.

Don’t try to use the node once the reference has been deleted.

const VSFrameRef *getFrame(int n, VSNodeRef *node, char *errorMsg, int bufSize)

Generates a frame directly. The frame is available when the function returns.

This function is meant for external applications using the core as a library, or if frame requests are necessary during a filter’s initialization.

Thread-safe.

n

The frame number. Negative values will cause an error.

node

The node from which the frame is requested.

errorMsg

Pointer to a buffer of bufSize bytes to store a possible error message. Can be NULL if no error message is wanted.

bufSize

Maximum length for the error message, in bytes (including the trailing ‘0’). Can be 0 if no error message is wanted.

Returns a reference to the generated frame, or NULL in case of failure. The ownership of the frame is transferred to the caller.

Warning

Never use inside a filter’s “getframe” function.

void getFrameAsync(int n, VSNodeRef *node, VSFrameDoneCallback callback, void *userData)

Requests the generation of a frame. When the frame is ready, a user-provided function is called.

This function is meant for applications using VapourSynth as a library.

Thread-safe.

n

Frame number. Negative values will cause an error.

node

The node from which the frame is requested.

callback

typedef void (VS_CC *VSFrameDoneCallback)(void *userData, const VSFrameRef *f, int n, VSNodeRef *node, const char *errorMsg)

Function of the client application called by the core when a requested frame is ready, after a call to getFrameAsync().

If multiple frames were requested, they can be returned in any order. Client applications must take care of reordering them.

This function is only ever called from one thread at a time.

getFrameAsync() may be called from this function to request more frames.

userData

Pointer to private data from the client application, as passed previously to getFrameAsync().

f

Contains a reference to the generated frame, or NULL in case of failure. The ownership of the frame is transferred to the caller.

n

The frame number.

node

Node the frame belongs to.

errorMsg

String that usually contains an error message if the frame generation failed. NULL if there is no error.

userData

Pointer passed to the callback.

Warning

Never use inside a filter’s “getframe” function.

const VSFrameRef *getFrameFilter(int n, VSNodeRef *node, VSFrameContext *frameCtx)

Retrieves a frame that was previously requested with requestFrameFilter().

Only use inside a filter’s “getframe” function.

A filter usually calls this function when its activation reason is arAllFramesReady or arFrameReady. See VSActivationReason.

It is safe to retrieve a frame more than once, but each reference needs to be freed.

n

The frame number.

node

The node from which the frame is retrieved.

frameCtx

The context passed to the filter’s “getframe” function.

Returns a pointer to the requested frame, or NULL if the requested frame is not available for any reason. The ownership of the frame is transferred to the caller.

void requestFrameFilter(int n, VSNodeRef *node, VSFrameContext *frameCtx)

Requests a frame from a node and returns immediately.

Only use inside a filter’s “getframe” function.

A filter usually calls this function when its activation reason is arInitial. The requested frame can then be retrieved using getFrameFilter(), when the filter’s activation reason is arAllFramesReady or arFrameReady. See VSActivationReason.

It is safe to request a frame more than once. An unimportant consequence of requesting a frame more than once is that the getframe function may be called more than once for the same frame with reason arFrameReady.

It is best to request frames in ascending order, i.e. n, n+1, n+2, etc.

n

The frame number. Negative values will cause an error.

node

The node from which the frame is requested.

frameCtx

The context passed to the filter’s “getframe” function.

const VSVideoInfo *getVideoInfo(VSNodeRef *node)

Returns a pointer to the video info associated with a node. The pointer is valid as long as the node lives.

void setVideoInfo(const VSVideoInfo *vi, int numOutputs, VSNode *node)

Sets the node’s video info.

vi

Pointer to numOutputs VSVideoInfo instances. The structures are copied by the core. The flags are however ignored and replaced by the flags passed to _createFilter.

numOutputs

Number of clips the filter wants to return. Must be greater than 0.

node

Pointer to the node whose video info is to be set.

const VSFormat *getFormatPreset(int id, VSCore *core)

Returns a VSFormat structure from a video format identifier.

Thread-safe.

id

The format identifier: one of VSPresetFormat or a custom registered format.

Returns NULL if the identifier is not known.

const VSFormat *registerFormat(int colorFamily, int sampleType, int bitsPerSample, int subSamplingW, int subSamplingH, VSCore *core)

Registers a custom video format.

Thread-safe.

colorFamily

One of VSColorFamily.

Note

Registering compat formats is not allowed. Only certain privileged built-in filters are allowed to handle compat formats.

sampleType

One of VSSampleType.

bitsPerSample

Number of meaningful bits for a single component. The valid range is 8-32.

For floating point formats, only 16 or 32 bits are allowed.

subSamplingW

log2 of the horizontal chroma subsampling. 0 == no subsampling.

subSamplingH

log2 of the vertical chroma subsampling. The valid range is 0-4.

Note

RGB formats are not allowed to be subsampled in VapourSynth.

Returns a pointer to the created VSFormat object. Its id member contains the attributed format identifier. The pointer is valid as long as the VSCore instance lives. Returns NULL in case an invalid format is described.

If the parameters specify a format that is already registered (including preset formats), then no new format is created and the existing one is returned.

VSMap *createMap(void)

Creates a new property map. It must be deallocated later with freeMap().

void freeMap(VSMap *map)

Frees a map and all the objects it contains.

void clearMap(VSMap *map)

Deletes all the keys and their associated values from the map, leaving it empty.

void setError(VSMap *map, const char *errorMessage)

Adds an error message to a map. The map is cleared first. The error message is copied. In this state the map may only be freed, cleared or queried for the error message.

For errors encountered in a filter’s “getframe” function, use setFilterError.

const char *getError(const VSMap *map)

Returns a pointer to the error message contained in the map, or NULL if there is no error message. The pointer is valid as long as the map lives.

int propNumKeys(const VSMap *map)

Returns the number of keys contained in a property map.

const char *propGetKey(const VSMap *map, int index)

Returns a key from a property map.

Passing an invalid index will cause a fatal error.

The pointer is valid as long as the key exists in the map.

int propDeleteKey(VSMap *map, const char *key)

Removes the property with the given key. All values associated with the key are lost.

Returns 0 if the key isn’t in the map. Otherwise it returns 1.

char propGetType(const VSMap *map, const char *key)

Returns the type of the elements associated with the given key in a property map.

The returned value is one of VSPropTypes. If there is no such key in the map, the returned value is ptUnset.

int propNumElements(const VSMap *map, const char *key)

Returns the number of elements associated with a key in a property map. Returns -1 if there is no such key in the map.

int64_t propGetInt(const VSMap *map, const char *key, int index, int *error)

Retrieves an integer from a map.

Returns the number on success, or 0 in case of error.

If the map has an error set (i.e. if getError() returns non-NULL), VapourSynth will die with a fatal error.

index

Zero-based index of the element.

Use propNumElements() to know the total number of elements associated with a key.

error

One of VSGetPropErrors, or 0 on success.

You may pass NULL here, but then any problems encountered while retrieving the property will cause VapourSynth to die with a fatal error.

const int64_t *propGetIntArray(const VSMap *map, const char *key, int *error)

Retrieves an array of integers from a map. Use this function if there are a lot of numbers associated with a key, because it is faster than calling propGetInt() in a loop.

Returns a pointer to the first element of the array on success, or NULL in case of error.

If the map has an error set (i.e. if getError() returns non-NULL), VapourSynth will die with a fatal error.

Use propNumElements() to know the total number of elements associated with a key.

error

One of VSGetPropErrors, or 0 on success.

You may pass NULL here, but then any problems encountered while retrieving the property will cause VapourSynth to die with a fatal error.

This function was introduced in API R3.1 (VapourSynth R26).

double propGetFloat(const VSMap *map, const char *key, int index, int *error)

Retrieves a floating point number from a map.

Returns the number on success, or 0 in case of error.

If the map has an error set (i.e. if getError() returns non-NULL), VapourSynth will die with a fatal error.

index

Zero-based index of the element.

Use propNumElements() to know the total number of elements associated with a key.

error

One of VSGetPropErrors, or 0 on success.

You may pass NULL here, but then any problems encountered while retrieving the property will cause VapourSynth to die with a fatal error.

const double *propGetFloatArray(const VSMap *map, const char *key, int *error)

Retrieves an array of floating point numbers from a map. Use this function if there are a lot of numbers associated with a key, because it is faster than calling propGetFloat() in a loop.

Returns a pointer to the first element of the array on success, or NULL in case of error.

If the map has an error set (i.e. if getError() returns non-NULL), VapourSynth will die with a fatal error.

Use propNumElements() to know the total number of elements associated with a key.

error

One of VSGetPropErrors, or 0 on success.

You may pass NULL here, but then any problems encountered while retrieving the property will cause VapourSynth to die with a fatal error.

This function was introduced in API R3.1 (VapourSynth R26).

const char *propGetData(const VSMap *map, const char *key, int index, int *error)

Retrieves arbitrary binary data from a map.

Returns a pointer to the data on success, or NULL in case of error.

The array returned is guaranteed to be NULL-terminated. The NULL byte is not considered to be part of the array (propGetDataSize doesn’t count it).

The pointer is valid until the map is destroyed, or until the corresponding key is removed from the map or altered.

If the map has an error set (i.e. if getError() returns non-NULL), VapourSynth will die with a fatal error.

index

Zero-based index of the element.

Use propNumElements() to know the total number of elements associated with a key.

error

One of VSGetPropErrors, or 0 on success.

You may pass NULL here, but then any problems encountered while retrieving the property will cause VapourSynth to die with a fatal error.

int propGetDataSize(const VSMap *map, const char *key, int index, int *error)

Returns the size in bytes of a property of type ptData (see VSPropTypes), or 0 in case of error. The terminating NULL byte added by propSetData() is not counted.

VSNodeRef *propGetNode(const VSMap *map, const char *key, int index, int *error)

Retrieves a node from a map.

Returns a pointer to the node on success, or NULL in case of error.

This function increases the node’s reference count, so freeNode() must be used when the node is no longer needed.

If the map has an error set (i.e. if getError() returns non-NULL), VapourSynth will die with a fatal error.

index

Zero-based index of the element.

Use propNumElements() to know the total number of elements associated with a key.

error

One of VSGetPropErrors, or 0 on success.

You may pass NULL here, but then any problems encountered while retrieving the property will cause VapourSynth to die with a fatal error.

const VSFrameRef *propGetFrame(const VSMap *map, const char *key, int index, int *error)

Retrieves a frame from a map.

Returns a pointer to the frame on success, or NULL in case of error.

This function increases the frame’s reference count, so freeFrame() must be used when the frame is no longer needed.

If the map has an error set (i.e. if getError() returns non-NULL), VapourSynth will die with a fatal error.

index

Zero-based index of the element.

Use propNumElements() to know the total number of elements associated with a key.

error

One of VSGetPropErrors, or 0 on success.

You may pass NULL here, but then any problems encountered while retrieving the property will cause VapourSynth to die with a fatal error.

VSFuncRef *propGetFunc(const VSMap *map, const char *key, int index, int *error)

Retrieves a function from a map.

Returns a pointer to the function on success, or NULL in case of error.

This function increases the function’s reference count, so freeFunc() must be used when the function is no longer needed.

If the map has an error set (i.e. if getError() returns non-NULL), VapourSynth will die with a fatal error.

index

Zero-based index of the element.

Use propNumElements() to know the total number of elements associated with a key.

error

One of VSGetPropErrors, or 0 on success.

You may pass NULL here, but then any problems encountered while retrieving the property will cause VapourSynth to die with a fatal error.

int propSetInt(VSMap *map, const char *key, int64_t i, int append)

Adds a property to a map.

Multiple values can be associated with one key, but they must all be the same type.

key

Name of the property. Alphanumeric characters and the underscore may be used.

i

Value to store.

append

One of VSPropAppendMode.

Returns 0 on success, or 1 if trying to append to a property with the wrong type.

int propSetIntArray(VSMap *map, const char *key, const int64_t *i, int size)

Adds an array of integers to a map. Use this function if there are a lot of numbers to add, because it is faster than calling propSetInt() in a loop.

If map already contains a property with this key, that property will be overwritten and all old values will be lost.

key

Name of the property. Alphanumeric characters and the underscore may be used.

i

Pointer to the first element of the array to store.

size

Number of integers to read from the array. It can be 0, in which case no integers are read from the array, and the property will be created empty.

Returns 0 on success, or 1 if size is negative.

This function was introduced in API R3.1 (VapourSynth R26).

int propSetFloat(VSMap *map, const char *key, double d, int append)

Adds a property to a map.

Multiple values can be associated with one key, but they must all be the same type.

key

Name of the property. Alphanumeric characters and the underscore may be used.

d

Value to store.

append

One of VSPropAppendMode.

Returns 0 on success, or 1 if trying to append to a property with the wrong type.

int propSetFloatArray(VSMap *map, const char *key, const double *d, int size)

Adds an array of floating point numbers to a map. Use this function if there are a lot of numbers to add, because it is faster than calling propSetFloat() in a loop.

If map already contains a property with this key, that property will be overwritten and all old values will be lost.

key

Name of the property. Alphanumeric characters and the underscore may be used.

d

Pointer to the first element of the array to store.

size

Number of floating point numbers to read from the array. It can be 0, in which case no numbers are read from the array, and the property will be created empty.

Returns 0 on success, or 1 if size is negative.

This function was introduced in API R3.1 (VapourSynth R26).

int propSetData(VSMap *map, const char *key, const char *data, int size, int append)

Adds a property to a map.

Multiple values can be associated with one key, but they must all be the same type.

key

Name of the property. Alphanumeric characters and the underscore may be used.

data

Value to store.

This function copies the data, so the pointer should be freed when no longer needed.

size

The number of bytes to copy. If this is negative, everything up to the first NULL byte will be copied.

This function will always add a NULL byte at the end of the data.

append

One of VSPropAppendMode.

Returns 0 on success, or 1 if trying to append to a property with the wrong type.

int propSetNode(VSMap *map, const char *key, VSNodeRef *node, int append)

Adds a property to a map.

Multiple values can be associated with one key, but they must all be the same type.

key

Name of the property. Alphanumeric characters and the underscore may be used.

node

Value to store.

This function will increase the node’s reference count, so the pointer should be freed when no longer needed.

append

One of VSPropAppendMode.

Returns 0 on success, or 1 if trying to append to a property with the wrong type.

int propSetFrame(VSMap *map, const char *key, const VSFrameRef *f, int append)

Adds a property to a map.

Multiple values can be associated with one key, but they must all be the same type.

key

Name of the property. Alphanumeric characters and the underscore may be used.

f

Value to store.

This function will increase the frame’s reference count, so the pointer should be freed when no longer needed.

append

One of VSPropAppendMode.

Returns 0 on success, or 1 if trying to append to a property with the wrong type.

int propSetFunc(VSMap *map, const char *key, VSFuncRef *func, int append)

Adds a property to a map.

Multiple values can be associated with one key, but they must all be the same type.

key

Name of the property. Alphanumeric characters and the underscore may be used.

func

Value to store.

This function will increase the function’s reference count, so the pointer should be freed when no longer needed.

append

One of VSPropAppendMode.

Returns 0 on success, or 1 if trying to append to a property with the wrong type.

VSPlugin *getPluginById(const char *identifier, VSCore *core)

Returns a pointer to the plugin with the given identifier, or NULL if not found.

identifier

Reverse URL that uniquely identifies the plugin.

VSPlugin *getPluginByNs(const char *ns, VSCore *core)

Returns a pointer to the plugin with the given namespace, or NULL if not found.

getPluginById should be used instead.

ns

Namespace.

VSMap *getPlugins(VSCore *core)

Returns a map containing a list of all loaded plugins. The map must be freed when no longer needed.

Keys:

Meaningless unique strings.

Values:

Namespace, identifier, and full name, separated by semicolons.

VSMap *getFunctions(VSPlugin *plugin)

Returns a map containing a list of the filters exported by a plugin. The map must be freed when no longer needed.

Keys:

The filter names.

Values:

The filter name followed by its argument string, separated by a semicolon.

const char *getPluginPath(const VSPlugin *plugin)

Returns the absolute path to the plugin, including the plugin’s file name. This is the real location of the plugin, i.e. there are no symbolic links in the path.

Path elements are always delimited with forward slashes.

VapourSynth retains ownership of the returned pointer.

This function was introduced in VapourSynth R25 without bumping the API version (R3).

VSFuncRef *createFunc(VSPublicFunction func, void *userData, VSFreeFuncData free, VSCore *core, const VSAPI *vsapi)

func

typedef void (VS_CC *VSPublicFunction)(const VSMap *in, VSMap *out, void *userData, VSCore *core, const VSAPI *vsapi)

User-defined function that may be called in any context.

userData

Pointer passed to func.

free

typedef void (VS_CC *VSFreeFuncData)(void *userData)

Callback tasked with freeing userData.

VSFuncRef *cloneFuncRef(VSFuncRef *f)

Duplicates a func reference. This new reference has to be deleted with freeFunc() when it is no longer needed.

void callFunc(VSFuncRef *func, const VSMap *in, VSMap *out, VSCore *core, const VSAPI *vsapi)

Calls a function. If the call fails out will have an error set.

func

Function to be called.

in

Arguments passed to func.

out

Returned values from func.

core

Must be NULL.

vsapi

Must be NULL.

void freeFunc(VSFuncRef *f)

Deletes a function reference, releasing the caller’s ownership of the function.

It is safe to pass NULL.

Don’t try to use the function once the reference has been deleted.

void createFilter(const VSMap *in, VSMap *out, const char *name, VSFilterInit init, VSFilterGetFrame getFrame, VSFilterFree free, int filterMode, int flags, void *instanceData, VSCore *core)

Creates a new filter node.

in

List of the filter’s arguments.

out

List of the filter’s return values (clip(s) or an error).

name

Instance name. Please make it the same as the filter’s name.

init

The filter’s “init” function. Must not be NULL.

getFrame

The filter’s “getframe” function. Must not be NULL.

free

The filter’s “free” function. Can be NULL.

filterMode

One of VSFilterMode. Indicates the level of parallelism supported by the filter.

flags

Set to nfNoCache (VSNodeFlags) if the frames generated by the filter should not be cached. It is useful for filters that only shuffle frames around without modifying them (e.g. std.Interleave). For most filters this should be 0.

instanceData

A pointer to the private filter data. This pointer will be passed to the init, getFrame, and free functions. It should be freed by the free function.

After this function returns, out will contain the new node(s) in the “clip” property, or an error, if something went wrong.

void registerFunction(const char *name, const char *args, VSPublicFunction argsFunc, void *functionData, VSPlugin *plugin)

VSMap *invoke(VSPlugin *plugin, const char *name, const VSMap *args)

Invokes a filter.

invoke() makes sure the filter has no compat input nodes, checks that the args passed to the filter are consistent with the argument list registered by the plugin that contains the filter, calls the filter’s “create” function, and checks that the filter doesn’t return any compat nodes. If everything goes smoothly, the filter will be ready to generate frames after invoke() returns.

Thread-safe.

plugin

A pointer to the plugin where the filter is located. Must not be NULL.

See getPluginById() and getPluginByNs().

name

Name of the filter to invoke.

args

Arguments for the filter.

Returns a map containing the filter’s return value(s). The caller gets ownership of the map. Use getError() to check if the filter was invoked successfully.

Most filters will either add an error to the map, or one or more clips with the key “clip”. The exception to this are functions, for example LoadPlugin, which doesn’t return any clips for obvious reasons.

void setFilterError(const char *errorMessage, VSFrameContext *frameCtx)

Adds an error message to a frame context, replacing the existing message, if any.

This is the way to report errors in a filter’s “getframe” function. Such errors are not necessarily fatal, i.e. the caller can try to request the same frame again.

int getOutputIndex(VSFrameContext *frameCtx)

Returns the index of the node from which the frame is being requested.

Only needed in the “getframe” function of filters that return more than one clip.

void queryCompletedFrame(VSNodeRef **node, int *n, VSFrameContext *frameCtx)

Warning

This function has several issues and may or may not return the actual node or frame number.

Finds out which requested frame is ready. To be used in a filter’s “getframe” function, when it is called with activationReason arFrameReady.

void releaseFrameEarly(VSNodeRef *node, int n, VSFrameContext *frameCtx)

Normally a reference is kept to all requested frames until the current frame is complete. If a filter scans a large number of frames this can consume all memory, instead the filter should release the internal frame references as well immediately by calling this function.

Only use inside a filter’s “getframe” function.

Functions

const VSAPI* getVapourSynthAPI(int version)

Returns a pointer to the global VSAPI instance.

Returns NULL if the requested API version is not supported or if the system does not meet the minimum requirements to run VapourSynth.

Writing plugins

A simple VapourSynth plugin which exports one filter will contain five functions: an entry point (called VapourSynthPluginInit), a function tasked with creating a filter instance (often called fooCreate), an “init” function (often called fooInit), a “getframe” function (often called fooGetframe), and a “free” function (often called fooFree). These functions are described below.

Another thing a filter requires is an object for storing a filter instance’s private data. This object will usually contain the filter’s input nodes (if it has any) and a VSVideoInfo struct describing the video the filter wants to return.

The sdk folder in the VapourSynth source contains some examples.

typedef void (VS_CC *VSInitPlugin)(VSConfigPlugin configFunc, VSRegisterFunction registerFunc, VSPlugin *plugin)

A plugin’s entry point. It must be called VapourSynthPluginInit. This function is called after the core loads the shared library. Its purpose is to configure the plugin and to register the filters the plugin wants to export.

configFunc

typedef void (VS_CC *VSConfigPlugin)(const char *identifier, const char *defaultNamespace, const char *name, int apiVersion, int readonly, VSPlugin *plugin)

Configures the plugin. Call once, before calling registerFunc.

identifier

Reverse URL that must uniquely identify the plugin.

If you don’t own a domain then make one up that’s related to the plugin name.

Example: “com.vapoursynth.std”

defaultNamespace

Namespace where the plugin’s filters will go. This, too, must be unique.

Only lowercase letters and the underscore should be used, and it shouldn’t be too long. Additionally, words that are special to Python, e.g. “del”, should be avoided.

Example: “resize”

name

Plugin name in readable form.

apiVersion

The VapourSynth API version the plugin uses.

Use the VAPOURSYNTH_API_VERSION macro.

readonly

If set to 0, the plugin can export new filters after initialisation. The built-in Avisynth compat plugin uses this feature to add filters at runtime, as they are loaded. Most plugins should set this to 1.

plugin

Pointer to the plugin object in the core, as passed to VapourSynthPluginInit().

registerFunc

typedef void (VS_CC *VSRegisterFunction)(const char *name, const char *args, VSPublicFunction argsFunc, void *functionData, VSPlugin *plugin)

Function that registers a filter exported by the plugin. A plugin can export any number of filters.

name

Filter name. The characters allowed are letters, numbers, and the underscore. The first character must be a letter. In other words: ^[a-zA-Z][a-zA-Z0-9_]*$

Filter names should be PascalCase.

args

String containing the filter’s list of arguments.

Arguments are separated by a semicolon. Each argument is made of several fields separated by a colon. Don’t insert additional whitespace characters, or VapourSynth will die.

Fields:
The argument name.

The same characters are allowed as for the filter’s name. Argument names should be all lowercase and use only letters and the underscore.

The type.

“int”: int64_t

“float”: double

“data”: const char*

“clip”: const VSNodeRef*

“frame”: const VSFrameRef*

“func”: const VSFuncRef*

It is possible to declare an array by appending “[]” to the type.

“opt”

If the parameter is optional.

“empty”

For arrays that are allowed to be empty.

The following example declares the arguments “blah”, “moo”, and “asdf”:

blah:clip;moo:int[]:opt;asdf:float:opt;
argsFunc

typedef void (VS_CC *VSPublicFunction)(const VSMap *in, VSMap *out, void *userData, VSCore *core, const VSAPI *vsapi)

User-defined function called by the core to create an instance of the filter. This function is often named fooCreate.

In this function, the filter’s input parameters should be retrieved and validated, the filter’s private instance data should be initialised, and createFilter() should be called. This is where the filter should perform any other initialisation it requires.

If for some reason you cannot create the filter, you have to free any created node references using freeNode(), call setError() on out, and return.

in

Input parameter list.

Use propGetInt() and friends to retrieve a parameter value.

The map is guaranteed to exist only until the filter’s “init” function returns. In other words, pointers returned by propGetData() will not be usable in the filter’s “getframe” and “free” functions.

out

Output parameter list. createFilter() will add the output node(s) with the key named “clip”, or an error, if something went wrong.

userData

Pointer that was passed to registerFunction().

functionData

Pointer to user data that gets passed to argsFunc when creating a filter. Useful to register multiple filters using a single argsFunc function.

plugin

Pointer to the plugin object in the core, as passed to VapourSynthPluginInit().

plugin

The plugin object in the core. Pass to configFunc and registerFunc.

typedef void (VS_CC *VSFilterInit)(VSMap *in, VSMap *out, void **instanceData, VSNode *node, VSCore *core, const VSAPI *vsapi)

A filter’s “init” function.

This function is called by createFilter() (indirectly).

This is the only place where setVideoInfo() can be called. There is no reason to do anything else here.

If an error occurs in this function:

  • free the input nodes, if any

  • free the instance data

  • free whatever else got allocated so far (obviously)

  • call setError() on the out map

  • return

instanceData

Pointer to a pointer to the filter’s private instance data.

typedef const VSFrameRef *(VS_CC *VSFilterGetFrame)(int n, int activationReason, void **instanceData, void **frameData, VSFrameContext *frameCtx, VSCore *core, const VSAPI *vsapi)

A filter’s “getframe” function. It is called by the core when it needs the filter to generate a frame.

It is possible to allocate local data, persistent during the multiple calls requesting the output frame.

In case of error, call setFilterError(), free *frameData if required, and return NULL.

Depending on the VSFilterMode set for the filter, multiple output frames could be requested concurrently.

It is never called concurrently for the same frame number.

n

Requested frame number.

activationReason

One of VSActivationReason.

This function is first called with activationReason arInitial. At this point the function should request the input frames it needs and return NULL. When one or all of the requested frames are ready, this function is called again with activationReason arFrameReady or arAllFramesReady. The function should only return a frame when called with activationReason arAllFramesReady.

In the case of arFrameReady, use queryCompletedFrame() to find out which of the requested frames is ready.

Most filters will only need to handle arInitial and arAllFramesReady.

instanceData

The filter’s private instance data.

frameData

Optional private data associated with output frame number n. It must be deallocated before the last call for the given frame (arAllFramesReady or error).

By default, frameData is a pointer to NULL.

Return a reference to the output frame number n when it is ready, or NULL. The ownership of the frame is transferred to the caller.

typedef void (VS_CC *VSFilterFree)(void *instanceData, VSCore *core, const VSAPI *vsapi)

A filter’s “free” function.

This is where the filter should free everything it allocated, including its instance data.

instanceData

The filter’s private instance data.