WAudio
WAudio is a component for creating audio output controls.
- Why use WAudio
- Creating WAudio
- Accessibility
- Usability
- HTML output
- Audio streams
- Hiding
- Customising based on HTML class
- 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.
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,
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");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 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.