doc/pythonbindings.rst

   1 Python Bindings
   2 ===============
   3 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,
   4 unique to Python scripting.
   5
   6 VapourSynth Structure and Functions
   7 ###################################
   8 To use the VapourSynth library you must first create a Core object. This core may then load plugins which all end up in their own unit, or namespace, so to say, to avoid naming conflicts in
   9 the contained functions. For this reason you call a plugin function with *core.unit.Function()*. Note that the loaded plugins are per core instance and not global so if you do create several
  10 processing cores at once (not recommended) you will have to load the plugins you want for each core.
  11
  12 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
  13 CamelCase for function names you can pass *accept_lowercase=True* to the Core constructor.
  14
  15 Slicing
  16 #######
  17 The VideoNode class (always referred to as clip in practice) supports the full range of indexing and slicing operations in Python.
  18 If you do perform a slicing operation on a clip you will get a new clip back with the desired frames.
  19 Here are some examples to illustrate::
  20
  21    # ret will be a one frame clip containing the 6th frame
  22    ret = clip[5]
  23    # ret will contain frames 6 to 9 (unlike trim the end value of python slicing is not inclusive)
  24    ret = clip[6:10]
  25
  26    # Select even numbered frames
  27    ret = clip[::2]
  28    # Select odd numbered frames
  29    ret = clip[1::2]
  30
  31    # Negative step is also allowed so this reverses a clip
  32    ret = clip[::-1]
  33
  34    # It may all be combined at once to confuse people, just like normal Python lists
  35    ret = clip[-400:-800:-5]
  36
  37 Output
  38 ######
  39 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.
  40 There are also other variables that can be set to control
  41 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).
  42 An example on how to get v210 output::
  43
  44    some_clip = core.resize.Bicubic(clip, format=vs.YUV422P10)
  45    some_clip.set_output()
  46    enable_v210 = True
  47
  48 Raw Access to Frame Data
  49 ########################
  50 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.
  51 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
  52 *get_read_ptr()* and *get_write_ptr()* only return a pointer. To get a frame simply call *get_frame(n)* on a clip.