krpano 1.19-pr16 (build 2018-04-04)

Videoplayer Plugin videoplayer.swf / videoplayer.js

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

Topics

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"
       onvideoready=""
       onvideoplay=""
       onvideopaused=""
       onvideocomplete=""
       onerror=""
       />

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"
         directionalsound="true"
         range="90.0"
         rangefalloff="1.0"
         outofrangevolume="0.0"
         onvideoready=""
         onvideoplay=""
         onvideopaused=""
         onvideocomplete=""
         onerror=""
         />

As panoramic image: 
<plugin name="video"
        url.flash="videoplayer.swf"
        url.html5="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 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, not for pano videos - because of this iOS bug!
  • 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.
  • iPhone notes (before iOS 10) - for getting sound for videos on the iPhone add an additional .m4a (HE-AAC) or .mp3 sound file to the list of available file formats.
    Example: videourl="video.mp4|video.webm|video-iphone-audio.m4a"
    iPhone with iOS 10 - with iOS 10 this is not necessary anymore, iOS 10 supports inline videos on the iPhone directly. No need for an additional sound file.
  • 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 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
use_as_videopano (old Pre-Release name) 		Boolean
Boolean		 false
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  (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.
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
iphoneworkarounds Boolean true
  • Enable workarounds for iPhone video support (for iOS versions before iOS 10).
  • Normally videos on the iPhone will be always played fullscreen in the iOS internal videoplayer, but this hack allows 'inline'-usage as part of the layout or as pano-video.
  • For sound support in this case, a separate .m4a (HE-AAC) or .mp3 sound file need to be provided in the videourl setting.
  • See also here: Mobile Limitations.
Attribute name  (HTML5 only)TypeDefault value
touchworkarounds 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.
  • See also here: Mobile Limitations.

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
onneedtouch 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 touchworkarounds setting is enabled, the videoplayer plugin will automatically wait for the next touch anywhere on the screen to start playing the video.
  • The onneedtouch 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 ongottouch event will be sent.
  • The needtouch state attribute will be set to true on this event.
Attribute nameTypeDefault value
ongottouch Action Event
  • This event will be called when the user had touched the screen to start playing the video.
  • The ongottouch event could be used to hide the play button or the user information that was previously shown on the onneedtouch event.
  • The needtouch state attribute will be set to false on this event.

Plugin State Attributes (read only)

Attribute nameTypeInitial value
isvideoready
ispaused
isseeking
iscomplete
isautopaused
needtouch 		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%).

Mobile Limitations

There are several system limitations on mobile Android and iOS devices:
  • No Autoplay / Autostart
    • A video can't start playing automatically!
    • The user would need to touch the video to start loading and playing it.
    • iOS 10 - with iOS 10 autoplay would be possible when using a video without sound or when enabling the muted setting.
    • Automatic workaround by krpano:
      • In such case the krpano videoplayer plugin will automatically take the first touch anywhere on the screen to start the video.
      • See also the touchworkarounds setting.
    • Recommended solution:
      • Use pausedonstart=true and a custom UI/UX for mobile usage to start playing the video (e.g. an initial play button or a kind of intro image/button).
  • iOS - No volume change
    • Changing the sound volume of a video is not possible on iOS devices.
    • The only way to change the volume is to use the device volume buttons.
  • iOS - Only one video / sound at one time
    • On iOS only one video or sound can be played at one time.
    • When an other video or sound will be started, the previous one will be automatically stopped by the system.
  • iPhone - No 'inline'-videos on the iPhone / Panoramic Videos on the iPhone
    • On the iPhone (update: before iOS 10) normally all videos will be automatically played fullscreen in an iOS-internal videoplayer! This was a system limitation by Apple!
    • That means playing videos 'inline' as normal element of the webpage or as panoramic video is normally not possible on the iPhone.
    • Automatic workaround by krpano:
      • The krpano videoplayer plugin uses a trick to bypass this limitation:
        Instead of playing the video, the video will kept paused and krpano constantly seeks through the video to simulate the playblack. All video events/interactions will be simulated.
      • That trick works in the iOS versions from 7 to 9, since iOS 10 inline video on the iPhone are directly supported, there this workaround is automatically disabled.
      • See also the iphoneworkarounds setting.
      • No Sound?
        • With this trick it's only possible to play the video itself, but not the sound of the video (because the video itself keeps paused)
        • To get a video-sound even with the iPhone limitations, the videoplayer plugin provides adding an additional .m4a (HE-AAC) or .mp3 sound file to the videourl setting. Then this sound file will be played automatically as sound for the video. The video itself will be synchronized to the playback of the sound file.
        • Note - when a sound is added, a touch is required to start playing the video and the sound - see at - No Autoplay / Autostart!

Known browser bugs / issues (state: 2017)

Here a list of all currently known browser bugs, including test cases and bug reports:
  • iOS and Mac Safari - WebGL CORS bugs
  • iOS and Mac Safari - 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
  • 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 not possible to show panoramic videos or video hotspots on these devices.

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: