API

The API is a python module named pv that allows users to modify the kernel’s behavior.

Properties

Properties are just variables, but they can be interpreted by the GUI and displayed properly.

class pv.Property

Base property class.

Inherit and define:

  • type: Type.

  • set(value): Set the property’s value. Default just sets it, but you may need to check requirements.

Call super().__init__() AFTER initializing self.default

set(value: Any) → None

Sets the property’s value.

Parameters

value – Any value. Will be casted with self.type.

Returns

None

class pv.BoolProp(name: str = '', description: str = '', default: bool = False)

Boolean property.

class pv.IntProp(name: str = '', description: str = '', default: int = 0, min: int = Ellipsis, max: int = Ellipsis)

Integer property.

class pv.FloatProp(name: str = '', description: str = '', default: float = 0, min: float = Ellipsis, max: float = Ellipsis)

Float property.

class pv.StrProp(name: str = '', description: str = '', default: str = '', max_len: int = 1000, choices: Sequence[str] = [])

String property.

class pv.ListProp(name: str = '', description: str = '', default: List[Any] = [0, 0, 0, 0])

List property. Use this for color. May contain a list of lists.

A PropertyGroup is a collection of properties.

class pv.PropertyGroup

A collection of Properties.

When creating your own PropertyGroup, you will inherit a class from this base class. Then, define:

  • idname: The unique idname of this property group.

  • properties: Define each property as a static attribute (shown below).

class MyProps(pv.PropertyGroup):
    prop1 = pv.props.BoolProp(name="hi")
_get_prop(name: str) → pv.props.Property

You can use this to bypass __getattribute__ and get the actual Property object.

Data and Cache

The API has a few classes for storing and accessing data.

class pv.DataGroup

A group of data pointers.

When creating your own DataGroup, inherit and define the idname.

Then, you can run video.data_idname.value = x or video.data_idname.value2 to access and set values.

The values can be any type. Value names cannot be idname or items, as they will overwrite internal variables.

class pv.Cache(video: None)

Cache managing for a video.

You can read and write specific file names with cache.fp(name, mode), or automatically set the name to the current frame with cache.fp_frame.

To add a cache, inherit and define:

  • idname: Cache idname. Will also be the cache folder name.

  • depends: Tuple of property idnames this cache depends on. If any of them change, the cache will be cleared. Default ().

Operators

Operators are functions that operate on a video and can be displayed in the GUI.

class pv.Operator(video: None)

A function that is positioned at pv.ops.group.idname. It can be displayed in the GUI.

The return value will always be None.

To create your own operator, inherit and define:

  • group: Operator group.

  • idname: Unique operator idname.

  • label: The text that will show on the GUI (as a button).

  • description: What this operator does.

  • execute(video): This will be run when the operator is called. The first parameter is the video class (pvkernel.Video)

Jobs

Jobs modify the rendering process.

class pv.Job

Create a job to modify the final video.

See https://piano-video.rtfd.io/en/latest/blog/render_jobs.html for more info.

Inherit and define:

  • idname: Job idname.

  • ops: List of operator idnames ("group.idname") to run.

  • execute: This function will run before running the operators. Default does nothing.

Utilities

pv.utils.register_class(cls: Type) → None

Register a class to “apply” it to the kernel.

pv.utils.add_callback(func: Callable, classes: Sequence[str]) → None

Add a callback function when a class is registered. The function will be passed one argument, the class.

Parameters

  • func – Function to call.

  • classes –

    A list of strings indicating which types of classes to listen for. Valid values:

    • ”cache”: Cache

    • ”dgroup”: DataGroup

    • ”pgroup”: PropertyGroup

    • ”ogroup”: Operator

pv.utils.get(objs: Sequence[Any], idname: str) → Any

Return the object in objs with idname idname.

pv.utils.get_index(objs: Sequence[Any], idname: str) → int

Return the index of the object in objs with idname idname.

pv.utils.get_exists(objs: Sequence[Any], idname: str) → bool

Check whether there is an object with idname idname.