Video"

From Documentation
 
(97 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 +
{{ZKComponentReferencePageHeader}}
 +
 
= Video =
 
= Video =
  
Line 4: Line 6:
 
*JavaScript API: <javadoc directory="jsdoc">zkmax.med.Video</javadoc>
 
*JavaScript API: <javadoc directory="jsdoc">zkmax.med.Video</javadoc>
  
[ ZK EE ]
+
{{ZK EE}}
[ since 8.5.2 ]
+
{{versionSince| 8.6.0}}
  
 
= Employment/Purpose =
 
= Employment/Purpose =
An <tt>video</tt> component is used to play the video at the browser. Like <tt>audio</tt>, you could use the <tt>src</tt> property to specify an URL of an video resource, or the <tt>setContent</tt> method to specify a dynamically generated video. Developers might be able to control the play of an video by the <tt>play</tt>, <tt>stop</tt> and <tt>pause</tt> methods.
+
A <code>Video</code> component is used to play the video in the browser. Like <code>audio</code>, you can either use the <code>src</code> property to specify an URL of the video resource, or use the <code>setContent</code> method to specify a dynamically generated video. Users can control the video by <code>play</code>, <code>stop</code> and <code>pause</code>.
  
 
= Example =
 
= Example =
Line 18: Line 20:
  
 
= Supports HTML5 =
 
= Supports HTML5 =
The video component support HTML 5, like <video>, it includes the properties like <tt>autoplay</tt>, <tt>controls</tt>, <tt>loop</tt>, <tt>muted</tt> and <tt>preload</tt>.
+
The Video component is based on HTML 5's <video> tag, and supports the following properties: <code>src</code>, <code>autoplay</code>, <code>controls</code>, <code>loop</code>, <code>playbackRate</code>, <code>dimBackground</code>, <code>preload</code>, <code>clipToFit</code>, <code>poster</code>, <code>playsinline</code> and <code>crossorigin</code>.
 +
 
 +
== Supported Formats ==
 +
[https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats#File_formats mp4, WebM, ogg]
 +
 
 +
= autoplay =
 +
Just set autoplay to <code>true</code> doesn't always work because '''autoplay policy is different among browsers'''. Please refer to  [https://developers.google.com/web/updates/2017/09/autoplay-policy-changes autoplay-policy-changes] and [https://webkit.org/blog/7734/auto-play-policy-changes-for-macos/ auto-play-policy-changes-for-macos].
  
 
= Multiple Sources =
 
= Multiple Sources =
Most browsers do not support all the video formats,so we could specify multiple source files in different formats for different browsers. For examples:  
+
Most browsers do not support all the video formats, so you can specify multiple source files in different formats for different browsers. If the first format is not supported by the browser, it will fallback to the 2nd format. For example:  
 
<source lang="xml" >
 
<source lang="xml" >
 
  <video src="zk.mp4, zk.webm, zk.ogg" />
 
  <video src="zk.mp4, zk.webm, zk.ogg" />
Line 27: Line 35:
  
 
= enableFullScreen =
 
= enableFullScreen =
Because security issue, fullScreen API can only be initiated by a user gesture, so the video component only can provide a client-side method <tt>enableFullScreen()</tt> to use full screen mode.
+
For security reasons, fullScreen API can only be initiated by an user gesture. Therefore the Video component only provides a client-side method <code>enableFullScreen()</code> to enable the full screen mode.
  
 
<source lang="xml" >
 
<source lang="xml" >
<video id="player" src="zk.mp4" />
+
<video id="player" src="zk.mp4" controls="true"/>
<button xmlns:w="client" w:onClick="zk.$('$player').enableFullScreen()" />
+
<button xmlns:w="client" w:onClick="zk.$('$player').enableFullScreen()" />
 
</source>
 
</source>
  
 
= dimBackground =
 
= dimBackground =
The video component provides theater mode, If dimBackground="true", the whole page will be covered by translucent black except the Video.
+
The Video component provides a theater mode, If dimBackground="true", the whole page will be covered by translucent black by default except the Video.
  
When theater mode is enabled, user can click anywhere on the page except the Video to disable theater mode.
+
When the theater mode is enabled, user can click anywhere on the page outside the Video to disable theater mode and return to the normal view.
  
 
[[Image:Player-turnOffLight.png]]
 
[[Image:Player-turnOffLight.png]]
 
<source lang="xml" >
 
<source lang="xml" >
 
  <video src="zk.mp4" dimBackground="true" />
 
  <video src="zk.mp4" dimBackground="true" />
 +
</source>
 +
 +
By default, css of dimBackground has two properties as shown in the following css code.
 +
 +
You can also customize the background in your preference by simply overriding .z-video-dim-background in css.
 +
 +
<source lang="css" >
 +
<style>
 +
.z-video-dim-background {
 +
    background: black;
 +
    opacity: 0.8;
 +
}
 +
</style>
 
</source>
 
</source>
  
 
= playbackRate =
 
= playbackRate =
 +
The Video component provides setPlaybackRate(double) to control the video playing speed. The valid value depends on the displayed browser.
 +
 +
Default: 1.0
 +
 +
<source lang="xml" >
 +
<video src="zk.mp4" playbackRate="0.5" />
 +
</source>
  
 
= currentTime =
 
= currentTime =
The video provides <tt>setCurrentTime(double)</tt> to decide which part of video to play, the value is seconds.
+
The Video component provides <code>setCurrentTime(double)</code> to jump to the specified time-point (in seconds) of the playback video.
  
 
<source lang="xml" >
 
<source lang="xml" >
Line 54: Line 82:
  
 
= playing =
 
= playing =
The video provieds <tt>setPlaying(boolean)</tt> to play or pause the video.
+
The Video component provides <code>setPlaying(boolean)</code> to play or pause the video.
  
playing="false" is same as invoking <tt>play()</tt>, playing="true" is same as invoking <tt>pause()</tt>.
+
playing="true" is same as invoking <code>play()</code>; playing="false" is same as invoking <code>pause()</code>.
  
 
<source lang="xml" >
 
<source lang="xml" >
  <video src="zk.mp4" playing="true" />
+
  <video src="zk.mp4" playing="false" />
 
</source>
 
</source>
  
 
= volume =
 
= volume =
The video component provides <tt>setVolume(double)</tt> to change the volume, the valid value is between 0.0 to 1.0.
+
The Video component provides <code>setVolume(double)</code> to change the volume. The value should range between 0.0 and 1.0.
 +
 
 +
Default: 1.0
  
 
<source lang="xml" >
 
<source lang="xml" >
Line 70: Line 100:
  
 
= muted =
 
= muted =
The video component provides <tt>setMuted(boolean)</tt> to mute the video.
+
The Video component provides <code>setMuted(boolean)</code> to mute the video.
 +
 
 +
Default: false
  
 
<source lang="xml" >
 
<source lang="xml" >
 
  <video src="zk.mp4" muted="true" />
 
  <video src="zk.mp4" muted="true" />
 
</source>
 
</source>
 +
 +
= clipToFit =
 +
 +
The Video component provides setClipToFit(boolean) to clip the video when the source size doesn't fit the size specified in the Video tag.
 +
 +
For example:
 +
 +
The source image used in the sample below is 450 * 320. When you set width="300px", height="320px", by default, blank space will be inserted above and below the video to preserve the aspect ratio (left image); when you set clipToFit="true", it will cut off the sides and fill up the space (right image).
 +
 +
[[file:ClipToFit(false).png]] [[file:ClipToFit(true).png]]
 +
<source lang="xml">
 +
  <video width="300px" height="320px" src="zk.mp4" style="border: 1px solid red;" />
 +
  <video width="300px" height="320px" src="zk.mp4" style="border: 1px solid red;" clipToFit="true" />
 +
</source>
 +
 +
= Display Subtitles=
 +
To display subtitles or captions on a video, please see [[ZK_Component_Reference/Multimedia_and_Miscellaneous/Track | Track]].
  
 
= StateChangeEvent =
 
= StateChangeEvent =
When calling <tt>play(), stop() or pause()</tt>, will trigger StateChangeEvent, you can check current state by calling event.getState(), Video has three states, you can access them by using <tt>Video.PLAY, Video.STOP and Video.PAUSE</tt>.
+
When you call <code>play(), stop(), pause()</code> StateChangeEvent will be triggered. You can check the current state by calling event.getState(). Video has three states, and you can access them by using <code>Video.PLAY, Video.STOP and Video.PAUSE</code>.
  
 
For example:  
 
For example:  
  
If you want to do something after start playing video, you can write codes as shown below (MVVM style).
+
If you want to do something after the video starts to play, you can write codes as shown below (MVVM style).
  
<source language="xml">
+
<source lang="xml">
 
   <video onStateChange="@command('stateChange', event=event)" />
 
   <video onStateChange="@command('stateChange', event=event)" />
 
</source>
 
</source>
<source language="java">
+
<source lang="java">
 
   @Command
 
   @Command
 
   public void stateChange(@BindingParam("event") StateChangeEvent event) {
 
   public void stateChange(@BindingParam("event") StateChangeEvent event) {
Line 94: Line 143:
 
   }
 
   }
 
</source>
 
</source>
 +
 +
Video component also provides <code>isPlaying(), isPaused() and isStopped()</code> methods to check the video state.
 +
 +
{{versionSince| 9.6.0}}
 +
 +
Since ZK 9.6.0, a new state - <code>Video.END</code> is added. When the video is played to the end, the StateChangeEvent will be triggered.
  
 
= Supported Events =
 
= Supported Events =
  
{| border="1" | width="100%"
+
{| class='wikitable' | width="100%"
 
! <center>Name</center>
 
! <center>Name</center>
 
! <center>Event Type</center>
 
! <center>Event Type</center>
 
|-
 
|-
| <center><tt>onStateChange</tt></center>
+
| <center><code>onStateChange</code></center>
 
| '''Event:''' <javadoc>org.zkoss.zkmax.zul.event.StateChangeEvent</javadoc>
 
| '''Event:''' <javadoc>org.zkoss.zkmax.zul.event.StateChangeEvent</javadoc>
 
Notifies when invoking play(), stop() or pause().
 
Notifies when invoking play(), stop() or pause().
Line 108: Line 163:
  
 
=Supported Children=
 
=Supported Children=
 +
* [[ZK_Component_Reference/Multimedia_and_Miscellaneous/Track|Track]]
 +
 +
=Version History=
 +
{{LastUpdated}}
 +
 +
{| class='wikitable' | width="100%"
 +
! Version !! Date !! Content
 +
|-
 +
| 8.6.0
 +
| May 2018
 +
| [https://tracker.zkoss.org/browse/ZK-3845 ZK-3845]: Provide a video component
 +
|-
 +
| 9.5.0
 +
| September 2020
 +
| [https://tracker.zkoss.org/browse/ZK-4649 ZK-4649]: Video supports to add tracks
 +
|}
  
*NONE
+
{{ZKComponentReferencePageFooter}}

Latest revision as of 06:31, 20 September 2022

Video

  • Available for ZK:
  • http://www.zkoss.org/product/zkhttp://www.zkoss.org/whyzk/zkeeVersion ee.png

Since 8.6.0

Employment/Purpose

A Video component is used to play the video in the browser. Like audio, you can either use the src property to specify an URL of the video resource, or use the setContent method to specify a dynamically generated video. Users can control the video by play, stop and pause.

Example

Player-Sample.png

 <video src="zk.mp4" controls="true" autoplay="true" loop="true" />

Supports HTML5

The Video component is based on HTML 5's <video> tag, and supports the following properties: src, autoplay, controls, loop, playbackRate, dimBackground, preload, clipToFit, poster, playsinline and crossorigin.

Supported Formats

mp4, WebM, ogg

autoplay

Just set autoplay to true doesn't always work because autoplay policy is different among browsers. Please refer to autoplay-policy-changes and auto-play-policy-changes-for-macos.

Multiple Sources

Most browsers do not support all the video formats, so you can specify multiple source files in different formats for different browsers. If the first format is not supported by the browser, it will fallback to the 2nd format. For example:

 <video src="zk.mp4, zk.webm, zk.ogg" />

enableFullScreen

For security reasons, fullScreen API can only be initiated by an user gesture. Therefore the Video component only provides a client-side method enableFullScreen() to enable the full screen mode.

<video id="player" src="zk.mp4" controls="true"/>
<button xmlns:w="client" w:onClick="zk.$('$player').enableFullScreen()" />

dimBackground

The Video component provides a theater mode, If dimBackground="true", the whole page will be covered by translucent black by default except the Video.

When the theater mode is enabled, user can click anywhere on the page outside the Video to disable theater mode and return to the normal view.

Player-turnOffLight.png

 <video src="zk.mp4" dimBackground="true" />

By default, css of dimBackground has two properties as shown in the following css code.

You can also customize the background in your preference by simply overriding .z-video-dim-background in css.

<style>
.z-video-dim-background {
    background: black;
    opacity: 0.8;
}
</style>

playbackRate

The Video component provides setPlaybackRate(double) to control the video playing speed. The valid value depends on the displayed browser.

Default: 1.0

 <video src="zk.mp4" playbackRate="0.5" />

currentTime

The Video component provides setCurrentTime(double) to jump to the specified time-point (in seconds) of the playback video.

 <video src="zk.mp4" currentTime="60" />

playing

The Video component provides setPlaying(boolean) to play or pause the video.

playing="true" is same as invoking play(); playing="false" is same as invoking pause().

 <video src="zk.mp4" playing="false" />

volume

The Video component provides setVolume(double) to change the volume. The value should range between 0.0 and 1.0.

Default: 1.0

 <video src="zk.mp4" volume="0.5" />

muted

The Video component provides setMuted(boolean) to mute the video.

Default: false

 <video src="zk.mp4" muted="true" />

clipToFit

The Video component provides setClipToFit(boolean) to clip the video when the source size doesn't fit the size specified in the Video tag.

For example:

The source image used in the sample below is 450 * 320. When you set width="300px", height="320px", by default, blank space will be inserted above and below the video to preserve the aspect ratio (left image); when you set clipToFit="true", it will cut off the sides and fill up the space (right image).

ClipToFit(false).png ClipToFit(true).png

  <video width="300px" height="320px" src="zk.mp4" style="border: 1px solid red;" />
  <video width="300px" height="320px" src="zk.mp4" style="border: 1px solid red;" clipToFit="true" />

Display Subtitles

To display subtitles or captions on a video, please see Track.

StateChangeEvent

When you call play(), stop(), pause() StateChangeEvent will be triggered. You can check the current state by calling event.getState(). Video has three states, and you can access them by using Video.PLAY, Video.STOP and Video.PAUSE.

For example:

If you want to do something after the video starts to play, you can write codes as shown below (MVVM style).

  <video onStateChange="@command('stateChange', event=event)" />
  @Command
  public void stateChange(@BindingParam("event") StateChangeEvent event) {
    if (event.getState() == Video.PLAY) {
      // do something...
    }
  }

Video component also provides isPlaying(), isPaused() and isStopped() methods to check the video state.

Since 9.6.0

Since ZK 9.6.0, a new state - Video.END is added. When the video is played to the end, the StateChangeEvent will be triggered.

Supported Events

Name
Event Type
onStateChange
Event: StateChangeEvent

Notifies when invoking play(), stop() or pause().

Supported Children

* Track

Version History

Last Update : 2022/09/20


Version Date Content
8.6.0 May 2018 ZK-3845: Provide a video component
9.5.0 September 2020 ZK-4649: Video supports to add tracks



Last Update : 2022/09/20

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.