.immerVR Sidecar Specification

Descriptions, audio, locations and effects for your VR slideshows.

Updated: 16 October 2026
Applies to: immerGallery 1.4.5d or newer
Authoring tools: immerGenerator 1.1.3 or newer · immerGenerator Web 1.3.5 or newer

A .immerVR file is a small text file that accompanies an image or video. You can use it to customize how that item appears in immerGallery, add a description, or include music, narration and environmental effects. All settings are optional.

You can create a sidecar with immerGenerator for Windows and macOS or immerGenerator Web, or write one in a plain-text editor.

File naming & syntax

Add .immerVR to the complete media filename, including its extension. Keep the sidecar in the same folder as the image or video.

Media file	Sidecar file
`beach.jpg`	`beach.jpg.immerVR`
`beach.mp4`	`beach.mp4.immerVR`

When creating a sidecar with immerGenerator Web, enter the complete media filename, such as beach.jpg, in the filename field.

One command per line: a name, a space, then its value or values. For example: showCopyright true.
Save as plain UTF-8 text without a byte order mark (BOM). Use spaces between values. Windows, macOS and Linux line endings are accepted.
Write numbers with a decimal point: 15.5, without thousands separators.
Booleans use true or false. Command names and the listed format/effect values are case-insensitive. Preserve file-path spelling.
Put text fields in straight double quotes. Descriptions and credits use quotes; audio file paths do not, even if they contain spaces.
Put comments on separate lines beginning with //. Do not append comments to a command.
Use each setting once. The phobia command can be repeated for multiple tags.
Square brackets mean an optional value. Do not write the brackets themselves.

Example folder

This overview shows a folder named My gallery. It contains an image, its sidecar and a custom map image. A subfolder named audio contains the background audio file:

                My gallery/
  01 Alpine morning.jpg
  01 Alpine morning.jpg.immerVR
  01 Alpine morning_map.jpg
  audio/
    Alpine ambience.mp3

File	Role
`01 Alpine morning.jpg`	The image displayed in immerGallery.
`01 Alpine morning.jpg.immerVR`	The text file containing the settings for that image.
`01 Alpine morning_map.jpg`	An optional custom map. Add `mapProvided true` to the sidecar when you supply it.
`audio/Alpine ambience.mp3`	An optional background track. Reference it with `audioBackgroundFile audio/Alpine ambience.mp3`.

A sidecar applies to one image or video. The order of a slideshow depends on the media filenames and the sorting mode selected in immerGallery. For example, filename sorting can use numbered prefixes such as 01, 02 and 03.

Descriptions & display information

You can give each item a caption and credit, and adjust how its information is displayed.

Command & syntax	Values & default	Purpose
`description` `description "text"`	Quoted text; up to 300 characters. Default: No sidecar caption.	Caption for the media. Supports <b>bold</b>, <i>italic</i>, and a literal \n for a displayed line break. Keep the entire command on one physical line. Formatting tags and the two characters in \n count toward the stored limit. Some Unicode symbols, including many emoji, count as two characters.
`copyright` `copyright "text"`	Quoted text; up to 60 characters. Default: No sidecar credit.	Stores the creator or copyright credit. Set showCopyright true to display it. Do not include a copyright symbol; immerGallery already supplies it in the display.
`showCopyright` `showCopyright true`	true / false Default: false	Shows the copyright text when available. False keeps the credit in the sidecar without displaying it.
`trimFilenameStart` `trimFilenameStart true`	true / false Default: false	Hides leading digits and spaces in the displayed filename. For example, 01 Alpine morning.jpg is displayed without the sorting prefix. It does not rename the file or define slideshow order.
`minimumAgeRequiredToWatch` `minimumAgeRequiredToWatch 12`	Integer: 0–99 years. Default: 0	Reserved for future use. This setting is not currently used by immerGallery and does not restrict access to an item.

                description "<b>Alpine morning</b>\nA view across the valley."
copyright "2026 Example Photographer"
showCopyright true

Location, maps & camera information

You can add a location or custom map and choose which camera information to display.

Command & syntax	Values & default	Purpose
`gpsLongLatAltitude` `gpsLongLatAltitude longitude latitude [altitude]`	Longitude: −180–180°. Latitude: −90–90°. Optional altitude in meters; negative values are allowed. Default: No sidecar location; embedded metadata may supply one.	Adds a location. Order is longitude first, then latitude. Positive values mean east and north. Omitting altitude uses 0 meters.
`showGPS` `showGPS true`	true / false Default: true	Controls the display of available GPS information, including coordinates obtained from embedded metadata.
`mapProvided` `mapProvided true`	true / false Default: false	Set to true when supplying a custom map image so immerGallery knows to load it. For beach.jpg, place beach_map.jpg in the same folder. A square 512 × 512 image is a practical choice. The map is a separate image file, not part of the sidecar text.
`showExif` `showExif true`	true / false Default: true	Shows available camera metadata, such as camera, lens, exposure, aperture and ISO. It does not add missing metadata.

Media format

You can specify the projection and stereo layout of an image or video.

Command & syntax	Values & default	Purpose
`imageFormat` `imageFormat VR_180_stereo_left_right`	Named format; see the format tables. Default: Automatic detection when omitted.	Selects the projection and stereo layout. Use a value from the format table below. It changes interpretation of existing media; it does not convert the file. Omit this command for MPO files to use automatic detection.
`swapLeftRight` `swapLeftRight true`	true / false Default: false	Exchanges the left-eye and right-eye views of stereo content.
`disabledBackgroundForLowFov` `disabledBackgroundForLowFov true`	true / false Default: false	Disables the image-derived ambient surround for low-field-of-view still images. The ordinary ambient view becomes black unless another active mode or environment supplies the background.

Format values

Use one of these values after imageFormat. Left/right layouts place the two eye views next to each other; top/bottom layouts stack them vertically. Half-size layouts compress each eye view along the packing direction.

Media layout	Value
Regular 2D	`Regular_mono`
Regular 3D L/R	`Regular_3D`
VR180 Stereo L/R equirect.	`VR_180_stereo_left_right`
VR360 mono equirect.	`VR_360_mono`
VR180 mono equirect.	`VR_180_mono`
VR180 mono fisheye	`VR_180_mono_fisheye`
VR180 stereo T/B equirect.	`VR_180_stereo_top_down`
VR180 stereo L/R fisheye	`VR_180_stereo_fisheye_left_right`
VR180 stereo T/B fisheye	`VR_180_stereo_fisheye_top_down`
VR180 stereo from .vr.jpg	`VR_180_stereo_VR_DOT_JPG_left_right`
VR180 stereo L/R Canon 5.2mm lens	`VR_180_stereo_left_right_canon52`
VR360 mono L/R fisheye	`VR_360_mono_fisheye_left_right`
VR360 mono T/B fisheye	`VR_360_mono_fisheye_top_down`
VR360 stereo L/R equirect.	`VR_360_stereo_left_right`
VR360 stereo T/B equirect.	`VR_360_stereo_top_down`
VR360 stereo from .vr.jpg	`VR_360_stereo_VR_DOT_JPG_left_right`
Regular 3D half L/R	`Regular_3D_half`
Regular 3D T/B	`Regular_3D_top_down`
Regular 3D half T/B	`Regular_3D_top_down_half`
Regular 3D red/blue anaglyph	`Regular_3D_anaglyph`
Cylindrical 2D Panorama	`Cylinder_mono`
Cylindrical 3D Panorama L/R	`Cylinder_stereo_left_right`
Cylindrical 3D Panorama half L/R	`Cylinder_stereo_left_right_half`
Cylindrical 3D Panorama T/B	`Cylinder_stereo_top_down`
Cylindrical 3D panorama half height (top/bottom)	`Cylinder_stereo_top_down_half`

Viewing direction & screen position

You can set a starting direction or adjust a flat screen or cylindrical panorama.

Command & syntax	Values & default	Purpose
`startRotationOffsetFor360` `startRotationOffsetFor360 45.0`	Decimal degrees; normally −180–180°. A full turn is 360°. Default: 0	Adjusts the initial horizontal orientation of 360° media. Pair with forceKeepRotationOff true when you need the specified starting view to take precedence over retained rotation. A value of 0 allows embedded orientation metadata to supply the starting direction.
`forceKeepRotationOff` `forceKeepRotationOff true`	true / false Default: false	Overrides the viewer’s keep-rotation preference when changing between 360° items, allowing the next item to start at its specified orientation.
`cinemaWallOffset` `cinemaWallOffset 1.0`	Decimal: −3.5–4.5. Default: 0	Moves a flat cinema screen forward or backward. Positive values move it farther away; negative values bring it closer. Not a spherical projection setting.
`cinemaWallOffsetLeftRight` `cinemaWallOffsetLeftRight 0.5`	Decimal: −5–5. Default: 0	Offsets a flat screen horizontally. Positive values move right; negative values move left.
`cinemaWallOffsetUpDown` `cinemaWallOffsetUpDown 0.5`	Decimal: −5–5. Default: 0	Offsets a flat screen vertically. Positive values move up and negative values move down.
`cylinderPanoramaHorizontalDegrees` `cylinderPanoramaHorizontalDegrees 180.0`	Decimal: 50–360°. Default: No explicit override.	Sets the horizontal coverage of a cylindrical panorama. Use a Cylinder_* format. A cylindrical panorama is different from a full spherical 360° panorama.
`cylinderHeightOffset` `cylinderHeightOffset 5.0`	Decimal: −50–50. Default: 0	Adjusts a cylindrical panorama vertically. Positive values move it up. This is a scaled cylinder offset, not a distance in meters.

Environmental effects

You can add an environment to an item and adjust the color of supported effects.

Command & syntax	Values & default	Purpose
`imageEnvironment` `imageEnvironment Snow`	Named environment; see the environment table. Default: No sidecar environment override.	Selects an environmental effect for the item. Use a value from the table below. Omit this command if you do not want to specify an effect.
`imageEnvironmentEffectColor` `imageEnvironmentEffectColor 220 235 255`	Three RGB integers, each 0–255. Default: 255 255 255: default effect appearance.	Colors snow, underwater fog/caustics, or the surrounding hot-air balloons. Applies to Snow, Underwater, UnderwaterNoAnimals and the four balloon variants that include surrounding balloons. It does not recolor the media. White restores the built-in colors for underwater and balloon effects; snow uses white.

Environment values

The available environment names are listed alphabetically.

Value	Effect
`Birds`	Birds around the viewer.
`Easter`	Easter environment.
`Egypt`	Egyptian environment.
`Halloween`	Halloween environment.
`HotAirBalloons`	Surrounding balloons; supports effect color.
`HotAirBalloonsBirds`	Surrounding balloons and birds; supports effect color.
`HotAirBalloonsBirdsEgo`	Surrounding balloons, birds and the viewer’s basket; supports effect color for surrounding balloons.
`HotAirBalloonsEgo`	Surrounding balloons plus the viewer’s balloon basket; supports effect color for surrounding balloons.
`HotAirBalloonsOnlyEgo`	The viewer’s balloon basket without the surrounding balloons.
`Leaves`	Falling leaves.
`Meadow`	Meadow with butterflies.
`MeadowNoButterflies`	Meadow without butterflies.
`Rain`	Rain effect.
`Snow`	Falling snow; supports effect color.
`StPatricksDay`	St. Patrick’s Day environment.
`Underwater`	Underwater scene with animals; supports effect color.
`UnderwaterNoAnimals`	Underwater scene without animals; supports effect color.
`Xmas`	Christmas environment; uses a flat screen where needed.

Slideshow timing

You can choose how long a still image stays on screen.

Command & syntax	Values & default	Purpose
`autoSwitchToNextImageSeconds` `autoSwitchToNextImageSeconds 15.0`	Decimal seconds: at least 3.0. Default: No per-image timer.	Advances from a still image after the specified display interval, subject to loading and playback state. The countdown waits for assigned audio to be ready. It does not wait for narration to finish and does not set a video’s duration. Omit this command to use normal viewer behavior; 0 is not a reset instruction.

Background audio & narration

You can accompany an item with music, ambience or a separate voice-over track.

Command & syntax	Values & default	Purpose
`audioBackgroundFile` `audioBackgroundFile audio/Forest ambience.mp3`	Relative path including .mp3, .ogg or .wav; or a built-in audio path. Default: No assigned background track.	Assigns music or ambience. Paths are relative to the media folder. Spaces are allowed; do not add quotes. Use forward slashes for subfolders. Built-in audio uses the special paths listed below.
`scaleAudioBackgroundVolume` `scaleAudioBackgroundVolume 0.2`	0–1. 0 is silent; 1 is full scale. Default: 1.0	Scales the assigned background track. For example, 0.2 is 20% of full scale. Viewer volume, muting and sound ducking can further change the audible level.
`loopAudioBackground` `loopAudioBackground true`	true / false Default: true	Controls repeat playback of the background track.
`audioVoiceOverFile` `audioVoiceOverFile narration/Arrival.mp3`	Relative path including .mp3, .ogg or .wav. Default: No assigned voice-over.	Assigns a separate narration track. Spaces are allowed without quotes. Built-in background tracks are not voice-over resources.
`scaleAudioVoiceOverVolume` `scaleAudioVoiceOverVolume 0.3`	0–1. 0 is silent; 1 is full scale. Default: 1.0	Scales narration independently of the background track. This does not control a video’s embedded soundtrack.
`loopAudioVoiceOver` `loopAudioVoiceOver false`	true / false Default: false	Requests repeat playback of the narration track. Set false for a narration track that should play once.
`lowerMusicDuringVoiceover` `lowerMusicDuringVoiceover true`	true / false Default: false	Lowers background audio while the voice-over plays, then restores it. This is also called sound ducking. It affects the background-audio track, not the video’s own soundtrack.
`disableImageSwitchSound` `disableImageSwitchSound true`	true / false Default: false	Disables the slide/projector sound associated with switching images.

Built-in background tracks

You can use the following built-in tracks without adding an audio file to your gallery. Put the filename after Assets/Resources/backgroundAudio/:

arabic.mp3, beach.mp3, birds.mp3, classical.mp3, corporate.mp3, nature 2.mp3, nature.mp3, night.mp3, ocean 2.mp3, ocean.mp3, people.mp3, rain.mp3, relax 2.mp3, relax 3.mp3, relax.mp3, traffic.mp3, underwater.mp3, waterfall.mp3, wind.mp3

                audioBackgroundFile Assets/Resources/backgroundAudio/nature.mp3
scaleAudioBackgroundVolume 0.2

For narration, choose a display interval long enough for the complete recording. The slideshow timer does not wait for narration to finish. A referenced audio file must exist and load successfully.

Capture date & time

You can supply a capture date and time or choose how existing information is displayed.

Command & syntax	Values & default	Purpose
`captureTimeYear` `captureTimeYear 2026`	Integer year; −1 is reserved for “not supplied”. Default: Not supplied; available embedded metadata may be used.	Sets the local capture year. Other negative years can represent historical dates. A historical year can be combined with showOnlyYear true.
`captureTimeMonth` `captureTimeMonth 10`	Integer: 1–12. Default: Not supplied; available embedded metadata may be used.	Sets the local capture month.
`captureTimeDay` `captureTimeDay 15`	Integer: 1–31. Default: Not supplied; available embedded metadata may be used.	Sets the local capture day. Use a valid calendar date together with the month and year.
`captureTimeHour` `captureTimeHour 14`	Integer: 0–23. Default: Not supplied; available embedded metadata may be used.	Sets the hour in local 24-hour time.
`captureTimeMinute` `captureTimeMinute 30`	Integer: 0–59. Default: Not supplied; available embedded metadata may be used.	Sets the local capture minute.
`showDate` `showDate true`	true / false Default: true	Displays an available capture date.
`showTime` `showTime true`	true / false Default: false	Displays an available capture time. No date or time is invented if metadata is missing.
`showOnlyYear` `showOnlyYear true`	true / false Default: false	Displays only the year, suppressing month, day and time. Enable showDate as well.

Capture times use local 24-hour time. These settings do not include a timezone. For historical images, you can display only the year:

                captureTimeYear 1925
showDate true
showOnlyYear true

Content sensitivity & phobia tags

You can tag potentially sensitive content so immerGallery can apply the viewer’s phobia preferences.

Command & syntax	Values & default	Purpose
`phobia` `phobia name [intensity]`	Name from the table below. Intensity: low, medium, high; omitted or unknown means unspecified. Default: No tag.	Adds a content-sensitivity tag for the item. Repeat the command for multiple triggers. Use medium or high for acrophobia; the other categories normally use high. To remove a tag, delete its line.

Name	Content
`acrophobia`	Heights
`arachnophobia`	Spiders
`carnophobia`	Meat intended for consumption
`claustrophobia`	Enclosed spaces
`cynophobia`	Dogs
`entomophobia`	Insects
`hematophobia`	Blood

                phobia acrophobia medium
phobia arachnophobia high

These tags describe the whole image or video. The viewer’s phobia settings determine how tagged items are handled. For heights, medium and high can also affect comfort-floor behavior.

Complete examples

360° image with music, map and snow

Save this as 01 Alpine morning.jpg.immerVR in the example folder shown above. Include the custom map and audio file listed there.

                // 01 Alpine morning.jpg.immerVR
description "<b>Alpine morning</b>\nA view across the valley."
copyright "2026 Example Photographer"
showCopyright true
imageFormat VR_360_mono
startRotationOffsetFor360 45.0
forceKeepRotationOff true
gpsLongLatAltitude 12.48350 50.73341 154.5
mapProvided true
autoSwitchToNextImageSeconds 20.0
audioBackgroundFile audio/Alpine ambience.mp3
scaleAudioBackgroundVolume 0.2
loopAudioBackground true
imageEnvironment Snow
imageEnvironmentEffectColor 220 235 255
trimFilenameStart true

Narrated museum image

Save this as 02 Museum.jpg.immerVR beside 02 Museum.jpg. Place the narration in narration/Museum introduction.mp3. Adjust the display interval to fit the recording.

                // 02 Museum.jpg.immerVR
description "An introduction to the collection."
imageFormat Regular_mono
audioVoiceOverFile narration/Museum introduction.mp3
scaleAudioVoiceOverVolume 0.3
loopAudioVoiceOver false
loopAudioBackground false
disableImageSwitchSound true
autoSwitchToNextImageSeconds 30.0

360° video with caption and starting direction

Save this as 03 Coast.mp4.immerVR beside 03 Coast.mp4. The video’s duration determines its playback length.

                // 03 Coast.mp4.immerVR
description "An evening walk along the coast."
imageFormat VR_360_mono
startRotationOffsetFor360 90.0
forceKeepRotationOff true
copyright "2026 Example Filmmaker"
showCopyright true

Using your sidecars

Keep accompanying files together. Copy the sidecar, custom map and referenced audio files along with the media. Audio paths are relative to the media folder.
Declare a custom map explicitly. Include mapProvided true whenever you supply a _map image.
Image timing applies to still images. autoSwitchToNextImageSeconds does not trim a video or change its playback duration.
Preview your slideshow. Check the viewing direction, text, audio levels and narration timing in immerGallery.
Use a gallery source that makes sidecars available. UPnP Gallery does not provide these accompanying text files.