News • Examples • Documentation • Download • Buy • Forum • Contact
NOTE: This page is from an older version, switch to the latest version here.

Videoplayer Plugin videoplayer.swf / videoplayer.js Version 1.18.1

  • 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.flash="videoplayer.swf"
       url.html5="videoplayer.js"
       videourl="video.m4v|video.webm"
       posterurl="videoposter.jpg"
       align="center" x="0" y="0"
       pausedonstart="false"
       loop="false"
       volume="1.0"
       playbackrate="1.0"
       preferredformat=""
       buffertime="0.1"
       ignoremetadata="false"
       onvideoready=""
       onvideoplay=""
       onvideopaused=""
       onvideocomplete=""
       />

As 3d-distorted hotspot: 
<hotspot name="video"
         url.flash="videoplayer.swf"
         url.html5="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"
         playbackrate="1.0"
         directionalsound="true"
         range="90.0"
         rangefalloff="1.0"
         outofrangevolume="0.0"
         preferredformat=""
         buffertime="0.1"
         ignoremetadata="false"
         onvideoready=""
         onvideoplay=""
         onvideopaused=""
         onvideocomplete=""
         />

As panoramic image: 
<plugin name="video"
        url.flash="videoplayer.swf"
        url.html5="videoplayer.js"
        videourl="video.m4v|video.webm"
        posterurl="videoposter.jpg"
        pausedonstart="false"
        loop="false"
        volume="1.0"
        playbackrate="1.0"
        preferredformat=""
        buffertime="0.1"
        ignoremetadata="false"
        onvideoready=""
        onvideoplay=""
        onvideopaused=""
        onvideocomplete=""
        />

<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
  • 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.
  • Flash notes - when not embedding the krpano Flash viewer with the default krpano embedding script, then the video url path need to be either absolute or relative to the root swf file!
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 or has started to play.
  • For videos on mobile devices using this setting is highly recommended!
  • The image should have the same pixel-size / resolution as the video itself. Some devices (e.g. some iOS versions) need to use the size of this image as size for the video.
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
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  (Flash only)TypeDefault value
buffertime Number 0.1
  • The time in seconds that the video should be preloaded / buffered before starting to play, default=0.1 (=Flashplayer default).
Attribute name  (Flash only)TypeDefault value
ignoremetadata Boolean false
  • The videoplayer uses the size information from the meta-data that was stored in the video file to determine the size/resolution of the video by default. But there are some videos and video-converter tools that will store wrong size information in the meta-data and this can cause distorted or wrong sized videos. With that setting, this meta-data information can be ignored / skipped.

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".

Plugin State Attributes (read only)

Attribute nameTypeDefault value
isvideoready
ispaused
isseeking
iswaiting
iscomplete 		Boolean
Boolean
Boolean
Boolean
Boolean		 false
false
false
false
false
Variables to check dynamically the playback state of the video:
  • isvideoready - check if the video is ready for playing.
  • ispaused - check if the video is currently paused.
  • isseeking - check if the video is currently seeking.
  • iswaiting - check if the video is currently waiting for new data (some browsers will pause the video during this time, so this could be used to differ between an intended pause from the user and a forced pause from the browser).
  • iscomplete - check if the video has ended.
Attribute nameTypeDefault 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 nameTypeDefault value
videowidth
videoheight 		int
int		 0
0
  • Pixel size of the source video frame.
  • Available after the onvideoready event.
Attribute nameTypeDefault 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.
    • 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. In Flash this setting will be ignored.

closevideo()
  • Stop the video and close the video stream.
  • Resuming or playing again will be not possible.

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

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

play()
  • Resume a paused or stopped video.

togglepause()
  • Either pause or resume the video.

seek(time)
  • Seek to the given time / playback position.
Parameters:
  • time
    • The intended playback position.
    • Either in seconds.
    • Or as percent value (0% - 100%).

HTML5 Notes

iOS Limitations

There are several system limitations on iOS devices (iPhone and iPad):
  • No Autoplay / Autostart!
    A video can't start to play automatically on iOS!
    The user would need to touch / click the video to start loading and playing it.
    When the video is intended to play, but will be paused by iOS, then the plugin automatically takes the first touch anywhere on the screen on start playing the video.
  • No Video preview and no size / dimension information at startup (before iOS 8.0)
    The video start to load first after a click or touch on the video element, and without loading there are is notthing to show and no information about the pixel size of the video. And without known size it's not possible to show/place the video on the screen or in the pano.
    There three solutions for that problem:
    1. Use an posterurl image.
      The size of this image will be also used for the size of the video.
      This is the recommended solution!
    2. Define the size (width / height) manually in the xml.
      The video image itself will be black.
    3. Without poster image and without manually size the default size of 320x240 pixels will be used.
  • No volume change!
    Changing the volume of a video is not allowed on iOS devices.
  • Only Fullscreen-Playing Video on the iPhone
    On the iPhone the Video will only play in Fullscreen. When starting to play the video will switch to Fullscreen and when the video will be stopped it will switch back to normal view.
  • No Multiple Simultaneous Audio or Video Streams
    Currently, all iOS devices are limited to playback only one single audio or video stream at one time. Playing more than one video - side by side, partly overlapping, or completely overlaid - is not currently supported on iOS devices.
  • More information:
    Apple Documentation about iOS Specific Considerations

Known browser bugs / issues (state: September 2014)

Here a list of all currently known browser bugs, including test cases and bug reports:
  • iOS 8 and Mac Safari 8 - WebGL CORS bugs
  • iOS 8 and Mac Safari 8 - Bad video to WebGL performance
    • The performance of the video image to WebGL transfer is way too slow.
    • This kind of performance only depends on the pixel-size of a video frame, the bitrate or the video filesize don't matter here - e.g. a 1024x512 video will be smoother and faster than a 2048x1024 video because fewer pixels need to be transfered between the CPU and the GPU.
    • As workaround for the moment, videos with smaller pixel sizes should be used for iOS until Apple would fix / improve this.
    • Testcase: http://krpano.com/ios/bugs/ios8-webgl-video-performance
    • Bugreport: https://bugs.webkit.org/show_bug.cgi?id=135387
  • iOS 8 - automatic video fullscreen playback on the iPhone
  • Chrome (Desktop) - Flickering when using hardware accelerated video decoding
    • On some systems there is sometimes an annoying flickering during the panormaic video rendering in the Chrome Desktop browser.
    • As workaround the hardware accelerated video decoding can be deactivated in Chrome by entering this url in Chrome: 
      chrome://flags/#disable-accelerated-video-decode
      and activating the given setting there and restarting Chrome.
  • Windows Phone - No WebGL Video Texture support
    • The IE11 on Windows Phone 8.x devices supports WebGL but no videos as textures. Without that feature it's currently not possible to show panoramic videos on these devices.

Examples (included in the download package)