immerVR MovieHint Specification v0.1

• Version: v0.1
• Publication date: 2025‑11‑27
• Author: immerVR GmbH (https://immerVR.com)

1. Scope & Goals

The MovieHint specification defines a simple, text‑based way to describe timed immersive cues associated with a media asset (typically a video). A single cue can describe:

• Optional 3D particle effect or environment (e.g. Rain, Meadow, Underwater).
• Optional 360° mono background media (image or video; default projection is 360° mono equirectangular).
• Optional fade‑in / fade‑out durations for the effect/background.
• Optional intensity ​(scalar intensity factor, default 1.0; 0.0 = no effect, values > 1.0 allowed for stronger effects).

Additional settings (e.g. stereo mode, projection type, color grading, presets) MAY be added later via new keys. The format is deliberately open and extensible. This spec defines:

• A concrete implementation for .immerVR sidecar files.
• An immerVR SRT extension to embed the same semantics into .srt subtitle files by adding tags to the timecode line.

The format itself is open. Other applications are free to:

• Implement their own readers / writers.
• Use other containers (JSON, XML, databases) that follow the same key semantics and value ranges.

Numeric values and enum orderings shown here are examples from immerGallery; other apps may use different internal representations as long as the text names and behavior match.

2. Encoding, whitespace & comments

2.1 Encoding

• All files using this spec MUST be encoded as UTF‑8.
• UTF‑8 with BOM is recommended, especially for .immerVR files.
• Readers MUST accept UTF‑8 both with and without BOM.
• Writers targeting unknown third‑party tools MAY choose to omit the BOM for maximum compatibility, especially in .srt.

2.2 Whitespace and line structure

• Files are processed line by line.
• Lines are separated by standard newline conventions (\n or \r\n). 
• Leading and trailing whitespace (spaces or tabs) on each line is ignored when interpreting keywords. 
• Each command must be on a single physical line. Line continuation is not supported.

Example of a valid single‑line movieHint:

movieHint 00:00:01,000 00:00:04,000 env:Meadow bg360:backgrounds/gray sky.jpg intensity:0.8 fadeIn:1 fadeOut:0,500 

2.3 Comments

• Anything after an unquoted # or // starts a comment to end of line.
• This applies both to whole lines and inline comments. 
• Comment markers are only treated as such if they appear outside double‑quoted strings.

Examples:

# Full-line comment
movieHint 5 10 env:Rain # Inline comment

movieHint 10 20 bg360:"C:/VR # Backgrounds/green.jpg" intensity:0.7 // OK, comment starts here 

2.4 Keywords and extensibility

Current top‑level keywords used in .immerVR files include:

• imageEnvironment 
• movieHint

Current parameter keys used inside movieHint:

• env
• bg360
• intensity
• fadeIn
• fadeOut

All keys are:

• Case‑insensitive (movieHint, MOVIEHINT, moviehint are equivalent).
• Extensible – additional keys MAY be defined in future versions, e.g.: projection:, stereo:, fxPreset:
• Readers MUST ignore unknown keys (and MAY log a warning).

3. Environment names (ImageEnvironment)

Environment names in files map to the following enum names as currently used in immerGallery:

public enum ImageEnvironment {
  Unknown,
  Rain,
  Meadow,
  MeadowNoButterflies,
  Snow,
  Underwater,
  UnderwaterNoAnimals,
  Halloween,
  Leaves,
  Xmas,
  StPatricksDay,
  HotAirBalloons,
  HotAirBalloonsEgo,
  HotAirBalloonsOnlyEgo,
  HotAirBalloonBirds,
  HotAirBalloonBirdsEgo,
  Birds,
  Easter,
  Platform,
  Egypt,
  None 
} 

Notes:

• This is the current supported set in immerGallery. Other environments (e.g. Moon, City, Space) MAY be added in future versions.
• In this version of the spec, only one ImageEnvironment can be active at any given time. To represent combined experiences (for example “hot-air balloons plus birds”), some enum values are defined as presets that internally combine multiple visual elements, such as HotAirBalloonBirds and HotAirBalloonBirdsEgo.
  
• Names ending in Ego indicate that the user / camera (the “ego”) is placed inside a primary object of the scene in addition to other elements appearing further away. For the hot-air balloon variants this means:  without Ego, hot air balloons are shown around the user at some distance;  with Ego, the user is placed inside a hot air balloon gondola while additional balloons remain visible further away. 
  
• The numeric values and ordering are implementation details of immerGallery. Other implementations MAY use different numeric codes, as long as the text names map to equivalent behavior.

Environment descriptions (informative):

• Unknown: Means “no explicit override”. If a hint says env:Unknown, it behaves as if env: were omitted.
• Rain: 3D rendered rain particle effect.
• Meadow: Outdoor meadow environment showing small dust particles, pollen, dandelions and butterflies around the user.
• MeadowNoButterflies: Same as Meadow, but without butterflies.
• Snow: 3D rendered snow particle effect.
• Underwater: Underwater scene with various underwater life, a ground floor with caustics, and distance-based volumetric fog so distant objects gradually fade into the water.
• UnderwaterNoAnimals: Underwater variant without fish or other animals; mainly water volume, a caustics-lit ground floor and distance fog. 
• Halloween: Shows falling leaves and a themed platform with Halloween-decorated items on which the user is placed.
• Leaves: Falling leaves in 3D space without additional themed decoration.
• Xmas: Christmas environment with snow and holiday-themed decoration.
• StPatricksDay: Falling clovers with a platform decorated with items commonly associated with St. Patrick’s Day.
• HotAirBalloons: Several hot air balloons drifting around the user at some distance; the user is not inside a balloon.
• HotAirBalloonsEgo: The user is placed inside a hot air balloon gondola (“ego view”) while additional balloons appear further away.
• HotAirBalloonsOnlyEgo: Only the “inside a hot air balloon” ego view is shown; other distant balloons are omitted.
• HotAirBalloonBirds: HotAirBalloons plus a flock of birds flying through the scene; the user is not inside a balloon.
• HotAirBalloonBirdsEgo: Combination of HotAirBalloonsEgo and HotAirBalloonBirds; the user is inside a balloon while other balloons and birds move around the scene.
• A flock of birds flying around the scene without balloons or additional themed decoration.
• Easter: Platform decorated with items in an Easter theme; the user stands on the platform.
• Platform: A general platform without a specific theme, providing a neutral floor under the user.
• Egypt: Egyptian-style environment (e.g. desert or temple surroundings) with sand dust particles in the air.
• None: Means “explicitly disable environment/effects” for this interval. This overrides any imageEnvironment default that might otherwise apply.

Comparisons of environment names are case‑insensitive.

4. Time and duration formats

Both absolute times (start/end) and durations (fadeIn/fadeOut) use the same flexible TimeValue syntax in .immerVR: 
Allowed forms:

• SS
• SS,fff
• MM:SS
• MM:SS,fff
• HH:MM:SS
• HH:MM:SS,fff

Parsing rules:

1. Split the string by ':' from right to left:

• Rightmost component = seconds (may include ,fff).
• Next component (if present) = minutes.
• Next component (if present) = hours.

2. ​If seconds contain ,fff, parse fff as milliseconds. Otherwise, milliseconds = 0.
3. Missing hours/minutes default to 0.

Examples:

• 5 → 00:00:05,000
• 1,250 → 00:00:01,250
• 1:05 → 00:01:05,000
• 1:05,250 → 00:01:05,250
• 2:03:04 → 02:03:04,000
• 2:03:04,123 → 02:03:04,123

For SRT timecodes, start and end MUST be canonical HH:MM:SS,fff on the timecode line (see chapter 9).

5. .immerVR keywords

5.1 imageEnvironment (global default)

Syntax:

imageEnvironment <EnvironmentName>

• EnvironmentName must be a known environment name from section 3 (Meadow, Rain, Underwater, etc.). 
  
• If no valid imageEnvironment line is present, the global default environment is Unknown.

Semantics:

• Defines the default environment when no movieHint with an env: applies.
• env:None in a movieHint overrides the global imageEnvironment during that hint’s interval.

5.2 movieHint (timed cue)

5.2.1 Syntax

General form:

movieHint <start> <end> [env:<EnvironmentName>] [bg360:<Path>] [intensity:<float>] [fadeIn:<duration>] [fadeOut:<duration>] [<futureKey>:<value>...] 

• movieHint keyword is case‑insensitive.
• <start> and <end> are TimeValues (section 4).
• Parameters are order‑independent.
• Known parameter keys (case‑insensitive): env, bg360, intensity, fadeIn, fadeOut
• Unknown keys MUST be ignored by readers (MAY log a warning).

Implementation SHOULD treat hints that have neither env: nor bg360: as no‑ops.

5.2.2 env:<EnvironmentName>

• Maps to ImageEnvironment (section 3).
• Case-insensitive.
• Unknown → no override for this hint.
• None → explicitly disable environment FX during this interval, even if imageEnvironment is set.

Example:

movieHint 3 6 env:Rain
movieHint 00:01:00 00:01:10 env:None 

5.2.3 bg360:<Path>

Indicates a 360° mono background to be shown on the sphere around the user during the hint interval.

Default assumption:

• Projection: 360° mono equirectangular.
• Other projection types MAY be supported later via additional keys (e.g. projection:).

Path value:
The bg360 value starts immediately after bg360: and continues until:

• the next parameter key (env:, intensity:, fadeIn:, fadeOut: or future key), or
• end‑of‑line.

Rules:

• Paths MAY contain spaces.
• Paths MUST NOT contain : except as part of a drive specification at the beginning (e.g. C:/... or D:\...).
• Tabs are treated like spaces.
• Both / and \ are allowed; readers MUST normalize \ to / internally.
• Double quotes are supported: If the first non‑whitespace character after bg360: is ", then: The path is everything up to the matching closing ".
• Comment markers and further keys start after that closing ".
• Single quotes ' are not special and are treated as normal characters.

Examples:

movieHint 1 4 bg360:/Pictures/background/gray.jpg
movieHint 10 20 bg360:backgrounds/gray sky.jpg intensity:0.8
movieHint 30 40 bg360:"C:/VR Backgrounds/Movie SciFi/green sphere.jpg" fadeIn:1 fadeOut:1 

Image vs video:

• Type is inferred from file extension (case-insensitive): Typical image extensions: .jpg, .jpeg, .png, etc.; typical video extensions: .mp4, .mov, .mkv, etc.
• Exact extension sets are implementation-defined.
• Unknown extensions MAY be treated as image by default, preferably with a warning

5.2.4 intensity:<float>

Scalar effect/background intensity hint.

• Default if omitted: 1.0 (“normal” or medium strength).
• Decimal separator: . (independent of locale).
• Intensity SHOULD be treated as ≥ 0.0. Negative values SHOULD be clamped to 0.0.
• Values > 1.0 are allowed and can be used for “stronger than normal” effects.

Example:

• For Rain, an intensity of 1.0 can represent a normal amount of rain. An intensity of 2.0 can be used for a representation that approximates raining twice as hard, while 0.5 can represent lighter rain.
• For fixed environments such as Egypt, intensity can control the amount or density of sand dust particles in the air.

movieHint 3 6 env:Rain intensity:0.7
movieHint 10 20 bg360:backgrounds/gray sky.jpg intensity:0.0 

5.2.5 fadeIn:<duration> and fadeOut:<duration>

Durations over which the hint ramps in and out.

• Format: TimeValue as a duration (section 4).
• Default: fadeIn omitted → 0 (instant on).
• Default: fadeOut omitted → 0 (instant off).

Recommended behavior:

• Fade‑in: From start to start + fadeIn, the effective strength for this hint increases from 0 to its configured intensity.
• Fade‑out: From end − fadeOut to end, the strength decreases from intensity to 0.
• If fadeIn or fadeOut exceeds the hint duration, implementations MAY clamp internally but SHOULD NOT fail.

Example:

movieHint 00:00:30,000 00:00:40,000 env:Snow bg360:winter/snow360.mp4 intensity:1.0 fadeIn:2 fadeOut:2,000 

6. Runtime semantics

6.1. Always-defined environment

Runtime data typically uses a class/struct like:

public class MovieHint {
  public TimeSpan Start;
  public TimeSpan End;

  // Always set; defaults to Unknown if not specified
  public ImageEnvironment Environment = ImageEnvironment.Unknown;

  // Empty string means "no background override"
  public string Bg360Path = string.Empty;

  public TimeSpan FadeIn = TimeSpan.Zero;
  public TimeSpan FadeOut = TimeSpan.Zero;

  public float Intensity = 1.0f;
} 

The environment is never null; it is always at least Unknown.

6.2. Channel separation

Conceptually, there are two channels:

1. Environment channel: Controlled by env
2. Background channel: Controlled by bg360

They are resolved independently at runtime.

6.3. Evaluating active hints at time t

For a given playback time t:

6.3.1 Environment

• Collect all hints with: Start ≤ t < End, and a specified env (not Unknown).
• Sort them by Start and (if needed) by file order.
• The last such hint is the active env hint.
• If active env is: None → environment FX are disabled even if imageEnvironment is set.
  Any other enum value → apply that environment (scaled by intensity and fades).
• If there is no active env hint: Use imageEnvironment if present; otherwise, treat as Unknown / app default.

6.3.2 Background

• Collect all hints with: Start ≤ t < End, and a non‑empty bg360.
• The last such hint is the active background for t.
• If none applies, no specific 360 background is enforced (implementation-defined).

6.3.3 Fades and intensity

• Compute time‑dependent factor fadeAlpha(t) for the active hint based on fadeIn/fadeOut.
• Effective strength = Intensity * fadeAlpha(t).
• The exact curve (linear, smoothstep, etc.) is implementation-defined.

6.4. Overlaps and gaps

• Overlapping hints are allowed.
• Per channel (“env” and “bg360”), the latest matching hint wins (“last-defined wins”).
• When a hint ends, its contribution disappears for that channel; previous hints or defaults take over.

6.5. Unknown keys

• Unknown keys in movieHint lines MUST be ignored to maintain forward compatibility.
• Applications are encouraged to log a warning for unexpected keys to aid debugging, but MUST NOT treat them as errors that stop parsing.

7. Example .immerVR file

# Example: movieSciFi.mp4.immerVR

# Global default environment
imageEnvironment ​Meadow

# 1–4s: meadow + static 360 background, strong intensity
movieHint 00:00:01,000 00:00:04,000 env:Meadow bg360:/Pictures/background/gray sky.jpg intensity:1.0 fadeIn:1 fadeOut:0,500

# 3–6s: rain effect only, medium intensity, no background override
movieHint 3 6 env:Rain intensity:0.7

# 10–20s: 360° video background, gentle fade in/out, no extra env override
movieHint 00:00:10,000 00:00:20,000 bg360:supported360/green_animated.mp4 intensity:1.0 fadeIn:2 fadeOut:2

# 30–40s: 360° background with spaces in path
movieHint 00:00:30,000 00:00:40,000 bg360:"C:/VR Backgrounds/Movie SciFi/green sphere.jpg" intensity:1.0 fadeIn:1 fadeOut:1

# 50–55s: explicitly disable environment FX even though imageEnvironment=​Meadow
movieHint 50 55 env:None 

8. immerVR SRT Extension

The immerVR SRT extension allows MovieHint information to be embedded into .srt subtitle files in a way that:

• Keeps the SRT valid and usable for ordinary players.
• Allows immerVR‑aware players to extract the same cue information.

8.1. Standard SRT block

Normal SRT blocks look like:

<index>
<start> --> <end>
<subtitle text line 1>
[subtitle text line 2...]
<blank line> 

start and end are always HH:MM:SS,fff.

8.2. Extended timecode line with movieHint

Added data after the standard time range on the timecode line:

<index>
<start> --> <end> IMMERVR MOVIEHINT [ENV:<EnvironmentName>] [BG360:<Path>] [INTENSITY:<float>] [FADEIN:<duration>] [FADEOUT:<duration>] [<futureKey>:<value>...]
<subtitle text lines...>
<blank line> 

Conventions:

• immerVR and movieHint are case-insensitive, but UPPERCASE is recommended (IMMERVR MOVIEHINT).
  Parameter keys in SRT are usually uppercase (ENV, BG360, INTENSITY, FADEIN, FADEOUT), but must be parsed case-insensitively.
• start and end MUST be canonical SRT times HH:MM:SS,fff.
• Durations (FADEIN, FADEOUT) and other values use the same syntax as in .immerVR.

Example (subtitle + hint in one block):

1
00:00:05,000 --> 00:00:08,000 IMMERVR MOVIEHINT ENV:Meadow BG360:backgrounds/gray sky.jpg INTENSITY:0.8 FADEIN:1 FADEOUT:0,500
This is the second subtitle. 

Ordinary SRT players:

• Parse 00:00:05,000 --> 00:00:08,000.
• Ignore the trailing tokens on the timecode line.
• Render “This is the second subtitle.” as usual.

immerVR-aware players:

• Detect IMMERVR MOVIEHINT and extract the parameters according to the rules in chapters 4–6.

8.3. Hint-only blocks

You can define “metadata-only” blocks with no visible subtitle text:

1001
00:00:03,000 --> 00:00:06,000 IMMERVR MOVIEHINT ENV:Rain BG360:/Pictures/background/gray sky.jpg FADEIN:0,500 FADEOUT:0,500

• There is a blank line immediately after the timecode line.
• Standard players will show nothing or treat it as an empty caption.
• immerVR-aware players still apply the hint.

8.4. Paths, comments & whitespace in SRT

Path handling for BG360: in SRT follows the same rules as bg360: in .immerVR:

• Paths may include spaces.
• Optional double quotes are supported.
• Tabs/spaces are treated equally.
• # and // start comments after the path, same as in .immerVR, when outside quotes.

Example:

2
00:00:10,000 --> 00:00:20,000 IMMERVR MOVIEHINT BG360:"C:/VR Backgrounds/Movie SciFi/green sphere.jpg" INTENSITY:1.0 FADEIN:2 FADEOUT:2 # sci-fi segment
The hero enters the simulation. 

8.5. Extensibility and unknown keys in SRT

• Future keys (e.g. PROJECTION:, STEREO:, FXPRESET:) MAY be added after IMVR movieHint.
• immerVR-aware readers MUST ignore unknown keys and MAY log them.
• Non‑immerVR players will continue to ignore all extra tokens as they do today.

9. Implementation notes (non‑normative)

Readers should:

• Strip BOM if present.
• Normalize path separators (\ → /).
• Treat keys case-insensitively.
• Clamp intensity values < 0.0 up to 0.0, but allow values > 1.0 and pass them through to the rendering implementation. 
  

Writers are free to:

• Use different internal numeric values for ImageEnvironment.
• Choose precedence rules when both .immerVR and SRT‑embedded hints exist.
• A typical approach is to prefer a dedicated .immerVR file when present, and use SRT hints as a fallback.

For 360° backgrounds, implementations and content creators SHOULD consider not always using the highest-resolution textures. A blurred or otherwise low-detail version of the scene (for example a 1024×512 equirectangular texture) is often sufficient for most of the playback and keeps texture memory usage low. For sequences such as intro and end credits, it can be worthwhile to switch to a higher-resolution spherical texture (for example 8192×4096) that provides more detail and may contain visual references to the movie content. 

Appendix A: Current implementation state of immerGallery

As of immerGallery 1.4 the following parts of the specification have been implemented:

• .immerVR support for movieHint with env: and bg360: being used automatically during video playback
• Parsing of fadeIn, fadeOut and intensity, but not applied yet