News Examples Documentation Download Buy Forum Contact

Documentation

Plugins

XML Extensions

Tools


Third Party Software
for krpano

Videoplayer Plugin videoplayer.js Version 1.21

  • The Videoplayer plugin can be used to play videos inside krpano...
    • as normal flat video via the <layer> element,
    • or as flat or 3D-distorted hotspot via the <hotspot> element,
    • or as pano when referring to the video via the <image> element.

Syntax

As flat layer element on the screen:
<layer name="video"
       url="videoplayer.js"
       videourl="video.m4v|video.webm"
       posterurl="videoposter.jpg"
       align="center" x="0" y="0"
       pausedonstart="false"
       loop="false"
       volume="1.0"
       onvideoready=""
       onvideoplay=""
       onvideopaused=""
       onvideocomplete=""
       onerror=""
       />

As 3D-distorted hotspot:
<hotspot name="video"
         url="videoplayer.js"
         videourl="video.m4v|video.webm"
         posterurl="videoposter.jpg"
         ath="0.0" atv="0.0"
         distorted="true"
         scale="1.0" 
         rx="0.0" 
         ry="0.0" 
         rz="0.0" 
         pausedonstart="false"
         loop="false"
         volume="1.0"
         onvideoready=""
         onvideoplay=""
         onvideopaused=""
         onvideocomplete=""
         onerror=""
         />

As panoramic image:
<plugin name="video"
        url="videoplayer.js"
        videourl="video.m4v|video.webm"
        posterurl="videoposter.jpg"
        panovideo="true"
        pausedonstart="false"
        loop="false"
        volume="1.0"
        onvideoready=""
        onvideoplay=""
        onvideopaused=""
        onvideocomplete=""
        onerror=""
        />

<image hfov="360" vfov="180">
   <sphere url="plugin:video" />
</image>

Plugin Attributes

Attribute nameTypeDefault value
videourl String
  • The url of the video file.
  • The browsers can have a different level of video format / codecs support. To make the video playable in all browsers on all systems, it can be necessary to provide the video in several formats.
  • Supported video formats are:
    • MPEG4 / H264 (.mp4, .m4v, .mov) - Firefox (Windows 7+) / Safari / Chrome / IE / iOS / Android
    • WebM (.webm) - Firefox / Chrome
    • Ogg Theora (.ogg, .ogv) - Firefox / Chrome
    • HTTP Live Streaming (.m3u, .m3u8) - iOS, Mac Safari only - and only for <layer> usage
  • To provide several video formats and let the plugin automatically choose the appropriate one, set the paths to all video files at once and separate them by a pipe | character.
  • When several formats of the given videos are supported, the plugin will select the videos in order from left to right. For example when MP4 and WebM are supported and MP4 should be used preferably, then write videourl="video.mp4|video.webm".
  • A custom format preference can be defined by the preferredformat setting.
  • By providing at least a baseline-MP4 and a WebM video, it should be possible to cover almost all today systems.
  • Consider also using the device checks for attributes to specify different video files for different devices.
  • Once the video is loaded, the value of the videourl attribute will be replaced by the url of the video file that was loaded.
  • HTML5 mobile notes - the MP4 format itself is supported by the most mobile devices, but the MP4-profile-level support can be depending on the device and its OS version.
Attribute nameTypeDefault value
posterurl String
  • This is the url to an image (typical a screenshot of the first video frame) that should be shown until the video is loaded and ready to play.
  • Adding the poster image is highly recommended!
  • The poster image needs to have the same pixel-size as the video itself!
Attribute nameTypeDefault value
panovideo Boolean false
  • Should the video be used as panoramic video?
  • This settings prepares the video for a 'later' (e.g. in an other scene) usage as pano video.
  • Without that setting the video would become visible as normal 2d layer/plugin element until the video will be used as pano.
Attribute nameTypeDefault value
pausedonstart Boolean false
  • Should the video be paused at the start.
  • Note - in many newer browser versions automatic playback is not allowed by default!
    An user-interaction like a click or touch might be requiered to start playing. krpano will automatically wait for the first click/touch anywhere on the screen to start playing the video when this is the case.
  • Note - by muting the video, automatic playback might be possible when not allowed otherwise.
Attribute nameTypeDefault value
loop Boolean false
  • Should the video loop or stop at the playback end.
Attribute nameTypeDefault value
volume Number 1.0
  • Volume of video sound (0.0 - 1.0)
  • Note - on iOS controlling the volume of the video is not possible!
Attribute name  (HTML5 only)TypeDefault value
muted Boolean false
  • Mute the video.
  • Note - When muting is enabled (set to true) this the automatic playback (without the need for a click or touch) might be possible (depending on the browser and device).
Attribute nameTypeDefault value
playbackrate Number 1.0
  • Set the video playback-rate/speed (HTML5-only).
  • Examples:
    • 1.0 is normal speed
    • 0.5 is half speed (slower)
    • 2.0 is double speed (faster)
  • Negative values for inverse playback are currently not supported or working probably in any browser.
  • HTML5 documenations:
Attribute nameTypeDefault value
preferredformat String
  • Set the preferred video file format to use when several formats are available.
  • When not set, the available video formats will be selected from left to right.
  • This could be used to prefer a specfic format for a specfic browser. For example - to prefer the usage of webm for Firefox set:
    preferredformat.firefox="webm"
Attribute nameTypeDefault value
autopause
autoresume
Boolean
Boolean
true
false
  • autopause - Automatically pause the video when the browser tab / window gets hidden.
  • autoresume - Automatically resume the video when it was paused before by hiding the browser tab / window.
Attribute nameTypeDefault value
html5controls Boolean false
Attribute nameTypeDefault value
html5preload String "auto"
Attribute nameTypeDefault value
playsinline Boolean true
  • Play the video 'inline' in krpano on mobile devices (iPhone, iPad, Android).
  • When disabled, then the browser might eventually play the video in its own internal videoplayer and inlined/embedded in the webpage/pano.
Attribute nameTypeDefault value
userinteractionworkarounds Boolean true
  • Enable automatic playback workarounds.
  • In many newer browser versions automatic playback is not allowed by default! An user-interaction like a click or touch might be requiered to start playing. When enabled krpano will automatically wait for the first click/touch anywhere on the screen to start playing the video when this is the case.

Plugin Events

Attribute nameTypeDefault value
onvideoready Action Event
  • This event will be called when the video is ready for playing.
  • At this time the video frame size and the playback length (totaltime) is known.
  • When no plugin size (width, height) was set in the xml, then the plugin will resize itself to pixel-size of the video now.
Attribute nameTypeDefault value
onvideoplay Action Event
  • This event will be called when the video will start playing.
Attribute nameTypeDefault value
onvideopaused Action Event
  • This event will be called when the video will be paused (a pause at the startup through pausedonstart=true will be ignored).
  • HTML5 notes - in HTML5 this event will be also called when the video has ended, just before the onvideocomplete event.
Attribute nameTypeDefault value
onvideocomplete Action Event
  • This event will be called when the video was played completely.
  • This happens only when loop is set to "false".
Attribute nameTypeDefault value
onerror Action Event
  • This event will be called when there was an error during loading or playing.
  • The error message itself will be set in the videoerror attribute.
  • When this event will be set, no default error message will appear.
Attribute nameTypeDefault value
onneeduserinteraction Action Event
  • This event will be called when a touch from the user will be required to play the video.
  • This can be a necessity from several mobile and tablet browsers.
  • When the userinteractionworkarounds setting is enabled, the videoplayer plugin will automatically wait for the next touch anywhere on the screen to start playing the video.
  • The onneeduserinteraction event could be used to show a play button or to inform the user to touch the screen for playing the video.
  • Once the user had touched the screen the ongotuserinteraction event will be sent.
  • The needuserinteraction state attribute will be set to true on this event.
Attribute nameTypeDefault value
ongotuserinteraction Action Event
  • This event will be called when the user had touched the screen to start playing the video.
  • The ongotuserinteraction event could be used to hide the play button or the user information that was previously shown on the onneeduserinteraction event.
  • The needuserinteraction state attribute will be set to false on this event.

Plugin State Attributes (read only)

Attribute nameTypeInitial value
isvideoready
ispaused
isseeking
iscomplete
isautopaused
needuserinteraction
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean
false
false
false
false
false
false
Variables to check dynamically the playback state of the video:
Attribute nameTypeInitial value
videoerror String
  • The last error message.
  • Will be only set when using the onerror event for a custom error handling.
Attribute nameTypeInitial value
time
totaltime
Number
Number
0.0
0.0
Playback time information:
  • time - the current video playback position in seconds.
  • totaltime - the length / totaltime of the video in seconds.
Attribute nameTypeInitial value
videowidth
videoheight
int
int
0
0
  • Pixel size of the source video frame.
  • Available after the onvideoready event.
Attribute nameTypeInitial value
loadedbytes
totalbytes
int
int
0
0
Loading information:
  • loadedbytes - the currently loaded bytes of the video file.
  • totalbytes - the total bytes of the video file.

HTML5 notes - in HTML5 it's not possible to determine the real byte sizes. Therefore in HTML5 these values represent the currently buffered data in seconds multiplied by 1048576 (=1024*1024, =1 MB).

Plugin Actions

playvideo(url, posterurl, pausedonstart, starttime)
  • Open a new video url and start playing it.
  • A currently playing video will be stopped and closed.
Parameters:
  • url
    • The url of the video file.
    • The same as the videourl setting.
  • posterurl (optionally)
    • The url of the poster image.
    • The same as the posterurl setting.
    • Adding the poster image is highly recommended!
  • pausedonstart (optionally)
    • Should the video be paused at the start.
    • The same as the pausedonstart setting.
  • starttime (optionally)
    • Set the start time of the video.
    • This works by directly seeking to the given time once the video is ready.
    • Only supported in HTML5.

play()
  • Play or resume a paused video.

pause()
  • Pause the video.
  • The video can be resumed by calling the play() action.

togglepause()
  • Either pause or resume the video depending on the current playback state.

stop()
  • Stop the video ⇒ move to the first frame and pause there.
  • The video can be resumed by calling the play() action.

seek(time)
  • Seek to the given time / playback position.
  • Depending on the video encoding (codec and keyframe-interval) the video will seek only 'near' to the given position.
Parameters:
  • time
    • The intended playback position.
    • Either in seconds.
    • Or as percent value (0% - 100%).

Open Source Plugin

If you are a Javascript developer and want to work directly with the HTML5 video object, e.g. for experimenting with HTML5 video streaming technologies like DASH or HLS, here is an open-source version of the krpano HTML5 videoplayer plugin.

The plugin source itself is reduced and provides only the basic interfaces (no state management, no iPhone support, no poster support), but it shows how the krpano Plugin Interface and the krpano video internals are working and how to use them.
Files: