How do I open a video in GizmoVR Lite from my website?

Use a gizmovr:// deep link: gizmovr://play?url=https%3A%2F%2Fexample.com%2Fvideo.mp4. When a user taps this link on a mobile device with GizmoVR Lite installed, the app opens and plays the video immediately. The url parameter must be URL-encoded.

What is the gizmovr:// deep link format?

GizmoVR Lite uses the gizmovr:// custom URL scheme on iOS and Android. Two actions are supported: gizmovr://play?url=... opens a single media item (video or image), and gizmovr://open?url=... loads a remote JSON collection on the app home screen. Links work from web pages, emails, QR codes, and native apps.

How do I create a custom VR media collection for GizmoVR Lite?

Host a JSON file on your server conforming to the GizmoVR Lite Collection Specification. The file must contain a root object with message 'OK' and a data.items array. Each item needs an id, title, type (video or image), thumbnail URL, format object (projection and stereo), and source URLs. Link to it via gizmovr://open?url=https%3A%2F%2Fyourserver.com%2Fcollection.json.

What VR projection formats does GizmoVR Lite support?

GizmoVR Lite supports three projection types: flat (standard 2D), 180 (VR180, 180° equirectangular), and 360 (full sphere, 360° equirectangular). For stereo packing: mono (monoscopic), tb (top-bottom stereo), and sbs (side-by-side stereo). These are specified in the format object of each collection item.

Developer Integration

Deep Links

GizmoVR Lite registers the gizmovr:// custom URL scheme on iOS and Android. A link with this scheme will launch the app (or wake it from the background) and immediately open your media or collection. Links work from web pages, emails, native apps, and QR codes.

Quick start

gizmovr://play?url=https%3A%2F%2Fexample.com%2Fvideo.mp4

play — open a single media item

Opens a video or image directly in the player. Optionally enters VR mode after loading.

Parameter	Type	Description
`url` Required	`string`	Media URL. Must be URL-encoded. Supports HTTPS, HTTP, and local file paths.
`type` Optional	`video` \| `image`	Media type. If omitted, inferred from the URL filename and any embedded format hints.
`vr` Optional	`true` \| `false`	Enter VR (Cardboard) mode immediately after opening. Default: `false`.

gizmovr://play?url=https%3A%2F%2Fexample.com%2Fvideo.mp4

gizmovr://play?url=https%3A%2F%2Fexample.com%2Fvideo_360.mp4&vr=true

gizmovr://play?url=https%3A%2F%2Fexample.com%2Fimage.jpg&type=image

open — load a collection

Loads a remote collection JSON and displays it on the app's home screen. See Collections for the JSON format.

Parameter	Type	Description
`url` Required	`string`	HTTPS URL to a collection JSON file. Must be URL-encoded. Must conform to the Collection Specification.

gizmovr://open?url=https%3A%2F%2Fexample.com%2Fcollection.json

Format inference: When type is omitted from a play link, the app checks the URL for format hints first (e.g. query params projection=360&stereo=sbs), then the filename (e.g. video_360_sbs.mp4 → 360°, side-by-side stereo). Falls back to flat projection, mono if no hints are found.

URL Builder

Action

Type

Media / Collection URL

Enter VR mode (vr=true)

Generated link

gizmovr://play?url=https%3A%2F%2Fexample.com%2Fvideo.mp4

Try it →

Collections

A collection is a JSON file you host on your own server. Link it via a gizmovr://open deep link and the app loads it as a browsable media library on the home screen. Use it for playlists, themed content, or any grouping of VR media.

Root schema

The top-level JSON envelope.

{
  "message": "OK",
  "data": {
    "title": "My VR Collection",
    "items": [ ... ]
  }
}

Field	Type	Description
`message` Required	`string`	Always `"OK"` on success.
`data` Required	`object`	Container for collection data.
`data.title` Optional	`string`	Collection title shown in the app.
`data.items` Required	`array`	Array of Item objects.

Item schema

Each entry in data.items represents a single video or image.

Field	Type	Description
`id` Required	`string`	Unique identifier. URL-safe characters only (`a-z`, `A-Z`, `0-9`, `-`, `_`). Max 128 chars.
`title` Required	`string`	Display title. Max 100 characters.
`type` Required	`"video"` \| `"image"`	Media type.
`thumb` Required	`string`	Thumbnail URL (HTTPS). JPEG or PNG, max 1024px, under 200 KB.
`format` Required	`object`	VR projection and stereo packing. See Format object.
`duration` Videos only	`integer`	Duration in seconds. Required for videos, ignored for images.
`sources` Conditional	`array`	Direct media URLs. Required for images. Videos: use this OR `metaUrl`.
`metaUrl` Conditional	`string`	HTTPS URL to a JSON endpoint that returns video sources at runtime. Videos only.
`description` Optional	`string`	Long description shown in the app. Max 500 characters.
`tags` Optional	`string[]`	Categorisation tags. Lowercase, max 10 tags, max 30 chars each.

Format object

Tells the app how to decode and display the media.

{ "projection": "360", "stereo": "mono" }

Field	Values	Description
`projection` Required	`"flat"`	Standard 2D / flat media.
	`"180"`	180° equirectangular (VR180).
	`"360"`	360° equirectangular (full sphere).
`stereo` Required	`"mono"`	Monoscopic — no stereo packing.
	`"tb"`	Top-bottom stereo packing.
	`"sbs"`	Side-by-side stereo packing.

Source object

A single media file URL, with optional quality metadata.

Field	Type	Description
`url` Required	`string`	Direct HTTPS URL to the media file.
`title` Optional	`string`	Quality label shown in the UI. E.g. `"4K"`, `"1080p"`, `"Original"`.
`width` Optional	`integer`	Width in pixels.
`height` Optional	`integer`	Height in pixels.
`codec` Optional	`string`	Video codec. E.g. `"h264"`, `"h265"`, `"vp9"`.
`bitrate` Optional	`string`	Bitrate in bps.
`size` Optional	`string`	File size, human-readable or in bytes.
`audioUrl` Optional	`string`	Separate audio track URL (for videos with split audio).

Full example

A complete collection with two items — one video using metaUrl and one image with inline sources.

{
  "message": "OK",
  "data": {
    "title": "My VR Collection",
    "items": [
      {
        "id": "bayview-pool",
        "title": "Bayview Pool Area",
        "description": "Relaxing 360° view of a pool area at sunset.",
        "type": "video",
        "duration": 238,
        "thumb": "https://media.example.com/thumbs/bayview-pool.jpg",
        "metaUrl": "https://api.example.com/video/bayview-pool",
        "sources": [],
        "tags": ["relaxing", "nature"],
        "format": {
          "projection": "360",
          "stereo": "mono"
        }
      },
      {
        "id": "dragon-ride",
        "title": "Riding a Dragon",
        "description": "POV: soaring past floating islands on the back of a dragon.",
        "type": "image",
        "thumb": "https://media.example.com/thumbs/dragon-ride.jpg",
        "tags": ["fantasy", "adventure"],
        "sources": [
          {
            "title": "4K",
            "url": "https://media.example.com/images/dragon-ride-4k.jpg",
            "width": 4096,
            "height": 2048
          }
        ],
        "format": {
          "projection": "360",
          "stereo": "mono"
        }
      }
    ]
  }
}

Validation checklist

All URLs (thumb, sources[].url, metaUrl) must be HTTPS.
Item id must be URL-safe: a-z, A-Z, 0-9, -, _ only. Max 128 characters. Must be unique within the collection.
Thumbnails: JPEG or PNG (JPEG preferred), max 1024px on the longest side, under 200 KB. Aspect ratio should match the media.
Videos must include duration (integer seconds, > 0) and either sources or metaUrl (or both).
Images must include a sources array with at least one entry.
Tags must be lowercase, alphanumeric + hyphens only, max 30 characters each, max 10 tags per item.
title max 100 characters; description max 500 characters.
Serve your JSON with Content-Type: application/json and CORS headers if needed.

Open media in GizmoVR Lite from your website

Deep Links

play — open a single media item

open — load a collection

URL Builder

Collections

Root schema

Item schema

Format object

Source object

Full example

Validation checklist