Meta Quest Sync

Meta Quest Sync connects an Obsidian desktop vault to the Obsidian AR WebXR experience on Meta Quest. From Obsidian, it exports the vault graph, connects to a companion bridge started by the user and displays a QR code for pairing.

The WebXR viewer, Rust bridge and cross-platform orchestration live in the Obsidian-Ar project. This repository contains only the Obsidian community plugin and its release artifacts.

Requirements

• Obsidian desktop;
• Git, Node.js 22.13+ and Rust/Cargo;
• cloudflared available on PATH;
• FFmpeg (ffmpeg and ffprobe) for AV1/HEVC video compatibility;
• a local clone of NElscost/Obsidian-Ar;
• Meta Quest with an up-to-date WebXR browser and hand tracking.

The recommended direct-graph mode does not require Blender, Obsidian CLI or the 3D Graph New plugin.

The companion bridge runs independently from Obsidian. This keeps process execution outside the community plugin and lets the user inspect, start and stop the bridge explicitly.

Usage

1. Install and enable Meta Quest Sync in Obsidian.

2. Clone the companion project:

   git clone https://github.com/NElscost/Obsidian-Ar.git
   

3. Open Settings → Meta Quest Sync and select the absolute path of that clone.

4. Select Connect once to write the bridge configuration. The plugin will report that the bridge is not running yet.

5. Start the companion bridge from the cloned project:

   node Scripts/note-bridge.mjs start --port 8765
   

6. Keep the default HTTPS viewer, select Connect again, then open the generated QR code on the Quest.

Species map blocks support cached GBIF occurrence markers, click-safe map panning, regional photos and sounds, and an IUCN 3.1 status scale. In WebXR, regional recordings can also feed the optional Spectral Trail.

The plugin creates the graph snapshot and connects to the running bridge. The companion project manages compilation and the optional tunnel. Session credentials are placed in the URL fragment and are not persisted in plugin settings.

Self-hosting

The default setup uses the hosted WebXR viewer and a local Rust backend exposed through Cloudflare Tunnel. Both endpoints are configurable:

• you can host the WebXR viewer on any HTTPS server and set its address in Settings → Meta Quest Sync → HTTPS viewer;
• you can self-host the backend and point the plugin at your own URL;
• for a persistent backend address, configure a Cloudflare Named Tunnel in the companion project and select it in the plugin settings.

The viewer and backend may use different domains. The backend still requires the session token and only accepts compatible HTTPS origins.

Commands

• Connect to AR session;
• Show session QR code;
• Refresh graph snapshot;
• Disconnect from AR session.

The settings page follows the Obsidian/system language when Portuguese is detected and uses English for other languages. Select Interface language → English to force English.

Biological visualization blocks

Use fenced Markdown blocks in a note.

Species map

taxon: Pitangus sulphuratus
source: gbif
mode: density
center: [-15, -55]
zoom: 2
style: classic.point

Select a map region to see its inferred name, occurrence count, photos and recordings. Regional recordings can generate an interactive 3D sound trail, inspired by Lucio Arese's Seeing Birdsong project. Dragging pans the desktop map.

IUCN status

status: LC
system: IUCN 3.1
label: Least Concern

status accepts EX, EW, CR, EN, VU, NT or LC.

FASTA

Paste one or more sequences using standard FASTA headers:

>Pitangus_sulphuratus
ATGAACGAAAATCTATACAAAAGCCTAACATTC
>Philohydor_lictor
ATGAACGAAAATCTATACAAAAGCCTAACATTC

The desktop plugin renders a color-coded, scrollable alignment. Use Alignment, UPGMA tree, and Distances to switch between the sequence grid, a lightweight phylogenetic tree inferred with p-distance, and a distance matrix. Tree inference is on demand and bounded to 64 taxa and 5,000 informative sites; this is intended for exploration and does not replace a reproducible MEGA analysis with an explicit substitution model and bootstrap settings. WebXR first creates a compact raster preview; selecting it opens the paged spatial comparison view. Up to 128 sequences and 500,000 input characters are parsed, with desktop display limited to 10,000 residues per sequence to protect responsiveness.

Privacy and network access

Meta Quest Sync reads note paths and links through the Obsidian API to generate the graph. It does not launch executables or install software. The separately started companion bridge exposes requested note content and media to the paired Quest through an HTTPS Cloudflare Tunnel.

Anyone holding both the temporary bridge URL and session token can access the allowed endpoints while the session is active. Keep them private and stop the companion bridge when finished. The plugin has no telemetry, advertising, payment flow or account system.

Security safeguards

The plugin only connects to a companion bridge that the user started separately. It verifies the local bridge on port 8765, reads its short-lived session state, and never invokes a command shell, starts executables, installs programs, or terminates operating-system processes. Bridge credentials are not stored in plugin settings.

See the main project documentation for tunnel configuration, platform notes, WebXR gestures, troubleshooting and the optional glTF pipeline.

Development

npm ci
npm test
npm run build

The GitHub release tag must exactly match manifest.json and include main.js, manifest.json and styles.css.

License

MIT