vapoursynth-graph 1.0.0__py3-none-win_amd64.whl

vapoursynth/plugins/graph/manifest.vs

@@ -0,0 +1,2 @@
+[VapourSynth Manifest V1]
+graph

vapoursynth_graph-1.0.0.dist-info/METADATA

@@ -0,0 +1,73 @@
+Metadata-Version: 2.5
+Name: vapoursynth-graph
+Version: 1.0.0
+Summary: VapourSynth filter graph inspection
+Author-email: Vardë <ichunjo.le.terrible@gmail.com>
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: vapoursynth>=79
+Description-Content-Type: text/markdown
+
+# vsgraph
+
+VapourSynth plugin (Rust) and typed Python API for inspecting filter graphs.
+
+Walks the dependency graph of a `VideoNode` or `AudioNode` and returns typed dataclasses describing every node (filter name, filter mode, media info, processing time, creation call stack) and edge (request pattern).
+
+Graphs can be exported to Mermaid, Graphviz DOT, ASCII, Cytoscape.js or JSON.
+
+## Requirements
+
+- Python ≥ 3.12
+- VapourSynth ≥ R79 (API 4.2 or 4.3)
+- The core must be created with `vs.CoreCreationFlags.ENABLE_GRAPH_INSPECTION`
+
+## Installation
+
+```powershell
+pip install vsgraph
+```
+
+The wheel ships the native `graph` plugin, which VapourSynth autoloads.
+
+## Usage
+
+```python
+import vapoursynth as vs
+from vsgraph import get_graph
+
+core = vs.core
+vs._try_enable_introspection(0)
+
+clip = core.std.BlankClip(width=1920, height=1080, format=vs.YUV420P8)
+clip = core.resize.Bicubic(clip, width=1280, height=720)
+
+graph = get_graph(clip)
+
+print(graph.root.name, graph.root.media_info.fps)
+print(graph.to_ascii())
+
+for node in graph.get_dependencies(graph.root):
+    print(node.name, node.filter_mode, f"{node.processing_time_ms:.2f} ms")
+```
+
+### Exports
+
+| Method                 | Output                     |
+| ---------------------- | -------------------------- |
+| `Graph.to_mermaid()`   | Mermaid flowchart          |
+| `Graph.to_dot()`       | Graphviz DOT               |
+| `Graph.to_ascii()`     | Tree view                  |
+| `Graph.to_cytoscape()` | Cytoscape.js elements dict |
+| `Graph.to_json()`      | JSON string                |
+
+The raw plugin functions are also available as `core.graph.VideoGraph(clip, pretty)` and `core.graph.AudioGraph(clip, pretty)`, both returning a JSON string.
+
+## Development
+
+Requires a Rust toolchain and [uv](https://docs.astral.sh/uv/).
+
+```powershell
+uv sync --no-editable
+uv run pytest
+```

vapoursynth_graph-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+vapoursynth/plugins/graph/graph.avx2.dll,sha256=aVV_u1ltBLIGDtHFtiHJ1SCMmxnPmYiEa2TyEnA4s6E,203776
+vapoursynth/plugins/graph/graph.dll,sha256=3rp5dHn1lIeIogm1Glc7ZWZNJHzaAsGeH-7kmLlvnDo,203776
+vapoursynth/plugins/graph/graph.zn4.dll,sha256=Y021uEzLg92hCvx1pT0oh3PbeVA1sM5dNQYmxAQrx7E,203776
+vapoursynth/plugins/graph/manifest.vs,sha256=-FtpHXQAwrfGg0HFTdIwWkpRUnQpXCfdyLe-MNz5ZmA,34
+vsgraph/__init__.py,sha256=tvqGAC_uUgqNUtsl42xtkgJy79ALKjj_5ViYq1xDbeI,777
+vsgraph/graph.py,sha256=n5FREOfJuv6MmyEZQIrZtJyyTgjieO8WQKb5mTF_srI,1377
+vsgraph/models.py,sha256=yKrclBiPOLo7aFtv8lx--Cgf4gfYkcPcQhziAHSpXYE,23089
+vsgraph/py.typed,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
+vsgraph/vs.py,sha256=6ngzc1RXQr4Pk0_8e-_PXE0-iHZ3n1YImc8_gHFlSXA,2245
+vapoursynth_graph-1.0.0.dist-info/METADATA,sha256=XE4YzBE-tCcfLLAl3AKfli2AI_1FC3TWh5uXjnZkuxI,2127
+vapoursynth_graph-1.0.0.dist-info/WHEEL,sha256=A7YmR1UrJozxyeLCzQFwQUdR7CRUwkFKasEDmnrjVxY,94
+vapoursynth_graph-1.0.0.dist-info/licenses/LICENSE,sha256=5N6rCiaYYl2Nma6bEvgCut4AoICEDLi9BkLKL4_OOGA,14120
+vapoursynth_graph-1.0.0.dist-info/RECORD,,

vapoursynth_graph-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: false
+Tag: py3-none-win_amd64

vapoursynth_graph-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,291 @@
+                      EUROPEAN UNION PUBLIC LICENCE v. 1.2
+                      EUPL © the European Union 2007, 2016
+
+This European Union Public Licence (the ‘EUPL’) applies to the Work (as
+defined below) which is provided under the terms of this Licence. Any use of
+the Work, other than as authorised under this Licence is prohibited (to the
+extent such use is covered by a right of the copyright holder of the Work).
+
+The Work is provided under the terms of this Licence when the Licensor (as
+defined below) has placed the following notice immediately following the
+copyright notice for the Work:
+
+        Licensed under the EUPL
+
+or has expressed by any other means his willingness to license under the EUPL.
+
+1. Definitions
+
+In this Licence, the following terms have the following meaning:
+
+- ‘The Licence’: this Licence.
+
+- ‘The Original Work’: the work or software distributed or communicated by the
+  Licensor under this Licence, available as Source Code and also as Executable
+  Code as the case may be.
+
+- ‘Derivative Works’: the works or software that could be created by the
+  Licensee, based upon the Original Work or modifications thereof. This
+  Licence does not define the extent of modification or dependence on the
+  Original Work required in order to classify a work as a Derivative Work;
+  this extent is determined by copyright law applicable in the country
+  mentioned in Article 15.
+
+- ‘The Work’: the Original Work or its Derivative Works.
+
+- ‘The Source Code’: the human-readable form of the Work which is the most
+  convenient for people to study and modify.
+
+- ‘The Executable Code’: any code which has generally been compiled and which
+  is meant to be interpreted by a computer as a program.
+
+- ‘The Licensor’: the natural or legal person that distributes or communicates
+  the Work under the Licence.
+
+- ‘Contributor(s)’: any natural or legal person who modifies the Work under
+  the Licence, or otherwise contributes to the creation of a Derivative Work.
+
+- ‘The Licensee’ or ‘You’: any natural or legal person who makes any usage of
+  the Work under the terms of the Licence.
+
+- ‘Distribution’ or ‘Communication’: any act of selling, giving, lending,
+  renting, distributing, communicating, transmitting, or otherwise making
+  available, online or offline, copies of the Work or providing access to its
+  essential functionalities at the disposal of any other natural or legal
+  person.
+
+2. Scope of the rights granted by the Licence
+
+The Licensor hereby grants You a worldwide, royalty-free, non-exclusive,
+sublicensable licence to do the following, for the duration of copyright
+vested in the Original Work:
+
+- use the Work in any circumstance and for all usage,
+- reproduce the Work,
+- modify the Work, and make Derivative Works based upon the Work,
+- communicate to the public, including the right to make available or display
+  the Work or copies thereof to the public and perform publicly, as the case
+  may be, the Work,
+- distribute the Work or copies thereof,
+- lend and rent the Work or copies thereof,
+- sublicense rights in the Work or copies thereof.
+
+Those rights can be exercised on any media, supports and formats, whether now
+known or later invented, as far as the applicable law permits so.
+
+In the countries where moral rights apply, the Licensor waives his right to
+exercise his moral right to the extent allowed by law in order to make
+effective the licence of the economic rights here above listed.
+
+The Licensor grants to the Licensee royalty-free, non-exclusive usage rights
+to any patents held by the Licensor, to the extent necessary to make use of
+the rights granted on the Work under this Licence.
+
+3. Communication of the Source Code
+
+The Licensor may provide the Work either in its Source Code form, or as
+Executable Code. If the Work is provided as Executable Code, the Licensor
+provides in addition a machine-readable copy of the Source Code of the Work
+along with each copy of the Work that the Licensor distributes or indicates,
+in a notice following the copyright notice attached to the Work, a repository
+where the Source Code is easily and freely accessible for as long as the
+Licensor continues to distribute or communicate the Work.
+
+4. Limitations on copyright
+
+Nothing in this Licence is intended to deprive the Licensee of the benefits
+from any exception or limitation to the exclusive rights of the rights owners
+in the Work, of the exhaustion of those rights or of other applicable
+limitations thereto.
+
+5. Obligations of the Licensee
+
+The grant of the rights mentioned above is subject to some restrictions and
+obligations imposed on the Licensee. Those obligations are the following:
+
+Attribution right: The Licensee shall keep intact all copyright, patent or
+trademarks notices and all notices that refer to the Licence and to the
+disclaimer of warranties. The Licensee must include a copy of such notices and
+a copy of the Licence with every copy of the Work he/she distributes or
+communicates. The Licensee must cause any Derivative Work to carry prominent
+notices stating that the Work has been modified and the date of modification.
+
+Copyleft clause: If the Licensee distributes or communicates copies of the
+Original Works or Derivative Works, this Distribution or Communication will be
+done under the terms of this Licence or of a later version of this Licence
+unless the Original Work is expressly distributed only under this version of
+the Licence — for example by communicating ‘EUPL v. 1.2 only’. The Licensee
+(becoming Licensor) cannot offer or impose any additional terms or conditions
+on the Work or Derivative Work that alter or restrict the terms of the
+Licence.
+
+Compatibility clause: If the Licensee Distributes or Communicates Derivative
+Works or copies thereof based upon both the Work and another work licensed
+under a Compatible Licence, this Distribution or Communication can be done
+under the terms of this Compatible Licence. For the sake of this clause,
+‘Compatible Licence’ refers to the licences listed in the appendix attached to
+this Licence. Should the Licensee's obligations under the Compatible Licence
+conflict with his/her obligations under this Licence, the obligations of the
+Compatible Licence shall prevail.
+
+Provision of Source Code: When distributing or communicating copies of the
+Work, the Licensee will provide a machine-readable copy of the Source Code or
+indicate a repository where this Source will be easily and freely available
+for as long as the Licensee continues to distribute or communicate the Work.
+
+Legal Protection: This Licence does not grant permission to use the trade
+names, trademarks, service marks, or names of the Licensor, except as required
+for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the copyright notice.
+
+6. Chain of Authorship
+
+The original Licensor warrants that the copyright in the Original Work granted
+hereunder is owned by him/her or licensed to him/her and that he/she has the
+power and authority to grant the Licence.
+
+Each Contributor warrants that the copyright in the modifications he/she
+brings to the Work are owned by him/her or licensed to him/her and that he/she
+has the power and authority to grant the Licence.
+
+Each time You accept the Licence, the original Licensor and subsequent
+Contributors grant You a licence to their contributions to the Work, under the
+terms of this Licence.
+
+7. Disclaimer of Warranty
+
+The Work is a work in progress, which is continuously improved by numerous
+Contributors. It is not a finished work and may therefore contain defects or
+‘bugs’ inherent to this type of development.
+
+For the above reason, the Work is provided under the Licence on an ‘as is’
+basis and without warranties of any kind concerning the Work, including
+without limitation merchantability, fitness for a particular purpose, absence
+of defects or errors, accuracy, non-infringement of intellectual property
+rights other than copyright as stated in Article 6 of this Licence.
+
+This disclaimer of warranty is an essential part of the Licence and a
+condition for the grant of any rights to the Work.
+
+8. Disclaimer of Liability
+
+Except in the cases of wilful misconduct or damages directly caused to natural
+persons, the Licensor will in no event be liable for any direct or indirect,
+material or moral, damages of any kind, arising out of the Licence or of the
+use of the Work, including without limitation, damages for loss of goodwill,
+work stoppage, computer failure or malfunction, loss of data or any commercial
+damage, even if the Licensor has been advised of the possibility of such
+damage. However, the Licensor will be liable under statutory product liability
+laws as far such laws apply to the Work.
+
+9. Additional agreements
+
+While distributing the Work, You may choose to conclude an additional
+agreement, defining obligations or services consistent with this Licence.
+However, if accepting obligations, You may act only on your own behalf and on
+your sole responsibility, not on behalf of the original Licensor or any other
+Contributor, and only if You agree to indemnify, defend, and hold each
+Contributor harmless for any liability incurred by, or claims asserted against
+such Contributor by the fact You have accepted any warranty or additional
+liability.
+
+10. Acceptance of the Licence
+
+The provisions of this Licence can be accepted by clicking on an icon ‘I
+agree’ placed under the bottom of a window displaying the text of this Licence
+or by affirming consent in any other similar way, in accordance with the rules
+of applicable law. Clicking on that icon indicates your clear and irrevocable
+acceptance of this Licence and all of its terms and conditions.
+
+Similarly, you irrevocably accept this Licence and all of its terms and
+conditions by exercising any rights granted to You by Article 2 of this
+Licence, such as the use of the Work, the creation by You of a Derivative Work
+or the Distribution or Communication by You of the Work or copies thereof.
+
+11. Information to the public
+
+In case of any Distribution or Communication of the Work by means of
+electronic communication by You (for example, by offering to download the Work
+from a remote location) the distribution channel or media (for example, a
+website) must at least provide to the public the information requested by the
+applicable law regarding the Licensor, the Licence and the way it may be
+accessible, concluded, stored and reproduced by the Licensee.
+
+12. Termination of the Licence
+
+The Licence and the rights granted hereunder will terminate automatically upon
+any breach by the Licensee of the terms of the Licence.
+
+Such a termination will not terminate the licences of any person who has
+received the Work from the Licensee under the Licence, provided such persons
+remain in full compliance with the Licence.
+
+13. Miscellaneous
+
+Without prejudice of Article 9 above, the Licence represents the complete
+agreement between the Parties as to the Work.
+
+If any provision of the Licence is invalid or unenforceable under applicable
+law, this will not affect the validity or enforceability of the Licence as a
+whole. Such provision will be construed or reformed so as necessary to make it
+valid and enforceable.
+
+The European Commission may publish other linguistic versions or new versions
+of this Licence or updated versions of the Appendix, so far this is required
+and reasonable, without reducing the scope of the rights granted by the
+Licence. New versions of the Licence will be published with a unique version
+number.
+
+All linguistic versions of this Licence, approved by the European Commission,
+have identical value. Parties can take advantage of the linguistic version of
+their choice.
+
+14. Jurisdiction
+
+Without prejudice to specific agreement between parties,
+
+- any litigation resulting from the interpretation of this License, arising
+  between the European Union institutions, bodies, offices or agencies, as a
+  Licensor, and any Licensee, will be subject to the jurisdiction of the Court
+  of Justice of the European Union, as laid down in article 272 of the Treaty
+  on the Functioning of the European Union,
+
+- any litigation arising between other parties and resulting from the
+  interpretation of this License, will be subject to the exclusive
+  jurisdiction of the competent court where the Licensor resides or conducts
+  its primary business.
+
+15. Applicable Law
+
+Without prejudice to specific agreement between parties,
+
+- this Licence shall be governed by the law of the European Union Member State
+  where the Licensor has his seat, resides or has his registered office,
+
+- this licence shall be governed by Belgian law if the Licensor has no seat,
+  residence or registered office inside a European Union Member State.
+
+Appendix
+
+‘Compatible Licences’ according to Article 5 EUPL are:
+
+- GNU General Public License (GPL) v. 2, v. 3
+- GNU Affero General Public License (AGPL) v. 3
+- Open Software License (OSL) v. 2.1, v. 3.0
+- Eclipse Public License (EPL) v. 1.0
+- CeCILL v. 2.0, v. 2.1
+- Mozilla Public Licence (MPL) v. 2
+- GNU Lesser General Public Licence (LGPL) v. 2.1, v. 3
+- Creative Commons Attribution-ShareAlike v. 3.0 Unported (CC BY-SA 3.0) for
+  works other than software
+- European Union Public Licence (EUPL) v. 1.1, v. 1.2
+- Québec Free and Open-Source Licence — Reciprocity (LiLiQ-R) or Strong
+  Reciprocity (LiLiQ-R+).
+
+The European Commission may update this Appendix to later versions of the
+above licences without producing a new version of the EUPL, as long as they
+provide the rights granted in Article 2 of this Licence and protect the
+covered Source Code from exclusive appropriation.
+
+All other changes or additions to this Appendix require the production of a
+new EUPL version.

vsgraph/__init__.py

@@ -0,0 +1,42 @@
+"""Typed dataclasses and utilities for VapourSynth graph inspection."""
+
+from .graph import get_graph
+from .models import (
+    AudioFrameInfo,
+    AudioMediaInfo,
+    AudioNodeRef,
+    CallFrame,
+    Edge,
+    FrameInfo,
+    FuncRef,
+    Graph,
+    MediaInfo,
+    Node,
+    NodeKey,
+    NodeRef,
+    VideoFrameInfo,
+    VideoMediaInfo,
+    VideoNodeRef,
+)
+from .vs import AudioFormat, RequestPattern
+
+__all__ = [
+    "AudioFormat",
+    "AudioFrameInfo",
+    "AudioMediaInfo",
+    "AudioNodeRef",
+    "CallFrame",
+    "Edge",
+    "FrameInfo",
+    "FuncRef",
+    "Graph",
+    "MediaInfo",
+    "Node",
+    "NodeKey",
+    "NodeRef",
+    "RequestPattern",
+    "VideoFrameInfo",
+    "VideoMediaInfo",
+    "VideoNodeRef",
+    "get_graph",
+]

vsgraph/graph.py

@@ -0,0 +1,34 @@
+from typing import Any, assert_never, overload
+
+import vapoursynth as vs
+
+from .models import AudioMediaInfo, Graph, VideoMediaInfo
+
+type MediaNode = vs.VideoNode | vs.AudioNode
+
+core = vs.core
+
+
+@overload
+def get_graph(clip: vs.VideoNode, /, *, pretty: bool = False, reset_timing: bool = False) -> Graph[VideoMediaInfo]: ...
+@overload
+def get_graph(clip: vs.AudioNode, /, *, pretty: bool = False, reset_timing: bool = False) -> Graph[AudioMediaInfo]: ...
+@overload
+def get_graph(clip: MediaNode, /, *, pretty: bool = False, reset_timing: bool = False) -> Graph[Any]: ...
+def get_graph(clip: MediaNode, /, *, pretty: bool = False, reset_timing: bool = False) -> Graph[Any]:
+    """
+    Inspect the dependency graph of a VideoNode or AudioNode and return a typed Graph.
+
+    Args:
+        clip: The VapourSynth VideoNode or AudioNode to inspect.
+        pretty: Whether the underlying JSON should be formatted with indentation.
+        reset_timing: Whether to reset the node and core freed node processing timers after inspection.
+    """
+    match clip:
+        case vs.VideoNode():
+            raw_json = core.graph.VideoGraph(clip, pretty, reset_timing)
+        case vs.AudioNode():
+            raw_json = core.graph.AudioGraph(clip, pretty, reset_timing)
+        case _:
+            assert_never(clip)
+    return Graph.from_json(raw_json)

vsgraph/models.py

@@ -0,0 +1,654 @@
+from __future__ import annotations
+
+import json
+from abc import ABC, abstractmethod
+from collections.abc import Collection, Iterator
+from dataclasses import dataclass, field, fields
+from fractions import Fraction
+from functools import cache
+from inspect import Signature
+from operator import attrgetter
+from typing import Any, Literal, Self, override
+
+import vapoursynth as vs
+
+from .vs import AudioFormat, RequestPattern
+
+type NodeKey = vs.RawNode | Node[Any] | NodeRef | str
+
+
+@dataclass(slots=True, kw_only=True)
+class MediaInfo(ABC):
+    @property
+    @abstractmethod
+    def format(self) -> vs.VideoFormat | AudioFormat: ...
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to a dictionary."""
+        data = dict[str, Any]()
+
+        for dfield in fields(self):
+            attr = getattr(self, dfield.name)
+            if dfield.name != "gpu_resident" or attr is not None:
+                data[dfield.name] = attr
+
+        data["format"] = self.format._as_dict()
+
+        return data
+
+    @classmethod
+    @abstractmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self: ...
+
+
+@dataclass(slots=True, kw_only=True)
+class VideoMediaInfo(MediaInfo):
+    """Media information for video nodes."""
+
+    format_id: vs.PresetVideoFormat
+    width: int
+    height: int
+    fps_num: int
+    fps_den: int
+    num_frames: int
+    gpu_resident: bool | None = None
+    type: Literal["vnode"] = "vnode"
+
+    @property
+    def fps(self) -> Fraction:
+        """Frame rate as an exact Fraction."""
+        return Fraction(self.fps_num, self.fps_den) if self.fps_den != 0 else Fraction(0, 1)
+
+    @property
+    @override
+    def format(self) -> vs.VideoFormat:
+        """The resolved VideoFormat from the core."""
+        return vs.core.get_video_format(self.format_id)
+
+    @override
+    def to_dict(self) -> dict[str, Any]:
+        data = super().to_dict()
+        data["format"] = self.format._as_dict()
+        return data
+
+    @classmethod
+    @override
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        """Construct from a dictionary."""
+        return cls(
+            format_id=vs.PresetVideoFormat(data["format_id"]),
+            width=int(data["width"]),
+            height=int(data["height"]),
+            fps_num=int(data["fps_num"]),
+            fps_den=int(data["fps_den"]),
+            num_frames=int(data["num_frames"]),
+            gpu_resident=data.get("gpu_resident"),
+        )
+
+
+@dataclass(slots=True, kw_only=True)
+class AudioMediaInfo(MediaInfo):
+    """Media information for audio nodes."""
+
+    format_id: int
+    sample_rate: int
+    num_samples: int
+    num_frames: int
+    gpu_resident: bool | None = None
+    type: Literal["anode"] = "anode"
+
+    @property
+    @override
+    def format(self) -> AudioFormat:
+        """The resolved AudioFormat."""
+        return AudioFormat.from_id(self.format_id)
+
+    @override
+    def to_dict(self) -> dict[str, Any]:
+        data = super().to_dict()
+        data["format"] = self.format._as_dict()
+        return data
+
+    @classmethod
+    @override
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        """Construct from a dictionary."""
+        return cls(
+            format_id=int(data["format_id"]),
+            sample_rate=int(data["sample_rate"]),
+            num_samples=int(data["num_samples"]),
+            num_frames=int(data["num_frames"]),
+            gpu_resident=data.get("gpu_resident"),
+        )
+
+
+@dataclass(slots=True, kw_only=True)
+class FrameInfo(ABC):
+    props: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to a dictionary."""
+        data = dict[str, Any]()
+
+        for dfield in fields(self):
+            attr = getattr(self, dfield.name)
+            if dfield.name != "gpu_resident" or attr is not None:
+                data[dfield.name] = attr
+
+        return data
+
+    @classmethod
+    @abstractmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self: ...
+
+
+@dataclass(slots=True, kw_only=True)
+class VideoFrameInfo(FrameInfo):
+    """Video frame argument metadata."""
+
+    id: str
+    format_id: vs.PresetVideoFormat
+    width: int
+    height: int
+    gpu_resident: bool | None = None
+    type: Literal["vframe"] = "vframe"
+
+    @property
+    def format(self) -> vs.VideoFormat:
+        """The resolved VideoFormat from the core."""
+        return vs.core.get_video_format(self.format_id)
+
+    @classmethod
+    @override
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        """Construct from a dictionary."""
+        return cls(
+            id=str(data["id"]),
+            format_id=vs.PresetVideoFormat(data["format_id"]),
+            width=int(data["width"]),
+            height=int(data["height"]),
+            gpu_resident=data.get("gpu_resident"),
+            props=dict(data["props"]),
+        )
+
+
+@dataclass(slots=True, kw_only=True)
+class AudioFrameInfo(FrameInfo):
+    """Audio frame argument metadata."""
+
+    id: str
+    format_id: int
+    num_samples: int
+    gpu_resident: bool | None = None
+    type: Literal["aframe"] = "aframe"
+
+    @property
+    def format(self) -> AudioFormat:
+        """The resolved AudioFormat."""
+        return AudioFormat.from_id(self.format_id)
+
+    @classmethod
+    @override
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        """Construct from a dictionary."""
+        return cls(
+            id=str(data["id"]),
+            format_id=int(data["format_id"]),
+            num_samples=int(data["num_samples"]),
+            gpu_resident=data.get("gpu_resident"),
+            props=dict(data["props"]),
+        )
+
+
+@dataclass(slots=True, kw_only=True)
+class NodeRef(ABC):
+    """Reference to a node in a call frame argument."""
+
+    id: str
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to a dictionary."""
+        return {dfield.name: getattr(self, dfield.name) for dfield in fields(self)}
+
+    @classmethod
+    @abstractmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self: ...
+
+
+@dataclass(slots=True, kw_only=True)
+class VideoNodeRef(NodeRef):
+    """Video node argument reference."""
+
+    type: Literal["vnode"] = "vnode"
+
+    @classmethod
+    @override
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        """Construct from a dictionary."""
+        return cls(id=str(data["id"]))
+
+
+@dataclass(slots=True, kw_only=True)
+class AudioNodeRef(NodeRef):
+    """Audio node argument reference."""
+
+    type: Literal["anode"] = "anode"
+
+    @classmethod
+    @override
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        """Construct from a dictionary."""
+        return cls(id=str(data["id"]))
+
+
+@dataclass(slots=True, kw_only=True)
+class FuncRef:
+    """Function argument reference."""
+
+    id: str
+    type: Literal["func"] = "func"
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to a dictionary."""
+        return {"id": self.id, "type": self.type}
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        """Construct from a dictionary."""
+        return cls(id=str(data["id"]))
+
+
+@dataclass(slots=True, kw_only=True)
+class CallFrame:
+    """Represents a call frame in the node creation stack."""
+
+    level: int
+    id: str
+    plugin_id: str
+    plugin_ns: str
+    function: str
+    arguments: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to a dictionary."""
+
+        def serialize_arg(val: Any) -> Any:
+            if isinstance(val, (FrameInfo, NodeRef, FuncRef)):
+                return val.to_dict()
+            if isinstance(val, list):
+                return [serialize_arg(item) for item in val]
+            return val
+
+        param_names = _get_param_names(f"{self.plugin_ns}.{self.function}")
+        arguments = {k: serialize_arg(self.arguments[k]) for k in param_names if k in self.arguments}
+
+        return {
+            "level": self.level,
+            "id": self.id,
+            "plugin_id": self.plugin_id,
+            "plugin_ns": self.plugin_ns,
+            "function": self.function,
+            "arguments": arguments,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        """Construct from a dictionary."""
+
+        def parse_args(val: Any) -> Any:
+            if isinstance(val, dict):
+                match val.get("type"):
+                    case "vnode":
+                        return VideoNodeRef.from_dict(val)
+                    case "anode":
+                        return AudioNodeRef.from_dict(val)
+                    case "vframe":
+                        return VideoFrameInfo.from_dict(val)
+                    case "aframe":
+                        return AudioFrameInfo.from_dict(val)
+                    case "func":
+                        return FuncRef.from_dict(val)
+                    case _:
+                        return val
+            return [parse_args(item) for item in val] if isinstance(val, list) else val
+
+        return cls(
+            level=int(data["level"]),
+            id=str(data["id"]),
+            plugin_id=str(data["plugin_id"]),
+            plugin_ns=str(data["plugin_ns"]),
+            function=str(data["function"]),
+            arguments={k: parse_args(v) for k, v in data["arguments"].items()},
+        )
+
+
+@dataclass(slots=True, kw_only=True)
+class Edge:
+    """Represents a dependency edge between nodes in the graph."""
+
+    source: str
+    target: str
+    pattern: RequestPattern
+    index: int
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to a dictionary."""
+        return {"source": self.source, "target": self.target, "pattern": self.pattern, "index": self.index}
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        """Construct from a dictionary."""
+        return cls(
+            source=str(data["source"]),
+            target=str(data["target"]),
+            pattern=RequestPattern(data["pattern"]),
+            index=int(data["index"]),
+        )
+
+
+@dataclass(slots=True, kw_only=True)
+class Node[MediaInfoT: MediaInfo]:
+    """Represents a filter node in the graph."""
+
+    id: str
+    name: str
+    filter_mode: vs.FilterMode
+    processing_time_ns: int
+    media_info: MediaInfoT
+    call_stack: list[CallFrame] = field(default_factory=list)
+
+    @property
+    def processing_time_ms(self) -> float:
+        """Processing time in milliseconds."""
+        return self.processing_time_ns / 1_000_000.0
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to a dictionary."""
+        data: dict[str, Any] = {
+            "id": self.id,
+            "name": self.name,
+            "filter_mode": self.filter_mode,
+            "processing_time_ns": self.processing_time_ns,
+            "media_info": self.media_info.to_dict(),
+            "call_stack": [frame.to_dict() for frame in self.call_stack],
+        }
+        return data
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        """Construct from a dictionary."""
+        match (raw_info := data["media_info"])["type"]:
+            case "vnode":
+                media_info = VideoMediaInfo.from_dict(raw_info)
+            case "anode":
+                media_info = AudioMediaInfo.from_dict(raw_info)
+            case other:
+                raise ValueError(f"Unknown media_info type: {other!r}")
+
+        call_stack = [CallFrame.from_dict(frame) for frame in data["call_stack"]]
+
+        return cls(
+            id=str(data["id"]),
+            name=str(data["name"]),
+            filter_mode=vs.FilterMode(data["filter_mode"]),
+            processing_time_ns=int(data["processing_time_ns"]),
+            media_info=media_info,
+            call_stack=call_stack,
+        )
+
+
+@dataclass(slots=True, kw_only=True)
+class Graph[MediaInfoT: (VideoMediaInfo, AudioMediaInfo)](Collection[Node[MediaInfoT]]):
+    """Full VapourSynth dependency graph output."""
+
+    root_id: str
+    nodes: list[Node[MediaInfoT]] = field(default_factory=list)
+    edges: list[Edge] = field(default_factory=list)
+
+    @override
+    def __contains__(self, node_or_id: object) -> bool:
+        return (
+            to_node_id(node_or_id) in self.nodes_by_id
+            if isinstance(node_or_id, (vs.RawNode, Node, NodeRef, str))
+            else False
+        )
+
+    @override
+    def __iter__(self) -> Iterator[Node[MediaInfoT]]:
+        return iter(self.nodes)
+
+    @override
+    def __len__(self) -> int:
+        return len(self.nodes)
+
+    def __getitem__(self, node_or_id: NodeKey) -> Node[MediaInfoT]:
+        if node := self.nodes_by_id.get(to_node_id(node_or_id)):
+            return node
+        raise KeyError(node_or_id)
+
+    @property
+    def root(self) -> Node[MediaInfoT]:
+        """The root node where inspection started."""
+        for node in self.nodes:
+            if node.id == self.root_id:
+                return node
+        raise KeyError(f"Root node '{self.root_id}' not found in graph nodes")
+
+    @property
+    def nodes_by_id(self) -> dict[str, Node[MediaInfoT]]:
+        """Dictionary of nodes keyed by their ID."""
+        return {node.id: node for node in self.nodes}
+
+    def get_incoming_edges(self, node_or_id: NodeKey) -> list[Edge]:
+        """Return all edges where this node is the target (inputs to this node)."""
+        nid = to_node_id(node_or_id)
+        return [edge for edge in self.edges if edge.target == nid]
+
+    def get_outgoing_edges(self, node_or_id: NodeKey) -> list[Edge]:
+        """Return all edges where this node is the source (outputs from this node)."""
+        nid = to_node_id(node_or_id)
+        return [edge for edge in self.edges if edge.source == nid]
+
+    def get_dependencies(self, node_or_id: NodeKey) -> list[Node[MediaInfoT]]:
+        """Return upstream nodes that this node directly depends on."""
+        node_map = self.nodes_by_id
+        incoming = self.get_incoming_edges(node_or_id)
+        return [node_map[e.source] for e in incoming if e.source in node_map]
+
+    def get_dependents(self, node_or_id: NodeKey) -> list[Node[MediaInfoT]]:
+        """Return downstream nodes that directly depend on this node."""
+        node_map = self.nodes_by_id
+        outgoing = self.get_outgoing_edges(node_or_id)
+        return [node_map[e.target] for e in outgoing if e.target in node_map]
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert graph to a dictionary matching the JSON format."""
+        return {
+            "root_id": self.root_id,
+            "nodes": [node.to_dict() for node in self.nodes],
+            "edges": [edge.to_dict() for edge in self.edges],
+        }
+
+    def to_json(self, *, indent: int | None = None, **kwargs: Any) -> str:
+        """Serialize graph to a JSON string."""
+        return json.dumps(self.to_dict(), indent=indent, **kwargs)
+
+    def to_mermaid(self) -> str:
+        """Generate a Mermaid flowchart diagram of the graph."""
+        lines = ["flowchart TD"]
+        for node in self.nodes:
+            lbl = f"{node.name} ({node.id})"
+            lines.append(f'    {node.id}["{lbl}"]')
+        for edge in self.edges:
+            pattern_label = edge.pattern.name if edge.pattern != RequestPattern.GENERAL else ""
+            if pattern_label:
+                lines.append(f"    {edge.source} -->|{pattern_label}| {edge.target}")
+            else:
+                lines.append(f"    {edge.source} --> {edge.target}")
+        return "\n".join(lines)
+
+    def to_dot(self, *, direction: str = "TB", detailed: bool = True, fontname: str | None = None) -> str:
+        """
+        Generate a Graphviz DOT representation of the graph.
+
+        Args:
+            direction: Layout direction ('TB', 'LR', 'BT', 'RL'). Default is 'TB'.
+            detailed: Whether to render HTML-like table record labels with media info and profiling.
+            fontname: Font name for Graphviz nodes and edges (e.g. 'Helvetica'). If None, uses Graphviz defaults.
+        """
+        font_attr = f'fontname="{fontname}", ' if fontname else ""
+        lines = [
+            "digraph VSDependencyGraph {",
+            f'    rankdir="{direction}";',
+            f'    node [shape=box, style="filled,rounded", {font_attr}fillcolor="#f8f9fa", color="#343a40"];',
+            f'    edge [{font_attr}color="#495057"];',
+        ]
+
+        for node in self.nodes:
+            is_root = node.id == self.root_id
+            if detailed:
+                border_color = "#dc3545" if is_root else "#6c757d"
+                header_bg = "#ffc107" if is_root else "#e9ecef"
+                root_badge = " (Root)" if is_root else ""
+
+                match node.media_info:
+                    case VideoMediaInfo() as vi:
+                        info_line = f"{vi.width}x{vi.height} | {vi.format.name} | {float(vi.fps):.3f} fps"
+                    case AudioMediaInfo() as ai:
+                        info_line = f"{ai.sample_rate} Hz | {ai.format.num_channels} ch"
+
+                perf_line = f"Time: {node.processing_time_ms:.2f} ms | Mode: {node.filter_mode.name}"
+
+                label = (
+                    f'<<TABLE BORDER="1" CELLBORDER="0" CELLSPACING="2" COLOR="{border_color}">'
+                    f'<TR><TD BGCOLOR="{header_bg}"><B>{node.name} [{node.id}]{root_badge}</B></TD></TR>'
+                    f'<TR><TD ALIGN="LEFT"><FONT POINT-SIZE="10">{info_line}</FONT></TD></TR>'
+                    f'<TR><TD ALIGN="LEFT"><FONT POINT-SIZE="10">{perf_line}</FONT></TD></TR>'
+                    f"</TABLE>>"
+                )
+                lines.append(f'    "{node.id}" [shape=none, margin=0, label={label}];')
+            else:
+                root_style = ', fillcolor="#fff3cd", color="#856404"' if is_root else ""
+                lines.append(f'    "{node.id}" [label="{node.name} ({node.id})"{root_style}];')
+
+        for edge in self.edges:
+            pattern_label = edge.pattern.name if edge.pattern != RequestPattern.GENERAL else ""
+            if pattern_label:
+                lines.append(f'    "{edge.source}" -> "{edge.target}" [label="{pattern_label}"];')
+            else:
+                lines.append(f'    "{edge.source}" -> "{edge.target}";')
+
+        lines.append("}")
+        return "\n".join(lines)
+
+    def to_ascii(self, *, compact: bool = False) -> str:
+        """
+        Generate an ASCII / Unicode tree representation of the dependency graph starting at root.
+
+        Args:
+            compact: If True, only prints 'Name [id]'. If False, includes format, resolution, and time.
+        """
+        root_node = self.root
+        lines = list[str]()
+        visited = set[str]()
+
+        def format_node_label(node: Node[MediaInfoT]) -> str:
+            if compact:
+                return f"{node.name} [{node.id}]"
+
+            match node.media_info:
+                case VideoMediaInfo() as vi:
+                    spec = f"{vi.width}x{vi.height} {vi.format.name}"
+                case AudioMediaInfo() as ai:
+                    spec = f"{ai.sample_rate}Hz {ai.format.num_channels}ch"
+
+            return f"{node.name} [{node.id}] ({spec}, {node.processing_time_ms:.2f}ms)"
+
+        def walk(current_node: Node[MediaInfoT], prefix: str = "") -> None:
+            deps = self.get_dependencies(current_node)
+            count = len(deps)
+            for i, dep in enumerate(deps):
+                is_last = i == count - 1
+                branch = "└── " if is_last else "├── "
+                extension = "    " if is_last else "│   "
+
+                if dep.id in visited:
+                    lines.append(f"{prefix}{branch}{dep.name} [{dep.id}] (ref)")
+                else:
+                    visited.add(dep.id)
+                    lines.append(f"{prefix}{branch}{format_node_label(dep)}")
+                    walk(dep, prefix + extension)
+
+        lines.append(format_node_label(root_node))
+        visited.add(root_node.id)
+        walk(root_node)
+        return "\n".join(lines)
+
+    def to_cytoscape(self) -> dict[str, list[dict[str, Any]]]:
+        """
+        Export the graph to a Cytoscape.js compatible dictionary.
+
+        Returns:
+            A dictionary with 'nodes' and 'edges' lists formatted for Cytoscape.js.
+        """
+        return {
+            "nodes": [
+                {
+                    "data": {
+                        "id": node.id,
+                        "label": node.name,
+                        "name": node.name,
+                        "filter_mode": node.filter_mode.value,
+                        "filter_mode_name": node.filter_mode.name,
+                        "processing_time_ns": node.processing_time_ns,
+                        "processing_time_ms": node.processing_time_ms,
+                        "media_info": node.media_info.to_dict(),
+                        "call_stack": [frame.to_dict() for frame in node.call_stack],
+                        "is_root": node.id == self.root_id,
+                    }
+                }
+                for node in self.nodes
+            ],
+            "edges": [
+                {
+                    "data": {
+                        "id": f"e{i}_{edge.source}_{edge.target}",
+                        "source": edge.source,
+                        "target": edge.target,
+                        "pattern": edge.pattern.value,
+                        "pattern_name": edge.pattern.name,
+                        "label": edge.pattern.name if edge.pattern != RequestPattern.GENERAL else "",
+                        "index": edge.index,
+                    }
+                }
+                for i, edge in enumerate(self.edges)
+            ],
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        """Construct a Graph from a dictionary."""
+        return cls(
+            root_id=str(data["root_id"]),
+            nodes=[Node.from_dict(n) for n in data["nodes"]],
+            edges=[Edge.from_dict(e) for e in data["edges"]],
+        )
+
+    @classmethod
+    def from_json(cls, json_str: str | bytes | bytearray) -> Self:
+        """Construct a Graph from a JSON string or bytes."""
+        return cls.from_dict(json.loads(json_str))
+
+
+def to_node_id(node_or_id: NodeKey) -> str:
+    """Normalize a Python VideoNode/AudioNode, graph Node, NodeRef, or string ID to a node ID string."""
+    if isinstance(node_or_id, vs.RawNode):
+        return str(hash(node_or_id))
+    if isinstance(node_or_id, (Node, NodeRef)):
+        return node_or_id.id
+    return str(node_or_id)
+
+
+@cache
+def _get_param_names(function_namespace: str) -> Collection[str]:
+    return Signature.from_callable(attrgetter(function_namespace)(vs.core)).parameters.keys()

vsgraph/py.typed

@@ -0,0 +1 @@
+

vsgraph/vs.py

@@ -0,0 +1,77 @@
+from dataclasses import dataclass
+from enum import IntEnum
+from typing import Any, Self, override
+
+import vapoursynth as vs
+
+
+class RequestPattern(IntEnum):
+    """VapourSynth node request pattern."""
+
+    GENERAL = 0
+    NO_FRAME_REUSE = 1
+    STRICT_SPATIAL = 2
+    FRAME_REUSE_LAST_ONLY = 3
+
+
+@dataclass(slots=True)
+class AudioFormat:
+    sample_type: vs.SampleType
+    bits_per_sample: int
+    bytes_per_sample: int
+    num_channels: int
+    channel_layout: vs.ChannelLayout
+
+    @override
+    def __eq__(self, other: object) -> bool:
+        return int(self) == int(other) if isinstance(other, AudioFormat) else NotImplemented
+
+    @override
+    def __hash__(self) -> int:
+        return int(self)
+
+    def __int__(self) -> int:
+        return (
+            (int(self.sample_type) & 0xF) << 60
+            | (self.bits_per_sample & 0xFF) << 48
+            | (self.channel_layout & 0x0000_FFFF_FFFF_FFFF)
+        )
+
+    @property
+    def id(self) -> int:
+        return int(self)
+
+    @property
+    def name(self) -> str:
+        return (
+            f"Audio{self.bits_per_sample}{'F' if self.sample_type is vs.SampleType.FLOAT else ''} "
+            f"({self.num_channels} CH)"
+        )
+
+    @classmethod
+    def from_id(cls, id: int) -> Self:
+        sample_type = vs.SampleType((id >> 60) & 0xF)
+        bits_per_sample = (id >> 48) & 0xFF
+        channel_layout = vs.ChannelLayout(id & 0x0000_FFFF_FFFF_FFFF)
+
+        bytes_per_sample = 1 << ((bits_per_sample + 7) // 8 - 1).bit_length()
+        num_channels = channel_layout.bit_count()
+
+        return cls(
+            sample_type=sample_type,
+            bits_per_sample=bits_per_sample,
+            bytes_per_sample=bytes_per_sample,
+            num_channels=num_channels,
+            channel_layout=channel_layout,
+        )
+
+    def _as_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "sample_type": self.sample_type,
+            "bits_per_sample": self.bits_per_sample,
+            "bytes_per_sample": self.bytes_per_sample,
+            "num_channels": self.num_channels,
+            "channel_layout": self.channel_layout,
+        }