Audio"

From Documentation
m ((via JWB))
 
(40 intermediate revisions by 7 users not shown)
Line 3: Line 3:
 
= Audio =
 
= Audio =
  
*Demonstration: [http://www.zkoss.org/zkdemo/userguide/#u5 Audio]
+
*Demonstration: [http://www.zkoss.org/zksandbox/userguide/#u5 Audio]
 
*Java API: <javadoc>org.zkoss.zul.Audio</javadoc>
 
*Java API: <javadoc>org.zkoss.zul.Audio</javadoc>
 
*JavaScript API: <javadoc directory="jsdoc">zul.med.Audio</javadoc>
 
*JavaScript API: <javadoc directory="jsdoc">zul.med.Audio</javadoc>
  
 
= Employment/Purpose =
 
= Employment/Purpose =
An <tt>audio</tt> component is used to play the audio at the browser. Like <tt>image</tt>, you could use the <tt>src</tt> property to specify an URL of an audio resource, or the <tt>setContent</tt> method to specify a dynamically generated audio.
+
An <code>audio</code> component is used to play the audio at the browser. Like <code>image</code>, you could use the <code>src</code> property to specify an URL of an audio resource, or the <code>setContent</code> method to specify a dynamically generated audio. Developers might be able to control the play of an audio by the <code>play</code>, <code>stop</code> and <code>pause</code> methods.
  
Depending on the browser and the <tt>audio</tt> plugin, developers might be able to control the play of an audio by the <tt>play</tt>, <tt>stop</tt> and <tt>pause</tt> methods. Currently, Internet Explorer with Media Player is capable of such controls.
+
= Example =
 +
[[Image:ZKComRef_Audio_Example.png]]
  
= Example =
+
<source lang="xml" >
 +
<audio src="music.wav" controls="true"></audio>
 +
</source>
 +
The audio supports controls property {{versionSince| 7.0.0}}
 +
 
 +
= Supports HTML5 =
 +
{{versionSince| 7.0.0}}
 +
 
 +
The audio component has now been enhanced to support HTML 5, it includes the properties like <code>autoplay</code>, <code>controls</code>, <code>loop</code>, <code>muted</code> and <code>preload</code>.
 +
 
 +
= Multiple Sources=
 +
{{versionSince| 7.0.0}}
 +
Most browsers do not support all the audio formats,so we could specify multiple source files in different formats for different browsers. For examples:
 +
<source lang="xml" >
 +
<audio src="music.wav, music.mp3, music.ogg" controls="true"></audio>
 +
</source>
 +
 
 +
= StateChangeEvent =
 +
{{versionSince| 9.6.0}}
  
 +
When you call <code>play(), stop(), pause()</code> or the audio is played to the end, an <code>StateChangeEvent</code> will be fired. You can check the current state by calling event.getState(). There are 4 states: <code>Audio.PLAY, Audio.STOP, Audio.PAUSE and Audio.END</code>.
  
 +
For example:
  
 +
If you want to do something after the audio starts to play, you can write codes as shown below (MVVM pattern).
  
 +
<source language="xml">
 +
  <audio onStateChange="@command('stateChange', event=event)" />
 +
</source>
 +
<source language="java">
 +
  @Command
 +
  public void stateChange(@BindingParam("event") StateChangeEvent event) {
 +
    if (event.getState() == Audio.PLAY) {
 +
      // do something...
 +
    }
 +
  }
 +
</source>
  
=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>
 
|-
 
|-
| None
+
| <center><code>onStateChange</code></center>
| None
+
| '''Event:''' <javadoc>org.zkoss.zk.ui.event.StateChangeEvent</javadoc>
 +
Notifies when invoking play(), stop(), pause() or the audio is played to the end.
 
|}
 
|}
 +
*Inherited Supported Events: [[ZK_Component_Reference/Base_Components/XulElement#Supported_Events | XulElement]]
  
 
=Supported Children=
 
=Supported Children=
  
  *ALL
+
  * [[ZK_Component_Reference/Multimedia_and_Miscellaneous/Track|Track]]
  
=Use cases=
+
=Use Cases=
  
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Description !! Example Location
 
! Version !! Description !! Example Location
 
|-
 
|-
| 5.0+
+
| &nbsp;
 
| &nbsp;
 
| &nbsp;
 
| &nbsp;
 
| &nbsp;
Line 43: Line 78:
  
 
=Version History=
 
=Version History=
 +
{{LastUpdated}}
  
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Date !! Content
 
! Version !! Date !! Content
 
|-
 
|-
| 5.x.x
+
| 7.0.0
| x/x/20xx
+
| August, 2013
| Initialization
+
| <javadoc>org.zkoss.zul.Audio</javadoc> now supports HTML 5
 +
|-
 +
| 9.5.0
 +
| September 2020
 +
| [https://tracker.zkoss.org/browse/ZK-4648 ZK-4648]: Audio supports to add tracks
 +
|-
 +
| 9.6.0
 +
| May 2021
 +
| [https://tracker.zkoss.org/browse/ZK-4779 ZK-4779]: audio supports to fire an event upon its playing state
 
|}
 
|}
  
 
{{ZKComponentReferencePageFooter}}
 
{{ZKComponentReferencePageFooter}}

Latest revision as of 08:44, 8 July 2022

Audio

Employment/Purpose

An audio component is used to play the audio at the browser. Like image, you could use the src property to specify an URL of an audio resource, or the setContent method to specify a dynamically generated audio. Developers might be able to control the play of an audio by the play, stop and pause methods.

Example

ZKComRef Audio Example.png

 <audio src="music.wav" controls="true"></audio>
The audio supports controls property Since  7.0.0

Supports HTML5

Since 7.0.0

The audio component has now been enhanced to support HTML 5, it includes the properties like autoplay, controls, loop, muted and preload.

Multiple Sources

Since 7.0.0 Most browsers do not support all the audio formats,so we could specify multiple source files in different formats for different browsers. For examples:

 <audio src="music.wav, music.mp3, music.ogg" controls="true"></audio>

StateChangeEvent

Since 9.6.0

When you call play(), stop(), pause() or the audio is played to the end, an StateChangeEvent will be fired. You can check the current state by calling event.getState(). There are 4 states: Audio.PLAY, Audio.STOP, Audio.PAUSE and Audio.END.

For example:

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

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

Supported Events

Name
Event Type
onStateChange
Event: StateChangeEvent

Notifies when invoking play(), stop(), pause() or the audio is played to the end.

Supported Children

* Track

Use Cases

Version Description Example Location
     

Version History

Last Update : 2022/07/08


Version Date Content
7.0.0 August, 2013 Audio now supports HTML 5
9.5.0 September 2020 ZK-4648: Audio supports to add tracks
9.6.0 May 2021 ZK-4779: audio supports to fire an event upon its playing state



Last Update : 2022/07/08

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