WVideo
WVideo is a component used to add an video player component to an application.
help required Needs code snippets.
- When to use WVideo
- Creating WVideo
- Accessibility
- Appearance
- Video files
- Pre-loading
- Mute
- HTML output
- Chapters
- Related Components
- Further information
You really need me to tell you this?
to be written
Every use of WVideo must comply with the requirements outlined in Media Accessibility User Requirements.
The WCAG quick references pertinent to WVideo can be found at Guideline 1.2 and if the video contains audio then those guidelines which pertain to audio content also apply. These are linked from the above document and are included in the documentation of WAudio.
It is recommended that a WVideo which has external non-video equivalent content (such as an external text description) and links to this content be encapsulated in a semantic wrapper such as a WFigure.
WVideo support an alternate text property which is used as a text alternative to the poster image used as a place-holder when the user agent is not able to support any supplied video format. This property must be set if the poster property is set (and the poster property must be set if the application has public use or any users who may use user agents which do not support the video formats to be used - which is pretty much all the time).
// with WVideo media
media.setAltText("Description of poster");It must be noted that the text equivalent applies only to the poster and not to the video. It is not sufficient to supply a text-equivalent instead of a full non-video description, captions or transcripts.
Pre-recorded vido should include an alternative as outlined in Guideline 1.2.1
Either an alternative for time-based media or an audio track is provided that presents equivalent information for prerecorded video-only content.
Where such a video includes an audio transcription or track then this track must comply with the accessibility requirements for audio which are described in the documentation for WAudio.
Captions and/or transcripts must be provided for pre-recorded video (with limited exceptions) to meet WCAG guidelines 1.2. WVideo supports closed captioning of pre-recorded video using WebVTT format captions. The following types of closed captioning are all independently available for any given video:
- Subtitles;
- Captions; and
- Descriptions.
For more information about the different closed caption track types (and the chapters track which is also supported) see the track element, iImplementation of which is user-agent dependent.
It is recommended that all video should be accompanied by unencapsulated transcript or description so that users who are not able to access the video or its caption/transcript tracks may still be able to obtain equivalent content.
TODO further info about how to create and attach captions to WVideo, code samples.
WVideo may be set to autoplay on load. This setting may be disregarded.
Use of this setting is discouraged as it may conflict with WCAG guideline 1.4.2. It is recommended that clips containing audio be played only on user request as outlined in G171. Some common user agents which support native video players disable autoplay.
Looping will cause the video to automatically restart once it 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.
The appearance of a video element is entirely user agent dependant. The following illustration shows a video element in Chrome 30-something on OS X
The poster property is an Image which points to a static image representative of the video. If not set the video player will be black until the first frame is loaded. It is strongly recommended that the poster be set as it will be used as a placeholder (and link target) if the user agent is not able to play any of the supplied formats.
If a poster is set then the WVideo alt text property must also be set.
// with WVideo `media`
ImageResource myPosterImage = new ImageResource("/PATH/poster.jpg");
media.setPoster(myPosterImage)
media.setAltText("Description of poster");The width of the video is set in pixels. It may be manipulated in CSS.
// with WVideo `media` set width to 300px
media.setWidth(300);The height of the video is set in pixels. It may be manipulated in CSS.
// with WVideo `media` - set height to 200px
media.setHeight(200);A WVideo component may be provided with a list of video files of the same video in different formats. This allows each user agent to attempt to find a format it is able to play. Some video formats are more conducive to playing than others and some may not be able to be played at all.
It is strongly recommended that each piece of embedded video be provided in each of:
-
mp4(H264) format -
ogvformat -
webmformat
All of the recommended formats will have issues in one or more user agents and at least two should be present, preferably MP4/H264 and one other.
It is strongly recommended that the following video formats not be used at all:
-
wmvformat may not be playable, is not supported by many native players; -
aviwill not play in most current user agents, is not optimised for network delivery and should not be used; -
quicktimewill not play in most current native players; it may play on OX-S and iOS devices under some circumstances; -
flvwill not play in any known native HTML 5 element.
The pre-load property determines what aspects of the media, if any, should be loaded before the user interacts with the media. Determining the best setting for this property is strongly bound to use cases for the media. For example on a media based site one would expect the main purpose of the visit is to play the media and preload would be AUTO; whereas if the use of the media is likely to be limited then it may be more appropriate to use NONE to prevent unnecessary use of the user's network connection.
This is an optional property and if not set will default to AUTO.
Available values for this property are:
-
NONE: nothing is loaded until the user interacts with the media, for example by pressing play. This will cause delay in the initial playing of the media but is the most efficient use of network resources. -
METADATA: only the media meta data is loaded. This will provide an accurate indication of the duration of the media and load chapters and closed caption tracks (if available) but will not speed up initial play by any perceptible amount except on very slow connections. -
AUTO: the user agent determines what should be preloaded. The video will be able to play as soon as enough of the media file has pre-loaded to allow commencement.
Setting the mute property true will cause the media to initially be muted.
WVideo is based on a video 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 video media. For all design purposes you should assume that WVideo includes non-phrasing content and interactive controls.
If the video media is able to be divided into chapters then these chapters may be exposed to the media player, and hence the user, by creating a WebVTT format chapter document and delivering it as a chapters track.