WAudio
WAudio is a component for creating audio output controls.
- Why use WAudio
- Creating WAudio
- Accessibility
- Usability
- Appearance
- Hiding
- HTML output
- Audio streams
- Related Components
- Further information
The sole use-case for WAudio is to present the user with an audio player. It is not guaranteed that the user will be able to play any audio source provided by the audio player or that the user agent will even provide a means to play an audio file.
WAudio should never be used as the sole mechanism to deliver a piece of content to the user. Any audio which contains meaningful content must be accompanied by a text transcript or captioning mechanism which is able to be consumed by any user who cannot easily consume the audio content: see below.
WAudio has four constructors. The default constructor create a WAudio component with no related audio files.
WAudio au = new WAudio();Other constructors allow addition of one or more audio sources as an Audio stream, a String resource or an array of Audio streams.
// Assume Audio stream `aStream`
WAudio au = new WAudio(aStream);
// or with an array of Audio streams
Audio[] audStreamArray = {aStream_1, aStream_2 /* etc */};
au = new WAudio(audStreamArray);
// or a reference to a resource on the classpath
au = new WAudio("/path/to/resource/file.mp3");Audio sources may be added using a specific constructor as shown above or by a setter accepting an Audio stream or an array of Audio streams.
// with WAudio `au` and Audio stream `stream`
au.setAudio(stream);
// or similarly with an array of streams.Every use of WAudio must comply with the requirements outlined in Media Accessibility User Requirements. The WCAG quick references pertinent to WAudio can be found at Guideline 1.2, Guideline 1.4.2 and Guideline 1.4.7.
It is recommended that a WAudio and links to its text equivalent be encapsulated in a semantic wrapper such as a WFigure.
The controls presented to the user are determined by the user agent. The JavaDoc for WAudio indicates that there is a Controls enum which may be used to modify these controls but that is no longer supported in the theme as it does not allow full unconditional conformance with accessibility guidelines.
The autoplay property, when set true, will cause the audio to play automatically in supported browsers. Use of this setting is discouraged as it may conflict with WCAG guideline 1.4.2. It is recommended that audio clips be played only on user request as outlined in G171. Some common user agents which support native audio players disable autoplay or provide a user setting to prevent autoplay.
// with WAudio `au`
au.setAutoplay(true);A WAudio may be set to loop, i.e. automatically restart once play finishes. This defaults to false and should generally be left there. This property should never be specified; it is in the API for completeness and is under review.
See toolTip. The toolTip applied to WAudio is applied to the span wrapper of the audio element.
// given WAudio `au`
// to set the toolTip
au.setToolTip("this is a toolTip");It is generally good practice to provide a choice of Audio streams to WAudio as different browsers have different levels of support for certain file types, though it should be noted that browser support for audio tracks is sparse. It is recommended that the current HTML specification and some form of browser support chart be consulted to determine appropriate types of audio file.
It is difficult to recommend an audio file format for all use-cases but .aac (Advanced Audio Coding) is quite well supported except for Firefox.
It is suggested that .wma and .wav files are never used as an audio source for WAudio,
The appearance of the HTML audio element is entirely user-agent and platform dependant. The illustration below is from Chrome 33 (probably on OS X):
When no supplied audio format is able to be played the component will output a simple list of links to each of the supplied sources so that the user may choose to download the audio to play in an external application.
WAudio may have one or more values to be added to the component's wrapper element. This can be used for fine-grain styling of specific components but should be used with care.
For more information see WComponents HTML class property.
A WAudio may be hidden on page load. When hidden the WAudio is not available to any compliant user agent. It is present in the source and is not obscured in any way. This property is determined by a WSubordinateControl.
WAudio is based on a HTML audio element. This is embedded content and is, in itself, phrasing content. However, it may be converted to, or be wrapped in, other components depending upon the user agent and the audio media.
For all design purposes you should assume that WAudio includes non-phrasing content and interactive controls.
WAudio will output links to source (and track if provided) files in any user agent which is unable to play any of the audio provided. No attempt will be made to provide an in-situ audio player for browsers which are not able to play the provided media.
An Audio stream is an interface which represents an audio clip - see Audio JavaDoc.
A common mechanism to create an Audio stream is to use AudioResource.
Audio clip = new AudioResource("/audio/aac.aac",
"Advanced Audio Coding audio file");