News Examples Documentation Download Buy Forum Contact

Videoplayer Plugin videoplayer.js / videoplayer.swf Version 1.20.2

  • 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.html5="videoplayer.js"
       url.flash="videoplayer.swf"
       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.html5="videoplayer.js"
         url.flash="videoplayer.swf"
         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"
         directionalsound="true"
         range="90.0"
         rangefalloff="1.0"
         outofrangevolume="0.0"
         onvideoready=""
         onvideoplay=""
         onvideopaused=""
         onvideocomplete=""
         onerror=""
         />

As panoramic image:
<plugin name="video"
        url.html5="videoplayer.js"
        url.flash="videoplayer.swf"
        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 Flashplayer and the HTML5 browsers are having a different level of video format / codecs support. To make the video playable in all browsers on all systems, it is necessary to provide the video in several formats.
  • Supported video formats are:
    • MPEG4 / H264 (.mp4, .m4v, .mov) - Flashplayer / Firefox (Windows 7+) / Safari / Chrome / IE / iOS / Android
    • WebM (.webm) - Firefox / Chrome
    • Ogg Theora (.ogg, .ogv) - Firefox / Chrome
    • Flash Video (.flv, .f4v) - Flashplayer only
    • RTMP Video Streaming (rtmp:// urls) - Flashplayer only
    • 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.
  • Transparent videos with alpha-channel are possible (Flash and VP6 codec only).
  • 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 name  (HTML5 only)TypeDefault 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 name (HTML5 only)TypeDefault 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 - on some devices (e.g. on iOS) the video will be always paused on start!
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.
  • When enabled (set to true) this allows automatic playing the video on iOS 10 (without the need for a touch).
Attribute name  (HTML5 only)TypeDefault 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 name  (Flash only)TypeDefault value
directionalsound Boolean false
  • Use directional 3d-sound when the video is played as hotspot.
  • The panning (left/right channel volume) will be automatically adjusted depending on the hotspot position and the viewing direction.
Attribute name  (Flash only)TypeDefault value
range
rangefalloff
outofrangevolume
Number
Number
Number
90.0
1.0
0.0
  • Range of the directional sound, distance from the viewing direction to the sound position, the sound volume will fall off within this distance from volume to outofrangevolume.
  • The rangefalloff factor, defines the volume falloff curve (e.g. ~0.01 to ~10.0), default=1.0.
  • The outofrangevolume setting defines the volume outside the range.
Attribute name  (HTML5 only)TypeDefault 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 name  (HTML5 only)TypeDefault 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 name  (HTML5 only)TypeDefault value
html5controls Boolean false
Attribute name  (HTML5 only)TypeDefault value
html5preload String "auto"
Attribute name  (HTML5 only)TypeDefault value
playsinline Boolean true
  • Play the video inline in krpano on mobile devices (iPhone, iPad, Android).
  • When disabled, then the browser could eventually play the video in its own internal videoplayer.
Attribute name  (HTML5 only)TypeDefault value
userinteractionworkarounds Boolean true
  • Enable autoplay by touch workarounds for mobile and tablet devices.
  • Normally videos on mobile or tablet devices can't start playing without user interaction, but with that workaround, the krpano videoplayer plugin will automatically take the first touch anywhere on the screen to start the video.

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.

Flash notes - the number of loaded bytes don't correlate directly with the number of loaded seconds when the video is encoded with a variable bitrate.

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!
    • The poster image will be used only in HTML5. In Flash this setting will be ignored.
  • 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: