VapourSynth4.h
Table of contents
- Macros
- Enums
- Structs
-
Functions that deal with the core:
Functions that deal with logging
Functions that deal with frames:
Functions that deal with filters and nodes:
Functions that deal with formats:
Functions that deal with maps:
Functions that deal with plugins and plugin functions:
Functions that deal with wrapped external functions:
Functions that are used to fetch frames and inside filters:
- Functions
- Writing plugins
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
VapourSynth4.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) VapourSynthPluginInit2(...) { ... }
VAPOURSYNTH_API_MAJOR
Major API version.
VAPOURSYNTH_API_MINOR
Minor API version. It is bumped when new functions are added to VSAPI or core behavior is noticeably changed.
VAPOURSYNTH_API_VERSION
API version. The high 16 bits are VAPOURSYNTH_API_MAJOR, the low 16 bits are VAPOURSYNTH_API_MINOR.
VS_AUDIO_FRAME_SAMPLES
The number of audio samples in an audio frame. It is a static number to make it possible to calculate which audio frames are needed to retrieve specific samples.
VS_MAKE_VERSION
Used to create version numbers. The first argument is the major version and second is the minor.
Enums
enum VSColorFamily
cfUndefined
cfGray
cfRGB
cfYUV
enum VSSampleType
stInteger
stFloat
enum VSPresetVideoFormat
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. All formats are planar. See the header for all currently defined video format presets.
pf*
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.
fmFrameState
For compatibility with other filtering architectures. DO NOT USE IN NEW FILTERS. 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 VSMediaType
Used to indicate the type of a VSFrame or VSNode object.
mtVideo
mtAudio
enum VSAudioChannels
Audio channel positions as an enum. Mirrors the FFmpeg audio channel constants in older api versions. See the header for all available values.
ac*
enum VSPropertyType
Types of properties that can be stored in a VSMap.
ptUnset
ptInt
ptFloat
ptData
ptFunction
ptVideoNode
ptAudioNode
ptVideoFrame
ptAudioFrame
enum VSMapPropertyError
When a mapGet* function fails, it returns one of these in the err parameter.
All errors are non-zero.
peSuccess
peUnset
The requested key was not found in the map.
peType
The wrong function was used to retrieve the property. E.g. mapGetInt() was used on a property of type ptFloat.
peIndex
The requested index was out of bounds.
peError
The map has the error state set.
enum VSMapAppendMode
Controls the behaviour of mapSetInt() and friends.
maReplace
All existing values associated with the key will be replaced with the new value.
maAppend
The new value will be appended to the list of existing values associated with the key.
enum VSActivationReason
See VSFilterGetFrame.
arInitial
arAllFramesReady
arError
enum VSMessageType
See addLogHandler().
mtDebug
mtInformation
mtWarning
mtCritical
mtFatal
enum VSCoreCreationFlags
Options when creating a core.
ccfEnableGraphInspection
Required to use the graph inspection api functions. Increases memory usage due to the extra information stored.
ccfDisableAutoLoading
Don’t autoload any user plugins. Core plugins are always loaded.
ccfDisableLibraryUnloading
Don’t unload plugin libraries when the core is destroyed. Due to a small amount of memory leaking every load and unload (windows feature, not my fault) of a library this may help in applications with extreme amount of script reloading.
enum VSPluginConfigFlags
Options when loading a plugin.
pcModifiable
Allow functions to be added to the plugin object after the plugin loading phase. Mostly useful for Avisynth compatibility and other foreign plugin loaders.
enum VSDataTypeHint
Since the data type can contain both pure binary data and printable strings the type also contains a hint for whether or not it is human readable. Generally the unknown type should be very rare and is almost only created as an artifact of API3 compatibility.
dtUnknown
dtBinary
dtUtf8
enum VSRequestPattern
Describes the upstream frame request pattern of a filter.
rpGeneral
Anything goes. Note that filters that may be requesting beyond the end of a VSNode length in frames (repeating the last frame) should use rpGeneral and not any of the other modes.
rpNoFrameReuse
Will only request an input frame at most once if all output frames are requested exactly one time. This includes filters such as Trim, Reverse, SelectEvery.
rpStrictSpatial
Only requests frame N to output frame N. The main difference to rpNoFrameReuse is that the requested frame is always fixed and known ahead of time. Filter examples Lut, Expr (conditionally, see rpGeneral note) and similar.
enum VSCacheMode
Describes how the output of a node is cached.
cmAuto
Cache is enabled or disabled based on the reported request patterns and number of consumers.
cmForceDisable
Never cache anything.
cmForceEnable
Always use the cache.
Structs
Most structs are opaque and their contents can only be accessed using functions in the API.
struct VSFrame
A frame that can hold audio or video data.
Each row of pixels in a frame is guaranteed to have an alignment of at least 32 bytes. Two frames with the same width and bytes per sample are guaranteed to have the same stride.
Audio data is also guaranteed to be at least 32 byte aligned.
Any data can be attached to a frame, using a VSMap.
struct VSNode
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, namespacestd), the resizers (identifiercom.vapoursynth.resize, namespaceresize), and the Avisynth compatibility module, if running in Windows (identifiercom.vapoursynth.avisynth, namespaceavs).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 VapourSynthPluginInit2() 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 version of the plugin.
The VapourSynth API version the plugin requires.
A file name.
Things you can do with a VSPlugin:
Enumerate all the filters it exports, using getNextPluginFunction().
Invoke one of its filters, using invoke().
Get its location in the file system, using getPluginPath().
All loaded plugins (including built-in) can be enumerated with getNextPlugin().
Once loaded, a plugin only gets unloaded when the VapourSynth core is freed.
struct VSPluginFunction
A function belonging to a Vapoursynth plugin. This object primarily exists so a plugin’s name, argument list and return type can be queried by editors.
One peculiarity is that plugin functions cannot be invoked using a VSPluginFunction pointer but is instead done using invoke() which takes a VSPlugin and the function name as a string.
struct VSFunction
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, VSNode, VSFrame, or VSFunction.
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 “map”.
A map’s contents can be erased with clearMap().
struct VSLogHandle
Opaque type representing a registered logger.
struct VSFrameContext
Opaque type representing the current frame request in a filter.
struct VSVideoFormat
Describes the format of a clip.
Use queryVideoFormat() to fill it in with proper error checking. Manually filling out the struct is allowed but discouraged since illegal combinations of values will cause undefined behavior.
- 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 VSVideoInfo
Contains information about a clip.
- VSVideoFormat format
Format of the clip. Will have colorFamily set to cfUndefined if the 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.
struct VSAudioFormat
Describes the format of a clip.
Use queryAudioFormat() to fill it in with proper error checking. Manually filling out the struct is allowed but discouraged since illegal combinations of values will cause undefined behavior.
- 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 numChannels
Number of audio channels.
- uint64_t channelLayout
A bitmask representing the channels present using the constants in 1 left shifted by the constants in VSAudioChannels.
struct VSAudioInfo
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 VSFilterDependency
Contains information about a VSCore instance.
- VSNode *source
The node frames are requested from.
- int requestPattern
A value from VSRequestPattern.
struct VSPLUGINAPI
This struct is used to access VapourSynth’s API when a plugin is initially loaded.
int getAPIVersion()
See getAPIVersion() in the struct VSAPI.
int configPlugin(const char *identifier, const char *pluginNamespace, const char *name, int pluginVersion, int apiVersion, int flags, VSPlugin *plugin)
Used to provide information about a plugin when loaded. Must be called exactly once from the VapourSynthPluginInit2 entry point. It is recommended to use the VS_MAKE_VERSION macro when providing the pluginVersion. If you don’t know the specific apiVersion you actually require simply pass VAPOURSYNTH_API_VERSION to match the header version you’re compiling against. The flags consist of values from VSPluginConfigFlags ORed together but should for most plugins typically be 0.
Returns non-zero on success.
int registerFunction(const char *name, const char *args, const char *returnType, VSPublicFunction argsFunc, void *functionData, VSPlugin *plugin)
See registerFunction() in the struct VSAPI.
struct VSAPI
This giant struct is the way to access VapourSynth’s public API.
VSCore *createCore(int flags)
Creates the VapourSynth processing core and returns a pointer to it. It is possible to create multiple cores but in most cases it shouldn’t be needed.
- flags
VSCoreCreationFlags ORed together if desired. Pass 0 for sane defaults that should suit most uses.
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.
int64_t setMaxCacheSize(int64_t bytes, VSCore *core)
Sets the maximum size of the framebuffer cache. Returns the new maximum size.
int setThreadCount(int threads, VSCore *core)
Sets the number of threads used for processing. Pass 0 to automatically detect. Returns the number of threads that will be used for processing.
void getCoreInfo(VSCore *core, VSCoreInfo *info)
Returns information about the VapourSynth core.
int getAPIVersion()
Returns the highest VAPOURSYNTH_API_VERSION the library support.
void logMessage(int msgType, const char *msg, VSCore *core)
Send a message through VapourSynth’s logging framework. See addLogHandler.
- msgType
The type of message. One of VSMessageType.
If msgType is mtFatal, VapourSynth will call abort() after delivering the message.
- msg
The message.
VSLogHandle *addLogHandler(VSLogHandler handler, VSLogHandlerFree free, void *userData, VSCore *core)
Installs a custom handler for the various error messages VapourSynth emits. The message handler is per VSCore instance. Returns a unique handle.
If no log handler is installed up to a few hundred messages are cached and will be delivered as soon as a log handler is attached. This behavior exists mostly so that warnings when auto-loading plugins (default behavior) won’t disappear-
- handler
typedef void (VS_CC *VSLogHandler)(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 *VSLogHandlerFree)(void *userData)
Called when a handler is removed.
- userData
Pointer that gets passed to the message handler.
int removeLogHandler(VSLogHandle *handle, VSCore *core)
Removes a custom handler. Return non-zero on success and zero if the handle is invalid.
- handle
Handle obtained from addLogHandler().
VSFrame *newVideoFrame(const VSVideoFormat *format, int width, int height, const VSFrame *propSrc, VSCore *core)
Creates a new video 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().
VSFrame *newVideoFrame2(const VSVideoFormat *format, int width, int height, const VSFrame **planeSrc, const int *planes, const VSFrame *propSrc, VSCore *core)
Creates a new video 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 VSFrame * frames[3] = { frameA, frameB, frameC }; const int planes[3] = { 1, 0, 2 }; VSFrame * 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.
VSFrame *newAudioFrame(const VSAudioFormat *format, int numSamples, const VSFrame *propSrc, VSCore *core)
Creates a new audio 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 audio format. Must not be NULL.
- numSamples
The number of samples in the frame. All audio frames apart from the last one returned by a filter must have VS_AUDIO_FRAME_SAMPLES.
- 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 newAudioFrame2().
VSFrame *newAudioFrame2(const VSAudioFormat *format, int numSamples, const VSFrame **channelSrc, const int *channels, const VSFrame *propSrc, VSCore *core)
Creates a new audio 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 audio format. Must not be NULL.
- numSamples
The number of samples in the frame. All audio frames apart from the last one returned by a filter must have VS_AUDIO_FRAME_SAMPLES.
- channelSrc
Array of frames from which channels will be copied. If any elements of the array are NULL, the corresponding planes in the new frame will contain uninitialised memory.
- channels
Array of channel numbers indicating which channel to copy from the corresponding source frame. Note that the number refers to the nth channel and not a channel name constant.
- 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().
void freeFrame(const VSFrame *f)
Decrements the reference count of a frame and deletes it when it reaches 0.
It is safe to pass NULL.
VSFrame *copyFrame(const VSFrame *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.
ptrdiff_t getStride(const VSFrame *f, int plane)
Returns the distance in bytes between two consecutive lines of a plane of a video frame. The stride is always positive. Returns 0 if the requested plane doesn’t exist or if it isn’t a video frame.
const uint8_t *getReadPtr(const VSFrame *f, int plane)
Returns a read-only pointer to a plane or channel of a frame. Returns NULL if an invalid plane or channel number is passed.
Note
Don’t assume all three planes of a frame are allocated in one contiguous chunk (they’re not).
uint8_t *getWritePtr(VSFrame *f, int plane)
Returns a read-write pointer to a plane or channel of a frame. Returns NULL if an invalid plane or channel number is passed.
Note
Don’t assume all three planes of a frame are allocated in one contiguous chunk (they’re not).
const VSVideoFormat *getVideoFrameFormat(const VSFrame *f)
Retrieves the format of a video frame.
const VSAudioFormat *getAudioFrameFormat(const VSFrame *f)
Retrieves the format of an audio frame.
int getFrameType(const VSFrame *f)
Returns a value from VSMediaType to distinguish audio and video frames.
int getFrameWidth(const VSFrame *f, int plane)
Returns the width of a plane of a given video frame, in pixels. The width depends on the plane number because of the possible chroma subsampling. Returns 0 for audio frames.
int getFrameHeight(const VSFrame *f, int plane)
Returns the height of a plane of a given video frame, in pixels. The height depends on the plane number because of the possible chroma subsampling. Returns 0 for audio frames.
int getFrameLength(const VSFrame *f)
Returns the number of audio samples in a frame. Always returns 1 for video frames.
void createVideoFilter(VSMap *out, const char *name, const VSVideoInfo *vi, VSFilterGetFrame getFrame, VSFilterFree free, int filterMode, const VSFilterDependency *dependencies, int numDeps, void *instanceData, VSCore *core)
Creates a new video filter node.
- out
Output map for the filter node.
- name
Instance name. Please make it the same as the filter’s name for easy identification.
- vi
The output format of the filter.
- 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.
- dependencies
An array of nodes the filter requests frames from and the access pattern. Used to more efficiently configure caches.
- numDeps
Length of the dependencies array.
- instanceData
A pointer to the private filter data. This pointer will be passed to the getFrame and free functions. It should be freed by the free function.
After this function returns, out will contain the new node appended to the “clip” property, or an error, if something went wrong.
VSNode *createVideoFilter2(const char *name, const VSVideoInfo *vi, VSFilterGetFrame getFrame, VSFilterFree free, int filterMode, const VSFilterDependency *dependencies, int numDeps, void *instanceData, VSCore *core)
Identical to createVideoFilter except that the new node is returned instead of appended to the out map. Returns NULL on error.
void createAudioFilter(VSMap *out, const char *name, const VSAudioInfo *ai, VSFilterGetFrame getFrame, VSFilterFree free, int filterMode, const VSFilterDependency *dependencies, int numDeps, void *instanceData, VSCore *core)
Creates a new video filter node.
- out
Output map for the filter node.
- name
Instance name. Please make it the same as the filter’s name for easy identification.
- ai
The output format of the filter.
- 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.
- dependencies
An array of nodes the filter requests frames from and the access pattern. Used to more efficiently configure caches.
- numDeps
Length of the dependencies array.
- instanceData
A pointer to the private filter data. This pointer will be passed to the getFrame and free functions. It should be freed by the free function.
After this function returns, out will contain the new node appended to the “clip” property, or an error, if something went wrong.
VSNode *createAudioFilter2(const char *name, const VSAudioInfo *ai, VSFilterGetFrame getFrame, VSFilterFree free, int filterMode, const VSFilterDependency *dependencies, int numDeps, void *instanceData, VSCore *core)
Identical to createAudioFilter except that the new node is returned instead of appended to the out map. Returns NULL on error.
int setLinearFilter(VSNode *node)
Must be called immediately after audio or video filter creation. Returns the upper bound of how many additional frames it is reasonable to pass to cacheFrame when trying to make a request more linear.
void setCacheMode(VSNode *node, int mode)
Determines the strategy for frame caching. Pass a VSCacheMode constant. Mostly useful for cache debugging since the auto mode should work well in just about all cases. Calls to this function may also be silently ignored.
Resets the cache to default options when called, discarding setCacheOptions changes.
void setCacheOptions(VSNode *node, int fixedSize, int maxSize, int maxHistorySize)
Call after setCacheMode or the changes will be discarded. Sets internal details of a node’s associated cache. Calls to this function may also be silently ignored.
- fixedSize
Set to non-zero to make the cache always hold maxSize frames.
- maxSize
The maximum number of frames to cache. Note that this value is automatically adjusted using an internal algorithm unless fixedSize is set.
- maxHistorySize
How many frames that have been recently evicted from the cache to keep track off. Used to determine if growing or shrinking the cache is beneficial. Has no effect when fixedSize is set.
void freeNode(VSNode *node)
Decreases the reference count of a node and destroys it once it reaches 0.
It is safe to pass NULL.
int getNodeType(VSNode *node)
Returns VSMediaType. Used to determine if a node is of audio or video type.
const VSVideoInfo *getVideoInfo(VSNode *node)
Returns a pointer to the video info associated with a node. The pointer is valid as long as the node lives. It is undefined behavior to pass a non-video node.
const VSAudioInfo *getAudioInfo(VSNode *node)
Returns a pointer to the audio info associated with a node. The pointer is valid as long as the node lives. It is undefined behavior to pass a non-audio node.
int getVideoFormatName(const VSVideoFormat *format, char *buffer)
Tries to output a fairly human-readable name of a video format.
- format
The input video format.
- buffer
Destination buffer. At most 32 bytes including terminating NULL will be written.
Returns non-zero on success.
int getAudioFormatName(const VSAudioFormat *format, char *buffer)
Tries to output a fairly human-readable name of an audio format.
- format
The input audio format.
- buffer
Destination buffer. At most 32 bytes including terminating NULL will be written.
Returns non-zero on success.
int queryVideoFormat(VSVideoFormat *format, int colorFamily, int sampleType, int bitsPerSample, int subSamplingW, int subSamplingH, VSCore *core)
Fills out a VSVideoInfo struct based on the provided arguments. Validates the arguments before filling out format.
- format
The struct to fill out.
- colorFamily
One of VSColorFamily.
- 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. The valid range is 0-4.
- subSamplingH
log2 of the vertical chroma subsampling. 0 == no subsampling. The valid range is 0-4.
Note
RGB formats are not allowed to be subsampled in VapourSynth.
Returns non-zero on success.
int queryAudioFormat(VSAudioFormat *format, int sampleType, int bitsPerSample, uint64_t channelLayout, VSCore *core)
Fills out a VSAudioFormat struct based on the provided arguments. Validates the arguments before filling out format.
- format
The struct to fill out.
- sampleType
One of VSSampleType.
- bitsPerSample
Number of meaningful bits for a single component. The valid range is 8-32.
For floating point formats only 32 bits are allowed.
- channelLayout
A bitmask constructed from bitshifted constants in VSAudioChannels. For example stereo is expressed as (1 << acFrontLeft) | (1 << acFrontRight).
Returns non-zero on success.
uint32_t queryVideoFormatID(int colorFamily, int sampleType, int bitsPerSample, int subSamplingW, int subSamplingH, VSCore *core)
Get the id associated with a video format. Similar to queryVideoFormat() except that it returns a format id instead of filling out a VSVideoInfo struct.
- colorFamily
One of VSColorFamily.
- 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. The valid range is 0-4.
- subSamplingH
log2 of the vertical chroma subsampling. 0 == no subsampling. The valid range is 0-4.
Note
RGB formats are not allowed to be subsampled in VapourSynth.
Returns a valid format id if the provided arguments are valid, on error 0 is returned.
int getVideoFormatByID(VSVideoFormat *format, uint32_t id, VSCore *core)
Fills out the VSVideoFormat struct passed to format based
- format
The struct to fill out.
- id
The format identifier: one of VSPresetVideoFormat or a value gotten from queryVideoFormatID.
Returns 0 on failure and non-zero on success.
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.
const char *mapGetError(const VSMap *map)
Returns a pointer to the error message contained in the map, or NULL if there is no error set. The pointer is valid until the next modifying operation on the map.
void mapSetError(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.
int mapNumKeys(const VSMap *map)
Returns the number of keys contained in a property map.
const char *mapGetKey(const VSMap *map, int index)
Returns the nth 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 mapDeleteKey(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.
int mapNumElements(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.
int mapGetType(const VSMap *map, const char *key)
Returns a value from VSPropertyType representing type of elements in the given key. If there is no such key in the map, the returned value is ptUnset. Note that also empty arrays created with mapSetEmpty are typed.
int mapSetEmpty(const VSMap *map, const char *key, int type)
Creates an empty array of type in key. Returns non-zero value on failure due to key already existing or having an invalid name.
int64_t mapGetInt(const VSMap *map, const char *key, int index, int *error)
Retrieves an integer from a specified key in a map.
Returns the number on success, or 0 in case of error.
If the map has an error set (i.e. if mapGetError() returns non-NULL), VapourSynth will die with a fatal error.
- index
Zero-based index of the element.
Use mapNumElements() to know the total number of elements associated with a key.
- error
One of VSMapPropertyError, peSuccess 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 *mapGetIntArray(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 mapGetInt() in a loop.
Returns a pointer to the first element of the array on success, or NULL in case of error. Use mapNumElements() to know the total number of elements associated with a key.
See mapGetInt() for a complete description of the arguments and general behavior.
int mapSetInt(VSMap *map, const char *key, int64_t i, int append)
Sets an integer to the specified key in 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 underscore may be used.
- i
Value to store.
- append
One of VSMapAppendMode.
Returns 0 on success, or 1 if trying to append to a property with the wrong type to an existing key.
int mapSetIntArray(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 mapSetInt() 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 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.
float mapGetFloatSaturated(const VSMap *map, const char *key, int index, int *error)
Works just like mapGetFloat() except that the value returned is also converted to a float.
const double *mapGetFloatArray(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 mapGetFloat() in a loop.
Returns a pointer to the first element of the array on success, or NULL in case of error. Use mapNumElements() to know the total number of elements associated with a key.
See mapGetInt() for a complete description of the arguments and general behavior.
int mapSetFloatArray(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 mapSetFloat() 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 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.
const char *mapGetData(const VSMap *map, const char *key, int index, int *error)
Retrieves arbitrary binary data from a map. Checking mapGetDataTypeHint() may provide a hint about whether or not the data is human readable.
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 (mapGetDataSize 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.
See mapGetInt() for a complete description of the arguments and general behavior.
int mapGetDataSize(const VSMap *map, const char *key, int index, int *error)
Returns the size in bytes of a property of type ptData (see VSPropertyType), or 0 in case of error. The terminating NULL byte added by mapSetData() is not counted.
See mapGetInt() for a complete description of the arguments and general behavior.
int mapGetDataTypeHint(const VSMap *map, const char *key, int index, int *error)
Returns the size in bytes of a property of type ptData (see VSPropertyType), or 0 in case of error. The terminating NULL byte added by mapSetData() is not counted.
See mapGetInt() for a complete description of the arguments and general behavior.
int mapSetData(VSMap *map, const char *key, const char *data, int size, int type, int append)
Sets binary data to the specified key in 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. A terminating NULL is always added to the copied data but not included in the total size to make string handling easier.
- size
The number of bytes to copy. If this is negative, everything up to the first NULL byte will be copied.
- type
One of VSDataTypeHint to hint whether or not it is human readable data.
- append
One of VSMapAppendMode.
Returns 0 on success, or 1 if trying to append to a property with the wrong type.
VSFunctionRef *mapGetFunc(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 freeFunction() must be used when the function is no longer needed.
See mapGetInt() for a complete description of the arguments and general behavior.
VSPlugin *getPluginByNamespace(const char *ns, VSCore *core)
Returns a pointer to the plugin with the given namespace, or NULL if not found.
getPluginByID is generally a better option.
- ns
Namespace.
VSPlugin *getNextPlugin(VSPlugin *plugin, VSCore *core)
Used to enumerate over all currently loaded plugins. The order is fixed but provides no other guarantees.
- plugin
Current plugin. Pass NULL to get the first plugin.
Returns a pointer to the next plugin in order or NULL if the final plugin has been reached.
const char *getPluginName(VSPlugin *plugin)
Returns the name of the plugin that was passed to configPlugin.
const char *getPluginID(VSPlugin *plugin)
Returns the identifier of the plugin that was passed to configPlugin.
const char *getPluginNamespace(VSPlugin *plugin)
Returns the namespace the plugin currently is loaded in.
VSPluginFunction *getNextPluginFunction(VSPluginFunction *func, VSPlugin *plugin)
Used to enumerate over all functions in a plugin. The order is fixed but provides no other guarantees.
- func
Current function. Pass NULL to get the first function.
- plugin
The plugin to enumerate functions in.
Returns a pointer to the next function in order or NULL if the final function has been reached.
VSPluginFunction *getPluginFunctionByName(const char *name, VSPlugin *plugin)
Get a function belonging to a plugin by its name.
const char *getPluginFunctionName(VSPluginFunction *func)
Returns the name of the function that was passed to registerFunction.
const char *getPluginFunctionArguments(VSPluginFunction *func)
Returns the argument string of the function that was passed to registerFunction.
const char *getPluginFunctionReturnType(VSPluginFunction *func)
Returns the return type string of the function that was passed to registerFunction.
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.
int getPluginVersion(const VSPlugin *plugin)
Returns the version of the plugin. This is the same as the version number passed to configPlugin.
VSMap *invoke(VSPlugin *plugin, const char *name, const VSMap *args)
Invokes a filter.
invoke() 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 returns the declared types. If everything goes smoothly, the filter will be ready to generate frames after invoke() returns.
- plugin
A pointer to the plugin where the filter is located. Must not be NULL.
See getPluginByID().
- name
Name of the filter to invoke.
- args
Arguments for the filter.
Returns a map containing the filter’s return value(s). The caller takes ownership of the map. Use mapGetError() to check if the filter was invoked successfully.
Most filters will either set an error, 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.
VSFunction *createFunction(VSPublicFunction func, void *userData, VSFreeFunctionData free, VSCore *core)
- 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 *VSFreeFunctionData)(void *userData)
Callback tasked with freeing userData. Can be NULL.
void freeFunction(VSFunction *f)
Decrements the reference count of a function and deletes it when it reaches 0.
It is safe to pass NULL.
VSFunction *addFunctionRef(VSFunction *f)
Increments the reference count of a function. Returns f as a convenience.
void callFunction(VSFunction *func, const VSMap *in, VSMap *out)
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.
const VSFrame *getFrame(int n, VSNode *node, char *errorMsg, int bufSize)
Fetches a frame synchronously. 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, VSNode *node, VSFrameDoneCallback callback, void *userData)
Requests the generation of a frame. When the frame is ready, a user-provided function is called. Note that the completion callback will only be called from a single thread at a time.
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 VSFrame *f, int n, VSNode *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 VSFrame *getFrameFilter(int n, VSNode *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, VSNode *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. See VSActivationReason.
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.
void releaseFrameEarly(VSNode *node, int n, VSFrameContext *frameCtx)
By default all requested frames are referenced until a filter’s frame request is done. In extreme cases where a filter needs to reduce 20+ frames into a single output frame it may be beneficial to request these in batches and incrementally process the data instead.
Should rarely be needed.
Only use inside a filter’s “getframe” function.
- node
The node from which the frame was requested.
- n
The frame number. Invalid frame numbers (not cached or negative) will simply be ignored.
- frameCtx
The context passed to the filter’s “getframe” function.
int registerFunction(const char *name, const char *args, const char *returnType, VSPublicFunction argsFunc, void *functionData, VSPlugin *plugin)
Function that registers a filter exported by the plugin. A plugin can export any number of filters. This function may only be called during the plugin loading phase unless the pcModifiable flag was set by configPlugin.
- 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*
“anode”: const VSNode* (audio type)
“vnode”: const VSNode* (video type)
“aframe”: const VSFrame* (audio type)
“vframe”: const VSFrame* (video type)
“func”: const VSFunctionRef*
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.
- “any”
Can only be placed last without a semicolon after. Indicates that all remaining arguments that don’t match should also be passed through.
The following example declares the arguments “blah”, “moo”, and “asdf”:
blah:vnode;moo:int[]:opt;asdf:float:opt;The following example declares the arguments “blah” and accepts all other arguments no matter the type:
blah:vnode;any- returnType
Specifies works similarly to args but instead specifies which keys and what type will be returned. Typically this will be:
clip:vnode;for video filters. It is important to not simply specify “any” for all filters since this information is used for better auto-completion in many editors.
- 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 createAudioFilter() or createVideoFilter() 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 mapSetError() on out, and return.
- in
Input parameter list.
Use mapGetInt() 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 mapGetData() will not be usable in the filter’s “getframe” and “free” functions.
- out
Output parameter list. createAudioFilter() or createVideoFilter() 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 VapourSynthPluginInit2().
void cacheFrame(const VSFrame *frame, int n, VSFrameContext *frameCtx)
Pushes a not requested frame into the cache. This is useful for (source) filters that greatly benefit from completely linear access and producing all output in linear order.
This function may only be used in filters that were created with setLinearFilter.
Only use inside a filter’s “getframe” function.
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.
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. It is recommended to pass VAPOURSYNTH_API_VERSION.
Writing plugins
A simple VapourSynth plugin which exports one filter will contain five
functions: an entry point (called VapourSynthPluginInit2), 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)(VSPlugin *plugin, const VSPLUGINAPI *vspapi)
A plugin’s entry point. It must be called
VapourSynthPluginInit2. 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.
- plugin
A pointer to the plugin object to be initialized.
- vspapi
A pointer to a VSPLUGINAPI struct with a subset of the VapourSynth API used for initializing plugins. The proper way to do things is to call configPlugin and then registerFunction for each function to export.
typedef const VSFrame *(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 arAllFramesReady. The function should only return a frame when called with activationReason arAllFramesReady.
If a the function is called with arError all processing has to be aborted and any.
- 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).
It points to a void *[4] array of memory that may be used freely. See filters like Splice and Trim for examples.
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.