TitleVideo (RPG Maker MV) — Robust Autoplay & Loop + Safe Cleanup

Bring your title screen to life with a looping video layer placed above the default title background. This fork of TitleVideo.js (original by Ryan Sivek) keeps the original feature set but fixes the common pain points—autoplay that sometimes stalls, loops that desync, and the dreaded “duration of null” crash when leaving the title scene.

Tested on RPG Maker MV v1.6.3.

What this plugin does

• Renders a video texture over the title background using PIXI (PIXI.Texture.fromVideo).

• Auto-selects the correct movie extension (.webm or .mp4) based on platform support.

• Lets you control size, position, opacity, tint, blend mode, and playback rate.

• Supports looping (full video or a custom loop region between two timestamps).

Problems in the base plugin (v1.2.0) & how this version fixes them

1) Intermittent autoplay stall on some platforms/browsers

Cause: Autoplay policy, timing of play() vs. readiness events.
Fixes in this fork:

• Sets video attributes earlier (autoplay, preload, playsinline).

• Calls play() reliably on loadedmetadata / canplay.

• Adds a document-level unlock (first click/keydown) fallback to start playback if blocked.

• Graceful retry: if play() is rejected due to autoplay policy and audio isn’t muted, temporarily mutes and tries again.

2) Custom loop timing drifts or doesn’t trigger

Cause: Floating-point timing and late metadata.
Fixes in this fork:

• Rebuilds the loop after metadata loads (accurate duration).

• Uses a small epsilon when comparing currentTime to loopEnd.

• Falls back to full-video loop when appropriate; otherwise uses a timeupdate-based custom loop.

3) Crash when leaving the title screen

Symptom: TypeError: Cannot read property 'duration' of null
Cause: Event listeners firing after the video element was already torn down.
Fixes in this fork:

• Orderly cleanup in Scene_Title.terminate():

  1. Remove document unlock handlers & video listeners

  2. Pause, detach src, load(), then remove the element

  3. Destroy PIXI sprite/texture

  4. Restore WebAudio.setMasterVolume hook

  5. Call the original terminate()

• All late events are neutered, so no “duration of null”.

4) Volume not tracking master volume

Fix: Keeps the original feature but ensures the hook is restored on exit so other scenes behave normally.

Parameters (Plugin Manager)

• Video Name
  Base filename in movies/ without extension (e.g., TitleMovie → TitleMovie.webm / TitleMovie.mp4). The plugin auto-picks the right extension.

• Muted (yes/no)
  Start muted. Tip: muted helps pass autoplay policies.

• Volume (0–1)
  Video volume multiplied by MV’s master volume.

• Width (auto | video | number)
  auto = window width, video = source width after metadata, or an exact pixel value.

• Height (auto | video | number)
  auto = window height, video = source height after metadata, or an exact pixel value.

• X, Y (numbers)
  Position of the video sprite on the title scene.

• Loop (yes/no)
  Loop playback.

• Playback Rate (number, default 1.0)
  Slow-mo (<1), normal (=1), fast-forward (>1).

• Blend Mode (NORMAL, ADD, MULTIPLY, SCREEN, …)
  PIXI blend mode applied to the video sprite.

• Opacity (0.0–1.0)
  Alpha of the video sprite.

• Tint (hex, e.g. 0xffffff)
  Tint color applied to the video sprite.

• Loop Start (seconds)
  Custom loop start time. Use 0 for the beginning.

• Loop End (end or seconds)
  Custom loop end time. Use end to loop to the actual duration.

• Debug (yes/no)
  Print extra logs to the console (F8).

Installation & usage

1. Put both .webm and .mp4 versions of your video in www/movies/ (same base name).

2. Install the plugin and set Video Name to the base file name (no extension).

3. Adjust size/position, loop, and playback settings to taste.

4. (Optional) If autoplay is blocked on a platform, enabling Muted = yes often resolves it.

Compatibility notes

• Built and tested on RPG Maker MV 1.6.3.

• Uses PIXI’s fromVideo texture and MV’s audio master volume.

• Cleans up its handlers so it doesn’t interfere with subsequent scenes or audio behavior.

Troubleshooting

• Video doesn’t start automatically:
  Try Muted = yes. Some platforms block autoplay with audio. The plugin also listens for the first click/keypress to unlock playback.

• Loop cuts early or late:
  Use Loop Start / Loop End with reasonable values; the plugin applies a small tolerance to avoid float errors.

• Black screen but audio plays:
  Make sure both formats exist in movies/ (.webm and .mp4) for cross-compatibility.

Credits

• Original plugin by Ryan Sivek

• Compatibility & reliability patch by Nixilliscyte (this release)

If this helped you…

This plugin is free. If it saved you time or made your title screen shine, please consider leaving a small donation. It helps me keep improving and supporting tools like this. Thank you! 💙🙏