gradio_mmd_viewer 0.0.1__tar.gz

gradio_mmd_viewer-0.0.1/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: gradio_mmd_viewer
+Version: 0.0.1
+Summary: Gradio custom component: 3D MMD model viewer powered by Babylon.js + babylon-mmd
+Keywords: gradio-custom-component,mmd,babylonjs,3d-viewer,miku-miku-dance
+Author: Winterreisender
+Author-email: Winterreisender <winterreisender@foxmail.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Dist: gradio>=6.0,<7.0
+Requires-Dist: uvicorn>=0.51.0
+Requires-Dist: websockets>=16.1
+Requires-Dist: build ; extra == 'dev'
+Requires-Python: >=3.13
+Project-URL: repository, https://github.com/Winterreisender/gradio-mmd-viewer
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# gradio_mmd_widget
+
+> [!WARNING] Unewviewed AI code
+> Unewviewed AI code still remains.
+
+> A Gradio custom component for rendering MMD motion data in the browser with Babylon.js and babylon-mmd.
+
+## Why this component?
+
+- Play VMD motion files with a built-in MMD character
+- Use it directly as a Gradio input or output component
+- Great for demos, interactive storytelling, and lightweight 3D previews
+
+## Installation
+
+```bash
+pip install gradio_mmd_viewer
+```
+
+## Quick start
+
+```python
+import gradio as gr
+from gradio_mmd_viewer import MMDViewer
+
+with gr.Blocks() as demo:
+    gr.Markdown("## MMD Viewer")
+    viewer = MMDViewer(
+        value="asset/demo.vmd",
+        label="MMD Viewer",
+        scale=2,
+        min_width=800,
+    )
+
+if __name__ == "__main__":
+    demo.launch()
+```
+
+## Features
+
+- Built-in model and default motion assets
+- Supports VMD URL input for switching animations
+- Includes a local demo for development and testing
+
+## Demo
+
+Run the bundled demo with:
+
+```bash
+python demo/app.py
+```
+
+## Development notes
+
+Technical implementation details, architecture notes, build steps, and troubleshooting guidance are maintained in [AGENTS.md](AGENTS.md).

gradio_mmd_viewer-0.0.1/README.md

@@ -0,0 +1,55 @@
+# gradio_mmd_widget
+
+> [!WARNING] Unewviewed AI code
+> Unewviewed AI code still remains.
+
+> A Gradio custom component for rendering MMD motion data in the browser with Babylon.js and babylon-mmd.
+
+## Why this component?
+
+- Play VMD motion files with a built-in MMD character
+- Use it directly as a Gradio input or output component
+- Great for demos, interactive storytelling, and lightweight 3D previews
+
+## Installation
+
+```bash
+pip install gradio_mmd_viewer
+```
+
+## Quick start
+
+```python
+import gradio as gr
+from gradio_mmd_viewer import MMDViewer
+
+with gr.Blocks() as demo:
+    gr.Markdown("## MMD Viewer")
+    viewer = MMDViewer(
+        value="asset/demo.vmd",
+        label="MMD Viewer",
+        scale=2,
+        min_width=800,
+    )
+
+if __name__ == "__main__":
+    demo.launch()
+```
+
+## Features
+
+- Built-in model and default motion assets
+- Supports VMD URL input for switching animations
+- Includes a local demo for development and testing
+
+## Demo
+
+Run the bundled demo with:
+
+```bash
+python demo/app.py
+```
+
+## Development notes
+
+Technical implementation details, architecture notes, build steps, and troubleshooting guidance are maintained in [AGENTS.md](AGENTS.md).

gradio_mmd_viewer-0.0.1/backend/gradio_mmd_viewer/__init__.py

@@ -0,0 +1,3 @@
+from .mmdviewer import MMDViewer, _MMDViewer, extract_pmx_zip
+
+__all__ = ['MMDViewer', '_MMDViewer', 'extract_pmx_zip']

gradio_mmd_viewer-0.0.1/backend/gradio_mmd_viewer/mmdviewer.py

@@ -0,0 +1,292 @@
+from __future__ import annotations
+
+import glob
+import hashlib
+import os
+import shutil
+import tempfile
+import zipfile
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING, Any, Literal
+
+from gradio.components.base import Component, FormComponent
+from gradio.events import Events
+from gradio.i18n import I18nData
+
+if TYPE_CHECKING:
+    from gradio.components import Timer
+
+
+class _MMDViewer(FormComponent):
+    """
+    Core MMD model viewer component using Babylon.js + babylon-mmd.
+    Handles only the Gradio component lifecycle — no path resolution or ZIP extraction.
+    Use `MMDViewer` (the shell) for end-user convenience features like PMX ZIP extraction.
+    """
+
+    EVENTS = [
+        Events.change,
+    ]
+
+    def __init__(
+        self,
+        value: str | Callable | None = None,
+        *,
+        model_url: str | None = None,
+        physics_enabled: bool = False,
+        grey_mode: bool = False,
+        camera_position: tuple[float, float, float] = (0.0, 22.0, -25.0),
+        camera_rotation: tuple[float, float] = (0.0, 0.0),
+        audio_url: str | None = None,
+        label: str | I18nData | None = None,
+        every: Timer | float | None = None,
+        inputs: Component | Sequence[Component] | set[Component] | None = None,
+        show_label: bool | None = None,
+        scale: int | None = None,
+        min_width: int = 160,
+        interactive: bool | None = None,
+        visible: bool | Literal["hidden"] = True,
+        elem_id: str | None = None,
+        elem_classes: list[str] | str | None = None,
+        render: bool = True,
+        key: int | str | tuple[int | str, ...] | None = None,
+        preserved_by_key: list[str] | str | None = "value",
+    ):
+        """
+        Parameters:
+            value: URL to a VMD motion file. The 3D viewer loads the built-in model
+                   and plays this motion. If a callable is provided, it's called on app load.
+            model_url: URL to a PMX/BPMX model file. If supplied, the viewer loads this
+                       model instead of the built-in one.
+            physics_enabled: if True, enables physics simulation for the model.
+            grey_mode: if True, renders the model in flat grey (no textures).
+            camera_position: initial camera position in the 3D scene.
+            camera_rotation: initial camera rotation as (alpha, beta) in radians.
+            audio_url: URL to an audio file for animation playback synchronization.
+            label: the label for this component.
+            every: Continuously calls `value` to recalculate it if `value` is a function.
+            inputs: Components used as inputs to calculate `value` if it's a function.
+            show_label: if True, will display label.
+            scale: relative size compared to adjacent Components.
+            min_width: minimum pixel width.
+            interactive: if True, component accepts user input; if False, display-only.
+            visible: If False, component will be hidden.
+            elem_id: HTML DOM id for this component.
+            elem_classes: HTML DOM classes for this component.
+            render: If False, component won't render in the Blocks context.
+            key: Components with the same key across re-renders are treated as same component.
+            preserved_by_key: Params preserved across re-renders when key matches.
+        """
+        self.model_url = model_url
+        self.physics_enabled = physics_enabled
+        self.grey_mode = grey_mode
+        self.camera_position = camera_position
+        self.camera_rotation = camera_rotation
+        self.audio_url = audio_url
+        super().__init__(
+            label=label,
+            every=every,
+            inputs=inputs,
+            show_label=show_label,
+            scale=scale,
+            min_width=min_width,
+            interactive=interactive,
+            visible=visible,
+            elem_id=elem_id,
+            elem_classes=elem_classes,
+            value=value,
+            render=render,
+            key=key,
+            preserved_by_key=preserved_by_key,
+        )
+
+    def preprocess(self, payload: str | None) -> str | None:
+        """
+        Parameters:
+            payload: the VMD URL from the frontend.
+        Returns:
+            The VMD URL as a string.
+        """
+        return None if payload is None else str(payload)
+
+    def postprocess(self, value: str | None) -> str | None:
+        """
+        Parameters:
+            value: A VMD URL string to send to the frontend.
+        Returns:
+            The VMD URL as-is.
+        """
+        return None if value is None else str(value)
+
+    def api_info(self) -> dict[str, Any]:
+        return {"type": "string"}
+
+    def example_payload(self) -> Any:
+        return "Hello!!"
+
+    def example_value(self) -> Any:
+        return "Hello!!"
+
+
+def _is_absolute_file_path(path: str) -> bool:
+    """Check if `path` is an absolute filesystem path that needs URL conversion."""
+    if len(path) >= 2 and path[1] == ":" and path[0].isalpha():
+        return True  # Windows drive letter: C:\...
+    if path.startswith("/") and not path.startswith("/gradio_api/"):
+        return True  # Unix absolute, but not already a Gradio URL
+    return False
+
+
+def _to_gradio_file_url(file_path: str) -> str:
+    """Convert an absolute filesystem path to /gradio_api/file=... URL."""
+    return f"/gradio_api/file={file_path.replace(chr(92), '/')}"
+
+
+def _get_mmd_cache_dir() -> str:
+    """Get or create the mmd_cache directory under Gradio's upload folder (always in allowed_paths)."""
+    cache_dir = os.path.join(tempfile.gettempdir(), "gradio", "mmd_cache")
+    os.makedirs(cache_dir, exist_ok=True)
+    return cache_dir
+
+
+def _ensure_servable(file_path: str) -> str:
+    """Copy a file to Gradio's upload cache and return its /gradio_api/file=... URL.
+
+    Idempotent — if the file has already been cached, reuses it.
+    Relative paths and existing Gradio URLs pass through unchanged.
+    """
+    if not _is_absolute_file_path(file_path):
+        return file_path
+
+    cache_dir = _get_mmd_cache_dir()
+    basename = os.path.basename(file_path)
+    name, ext = os.path.splitext(basename)
+    hash_suffix = hashlib.md5(file_path.encode()).hexdigest()[:8]
+    dest = os.path.join(cache_dir, f"{name}_{hash_suffix}{ext}")
+
+    if not os.path.exists(dest):
+        shutil.copy2(file_path, dest)
+
+    return _to_gradio_file_url(dest)
+
+
+def extract_pmx_zip(zip_path: str) -> str:
+    """
+    Extract a PMX ZIP file to .mmd_cache/, find the .pmx file,
+    and return the /gradio_api/file=... URL.
+
+    Use this both in __init__ and in callbacks that produce gr.update():
+
+        model_url = extract_pmx_zip(zip_path)
+        return gr.update(model_url=model_url, ...)
+
+    Raises FileNotFoundError if no .pmx file is found in the archive.
+    """
+    cache_dir = _get_mmd_cache_dir()
+    zip_hash = hashlib.md5(zip_path.encode()).hexdigest()[:8]
+    extract_dir = os.path.join(cache_dir, f"pmx_{zip_hash}")
+    os.makedirs(extract_dir, exist_ok=True)
+    with zipfile.ZipFile(zip_path, "r") as zf:
+        zf.extractall(extract_dir)
+
+    candidates = glob.glob(
+        os.path.join(glob.escape(extract_dir), "**", "*.[pP][mM][xX]"),
+        recursive=True,
+    )
+    if not candidates:
+        raise FileNotFoundError(f"No .pmx file found in archive: {zip_path}")
+
+    pmx_file = candidates[0]
+
+    return _to_gradio_file_url(pmx_file)
+
+
+class MMDViewer(_MMDViewer):
+    """
+    Thin shell around _MMDViewer — accepts filesystem paths only, never URLs.
+
+    - `value`: VMD motion file path. Absolute paths auto-converted to /gradio_api/file=...
+      via postprocess(). Relative paths pass through as-is (Gradio serves them as assets).
+    - `pmx_zip`: path to a .zip containing a PMX model → extracted → model_url.
+
+    For pmx_zip in gr.update(), compose explicitly:
+
+        from gradio_mmd_viewer import extract_pmx_zip
+        model_url = extract_pmx_zip(zip_path)
+        return gr.update(model_url=model_url, ...)
+    """
+
+    def __init__(
+        self,
+        value: str | Callable | None = None,
+        *,
+        pmx_zip: str | None = None,
+        model_url: str | None = None,
+        physics_enabled: bool = False,
+        grey_mode: bool = False,
+        camera_position: tuple[float, float, float] = (0.0, 38.0, -25.0),
+        camera_rotation: tuple[float, float] = (0.0, 0.0),
+        audio_url: str | None = None,
+        label: str | I18nData | None = None,
+        every: Timer | float | None = None,
+        inputs: Component | Sequence[Component] | set[Component] | None = None,
+        show_label: bool | None = None,
+        scale: int | None = None,
+        min_width: int = 160,
+        interactive: bool | None = None,
+        visible: bool | Literal["hidden"] = True,
+        elem_id: str | None = None,
+        elem_classes: list[str] | str | None = None,
+        render: bool = True,
+        key: int | str | tuple[int | str, ...] | None = None,
+        preserved_by_key: list[str] | str | None = "value",
+    ):
+        """
+        Parameters:
+            value: VMD motion file path — absolute (auto-converted to /gradio_api/file=...)
+                   or relative (passed through, served as Gradio asset).
+            pmx_zip: Path to a .zip containing a PMX model. Extracted → model_url.
+            model_url: Direct path/URL to a PMX/BPMX model file. Used as-is.
+            physics_enabled: if True, enables physics simulation.
+            grey_mode: if True, renders the model in flat grey (no textures).
+            camera_position: initial camera position as (x, y, z).
+            camera_rotation: initial camera rotation as (alpha, beta) in radians.
+            audio_url: URL/path to audio file for playback synchronization.
+        """
+        if pmx_zip:
+            model_url = extract_pmx_zip(pmx_zip)
+
+        if audio_url and _is_absolute_file_path(audio_url):
+            audio_url = _ensure_servable(audio_url)
+
+        super().__init__(
+            value=value,
+            model_url=model_url,
+            physics_enabled=physics_enabled,
+            grey_mode=grey_mode,
+            camera_position=camera_position,
+            camera_rotation=camera_rotation,
+            audio_url=audio_url,
+            label=label,
+            every=every,
+            inputs=inputs,
+            show_label=show_label,
+            scale=scale,
+            min_width=min_width,
+            interactive=interactive,
+            visible=visible,
+            elem_id=elem_id,
+            elem_classes=elem_classes,
+            render=render,
+            key=key,
+            preserved_by_key=preserved_by_key,
+        )
+
+    # ── postprocess: Gradio's standard hook for path → URL ─────────
+    # Called on every value flowing to the frontend, including from gr.update().
+    # Copies absolute filesystem paths to .mmd_cache/ and returns /gradio_api/file=...
+    def postprocess(self, value: str | None) -> str | None:
+        value = super().postprocess(value)
+        if value and _is_absolute_file_path(value):
+            value = _ensure_servable(value)
+        return value

gradio_mmd_viewer-0.0.1/backend/gradio_mmd_viewer/mmdviewer.pyi

@@ -0,0 +1,357 @@
+from __future__ import annotations
+
+import glob
+import hashlib
+import os
+import shutil
+import tempfile
+import zipfile
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING, Any, Literal
+
+from gradio.components.base import Component, FormComponent
+from gradio.events import Events
+from gradio.i18n import I18nData
+
+if TYPE_CHECKING:
+    from gradio.components import Timer
+
+from gradio.events import Dependency
+
+class _MMDViewer(FormComponent):
+    """
+    Core MMD model viewer component using Babylon.js + babylon-mmd.
+    Handles only the Gradio component lifecycle — no path resolution or ZIP extraction.
+    Use `MMDViewer` (the shell) for end-user convenience features like PMX ZIP extraction.
+    """
+
+    EVENTS = [
+        Events.change,
+    ]
+
+    def __init__(
+        self,
+        value: str | Callable | None = None,
+        *,
+        model_url: str | None = None,
+        physics_enabled: bool = False,
+        grey_mode: bool = False,
+        camera_position: tuple[float, float, float] = (0.0, 22.0, -25.0),
+        camera_rotation: tuple[float, float] = (0.0, 0.0),
+        audio_url: str | None = None,
+        label: str | I18nData | None = None,
+        every: Timer | float | None = None,
+        inputs: Component | Sequence[Component] | set[Component] | None = None,
+        show_label: bool | None = None,
+        scale: int | None = None,
+        min_width: int = 160,
+        interactive: bool | None = None,
+        visible: bool | Literal["hidden"] = True,
+        elem_id: str | None = None,
+        elem_classes: list[str] | str | None = None,
+        render: bool = True,
+        key: int | str | tuple[int | str, ...] | None = None,
+        preserved_by_key: list[str] | str | None = "value",
+    ):
+        """
+        Parameters:
+            value: URL to a VMD motion file. The 3D viewer loads the built-in model
+                   and plays this motion. If a callable is provided, it's called on app load.
+            model_url: URL to a PMX/BPMX model file. If supplied, the viewer loads this
+                       model instead of the built-in one.
+            physics_enabled: if True, enables physics simulation for the model.
+            grey_mode: if True, renders the model in flat grey (no textures).
+            camera_position: initial camera position in the 3D scene.
+            camera_rotation: initial camera rotation as (alpha, beta) in radians.
+            audio_url: URL to an audio file for animation playback synchronization.
+            label: the label for this component.
+            every: Continuously calls `value` to recalculate it if `value` is a function.
+            inputs: Components used as inputs to calculate `value` if it's a function.
+            show_label: if True, will display label.
+            scale: relative size compared to adjacent Components.
+            min_width: minimum pixel width.
+            interactive: if True, component accepts user input; if False, display-only.
+            visible: If False, component will be hidden.
+            elem_id: HTML DOM id for this component.
+            elem_classes: HTML DOM classes for this component.
+            render: If False, component won't render in the Blocks context.
+            key: Components with the same key across re-renders are treated as same component.
+            preserved_by_key: Params preserved across re-renders when key matches.
+        """
+        self.model_url = model_url
+        self.physics_enabled = physics_enabled
+        self.grey_mode = grey_mode
+        self.camera_position = camera_position
+        self.camera_rotation = camera_rotation
+        self.audio_url = audio_url
+        super().__init__(
+            label=label,
+            every=every,
+            inputs=inputs,
+            show_label=show_label,
+            scale=scale,
+            min_width=min_width,
+            interactive=interactive,
+            visible=visible,
+            elem_id=elem_id,
+            elem_classes=elem_classes,
+            value=value,
+            render=render,
+            key=key,
+            preserved_by_key=preserved_by_key,
+        )
+
+    def preprocess(self, payload: str | None) -> str | None:
+        """
+        Parameters:
+            payload: the VMD URL from the frontend.
+        Returns:
+            The VMD URL as a string.
+        """
+        return None if payload is None else str(payload)
+
+    def postprocess(self, value: str | None) -> str | None:
+        """
+        Parameters:
+            value: A VMD URL string to send to the frontend.
+        Returns:
+            The VMD URL as-is.
+        """
+        return None if value is None else str(value)
+
+    def api_info(self) -> dict[str, Any]:
+        return {"type": "string"}
+
+    def example_payload(self) -> Any:
+        return "Hello!!"
+
+    def example_value(self) -> Any:
+        return "Hello!!"
+    from typing import Callable, Literal, Sequence, Any, TYPE_CHECKING
+    from gradio.blocks import Block
+    if TYPE_CHECKING:
+        from gradio.components import Timer
+        from gradio.components.base import Component
+
+    
+    def change(self,
+        fn: Callable[..., Any] | None = None,
+        inputs: Block | Sequence[Block] | set[Block] | None = None,
+        outputs: Block | Sequence[Block] | None = None,
+        api_name: str | None = None,
+        scroll_to_output: bool = False,
+        show_progress: Literal["full", "minimal", "hidden"] = "full",
+        show_progress_on: Component | Sequence[Component] | None = None,
+        queue: bool | None = None,
+        batch: bool = False,
+        max_batch_size: int = 4,
+        preprocess: bool = True,
+        postprocess: bool = True,
+        cancels: dict[str, Any] | list[dict[str, Any]] | None = None,
+        every: Timer | float | None = None,
+        trigger_mode: Literal["once", "multiple", "always_last"] | None = None,
+        js: str | Literal[True] | None = None,
+        concurrency_limit: int | None | Literal["default"] = "default",
+        concurrency_id: str | None = None,
+        api_visibility: Literal["public", "private", "undocumented"] = "public",
+        key: int | str | tuple[int | str, ...] | None = None,
+        api_description: str | None | Literal[False] = None,
+        validator: Callable[..., Any] | None = None,
+    
+        ) -> Dependency:
+        """
+        Parameters:
+            fn: the function to call when this event is triggered. Often a machine learning model's prediction function. Each parameter of the function corresponds to one input component, and the function should return a single value or a tuple of values, with each element in the tuple corresponding to one output component.
+            inputs: list of gradio.components to use as inputs. If the function takes no inputs, this should be an empty list.
+            outputs: list of gradio.components to use as outputs. If the function returns no outputs, this should be an empty list.
+            api_name: defines how the endpoint appears in the API docs. Can be a string or None. If set to a string, the endpoint will be exposed in the API docs with the given name. If None (default), the name of the function will be used as the API endpoint.
+            scroll_to_output: if True, will scroll to output component on completion
+            show_progress: how to show the progress animation while event is running: "full" shows a spinner which covers the output component area as well as a runtime display in the upper right corner, "minimal" only shows the runtime display, "hidden" shows no progress animation at all
+            show_progress_on: Component or list of components to show the progress animation on. If None, will show the progress animation on all of the output components.
+            queue: if True, will place the request on the queue, if the queue has been enabled. If False, will not put this event on the queue, even if the queue has been enabled. If None, will use the queue setting of the gradio app.
+            batch: if True, then the function should process a batch of inputs, meaning that it should accept a list of input values for each parameter. The lists should be of equal length (and be up to length `max_batch_size`). The function is then *required* to return a tuple of lists (even if there is only 1 output component), with each list in the tuple corresponding to one output component.
+            max_batch_size: maximum number of inputs to batch together if this is called from the queue (only relevant if batch=True)
+            preprocess: if False, will not run preprocessing of component data before running 'fn' (e.g. leaving it as a base64 string if this method is called with the `Image` component).
+            postprocess: if False, will not run postprocessing of component data before returning 'fn' output to the browser.
+            cancels: a list of other events to cancel when this listener is triggered. For example, setting cancels=[click_event] will cancel the click_event, where click_event is the return value of another components .click method. Functions that have not yet run (or generators that are iterating) will be cancelled, but functions that are currently running will be allowed to finish.
+            every: continuously calls `value` to recalculate it if `value` is a function (has no effect otherwise). Can provide a Timer whose tick resets `value`, or a float that provides the regular interval for the reset Timer.
+            trigger_mode: if "once" (default for all events except `.change()`) would not allow any submissions while an event is pending. If set to "multiple", unlimited submissions are allowed while pending, and "always_last" (default for `.change()` and `.key_up()` events) would allow a second submission after the pending event is complete.
+            js: optional frontend js method to run before running 'fn'. Input arguments for js method are values of 'inputs' and 'outputs', return should be a list of values for output components.
+            concurrency_limit: if set, this is the maximum number of this event that can be running simultaneously. Can be set to None to mean no concurrency_limit (any number of this event can be running simultaneously). Set to "default" to use the default concurrency limit (defined by the `default_concurrency_limit` parameter in `Blocks.queue()`, which itself is 1 by default).
+            concurrency_id: if set, this is the id of the concurrency group. Events with the same concurrency_id will be limited by the lowest set concurrency_limit.
+            api_visibility: controls the visibility and accessibility of this endpoint. Can be "public" (shown in API docs and callable by clients), "private" (hidden from API docs and not callable by the Gradio client libraries), or "undocumented" (hidden from API docs but callable by clients and via gr.load). If fn is None, api_visibility will automatically be set to "private".
+            key: A unique key for this event listener to be used in @gr.render(). If set, this value identifies an event as identical across re-renders when the key is identical.
+            api_description: Description of the API endpoint. Can be a string, None, or False. If set to a string, the endpoint will be exposed in the API docs with the given description. If None, the function's docstring will be used as the API endpoint description. If False, then no description will be displayed in the API docs.
+            validator: Optional validation function to run before the main function. If provided, this function will be executed first with queue=False, and only if it completes successfully will the main function be called. The validator receives the same inputs as the main function.
+        
+        """
+        ...
+
+
+def _is_absolute_file_path(path: str) -> bool:
+    """Check if `path` is an absolute filesystem path that needs URL conversion."""
+    if len(path) >= 2 and path[1] == ":" and path[0].isalpha():
+        return True  # Windows drive letter: C:\...
+    if path.startswith("/") and not path.startswith("/gradio_api/"):
+        return True  # Unix absolute, but not already a Gradio URL
+    return False
+
+
+def _to_gradio_file_url(file_path: str) -> str:
+    """Convert an absolute filesystem path to /gradio_api/file=... URL."""
+    return f"/gradio_api/file={file_path.replace(chr(92), '/')}"
+
+
+def _get_mmd_cache_dir() -> str:
+    """Get or create the mmd_cache directory under Gradio's upload folder (always in allowed_paths)."""
+    cache_dir = os.path.join(tempfile.gettempdir(), "gradio", "mmd_cache")
+    os.makedirs(cache_dir, exist_ok=True)
+    return cache_dir
+
+
+def _ensure_servable(file_path: str) -> str:
+    """Copy a file to Gradio's upload cache and return its /gradio_api/file=... URL.
+
+    Idempotent — if the file has already been cached, reuses it.
+    Relative paths and existing Gradio URLs pass through unchanged.
+    """
+    if not _is_absolute_file_path(file_path):
+        return file_path
+
+    cache_dir = _get_mmd_cache_dir()
+    basename = os.path.basename(file_path)
+    name, ext = os.path.splitext(basename)
+    hash_suffix = hashlib.md5(file_path.encode()).hexdigest()[:8]
+    dest = os.path.join(cache_dir, f"{name}_{hash_suffix}{ext}")
+
+    if not os.path.exists(dest):
+        shutil.copy2(file_path, dest)
+
+    return _to_gradio_file_url(dest)
+
+
+def extract_pmx_zip(zip_path: str) -> str:
+    """
+    Extract a PMX ZIP file to .mmd_cache/, find the .pmx file,
+    and return the /gradio_api/file=... URL.
+
+    Use this both in __init__ and in callbacks that produce gr.update():
+
+        model_url = extract_pmx_zip(zip_path)
+        return gr.update(model_url=model_url, ...)
+
+    Raises FileNotFoundError if no .pmx file is found in the archive.
+    """
+    cache_dir = _get_mmd_cache_dir()
+    zip_hash = hashlib.md5(zip_path.encode()).hexdigest()[:8]
+    extract_dir = os.path.join(cache_dir, f"pmx_{zip_hash}")
+    os.makedirs(extract_dir, exist_ok=True)
+    with zipfile.ZipFile(zip_path, "r") as zf:
+        zf.extractall(extract_dir)
+
+    candidates = glob.glob(
+        os.path.join(glob.escape(extract_dir), "**", "*.[pP][mM][xX]"),
+        recursive=True,
+    )
+    if not candidates:
+        raise FileNotFoundError(f"No .pmx file found in archive: {zip_path}")
+
+    pmx_file = candidates[0]
+
+    return _to_gradio_file_url(pmx_file)
+
+
+class MMDViewer(_MMDViewer):
+    """
+    Thin shell around _MMDViewer — accepts filesystem paths only, never URLs.
+
+    - `value`: VMD motion file path. Absolute paths auto-converted to /gradio_api/file=...
+      via postprocess(). Relative paths pass through as-is (Gradio serves them as assets).
+    - `pmx_zip`: path to a .zip containing a PMX model → extracted → model_url.
+
+    For pmx_zip in gr.update(), compose explicitly:
+
+        from gradio_mmd_viewer import extract_pmx_zip
+        model_url = extract_pmx_zip(zip_path)
+        return gr.update(model_url=model_url, ...)
+    """
+
+    def __init__(
+        self,
+        value: str | Callable | None = None,
+        *,
+        pmx_zip: str | None = None,
+        model_url: str | None = None,
+        physics_enabled: bool = False,
+        grey_mode: bool = False,
+        camera_position: tuple[float, float, float] = (0.0, 38.0, -25.0),
+        camera_rotation: tuple[float, float] = (0.0, 0.0),
+        audio_url: str | None = None,
+        label: str | I18nData | None = None,
+        every: Timer | float | None = None,
+        inputs: Component | Sequence[Component] | set[Component] | None = None,
+        show_label: bool | None = None,
+        scale: int | None = None,
+        min_width: int = 160,
+        interactive: bool | None = None,
+        visible: bool | Literal["hidden"] = True,
+        elem_id: str | None = None,
+        elem_classes: list[str] | str | None = None,
+        render: bool = True,
+        key: int | str | tuple[int | str, ...] | None = None,
+        preserved_by_key: list[str] | str | None = "value",
+    ):
+        """
+        Parameters:
+            value: VMD motion file path — absolute (auto-converted to /gradio_api/file=...)
+                   or relative (passed through, served as Gradio asset).
+            pmx_zip: Path to a .zip containing a PMX model. Extracted → model_url.
+            model_url: Direct path/URL to a PMX/BPMX model file. Used as-is.
+            physics_enabled: if True, enables physics simulation.
+            grey_mode: if True, renders the model in flat grey (no textures).
+            camera_position: initial camera position as (x, y, z).
+            camera_rotation: initial camera rotation as (alpha, beta) in radians.
+            audio_url: URL/path to audio file for playback synchronization.
+        """
+        if pmx_zip:
+            model_url = extract_pmx_zip(pmx_zip)
+
+        if audio_url and _is_absolute_file_path(audio_url):
+            audio_url = _ensure_servable(audio_url)
+
+        super().__init__(
+            value=value,
+            model_url=model_url,
+            physics_enabled=physics_enabled,
+            grey_mode=grey_mode,
+            camera_position=camera_position,
+            camera_rotation=camera_rotation,
+            audio_url=audio_url,
+            label=label,
+            every=every,
+            inputs=inputs,
+            show_label=show_label,
+            scale=scale,
+            min_width=min_width,
+            interactive=interactive,
+            visible=visible,
+            elem_id=elem_id,
+            elem_classes=elem_classes,
+            render=render,
+            key=key,
+            preserved_by_key=preserved_by_key,
+        )
+
+    # ── postprocess: Gradio's standard hook for path → URL ─────────
+    # Called on every value flowing to the frontend, including from gr.update().
+    # Copies absolute filesystem paths to .mmd_cache/ and returns /gradio_api/file=...
+    def postprocess(self, value: str | None) -> str | None:
+        value = super().postprocess(value)
+        if value and _is_absolute_file_path(value):
+            value = _ensure_servable(value)
+        return value
+    from typing import Callable, Literal, Sequence, Any, TYPE_CHECKING
+    from gradio.blocks import Block
+    if TYPE_CHECKING:
+        from gradio.components import Timer
+        from gradio.components.base import Component

gradio_mmd_viewer-0.0.1/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["uv_build>=0.11.29,<0.12"]
+build-backend = "uv_build"
+
+[project]
+name = "gradio_mmd_viewer"
+version = "0.0.1"
+description = "Gradio custom component: 3D MMD model viewer powered by Babylon.js + babylon-mmd"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.13"
+authors = [{ name = "Winterreisender", email = "winterreisender@foxmail.com" }]
+keywords = [
+  "gradio-custom-component",
+  "mmd",
+  "babylonjs",
+  "3d-viewer",
+  "miku-miku-dance",
+]
+# Add dependencies here
+dependencies = [
+    "gradio>=6.0,<7.0",
+    "uvicorn>=0.51.0",
+    "websockets>=16.1",
+]
+classifiers = [
+  'Development Status :: 3 - Alpha',
+  'Operating System :: OS Independent',
+  'Programming Language :: Python :: 3',
+  'Programming Language :: Python :: 3 :: Only',
+  'Programming Language :: Python :: 3.13',
+  'Topic :: Scientific/Engineering',
+  'Topic :: Scientific/Engineering :: Visualization',
+]
+
+# The repository and space URLs are optional, but recommended.
+# Adding a repository URL will create a badge in the auto-generated README that links to the repository.
+# Adding a space URL will create a badge in the auto-generated README that links to the space.
+# This will make it easy for people to find your deployed demo or source code when they
+# encounter your project in the wild.
+
+[project.urls]
+repository = "https://github.com/Winterreisender/gradio-mmd-viewer"
+
+[project.optional-dependencies]
+dev = ["build"]
+
+[tool.uv.build-backend]
+module-name = "gradio_mmd_viewer"
+module-root = "backend"
+
+[dependency-groups]
+dev = [
+    "build>=1.5.0",
+]