VRM Viewer for Nextcloud

Japanese

VRM Viewer is a Nextcloud Files app that opens .vrm avatar files in an interactive 3D preview. It supports VRM 0.x, VRM 1.0, embedded VRM thumbnails, and playback of .vrma animation files stored in the same Nextcloud instance.

Features

• Open .vrm files from the Nextcloud Files app
• Open .vrm files in the official Nextcloud Android app through Direct Editing
• Preview VRM 0.x and VRM 1.0 models with Three.js and @pixiv/three-vrm
• Normalize models to an A-pose with lowered upper arms
• Rotate, pan, zoom, and reset the camera
• Select and loop .vrma animation files from Nextcloud
• Navigate between VRM files in the Nextcloud Viewer
• Show embedded PNG/JPEG VRM thumbnails in the Files list
• Display clear errors for broken files, download failures, and WebGL issues
• Render in the browser without loading runtime assets from external CDNs

Requirements

• Nextcloud 34
• A logged-in user using the Files app
• A browser or Android System WebView with WebGL support
• Same-origin WebDAV access to the selected files
• Self-contained GLB-based VRM and VRMA files

Files with external GLB resources are rejected. VRM files without a valid embedded thumbnail fall back to the standard file icon in the Files list; this app does not render models server-side to generate new thumbnails.

Installation

Download files_vrmviewer-1.1.0.tar.gz from the GitHub Release, then extract it into Nextcloud's custom_apps directory.

tar -xzf files_vrmviewer-1.1.0.tar.gz -C /path/to/nextcloud/custom_apps
sudo -u www-data php /path/to/nextcloud/occ app:enable files_vrmviewer

The app automatically registers .vrm as model/vrm and repairs the MIME of existing .vrm and .VRM filecache entries during installation or update. It does not modify Nextcloud's shared MIME configuration files.

Usage

1. Open the Nextcloud Files app.
2. Click a .vrm file, or use the file action menu and choose Open in VRM Viewer.
3. Use the viewer controls to rotate, pan, zoom, or reset the camera.
4. Click Load VRMA to select a .vrma file from Nextcloud.
5. Click Stop animation to stop the current VRMA playback.

The VRMA file picker shows folders and .vrma files only, so animations can be loaded from child directories while unrelated files stay hidden.

Android

1. Install and enable VRM Viewer on the Nextcloud 34 server.
2. In the official Nextcloud Android app, refresh the account or Files list.
3. Open an online .vrm file. If Android has a native VRM handler for a locally downloaded copy, use the file's Edit action to choose VRM Viewer.
4. Use touch gestures and the shared viewer controls. Use Android's Back action to close the viewer.

The Android path requires a logged-in, online account and a WebGL-capable Android System WebView. No custom APK or Android client fork is required.

Automatic MIME Configuration

No manual mimetypemapping.json, MIME alias, or update-js change is required. The app adds the runtime mapping after Nextcloud's standard mappings are loaded, then runs a one-time filecache repair during installation or update. Other file types are left unchanged, and disabling or uninstalling the app does not rewrite existing filecache entries.

If an interrupted installation prevented the repair, an administrator can rerun Nextcloud's standard filecache repair after confirming the app is enabled:

sudo -u www-data php occ maintenance:mimetype:update-db --repair-filecache

Limitations

The following features are not part of v1.1.0:

• Opening VRM files from public share links
• E2EE files and offline viewing in Android
• Guaranteed iOS support
• Always taking priority over native Android apps registered for local VRM files
• Selecting local VRMA files directly from the browser
• Animation speed controls
• Expression or blendshape editing
• Server-side rendered thumbnails for VRM files without embedded thumbnails

Development

Use Node.js 24 and npm 11.

npm ci
npm run build
npm run typecheck
npm run lint
npm run stylelint
npm test

Local Nextcloud 34 environment:

npm run build
npm run docker:up
npm run docker:setup
npx playwright install chromium
npm run test:e2e
npm run docker:down

The E2E setup downloads fixed upstream VRM/VRMA sample files and verifies their SHA-256 hashes. Sample binaries are not stored in this repository.

Packaging

npm run package

This creates:

• build/artifacts/files_vrmviewer-1.1.0.tar.gz
• build/artifacts/files_vrmviewer-1.1.0.tar.gz.sha256

Release tags must match package.json and appinfo/info.xml. For example, version 1.1.0 should be released with tag v1.1.0.

Privacy and Network Behavior

VRM and VRMA files are loaded from the user's Nextcloud WebDAV endpoint. Runtime rendering is performed in the browser, and the app does not intentionally fetch rendering libraries or model assets from external CDNs.

License

MIT