Virtual Tour Creator — Desktop App
Features • Prerequisites • Getting Started • Building • Structure • Contributing
Obsipano is a cross-platform desktop application for creating, editing, and presenting immersive 360° virtual tours. Built with Tauri 2, React 19, and Photo Sphere Viewer, it offers a smooth, native experience for crafting interactive walkthroughs from panoramic images.
- 360° Panorama Viewer — Full-screen panorama exploration with smooth navigation.
- Hotspots & Links — Add clickable info markers and navigation links between scenes.
- Interactive Markers — Rich hotspot actions: show images, videos, text, or play audio.
- Virtual Tour Mode — Seamlessly connect scenes into a guided walkthrough.
- Asset Manager — Import and manage images, audio, video, and documents.
- Present Mode — Separate full-screen presentation window with a clean interface.
- Project File (.obsipano) — Save and load projects in a custom file format with compression.
- Multi-Resolution Processing — Automatic panorama resizing (low, medium, high) to WebP.
- Media Conversion — Automatic audio/video conversion for optimized playback.
- File Locking — Safe concurrent access to project files across windows.
- Drag & Drop Hotspots — Reposition markers by dragging in the viewer.
- Theme Support — Light, dark, and black themes.
- Command Architecture — Every editor action runs through a typed command registry consumed by the UI and by extensions.
- Extension SDK — Namespaced
obsipano-sdkAPI (commands,window,workspace,tour,present,media,extensions) with contribution points (menus, panels, hotspot/document renderers, validation rules). - Official Plugin Files (.veix) — Versioned, validated plugin packages; only official publisher files pass the installer gate.
- Project Diagnostics — Detect missing panoramas, broken links, duplicate scene IDs, and unreachable scenes.
Before you begin, ensure you have the following installed:
- Bun 1.x (mandatory package manager — never npm/yarn/pnpm)
- Rust 1.85+ (via rustup)
- System dependencies for Tauri 2
# Clone the repository
git clone https://github.com/fazelstudio/obsipano.git
cd obsipano
# Install JavaScript dependencies (downloads a local FFmpeg copy for development only)
bun install
# Run the app in development mode
bun run tauri devThe app will launch with hot-reload enabled. The Tauri window will open automatically once the Vite dev server is ready on port 1420.
The installer ships without FFmpeg to keep downloads small. Users can install it on demand:
- Open Settings > Media Optimization.
- Select Download FFmpeg (one-time download, about 25–80 MB depending on the system) or Use local file… to reuse an FFmpeg binary already on your device (any file name works; it is validated and copied automatically).
- The exact download package for your system is shown upfront (Windows x64/ARM64, macOS Intel, Linux x64/ARM64). Platforms without a published binary yet show a clear notice instead — macOS ARM users should use a local file for now.
- Progress is shown in Settings. If the connection drops, select Download again to resume.
- It can be removed at any time from the same screen. Without it, original audio/video files are used as-is.
For development, bun install downloads a local FFmpeg copy via the postinstall hook (not bundled into the installer). Binaries are fetched from the ffmpeg-sidecar-v1 GitHub Release, with canonical sources as fallback.
| Command | Description |
|---|---|
bun run dev |
Start Vite dev server only |
bun run build |
Build the frontend for production |
bun run tauri dev |
Run the full Tauri desktop app in dev mode |
bun run tauri build |
Build the desktop app for distribution |
bun run check |
Run TypeScript type checking (app + SDK) |
bun run lint |
Run ESLint on all source files |
bun run sidecar:download |
Download a local FFmpeg copy for development |
bun run sdk:test |
Run the headless SDK functional tests |
To create a distributable package for your platform:
bun run tauri buildThe output binaries will be placed in src-tauri/target/release/bundle/.
- Identifier:
com.fazli.obsipano - File Association:
.obsipano— virtual tour project files - Supported Targets: Windows (NSIS installer), macOS (.dmg), Linux (.deb, .AppImage)
| Layer | Technology |
|---|---|
| Desktop Shell | Tauri 2 |
| Frontend | React 19, TypeScript |
| Styling | Tailwind CSS 4 |
| State Management | Zustand |
| UI Components | Radix UI, Framer Motion |
| Panorama Rendering | Photo Sphere Viewer |
| Image Processing | image crate (Rust) |
| Packaging | Bun |
obsipano/
├── src/ # Frontend source (React + TypeScript)
│ ├── commands/ # Typed command API, extension boundary, SDK host adapter
│ ├── components/ # Feature screens and shared UI primitives
│ │ ├── Editor/ # Main editor (panorama, hotspots, assets)
│ │ ├── Home/ # Home screen and project list
│ │ ├── Present/ # Presentation mode (separate window)
│ │ ├── Settings/ # Settings modal
│ │ └── ui/ # Shared UI primitives
│ ├── contexts/ # React providers
│ ├── lib/ # Persistence, validation, media, and platform helpers
│ ├── store/ # Zustand state and mutation orchestration
│ ├── types/ # Persisted project and public contracts
│ └── constants.ts # Shared defaults and limits
├── packages/obsipano-sdk/ # Extension SDK (published to npmjs + GitHub Packages)
├── scripts/ # Dev scripts (sidecar download, SDK publish/test)
├── src-tauri/ # Tauri backend (Rust)
│ ├── src/
│ │ ├── lib.rs # App entry point and command registration
│ │ ├── image_processor.rs # Panorama processing (resize, WebP)
│ │ ├── media_processor.rs # Audio/video conversion (FFmpeg)
│ │ ├── ffmpeg_manager.rs # FFmpeg sidecars (download, local import, assets)
│ │ └── file_lock.rs # File locking for project files
│ ├── Cargo.toml
│ └── tauri.conf.json # Tauri configuration
├── package.json # Bun monorepo root (workspaces)
├── tsconfig.json
└── vite.config.ts
The design rationale and dependency boundaries are documented in docs/ARCHITECTURE.md. Extension authors should start with docs/EXTENSIONS.md.
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
This project is licensed under the MIT License — see LICENSE for details.
- Photo Sphere Viewer for the excellent panorama rendering library.
- Tauri for the lightweight, secure desktop runtime.
- All contributors and users who support this project.
Created by Zulfazli (fazelstudio)