doc/pythonreference.rst

   1 .. _pythonreference:
   2
   3 Python Reference
   4 ================
   5
   6 VapourSynth is separated into a core library and a Python module. This section
   7 explains how the core library is exposed through Python and some of the
   8 special things unique to Python scripting, such as slicing and output.
   9
  10 .. note::
  11
  12    Any script executed through the vsscript api (that means vspipe, avfs, vsvfw or
  13    other API users) will have __name__ set to "__vapoursynth__" unlike normal Python
  14    scripts where it usually is "__main__".
  15
  16 VapourSynth Structure
  17 #####################
  18
  19 Most operations in the VapourSynth library are performed through the singleton
  20 core object. This core may load plugins, which all end up in their own unit,
  21 or namespace, so to say, to avoid naming conflicts in the contained functions.
  22 For this reason you call a plugin function with *core.unit.Function()*.
  23
  24 All arguments to functions have names that are lowercase and all function names
  25 are CamelCase. Unit names are also lowercase and usually short. This is good to
  26 remember as a general rule.
  27
  28 Grammar
  29 #######
  30
  31 Slicing and Other Syntactic Sugar
  32 *********************************
  33
  34 The VideoNode and AudioNode class (always called "clip" in practice) supports the full
  35 range of indexing and slicing operations in Python. If you do perform a slicing
  36 operation on a clip, you will get a new clip back with the desired frames.
  37 Here are a few examples.
  38
  39 +---------------------------------+---------------------------------------------------------------+--------------------------------------------------------+
  40 | Operation                       | Description                                                   | Equivalent                                             |
  41 +=================================+===============================================================+========================================================+
  42 | clip = clip[5]                  | Make a single frame clip containing frame number 5            | clip = core.std.Trim(clip, first=5, last=5)            |
  43 +---------------------------------+---------------------------------------------------------------+--------------------------------------------------------+
  44 | clip = clip[5:11]               | Make a clip containing frames 5 to 10 [#f1]_                  | clip = core.std.Trim(clip, first=5, last=10)           |
  45 |                                 |                                                               |                                                        |
  46 |                                 |                                                               | clip = core.std.AudioTrim(clip, first=5, last=10)      |
  47 +---------------------------------+---------------------------------------------------------------+--------------------------------------------------------+
  48 | clip = clip[::2]                | Select even numbered frames                                   | clip = core.std.SelectEvery(clip, cycle=2, offsets=0)  |
  49 +---------------------------------+---------------------------------------------------------------+--------------------------------------------------------+
  50 | clip = clip[1::2]               | Select odd numbered frames                                    | clip = core.std.SelectEvery(clip, cycle=2, offsets=1)  |
  51 +---------------------------------+---------------------------------------------------------------+--------------------------------------------------------+
  52 | clip = clip[::-1]               | Reverses a clip                                               | clip = core.std.Reverse(clip)                          |
  53 |                                 |                                                               |                                                        |
  54 |                                 |                                                               | clip = core.std.AudioReverse(clip)                     |
  55 +---------------------------------+---------------------------------------------------------------+--------------------------------------------------------+
  56 | clip = clip1 + clip2            | The addition operator can be used to splice clips together    | clip = core.std.Splice([clip1, clip2], mismatch=False) |
  57 |                                 |                                                               |                                                        |
  58 |                                 |                                                               | clip = core.std.AudioSplice([clip1, clip2])            |
  59 +---------------------------------+---------------------------------------------------------------+--------------------------------------------------------+
  60 | clip = clip * 10                | The multiplication operator can be used to loop a clip [#f2]_ | clip = core.std.Loop(clip, times=10)                   |
  61 |                                 |                                                               |                                                        |
  62 |                                 |                                                               | clip = core.std.AudioLoop(clip, times=10)              |
  63 +---------------------------------+---------------------------------------------------------------+--------------------------------------------------------+
  64
  65 .. [#f1] Note that frame numbers, like python arrays, start counting at 0 and the end value of slicing is not inclusive
  66
  67 .. [#f2] Note that multiplication by 0 is a special case that will repeat the clip up to the maximum frame count
  68
  69
  70 Filters can be chained with a dot::
  71
  72    clip = clip.std.Trim(first=100, last=2000).std.FlipVertical()
  73
  74 Which is quivalent to::
  75
  76    clip = core.std.FlipVertical(core.std.Trim(clip, first=100, last=2000))
  77
  78 Function Arguments, Return Types and Property Type Deduction in Python
  79 **********************************************************************
  80
  81 VapourSynth internally uses a very simple map of key-value pairs to pass values to and from functions.
  82 As a result of this every key is actually a one dimensional array of values of a single type. The Python bindings
  83 try to hide this as best as possible to make things less annoying. For example a function returning only a single key
  84 will have the only the array itself returned and an array with a single value will in turn only have the single value returned.
  85
  86 Similarly function arguments are first converted to the appropriate type specified by the function's argument string or fails if this isn't possible.
  87 There is however one quirk where the data type's type hint (utf-8/non-printable raw data) is set based on whether a *str* or a *bytes*/*bytearray*
  88 object is passed. Likewise a *str* object will be returned for all utf-8 hinted data and a bytes object for all other types.
  89
  90 Frame properties and "anything goes" function arguments have much stricter type requirements since the underlying type has to be possible to deduce from them.
  91 When using this type of functions, such as SetFrameProps, or property assignment it may be necessary to convert to int, float, str or bytes explicitly
  92 to make things works.
  93
  94 Python Keywords as Filter Arguments
  95 ***********************************
  96
  97 If a filter's argument happens to be a Python keyword, you may append
  98 an underscore to the argument's name when invoking the filter. The Python
  99 module will strip one trailing underscore (if present) from all filter arguments before
 100 passing them to the filters.
 101
 102 ::
 103
 104    clip = core.plugin.Filter(clip, lambda_=1)
 105
 106 Another way to deal with such arguments is to place them in a dictionary::
 107
 108    kwargs = { "lambda": 1 }
 109    clip = core.plugin.Filter(clip, **kwargs)
 110
 111 VapourSynth will also support the PEP8 convention of using a single trailing
 112 underscore to prevent collisions with python keywords.
 113
 114 Windows File Paths
 115 ******************
 116
 117 If you have a string containing backslashes, you must either prefix the
 118 string with "r", or duplicate every single backslash. The reason is
 119 that the backslash is an escape character in Python.
 120
 121 Use `os.path.normcase(path) <https://docs.python.org/3/library/os.path.html#os.path.normcase>`_
 122 to fix Incorrect path string.
 123
 124 Correct example::
 125
 126    "B:/VapourSynth/VapourSynth.dll"
 127    "B:\\VapourSynth\\VapourSynth.dll"
 128    r"B:\VapourSynth\VapourSynth.dll"
 129
 130 Output
 131 ******
 132
 133 The normal way of specifying the clip(s) to output is to call
 134 *clip.set_output()*. All standard VapourSynth components only use output
 135 index 0, except for vspipe where it's configurable but defaults to 0.
 136 There are also other variables that can be set to control how a format is
 137 output. For example, setting *alt_output=1* changes the packing of the
 138 YUV422P10 format to one that is common in professional software (like Adobe
 139 products). Note that currently *alt_output* modes only has an effect with
 140 YUV420P8 (I420, IYUV), YUV422P8 (YUY2, UYVY) and YUV422P10 (v210).
 141
 142 An example on how to get v210 output::
 143
 144    some_clip = core.resize.Bicubic(clip, format=vs.YUV422P10)
 145    some_clip.set_output(alt_output=1)
 146
 147 An example on how to get UYVY output::
 148
 149    some_clip = core.resize.Bicubic(clip, format=vs.YUV422P8)
 150    some_clip.set_output(alt_output=2)
 151
 152 Raw Access to Frame Data
 153 ************************
 154
 155 The VideoFrame and AudioFrame classes contains one picture/audio chunk and all the metadata
 156 associated with it. It is possible to access the raw data using either
 157 *get_read_ptr(plane)* or *get_write_ptr(plane)* and *get_stride(plane)* with ctypes.
 158
 159 A more Python friendly wrapping is also available where each plane/channel can be accessed
 160 as a Python array using *frame[plane/channel]*.
 161
 162 To get a frame simply call *get_frame(n)* on a clip. Should you desire to get
 163 all frames in a clip, use this code::
 164
 165    for frame in clip.frames():
 166        # Do stuff with your frame
 167        pass
 168
 169 Classes and Functions
 170 #####################
 171
 172 .. py:attribute:: core
 173
 174    Gets the singleton Core object. If it is the first time the function is called,
 175    the Core will be instantiated with the default options. This is the preferred
 176    way to reference the core.
 177
 178 .. py:function:: get_outputs()
 179
 180    Return a read-only mapping of all outputs registered on the current node.
 181
 182    The mapping will automatically update when a new output is registered.
 183
 184 .. py:function:: get_output([index = 0])
 185
 186    Get a previously set output node. Throws an error if the index hasn't been
 187    set. Will return a VideoOutputTuple containing *alpha* and the *alt_output* setting for video output and an AudioNode for audio.
 188
 189 .. py:function:: clear_output([index = 0])
 190
 191    Clears a clip previously set for output.
 192
 193 .. py:function:: clear_outputs()
 194
 195    Clears all clips set for output in the current environment.
 196
 197 .. py:function:: construct_signature(signature[, injected=None])
 198
 199    Creates a *inspect.Signature* object for the given registration signature.
 200
 201    If *injected* is not None, the default of the first argument of the signature will be replaced with the value supplied with injected.
 202
 203
 204 .. py:function:: register_on_destroy(callback)
 205
 206    Registers a callback that is called when the script is being finalized.
 207    This allows you to release resources at the end of a script.
 208
 209    A callback must be registered with every script that is run,
 210    even if the code is being reused in multiple script runs.
 211
 212    No new callbacks can be registered when the script is already being finalized.
 213
 214 .. py:function:: unregister_on_destroy(callback)
 215
 216    Unregisters a previously added callback.
 217
 218 .. py:class:: Core
 219
 220    The *Core* class uses a singleton pattern. Use the *core* attribute to obtain an
 221    instance. All loaded plugins are exposed as attributes of the core object.
 222    These attributes in turn hold the functions contained in the plugin.
 223    Use *plugins()* to obtain a full list of all currently loaded plugins
 224    you may call this way.
 225
 226    .. py:attribute:: num_threads
 227
 228       The number of concurrent threads used by the core. Can be set to change the number. Setting to a value less than one makes it default to the number of hardware threads.
 229
 230    .. py:attribute:: max_cache_size
 231
 232       Set the upper framebuffer cache size after which memory is aggressively
 233       freed. The value is in megabytes.
 234
 235    .. py:attribute:: used_cache_size
 236
 237       The size of the core's current cache. The value is in bytes.
 238
 239    .. py:attribute:: core_version
 240
 241       Returns the core version as VapourSynthVersion tuple.
 242
 243       .. note::
 244
 245          If you are writing a library, and are not retrieving this from the proxy,
 246          you should consider using *vapoursynth.__version__* instead not to have to
 247          unnecessarily fetch the core and lock inside an environment.
 248
 249    .. py:attribute:: api_version
 250
 251       Returns the api version as VapourSynthAPIVersion tuple.
 252
 253       .. note::
 254
 255          If you are writing a library, and are not retrieving this from the proxy,
 256          you should consider using *vapoursynth.__api_version__* instead not to have to
 257          unnecessarily fetch the core and lock inside an environment.
 258
 259    .. py:method:: plugins()
 260
 261       Containing all loaded plugins.
 262
 263    .. py:method:: get_video_format(id)
 264
 265       Retrieve a Format object corresponding to the specified id. Returns None if the *id* is invalid.
 266
 267    .. py:method:: query_video_format(color_family, sample_type, bits_per_sample, subsampling_w, subsampling_h)
 268
 269       Retrieve a Format object corresponding to the format information, Invalid formats throw an exception.
 270
 271    .. py:method:: create_video_frame(format, width, height)
 272
 273       Creates a new frame with uninitialized planes with the given dimensions and format.
 274       This function is safe to call within a frame callback.
 275
 276    .. py:method:: add_log_handler(handler_func)
 277
 278       Installs a custom handler for the various error messages VapourSynth emits.
 279       The message handler is currently global, i.e. per process, not per VSCore instance.
 280       Returns a LogHandle object.
 281       *handler_func* is a callback function of the form *func(MessageType, message)*.
 282
 283    .. py:method:: remove_log_handler(handle)
 284
 285       Removes a custom handler.
 286
 287    .. py:method:: log_message(message_type, message)
 288
 289       Send a message through VapourSynth’s logging framework.
 290
 291    .. py:method:: rule6()
 292
 293       Illegal behavior detection.
 294
 295 .. py:class:: Local
 296
 297    Internally, there can be more than one core. This is usually the case in previewer-applications.
 298    Use this class to store variables that depend on the currently active core.
 299
 300    .. code::
 301
 302         l = Local()
 303         l.test = 1
 304
 305
 306 .. py:class:: VideoNode
 307
 308    Represents a video clip. The class itself supports indexing and slicing to
 309    perform trim, reverse and selectevery operations. Several operators are also
 310    defined for the VideoNode class: addition appends clips and multiplication
 311    repeats them. Note that slicing and indexing always return a new VideoNode
 312    object and not a VideoFrame.
 313
 314    .. py:attribute:: format
 315
 316       A Format object describing the frame data. If the format can change
 317       between frames, this value is None.
 318
 319    .. py:attribute:: width
 320
 321       The width of the video. This value will be 0 if the width and height can
 322       change between frames.
 323
 324    .. py:attribute:: height
 325
 326       The height of the video. This value will be 0 if the width and height can
 327       change between frames.
 328
 329    .. py:attribute:: num_frames
 330
 331       The number of frames in the clip.
 332
 333    .. py:attribute:: fps
 334
 335       The framerate represented as a *Fraction*. It is 0/1 when the clip has a variable
 336       framerate.
 337
 338       .. py:attribute:: numerator
 339
 340          The numerator of the framerate. If the clip has variable framerate, the value will be 0.
 341
 342       .. py:attribute:: denominator
 343
 344          The denominator of the framerate. If the clip has variable framerate, the value will be 0.
 345
 346    .. py:attribute:: fps_num
 347
 348       Deprecated, use *fps.numerator* instead
 349
 350    .. py:attribute:: fps_den
 351
 352       Deprecated, use *fps.denominator* instead
 353
 354    .. py:attribute:: flags
 355
 356       Special flags set for this clip. This attribute should normally be
 357       ignored.
 358
 359    .. py:method:: get_frame(n)
 360
 361       Returns a VideoFrame from position *n*.
 362
 363    .. py:method:: get_frame_async(n)
 364
 365       Returns a concurrent.futures.Future-object which result will be a VideoFrame instance or sets the
 366       exception thrown when rendering the frame.
 367
 368       *The future will always be in the running or completed state*
 369
 370    .. py:method:: get_frame_async(n, cb: callable)
 371       :noindex:
 372
 373       Renders a frame in another thread. When the frame is rendered, it will either call `cb(Frame, None)` on success
 374       or `cb(None, Exception)` if something fails.
 375
 376       Added: R58
 377
 378    .. py:method:: set_output(index = 0, alpha = None, alt_output = 0)
 379
 380       Set the clip to be accessible for output. This is the standard way to
 381       specify which clip(s) to output. All VapourSynth tools (vsvfw, vsfs,
 382       vspipe) use the clip in *index* 0. It's possible to specify an additional
 383       containing the *alpha* to output at the same time. Currently only vspipe
 384       takes *alpha* into consideration when outputting.
 385       The *alt_output* argument is for optional alternate output modes. Currently
 386       it controls the FOURCCs used for VFW-style output with certain formats.
 387
 388    .. py:method:: output(fileobj[, y4m = False, prefetch = 0, progress_update = None, backlog=-1])
 389
 390       Write the whole clip to the specified file handle. It is possible to pipe to stdout by specifying *sys.stdout* as the file.
 391       YUV4MPEG2 headers will be added when *y4m* is true.
 392       The current progress can be reported by passing a callback function of the form *func(current_frame, total_frames)* to *progress_update*.
 393       The *prefetch* argument is only for debugging purposes and should never need to be changed.
 394       The *backlog* argument is only for debugging purposes and should never need to be changed.
 395
 396    .. py:method:: frames([prefetch=None, backlog=None, close=False])
 397
 398       Returns a generator iterator of all VideoFrames in the clip. It will render multiple frames concurrently.
 399
 400       The *prefetch* argument defines how many frames are rendered concurrently. Is only there for debugging purposes and should never need to be changed.
 401       The *backlog* argument defines how many unconsumed frames (including those that did not finish rendering yet) vapoursynth buffers at most before it stops rendering additional frames. This argument is there to limit the memory this function uses storing frames.
 402       The *close* argument determines if the frame should be closed after each iteration step. It defaults to false to remain backward compatible.
 403
 404    .. py:method:: is_inspectable(version=None)
 405
 406       Returns a truthy value if you can use the node inspection API with a given version.
 407       The python inspection-api is versioned, as the underlying API is unstable at the time of writing.
 408       The version number will be incremented every time the python API changes.
 409       There will be no attempt to maintain backwards compatibility as long as the API is marked as unstable.
 410
 411       This method may never return a truthy value.
 412
 413       This is the only stable function in the current inspection api-implementation.
 414
 415       .. note::
 416
 417          Be aware that introspection features must be enabled manually by the backing environment. Standalone Python-Scripts,
 418          not running inside vspipe or other editors, have introspection enabled automatically.
 419
 420       .. warning::
 421
 422          The graph-inspection-api is unstable. Omitting the version-argument will therefore always return
 423          None.
 424
 425       The current version of the unstable python graph-inspection API is 0.
 426
 427       Added: R58
 428
 429       :param version: If None, it will use the version number of the last stable API.
 430
 431 .. py:class:: VideoOutputTuple
 432
 433       This class is returned by get_output if the output is video.
 434
 435       .. py:attribute:: clip
 436
 437          A VideoNode-instance containing the color planes.
 438
 439       .. py:attribute:: alpha
 440
 441          A VideoNode-instance containing the alpha planes.
 442
 443       .. py:attribute:: alt_output
 444
 445          An integer with the alternate output mode to be used. May be ignored if no meaningful mapping exists.
 446
 447 .. py:class:: VideoFrame
 448
 449       This class represents a video frame and all metadata attached to it.
 450
 451    .. py:attribute:: format
 452
 453       A Format object describing the frame data.
 454
 455    .. py:attribute:: width
 456
 457       The width of the frame.
 458
 459    .. py:attribute:: height
 460
 461       The height of the frame.
 462
 463    .. py:attribute:: readonly
 464
 465       If *readonly* is True, the frame data and properties cannot be modified.
 466
 467    .. py:attribute:: props
 468
 469       This attribute holds all the frame's properties as a dict. They are also mapped as sub-attributes for
 470       compatibility with older scripts. For more information, see:
 471       `API Reference <apireference.html#reserved-frame-properties>`_
 472       Note: This includes the data for matrix, transfer and primaries. (_Matrix,
 473       _Transfer, _Primaries) See `Resize <functions/resize.html>`_ for more information.
 474
 475    .. py:method:: copy()
 476
 477       Returns a writable copy of the frame.
 478
 479    .. py:method:: close()
 480
 481       Forcefully releases the frame. Once freed, the you cannot call any function on the frame, nor use the associated
 482       FrameProps.
 483
 484       To make sure you don't forget to close the frame, the frame is now a context-manager that automatically calls
 485       this method for you:
 486
 487       .. code::
 488
 489            with core.std.BlankClip().get_frame(0) as f:
 490                print(f.props)
 491
 492    .. py:attribute:: closed
 493
 494       Tells you if the frame has been closed. It will be False if the close()-method has not been called yet.
 495
 496    .. py:method:: get_read_ptr(plane)
 497
 498       Returns a pointer to the raw frame data. The data may not be modified.
 499       Note that this is a thin wrapper for the underlying
 500       C-api and as such calls to *get_write_ptr*, including the ones made internally by other functions in the Python bindings,
 501       may invalidate any pointers previously gotten to the frame with
 502       *get_read_ptr* when called.
 503
 504    .. py:method:: get_write_ptr(plane)
 505
 506       Returns a pointer to the raw frame data. It may be modified using ctypes
 507       or some other similar python package.  Note that this is a thin wrapper for the underlying
 508       C-api and as such calls to *get_write_ptr*, including the ones made internally by other functions in the Python bindings,
 509       may invalidate any pointers previously gotten to the frame with
 510       *get_read_ptr* when called.
 511
 512    .. py:method:: get_stride(plane)
 513
 514       Returns the stride between lines in a *plane*.
 515
 516    .. py:method:: readchunks()
 517
 518       This method is usually used to dump the contents of a VideoFrame to disk.
 519       The returned generator yields contiguous chunks of the VideoFrame memory.
 520
 521       .. code::
 522
 523          with open('output.raw', 'wb') as file:
 524             with vs.core.std.BlankClip(color=[25, 50, 60]).get_frame(0) as f:
 525                for chunk in f.readchunks():
 526                   file.write(chunk)
 527
 528       .. note::
 529          Usually, the frame contents will be held in a contiguous array,
 530          and this method will yield *n_planes* of data chunks each holding the entire plane.
 531          Don't, however, take this for granted, as it can't be the case,
 532          and you will iterate over lines of plane data instead, which are assured to be contiguous.
 533
 534          If you want to safely read the whole plane, use frame[plane_idx] to get the plane memoryview.
 535
 536 .. py:class:: VideoFormat
 537
 538    This class represents all information needed to describe a frame format. It
 539    holds the general color type, subsampling, number of planes and so on.
 540    The names map directly to the C API so consult it for more detailed
 541    information.
 542
 543    .. py:attribute:: id
 544
 545       A unique *id* identifying the format.
 546
 547    .. py:attribute:: name
 548
 549       A human readable name of the format.
 550
 551    .. py:attribute:: color_family
 552
 553       Which group of colorspaces the format describes.
 554
 555    .. py:attribute:: sample_type
 556
 557       If the format is integer or floating point based.
 558
 559    .. py:attribute:: bits_per_sample
 560
 561       How many bits are used to store one sample in one plane.
 562
 563    .. py:attribute:: bytes_per_sample
 564
 565       The actual storage is padded up to 2^n bytes for efficiency.
 566
 567    .. py:attribute:: subsampling_w
 568
 569       The subsampling for the second and third plane in the horizontal
 570       direction.
 571
 572    .. py:attribute:: subsampling_h
 573
 574       The subsampling for the second and third plane in the vertical direction.
 575
 576    .. py:attribute:: num_planes
 577
 578       The number of planes the format has.
 579
 580    .. py:method:: replace(core=None, **kwargs)
 581
 582       Returns a new format with the given modifications.
 583
 584       The only supported attributes that can be replaced are `color_family`,
 585       `sample_type`, `bits_per_sample`, `subsampling_w`, `subsampling_h`.
 586
 587       The optional `core`-parameter defines on which core the new format
 588       should be registered. This is usually not needed and defaults
 589       to the core of the current environment.
 590
 591 .. py:class:: AudioNode
 592
 593    Represents an audio clip. The class itself supports indexing and slicing to
 594    perform trim, reverse and selectevery operations. Several operators are also
 595    defined for the AudioNode class: addition appends clips and multiplication
 596    repeats them. Note that slicing and indexing always return a new AudioNode
 597    object and not a AudioFrame.
 598
 599    .. py:attribute:: sample_type
 600
 601       If the format is integer or floating point based.
 602
 603    .. py:attribute:: bits_per_sample
 604
 605       How many bits are used to store one sample in one plane.
 606
 607    .. py:attribute:: bytes_per_sample
 608
 609       The actual storage is padded up to 2^n bytes for efficiency.
 610
 611    .. py:attribute:: channel_layout
 612
 613       A mask of used channels.
 614
 615    .. py:attribute:: num_channels
 616
 617       The number of channels the format has.
 618
 619    .. py:attribute:: sample_rate
 620
 621       Playback sample rate.
 622
 623    .. py:method:: get_frame(n)
 624
 625       Returns an AudioFrame from position *n*.
 626
 627    .. py:method:: get_frame_async(n)
 628
 629       Returns a concurrent.futures.Future-object which result will be an AudioFrame instance or sets the
 630       exception thrown when rendering the frame.
 631
 632       *The future will always be in the running or completed state*
 633
 634    .. py:method:: set_output(index = 0)
 635
 636       Set the clip to be accessible for output.
 637
 638    .. py:method:: frames([prefetch=None, backlog=None])
 639
 640       Returns a generator iterator of all AudioFrames in the clip. It will render multiple frames concurrently.
 641
 642       The *prefetch* argument defines how many frames are rendered concurrently. Is only there for debugging purposes and should never need to be changed.
 643       The *backlog* argument defines how many unconsumed frames (including those that did not finish rendering yet) vapoursynth buffers at most before it stops rendering additional frames. This argument is there to limit the memory this function uses storing frames.
 644
 645    .. py:method:: is_inspectable(version=None)
 646
 647       Returns a truthy value if you can use the node inspection API with a given version.
 648       The python inspection-api is versioned, as the underlying API is unstable at the time of writing.
 649       The version number will be incremented every time the python API changes.
 650       There will be no attempt to maintain backwards compatibility as long as the API is marked as unstable.
 651
 652       This method may never return a truthy value.
 653
 654       This is the only stable function in the current inspection api-implementation.
 655
 656       .. note::
 657
 658          Be aware that introspection features must be enabled manually by the backing environment. Standalone Python-Scripts,
 659          not running inside vspipe or other editors, have introspection enabled automatically.
 660
 661       .. warning::
 662
 663          The graph-inspection-api is unstable. Omitting the version-argument will therefore always return
 664          None.
 665
 666       The current version of the unstable python graph-inspection API is 0.
 667
 668       Added: R58
 669
 670       :param version: If None, it will use the version number of the last stable API.
 671
 672
 673 .. py:class:: AudioFrame
 674
 675       This class represents an audio frame and all metadata attached to it.
 676
 677    .. py:attribute:: sample_type
 678
 679       If the format is integer or floating point based.
 680
 681    .. py:attribute:: bits_per_sample
 682
 683       How many bits are used to store one sample in one plane.
 684
 685    .. py:attribute:: bytes_per_sample
 686
 687       The actual storage is padded up to 2^n bytes for efficiency.
 688
 689    .. py:attribute:: channel_layout
 690
 691       A mask of used channels.
 692
 693    .. py:attribute:: num_channels
 694
 695       The number of channels the format has.
 696
 697    .. py:attribute:: readonly
 698
 699       If *readonly* is True, the frame data and properties cannot be modified.
 700
 701    .. py:attribute:: props
 702
 703       This attribute holds all the frame's properties as a dict. Note that audio frame properties are fairly
 704       non-sensical as a concept for audio due to an arbitrary number of samples being lumped together and rarely used.
 705
 706    .. py:method:: copy()
 707
 708       Returns a writable copy of the frame.
 709
 710    .. py:method:: get_read_ptr(plane)
 711
 712       Returns a pointer to the raw frame data. The data may not be modified.
 713
 714    .. py:method:: get_write_ptr(plane)
 715
 716       Returns a pointer to the raw frame data. It may be modified using ctypes
 717       or some other similar python package.
 718
 719    .. py:method:: get_stride(plane)
 720
 721       Returns the stride between lines in a *plane*.
 722
 723 .. py:class:: Plugin
 724
 725    Plugin is a class that represents a loaded plugin and its namespace.
 726
 727    .. py:attribute:: namespace
 728
 729       The namespace of the plugin.
 730
 731    .. py:attribute:: name
 732
 733       The name string of the plugin.
 734
 735    .. py:attribute:: version
 736
 737       The version of the plugin returned as a PluginVersion tuple.
 738
 739    .. py:attribute:: plugin_path
 740
 741       The main library location of the plugin. Note that internal functions don't have a plugin path and instead return None.
 742
 743    .. py:attribute:: identifier
 744
 745    .. py:method:: functions()
 746
 747       Containing all the functions in the plugin, You can access it by calling *core.<namespace>.functions()*.
 748
 749 .. py:class:: Function
 750
 751    Function is a simple wrapper class for a function provided by a VapourSynth plugin.
 752    Its main purpose is to be called and nothing else.
 753
 754    .. py:attribute:: name
 755
 756       The function name. Identical to the string used to register the function.
 757
 758    .. py:attribute:: plugin
 759
 760       The *Plugin* object the function belongs to.
 761
 762    .. py:attribute:: signature
 763
 764       Raw function signature string. Identical to the string used to register the function.
 765
 766    .. py:attribute:: return_signature
 767
 768       Raw function signature string. Identical to the return type string used register the function.
 769
 770 .. py:class:: Environment
 771
 772    This class represents an environment.
 773
 774    Some editors allow multiple vapoursynth-scripts to run in the same process, each of them comes with a different Core-instance and
 775    their own set of outputs. Each core-instance with their associated outputs represent their own environment.
 776
 777    At any given time, only one environment can be active (in the same context). This class allows introspection about
 778    environments and allows to switch to them at will.
 779
 780    .. code::
 781
 782         env = get_current_environment()
 783         # sometime later
 784         with env.use():
 785           # Do stuff inside this env.
 786
 787    .. py:function:: is_single()
 788
 789       Returns True if the script is _not_ running inside a vsscript-Environment.
 790       If it is running inside a vsscript-Environment, it returns False.
 791
 792    .. py:attribute:: env_id
 793
 794       Return -1 if the script is not running inside a vsscript-Environment.
 795       Otherwise, it will return the current environment-id.
 796
 797    .. py:attribute:: single
 798
 799       See is_single()
 800
 801    .. py:attribute:: alive
 802
 803       Has the environment been destroyed by the underlying application?
 804
 805    .. py:method:: copy()
 806
 807       Creates a copy of the environment-object.
 808
 809       Added: R51
 810
 811    .. py:method:: use()
 812
 813       Returns a context-manager that enables the given environment in the block enclosed in the with-statement and restores the environment to the one
 814       defined before the with-block has been encountered.
 815
 816       .. code::
 817
 818          env = get_current_environment()
 819          with env.use():
 820              with env.use():
 821                  pass
 822
 823       Added: R51
 824
 825 .. py:function:: get_current_environment()
 826
 827    Returns an Environment-object representing the environment the script is currently running in. It will raise an error if we are currently not inside any
 828    script-environment while vsscript is being used.
 829
 830    This function is intended for Python-based editors using vsscript.
 831
 832    Added: R51
 833
 834 .. py:class:: EnvironmentPolicy
 835
 836    This class is intended for subclassing by custom Script-Runners and Editors.
 837    Normal users don't need this class. Most methods implemented here have corresponding APIs in other parts of this module.
 838
 839    An instance of this class controls which environment is activated in the current context.
 840    The exact meaning of "context" is defined by the concrete EnvironmentPolicy. A environment is represented by a :class:`EnvironmentData`-object.
 841
 842    To use this class, first create a subclass and then use :func:`register_policy` to get VapourSynth to use your policy. This must happen before vapoursynth is first
 843    used. VapourSynth will automatically register an internal policy if it needs one. The subclass must be weak-referenciable!
 844
 845    Once the method :meth:`on_policy_registered` has been called, the policy is responsible for creating and managing environments.
 846
 847    Special considerations have been made to ensure the functions of class cannot be abused. You cannot retrieve the current running policy yourself.
 848    The additional API exposed by "on_policy_registered" is only valid if the policy has been registered.
 849    Once the policy is unregistered, all calls to the additional API will fail with a RuntimeError.
 850
 851    Added: R51
 852
 853    .. py:method:: on_policy_registered(special_api)
 854
 855       This method is called when the policy has successfully been registered. It proivdes additional internal methods that are hidden as they are useless and or harmful
 856       unless you implement your own policy.
 857
 858       :param special_api: This is a :class:`EnvironmentPolicyAPI`-object that exposes additional API
 859
 860    .. py:method:: on_policy_cleared()
 861
 862       This method is called once the python-process exits or when unregister_policy is called by the environment-policy. This allows the policy to free the resources
 863       used by the policy.
 864
 865    .. py:method:: get_current_environment()
 866
 867       This method is called by the module to detect which environment is currently running in the current context. If None is returned, it means that no environment is currently active.
 868
 869       :returns: An :class:`EnvironmentData`-object representing the currently active environment in the current context.
 870
 871    .. py:method:: set_environment(environment)
 872
 873       This method is called by the module to change the currently active environment. If None is passed to this function the policy may switch to another environment of its choosing.
 874
 875       Note: The function is responsible to check whether or not the environment is alive. If a dead environment is passed, it should act like None has been passed instead of the dead environment but must never error.
 876
 877       :param environment: The :class:`EnvironmentData` to enable in the current context.
 878       :returns: The environment that was enabled previously.
 879
 880    .. py:method:: is_alive(environment)
 881
 882       Is the current environment still active and managed by the policy.
 883
 884       The default implementation checks if `EnvironmentPolicyAPI.destroy_environment` has been called on the environment.
 885
 886
 887 .. py:class:: EnvironmentPolicyAPI
 888
 889    This class is intended to be used by custom Script-Runners and Editors. An instance of this class exposes an additional API.
 890    The methods are bound to a specific :class:`EnvironmentPolicy`-instance and will only work if the policy is currently registered.
 891
 892    Added: R51
 893
 894    .. py:method:: wrap_environment(environment)
 895
 896       Creates a new :class:`Environment`-object bound to the passed environment-id.
 897
 898       .. warning::
 899
 900          This function does not check if the id corresponds to a live environment as the caller is expected to know which environments are active.
 901
 902    .. py:method:: create_environment(flags = 0)
 903
 904       Returns a :class:`Environment` that is used by the wrapper for context sensitive data used by VapourSynth.
 905       For example it holds the currently active core object as well as the currently registered outputs.
 906
 907    .. py:method:: set_logger(environment, callback)
 908
 909       This function sets the logger for the given environment.
 910
 911       This logger is a callback function that accepts two parameters: Level, which is an instance of vs.MessageType and a string containing the log message.
 912
 913    .. py:method:: destroy_environment(environment)
 914
 915       Marks an environment as destroyed. Older environment-policy implementations that don't use this function still work.
 916
 917       Either EnvironmentPolicy.is_alive must be overridden or this method be used to mark the environment as destroyed.
 918
 919       Added: R52
 920
 921    .. py:method:: unregister_policy()
 922
 923       Unregisters the policy it is bound to and allows another policy to be registered.
 924
 925    .. py:method:: get_vapoursynth_api(version)
 926
 927       Exposes getVapoursynthAPI to python. Returns a ctypes.c_void_p.
 928
 929       Access to this function is provisional and might be removed if it is abused too much.
 930
 931       Added: R62
 932
 933    .. py:method:: get_core_ptr(environment)
 934
 935       Returns a ctypes.c_void_p pointing to the `Core*`-object that powers the environment.
 936
 937       Access to this function is provisional and might be removed if it is abused too much.
 938
 939       Added: R62
 940
 941 .. py:function:: register_policy(policy)
 942
 943    This function is intended for use by custom Script-Runners and Editors. It installs your custom :class:`EnvironmentPolicy`. This function only works if no other policy has been
 944    installed.
 945
 946    If no policy is installed, the first environment-sensitive call will automatically register an internal policy.
 947
 948    Added: R50
 949
 950    .. note::
 951
 952       This must be done before VapourSynth is used in any way. Here is a non-exhaustive list that automatically register a policy:
 953
 954       * Using "vsscript_init" in "VSScript.h"
 955       * Using :func:`get_outputs`
 956       * Using :func:`get_output`
 957       * Using :func:`clear_output`
 958       * Using :func:`clear_outputs`
 959       * Using :func:`get_current_environment`
 960       * Accessing any attribute of :attr:`core`
 961
 962
 963 .. py:function:: _try_enable_introspection(version=None)
 964
 965    Tries to enable introspection. Returns true if it succeeds.
 966
 967    :param version: If not passed it will use the newest stable introspection-api.
 968
 969    Added: R58
 970
 971 .. py:function:: has_policy()
 972
 973    This function is intended for subclassing by custom Script-Runners and Editors. This function checks if a :class:`EnvironmentPolicy` has been installed.
 974
 975    Added: R50
 976
 977 .. py:class:: EnvironmentData
 978
 979    Internal class that stores the context sensitive data that VapourSynth needs. It is an opaque object whose attributes you cannot access directly.
 980
 981    A normal user has no way of getting an instance of this object. You can only encounter EnvironmentData-objects if you work with EnvironmentPolicies.
 982
 983    This object is weak-referenciable meaning you can get a callback if the environment-data object is actually being freed (i.e. no other object holds an instance
 984    to the environment data.)
 985
 986    Added: R50
 987
 988 .. py:class:: Func
 989
 990    Func is a simple wrapper class for VapourSynth VSFunc objects.
 991    Its main purpose is to be called and manage reference counting.
 992
 993 .. py:exception:: Error
 994
 995    The standard exception class. This exception is thrown on most errors
 996    encountered in VapourSynth.
 997
 998 Constants
 999 #########
1000
1001 Video
1002 *****
1003
1004 Color Family
1005 ------------
1006
1007 The color family constants describe groups of formats and the basic way their
1008 color information is stored. You should be familiar with all of them apart from
1009 maybe *YCOCG* and *COMPAT*. The latter is a special junk category for non-planar
1010 formats. These are the declared constants in the module::
1011
1012    UNDEFINED
1013    RGB
1014    YUV
1015    GRAY
1016
1017 Format
1018 ------
1019
1020 Format constants exactly describe a format. All common and even more uncommon
1021 formats have handy constants predefined so in practice no one should really
1022 need to register one of their own. These values are mostly used by the resizers
1023 to specify which format to convert to. The naming system is quite simple. First
1024 the color family, then the subsampling (only YUV has it) and after that how many
1025 bits per sample in one plane. The exception to this rule is RGB, which has the
1026 bits for all 3 planes added together. The long list of values::
1027
1028    NONE
1029    GRAY8
1030    GRAY9
1031    GRAY10
1032    GRAY12
1033    GRAY14
1034    GRAY16
1035    GRAY32
1036    GRAYH
1037    GRAYS
1038    YUV420P8
1039    YUV422P8
1040    YUV444P8
1041    YUV410P8
1042    YUV411P8
1043    YUV440P8
1044    YUV420P9
1045    YUV422P9
1046    YUV444P9
1047    YUV420P10
1048    YUV422P10
1049    YUV444P10
1050    YUV420P12
1051    YUV422P12
1052    YUV444P12
1053    YUV420P14
1054    YUV422P14
1055    YUV444P14
1056    YUV420P16
1057    YUV422P16
1058    YUV444P16
1059    YUV444PH
1060    YUV444PS
1061    RGB24
1062    RGB27
1063    RGB30
1064    RGB36
1065    RGB42
1066    RGB48
1067    RGBH
1068    RGBS
1069
1070 Chroma Location
1071 ---------------
1072
1073 ::
1074
1075    CHROMA_LEFT
1076    CHROMA_CENTER
1077    CHROMA_TOP_LEFT
1078    CHROMA_TOP
1079    CHROMA_BOTTOM_LEFT
1080    CHROMA_BOTTOM
1081
1082 Field Based
1083 -----------
1084
1085 ::
1086
1087    FIELD_PROGRESSIVE
1088    FIELD_TOP
1089    FIELD_BOTTOM
1090
1091 Color Range
1092 -----------
1093
1094 ::
1095
1096    RANGE_FULL
1097    RANGE_LIMITED
1098
1099 Matrix Coefficients
1100 -------------------
1101
1102 ::
1103
1104    MATRIX_RGB
1105    MATRIX_BT709
1106    MATRIX_UNSPECIFIED
1107    MATRIX_FCC
1108    MATRIX_BT470_BG
1109    MATRIX_ST170_M
1110    MATRIX_ST240_M
1111    MATRIX_YCGCO
1112    MATRIX_BT2020_NCL
1113    MATRIX_BT2020_CL
1114    MATRIX_CHROMATICITY_DERIVED_NCL
1115    MATRIX_CHROMATICITY_DERIVED_CL
1116    MATRIX_ICTCP
1117
1118 TransferCharacteristics
1119 -----------------------
1120
1121 ::
1122
1123    TRANSFER_BT709
1124    TRANSFER_UNSPECIFIED
1125    TRANSFER_BT470_M
1126    TRANSFER_BT470_BG
1127    TRANSFER_BT601
1128    TRANSFER_ST240_M
1129    TRANSFER_LINEAR
1130    TRANSFER_LOG_100
1131    TRANSFER_LOG_316
1132    TRANSFER_IEC_61966_2_4
1133    TRANSFER_IEC_61966_2_1
1134    TRANSFER_BT2020_10
1135    TRANSFER_BT2020_12
1136    TRANSFER_ST2084
1137    TRANSFER_ST428
1138    TRANSFER_ARIB_B67
1139
1140 Color Primaries
1141 ---------------
1142
1143 ::
1144
1145    PRIMARIES_BT709
1146    PRIMARIES_UNSPECIFIED
1147    PRIMARIES_BT470_M
1148    PRIMARIES_BT470_BG
1149    PRIMARIES_ST170_M
1150    PRIMARIES_ST240_M
1151    PRIMARIES_FILM
1152    PRIMARIES_BT2020
1153    PRIMARIES_ST428
1154    PRIMARIES_ST431_2
1155    PRIMARIES_ST432_1
1156    PRIMARIES_EBU3213_E
1157
1158 Audio
1159 *****
1160
1161 Channels
1162 --------
1163
1164 ::
1165
1166    FRONT_LEFT
1167    FRONT_RIGHT
1168    FRONT_CENTER
1169    LOW_FREQUENCY
1170    BACK_LEFT
1171    BACK_RIGHT
1172    FRONT_LEFT_OF_CENTER
1173    FRONT_RIGHT_OF_CENTER
1174    BACK_CENTER
1175    SIDE_LEFT
1176    SIDE_RIGHT
1177    TOP_CENTER
1178    TOP_FRONT_LEFT
1179    TOP_FRONT_CENTER
1180    TOP_FRONT_RIGHT
1181    TOP_BACK_LEFT
1182    TOP_BACK_CENTER
1183    TOP_BACK_RIGHT
1184    STEREO_LEFT
1185    STEREO_RIGHT
1186    WIDE_LEFT
1187    WIDE_RIGHT
1188    SURROUND_DIRECT_LEFT
1189    SURROUND_DIRECT_RIGHT
1190    LOW_FREQUENCY2
1191
1192 Sample Type
1193 ***********
1194
1195 ::
1196
1197    INTEGER
1198    FLOAT