Configuration Guide¶

JSON Configuration System¶

The XRGallery now uses a clean JSON-based configuration system to define your experience stages.

Configuration File Location¶

/public/config.json

This file is automatically loaded when the application starts.

Configuration Structure¶

{
  "experience": {
    "title": "Your Experience Title",
    "description": "Brief description"
  },
  "stages": [
    {
      "id": "stage-1",
      "type": "video" | "image" | "model",
      "url": "https://storage.googleapis.com/your-bucket/path/to/media.mp4",
      "thumbnail": "https://storage.googleapis.com/.../thumbnail.jpg",
      "autoplay": true,
      "loop": true
    }
  ]
}

Stage Types¶

1. Video Stage¶

{
  "id": "intro-video",
  "type": "video",
  "url": "https://storage.googleapis.com/bucket/videos/intro-360.mp4",
  "thumbnail": "https://storage.googleapis.com/bucket/videos/intro-thumb.jpg",
  "autoplay": true,
  "loop": true
}

Properties: - id (required): Unique identifier for the stage - type (required): Must be "video" - url (required): Full URL to 360 video file (MP4, equirectangular) - thumbnail (optional): Thumbnail image URL - autoplay (optional): Auto-play video when stage loads (default: false) - loop (optional): Loop video playback (default: true)

2. Image Stage¶

{
  "id": "panorama-1",
  "type": "image",
  "url": "https://storage.googleapis.com/bucket/images/panorama.jpg",
  "thumbnail": "https://storage.googleapis.com/bucket/images/panorama-thumb.jpg"
}

Properties: - id (required): Unique identifier for the stage - type (required): Must be "image" - url (required): Full URL to 360 panoramic image (JPG/PNG, equirectangular 2:1) - thumbnail (optional): Thumbnail image URL

3. Model Stage¶

{
  "id": "model-showcase",
  "type": "model",
  "url": "https://storage.googleapis.com/bucket/models/sculpture.glb",
  "thumbnail": "https://storage.googleapis.com/bucket/models/sculpture-thumb.jpg",
  "scale": 1.5,
  "rotation": { "x": 0, "y": 1.57, "z": 0 }
}

Properties: - id (required): Unique identifier for the stage - type (required): Must be "model" - url (required): Full URL to 3D model file (GLB/GLTF) - thumbnail (optional): Thumbnail image URL - scale (optional): Model scale multiplier (default: 1.0) - rotation (optional): Initial rotation in radians { x, y, z } (default: all 0)

Example Complete Configuration¶

{
  "experience": {
    "title": "Art Gallery VR Tour",
    "description": "An immersive journey through digital art"
  },
  "stages": [
    {
      "id": "welcome-video",
      "type": "video",
      "url": "https://storage.googleapis.com/my-bucket/videos/welcome-360.mp4",
      "autoplay": true,
      "loop": false
    },
    {
      "id": "gallery-entrance",
      "type": "image",
      "url": "https://storage.googleapis.com/my-bucket/images/entrance-panorama.jpg"
    },
    {
      "id": "sculpture-1",
      "type": "model",
      "url": "https://storage.googleapis.com/my-bucket/models/david-statue.glb",
      "scale": 2.0,
      "rotation": { "x": 0, "y": 3.14, "z": 0 }
    },
    {
      "id": "main-hall",
      "type": "image",
      "url": "https://storage.googleapis.com/my-bucket/images/main-hall-panorama.jpg"
    },
    {
      "id": "closing-video",
      "type": "video",
      "url": "https://storage.googleapis.com/my-bucket/videos/thanks-360.mp4",
      "autoplay": true,
      "loop": false
    }
  ]
}

Media Format Guidelines¶

360 Videos¶

Format: MP4 (H.264/H.265 codec)
Resolution: 4K (3840×2160) or 2K (2880×1440)
Projection: Equirectangular (spherical)
Frame Rate: 30fps or 60fps
Bitrate: 10-20 Mbps for 4K

360 Images¶

Format: JPG or PNG
Resolution: 4096×2048 (4K) or 8192×4096 (8K)
Aspect Ratio: 2:1 (equirectangular)
Color Space: sRGB
File Size: Compressed to < 5MB recommended

3D Models¶

Format: GLB (preferred) or GLTF
Triangles: < 100K for best performance
Textures: 2K resolution or lower
File Size: < 50MB recommended
PBR Materials: Supported (Metallic-Roughness workflow)

Setting Up Google Cloud Storage URLs¶

Step 1: Upload Media¶

gsutil cp your-video.mp4 gs://your-bucket/videos/
gsutil cp your-image.jpg gs://your-bucket/images/
gsutil cp your-model.glb gs://your-bucket/models/

Step 2: Make Files Public (if needed)¶

gsutil acl ch -u AllUsers:R gs://your-bucket/videos/your-video.mp4

Step 3: Get Public URL¶

https://storage.googleapis.com/your-bucket/videos/your-video.mp4

Step 4: Update config.json¶

Paste the full URLs into your config.json file.

Hot Reload¶

The configuration is loaded at startup. To see changes: 1. Edit /public/config.json 2. Refresh your browser 3. The new configuration will load automatically

Testing Without Media Files¶

For testing the UI without actual media files, you can use placeholder URLs:

{
  "experience": {
    "title": "Test Experience",
    "description": "Testing the interface"
  },
  "stages": [
    {
      "id": "test-1",
      "type": "image",
      "url": ""
    },
    {
      "id": "test-2",
      "type": "video",
      "url": ""
    }
  ]
}

Note: Empty URLs will fail to load media, but you can test the UI navigation (prev/next buttons).

Troubleshooting¶

Media Not Loading¶

Check that URLs are accessible in browser
Verify CORS is enabled on your GCS bucket
Ensure files are publicly readable
Check browser console for specific errors

Ensure you have multiple stages in config
Check browser console for JavaScript errors
Verify JSON syntax is valid

Performance Issues¶

Reduce video resolution (use 2K instead of 4K)
Compress images to lower file sizes
Optimize 3D model polygon count
Use progressive JPG encoding for images

Minimal UI Features¶

The new iPhone-style UI includes: - Left Circle Button: Previous stage - Right Circle Button: Next stage - No Overlays: Clean immersive experience - No Titles: Media speaks for itself - Auto-hide: Buttons fade in/out on hover

Perfect for distraction-free VR experiences!