VapourSynth 1.0 documentation
previous | next | index

# Python Bindings

VapourSynth is separated into a core library and a Python module. This section deals with how the core library is exposed through Python and some of the special things, such as slicing and output, unique to Python scripting.

## VapourSynth Structure and Functions

To use the VapourSynth library you must first retrieve the Core object, using get_core(). This core may then load plugins which all end up in their own unit, or namespace, so to say, to avoid naming conflicts in the contained functions. For this reason you call a plugin function with core.unit.Function().

All arguments to functions have names that are lowercase and all function names are CamelCase. Unit names are also lowercase and usually short. This is good to remember. If you do not like CamelCase for function names you can pass accept_lowercase=True to get_core().

## Slicing

The VideoNode class (always referred to as clip in practice) supports the full range of indexing and slicing operations in Python. If you do perform a slicing operation on a clip you will get a new clip back with the desired frames. Here are some examples to illustrate:

    # ret will be a one frame clip containing the 6th frame
    ret = clip[5]
    # ret will contain frames 6 to 9 (unlike trim the end value of python slicing is not inclusive)
    ret = clip[6:10]

    # Select even numbered frames
    ret = clip[::2]
    # Select odd numbered frames
    ret = clip[1::2]

    # Negative step is also allowed so this reverses a clip
    ret = clip[::-1]

    # It may all be combined at once to confuse people, just like normal Python lists
    ret = clip[-400:-800:-5]

## Output

The normal way of specifying the clip(s) to output is to call clip.set_output(). All standard VapourSynth components only use output index 0 but other tools may use something similar. There are also other variables that can be set to control how a format is output. For example setting enable_v210=True changes the packing of the YUV422P10 format to one that is common in professional software (like Adobe products). An example on how to get v210 output:

    some_clip = core.resize.Bicubic(clip, format=vs.YUV422P10)
    some_clip.set_output()
    enable_v210 = True

## Raw Access to Frame Data

The VideoFrame class simply contains one picture and all the metadata associated with it. It is possible to access the raw data using ctypes and some persistence. The three relevant functions are get_read_ptr(plane), get_write_ptr(plane) and get_stride(plane), all of which take the plane to access as an argument. Accessing the data is a bit trickier as get_read_ptr() and get_write_ptr() only return a pointer. To get a frame simply call get_frame(n) on a clip.