video
elementcontrols
attribute: Interactive content.src
attribute:
zero or more track
elements, then
transparent, but with no media element descendants.src
attribute: zero or more source
elements, then
zero or more track
elements, then
transparent, but with no media element descendants.src
crossorigin
poster
preload
autoplay
mediagroup
loop
muted
controls
width
height
interface HTMLVideoElement : HTMLMediaElement { attribute unsigned long width; attribute unsigned long height; readonly attribute unsigned long videoWidth; readonly attribute unsigned long videoHeight; attribute DOMString poster; };
A video
element is used for playing videos or
movies, and audio files with captions.
Content may be provided inside the video
element. User agents should not show this content
to the user; it is intended for older Web browsers which do
not support video
, so that legacy video plugins can be
tried, or to show text to the users of these older browsers informing
them of how to access the video contents.
In particular, this content is not intended to
address accessibility concerns. To make video content accessible to
the partially sighted, the blind, the hard-of-hearing, the deaf, and
those with other physical or cognitive disabilities, a variety of
features are available. Captions can be provided, either embedded in
the video stream or as external files using the track
element. Sign-language tracks can be provided, again either embedded
in the video stream or by synchronizing multiple video
elements using the mediagroup
attribute or a
MediaController
object. Audio descriptions can be
provided, either as a separate track embedded in the video stream,
or a separate audio track in an audio
element slaved to the same controller
as the video
element(s), or in text form using a
caption file
referenced using the track
element and synthesized into
speech by the user agent. WebVTT can also be used to provide chapter
titles. For users who would rather not use a media element at all,
transcripts or other textual alternatives can be provided by simply
linking to them in the prose near the video
element.
The video
element is a media element
whose media data is ostensibly video data, possibly
with associated audio data.
The src
, preload
, autoplay
,
mediagroup
,
loop
,
muted
, and controls
attributes are the attributes common to all media
elements.
The poster
attribute gives the address of an image file that the user agent can
show while no video data is available. The attribute, if present,
must contain a valid non-empty URL potentially surrounded by
spaces.
If the specified resource is to be used, then, when the element
is created or when the poster
attribute is set, changed, or removed, the user agent must run the
following steps to determine the element's poster
frame:
If there is an existing instance of this algorithm running
for this video
element, abort that instance of this
algorithm without changing the poster frame.
If the poster
attribute's value is the empty string or if the attribute is
absent, then there is no poster frame; abort these
steps.
Resolve the poster
attribute's value relative
to the element. If this fails, then there is no poster
frame; abort these steps.
Fetch the resulting absolute
URL, from the element's Document
's
origin. This must delay the load event of
the element's document.
If an image is thus obtained, the poster frame is that image. Otherwise, there is no poster frame.
The image given by the poster
attribute, the poster
frame, is intended to be a representative frame of the video
(typically one of the first non-blank frames) that gives the user an
idea of what the video is like.
When no video data is available (the element's readyState
attribute is either
HAVE_NOTHING
, or HAVE_METADATA
but no video
data has yet been obtained at all, or the element's readyState
attribute is any
subsequent value but the media resource does not have a
video channel), the video
element
represents the poster frame.
When a video
element is paused and the current playback position is the first
frame of video, the element represents the poster
frame, unless a frame of video has already been shown, in
which case the element represents the frame of video
corresponding to the current
playback position.
When a video
element is paused at any other position, and
the media resource has a video channel, the element
represents the frame of video corresponding to the
current playback
position, or, if that is not yet available (e.g. because the
video is seeking or buffering), the last frame of the video to have
been rendered.
When a video
element whose media
resource has a video channel is potentially
playing, it represents the frame of video at the
continuously increasing "current" position. When the current playback
position changes such that the last frame rendered is no
longer the frame corresponding to the current playback
position in the video, the new frame must be rendered.
Similarly, any audio associated with the media resource
must, if played, be played synchronized with the current
playback position, at the element's effective media
volume.
When a video
element whose media
resource has a video channel is neither potentially
playing nor paused
(e.g. when seeking or stalled), the element represents
the last frame of the video to have been rendered.
Which frame in a video stream corresponds to a particular playback position is defined by the video stream's format.
The video
element also represents any
text track cues whose text
track cue active flag is set and whose text
track is in the showing mode.
In addition to the above, the user agent may provide messages to the user (such as "buffering", "no video loaded", "error", or more detailed information) by overlaying text or icons on the video or other areas of the element's playback area, or in another appropriate manner.
User agents that cannot render the video may instead make the element represent a link to an external video playback utility or to the video data itself.
When a video
element's media resource
has a video channel, the element provides a paint
source whose width is the media resource's intrinsic width, whose
height is the media resource's intrinsic height, and
whose appearance is the frame of video corresponding to the current playback position,
if that is available, or else (e.g. when the video is seeking or
buffering) its previous appearance, if any, or else (e.g. because
the video is still loading the first frame) blackness.
videoWidth
videoHeight
These attributes return the intrinsic dimensions of the video, or zero if the dimensions are not known.
The intrinsic width and intrinsic height of the media resource are the dimensions of the resource in CSS pixels after taking into account the resource's dimensions, aspect ratio, clean aperture, resolution, and so forth, as defined for the format used by the resource. If an anamorphic format does not define how to apply the aspect ratio to the video data's dimensions to obtain the "correct" dimensions, then the user agent must apply the ratio by increasing one dimension and leaving the other unchanged.
The videoWidth
IDL
attribute must return the intrinsic width of the
video in CSS pixels. The videoHeight
IDL
attribute must return the intrinsic height of
the video in CSS pixels. If the element's readyState
attribute is HAVE_NOTHING
, then the
attributes must return 0.
The video
element supports dimension
attributes.
In the absence of style rules to the contrary, video content should be rendered inside the element's playback area such that the video content is shown centered in the playback area at the largest possible size that fits completely within it, with the video content's aspect ratio being preserved. Thus, if the aspect ratio of the playback area does not match the aspect ratio of the video, the video will be shown letterboxed or pillarboxed. Areas of the element's playback area that do not contain the video represent nothing.
In user agents that implement CSS, the above requirement can be implemented by using the style rule suggested in the rendering section.
The intrinsic width of a video
element's playback
area is the intrinsic
width of the video resource, if that is available; otherwise
it is the intrinsic width of the poster frame, if that
is available; otherwise it is 300 CSS pixels.
The intrinsic height of a video
element's playback
area is the intrinsic
height of the video resource, if that is available; otherwise
it is the intrinsic height of the poster frame, if that
is available; otherwise it is 150 CSS pixels.
User agents should provide controls to enable or disable the display of closed captions, audio description tracks, and other additional data associated with the video stream, though such features should, again, not interfere with the page's normal rendering.
User agents may allow users to view the video content in manners
more suitable to the user (e.g. full-screen or in an independent
resizable window). As for the other user interface features,
controls to enable this should not interfere with the page's normal
rendering unless the user agent is exposing a user interface. In such an
independent context, however, user agents may make full user
interfaces visible, with, e.g., play, pause, seeking, and volume
controls, even if the controls
attribute is absent.
User agents may allow video playback to affect system features that could interfere with the user's experience; for example, user agents could disable screensavers while video playback is in progress.
The poster
IDL
attribute must reflect the poster
content attribute.
This example shows how to detect when a video has failed to play correctly:
<script> function failed(e) { // video playback failed - show a message saying why switch (e.target.error.code) { case e.target.error.MEDIA_ERR_ABORTED: alert('You aborted the video playback.'); break; case e.target.error.MEDIA_ERR_NETWORK: alert('A network error caused the video download to fail part-way.'); break; case e.target.error.MEDIA_ERR_DECODE: alert('The video playback was aborted due to a corruption problem or because the video used features your browser did not support.'); break; case e.target.error.MEDIA_ERR_SRC_NOT_SUPPORTED: alert('The video could not be loaded, either because the server or network failed or because the format is not supported.'); break; default: alert('An unknown error occurred.'); break; } } </script> <p><video src="tgif.vid" autoplay controls onerror="failed(event)"></video></p> <p><a href="tgif.vid">Download the video file</a>.</p>