Skip to main content

TVPlugin Scripting API

List of Available Plugin Events​

The following is the list of variables used by the plugin events:

  • OUT_ERROR (VideoError)
  • OUT_VOLUME (float)
  • OUT_VIDEOPLAYER (int)
  • OUT_MODE (int)
  • OUT_OWNER (int)
  • OUT_SEEK (float)
  • OUT_SPEED (float)
  • OUT_TITLE (string)
  • OUT_URL (VRCUrl)

Each variable will be referenced by their respective events below.

The following is the list of events that any listener behavior may receive (they ALL start with _Tv):

  • _TvReady
    • Occurs when the TV has completed all initialization and is ready to be controlled.
    • If a behavior is registered to the TV after the initialization phase (Start event), then it will be called on the target behavior immediately after registering.
    • USE THIS EVENT TO "CATCH UP" WITH THE TV'S CURRENT STATE. This helps ensure that even if the plugin starts off as disabled on world load, as soon as it becomes registered, it can immediately sync up its internal state with the TV's.
    • This event will always be the first event to be called on the plugin and will only be called once.
  • _TvPlay
    • Occurs when a video has started or resumed playing.
  • _TvPause
    • Occurs when a video has been paused.
  • _TvStop
    • Occurs when a video has been stopped.
  • _TvMediaChange
    • Occurs when a user has claimed ownership of the TV and prepares a new video to play.
    • This event happens before the video is actually loaded.
    • To take action when a video is ready after it has been loaded, use the _TvMediaReady event.
    • This event will set the variable OUT_URL (VRCUrl) to the url that has been prepared.
  • _TvMediaReady
    • Occurs immediately after a video has been loaded and is ready.
    • This event occurs prior to any implicit call to _TvPlay or _TvPause.
    • This event will set the variable OUT_URL (VRCUrl) to the url that has been loaded.
  • _TvMediaEnd
    • Occurs immediately after a video has finished playing.
    • Can be used to trigger a new video, does NOT occur if video is set to loop.
  • _TvPlaybackStart
    • Occurs as soon as playback is detected to be enabled upon it's first attempt to play.
    • May be called multiple times per media load, but _TvPlaybackEnd must have been triggered before this event is allowed to be called again (such as the media reaching the end of its duration).
    • The TV will effectively toggle between the two events.
    • If the event is allowed to trigger, it will occur immediately after the _TvPlay event
  • _TvPlaybackEnd
    • Occurs whenever the playback is considered to have been completed/ended.
    • This event can only occur if the playback start has already been triggered for some media.
    • If the event is allowed to trigger, it will occur immediately after the _TvMediaEnd, _TvStop, _TvVideoPlayerError events.
    • Pausing media is NOT considered to be playback ending. Use _TvPause to detect when pausing happens.
  • _TvMediaLoop
    • Occurs when a video starts over after finishing.
    • Triggered only if video is set to loop OR if video is at the end and the owner pressed the play button for a one-time loop.
  • _TvTitleChange
    • Occurs when a title-only change has been requested of the TV. Will NOT be called if the URL also changes.
    • This event will set the variable OUT_TITLE (string) to the new title value.
  • _TvOwnerChange
    • Occurs when a different player takes control of the TV.
    • This event will set the variable OUT_OWNER (int) to the current int player ID value that ownership has switched to.
  • _TvVideoPlayerChange
    • Occurs when the TV has swapped the video player configuration to a different one.
    • This event will set the variable OUT_VIDEOPLAYER (int) to the current index value of the video player configuration that has been swapped to.
  • _TvVideoPlayerError
    • Occurs when the video failed to resolve and play for some reason.
    • This event will set the variable OUT_ERROR (VideoError) to the VideoError value that caused the event to trigger.
  • _TvMute
    • Occurs when the TV becomes muted.
  • _TvUnMute
    • Occurs when the TV becomes un-muted.
  • _TvVolumeChange
    • Occurs when the local user updates the volume percent value.
    • This event will set the variable OUT_VOLUME (float) to the updated volume percent. This event might be called many times in a short period, especially if it is affected by a slider element modifying the TV's volume.
  • _TvAudioMode3d
    • Occurs when the local user switches from positional to stereo audio.
  • _TvAudioMode2d
    • Occurs when the local user switches from stereo to positional audio.
  • _TvEnableLoop
    • Occurs when looping is enabled for the current video.
  • _TvDisableLoop
    • Occurs when looping is disabled for the current video.
  • _TvSync
    • Occurs when the local user enables video synchronization (disabled for owner as one cannot desync with oneself)
  • _TvDeSync
    • Occurs when the local user disables video synchronization (disabled for owner as one cannot desync with oneself)
  • _TvLock
    • Occurs when an authorized user (usually instance master) locks the TV for authorized use only.
  • _TvUnLock
    • Occurs when an authorized user (usually instance master) unlocks the TV for anyone to use.
  • _TvLoading
    • Occurs when the TV's loading state is enabled
    • It can happen at various points, so this event is mostly used for UIs to reflect the loading state of the TV.
  • _TvLoadingEnd
    • Occurs when the TV's loading state is disabled
    • It can happen at various points, so this event is mostly used for UIs to reflect the loading state of the TV.
  • _TvLoadingAbort
    • Occurs when the TV's loading state is interrupted
    • This is caused when the _Stop event is triggered while a video is loading.
  • _TvSeekChange
    • Occurs when the seek of the TV's current media is forcefully modified.
    • This event will set the variable OUT_SEEK (float) to the current seek time of the active media.
  • _TvSeekOffsetChange
    • Occurs when the seek offset value has been modified.
    • This event will set the variable OUT_SEEK (float) to the time offset in seconds, can be negative.
  • _TvAuthChange
    • Occurs when an auth plugin tells the TV that some change has happened and the plugins need to recheck authentication conditions.
  • _TvPlaybackSpeedChange
    • Occurs when the TV's playback speed has been modified.
    • This event will set the variable OUT_SPEED (float) to the speed multiplier (between 0.5f and 2f).
  • _Tv3DModeChange
    • Occurs when the TV's 3D mode has been changed.
    • This event will set the variable OUT_MODE (int) to the value of the TV3DMode enum for the active 3d mode.
  • _Tv3DWidthHalf
    • Occurs when the TV's 3D width mode is updated to half-width.
    • This is the default width mode and is most common with 3d videos on sites like youtube.
    • This means that each eye uses the full video resolution, thus half the quality due to scaling.
  • _Tv3DWidthFull
    • Occurs when the TV's 3D width mode is updated to full-width.
    • This means that each eye uses half the video resolution (orientation depends on the 3D mode), thus gets full pixel quality as no extra scaling is involved.
  • _TvColorSpaceCorrected
    • Occurs when the TV's gamma correction is enabled.
    • This is the default state.
  • _TvColorSpaceRaw
    • Occurs when the TV's gamma correction is disabled.

The following is the list of U# specific API methods that the TV may call for specific purposes:

  • _IsPreApprovedUrl(VRCUrl, VRCUrl)
    • This method returns a boolean of whether the given URLs should be viewed as implicitly allowed by the TV.
    • Returning true makes the requested urls allowed to be played, regardless of tv owner's specific permissions.
    • This is intended to handle the situation where a playlist (or other plugin) is auto-playing, but the TV is locked and some random user is master/owner of the TV.
    • It ensures that the TV doesn't undesirably lock up or halt when urls are effectively pre-approved.