1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
|
---
title: HTMLMediaElement
slug: Web/API/HTMLMediaElement
translation_of: Web/API/HTMLMediaElement
---
<p>{{APIRef("HTML DOM")}}</p>
<p><span class="seoSummary">The <strong><code>HTMLMediaElement</code></strong> interface adds to {{domxref("HTMLElement")}} the properties and methods needed to support basic media-related capabilities that are common to audio and video.</span> The {{domxref("HTMLVideoElement")}} and {{domxref("HTMLAudioElement")}} elements both inherit this interface.</p>
<p>{{InheritanceDiagram(600, 120)}}</p>
<h2 id="屬性">屬性</h2>
<p><em>這個介面從{{domxref("HTMLElement")}}、{{domxref("Element")}}、{{domxref("Node")}}，和{{domxref("EventTarget")}}繼承了屬性</em></p>
<dl>
<dt>{{domxref("HTMLMediaElement.audioTracks")}}</dt>
<dd>{{domxref("AudioTrackList")}} 會列出包含在該媒體元素內部的{{domxref("AudioTrack")}}物件。</dd>
<dt>{{domxref("HTMLMediaElement.autoplay")}}</dt>
<dd>是一個布林值，表達了HTML中是否有{{htmlattrxref("autoplay", "video")}}屬性；意即；表明是否只要在媒體可以播放且不中斷的時候，能夠自動播放。
<div class="note">在網站上自動播放音訊（或是有音訊的影片），可能是惱人的使用者體驗；因此，應該盡可能地避免。如果你必須要有自動播放的功能，你應該讓它是可選擇的（讓使用者特地去啟動）。 However, this can be useful when creating media elements whose source will be set at a later time, under user control.</div>
</dd>
<dt>{{domxref("HTMLMediaElement.buffered")}} {{readonlyinline}}</dt>
<dd>回傳一個{{domxref("TimeRanges")}}物件，表示媒體當下<code>buffered</code>屬性被瀏覽器存取時的緩存（如果有的話）區間。</dd>
<dt>{{domxref("HTMLMediaElement.controller")}}</dt>
<dd>Is a {{domxref("MediaController")}} object that represents the media controller assigned to the element, or <code>null</code> if none is assigned.</dd>
<dt>{{domxref("HTMLMediaElement.controls")}}</dt>
<dd>Is a {{jsxref('Boolean')}} that reflects the {{htmlattrxref("controls", "video")}} HTML attribute, indicating whether user interface items for controlling the resource should be displayed.</dd>
<dt>{{domxref("HTMLMediaElement.controlsList")}} {{readonlyinline}}</dt>
<dd>Returns a {{domxref("DOMTokenList")}} that helps the user agent select what controls to show on the media element whenever the user agent shows its own set of controls. The <code>DOMTokenList</code> takes one or more of three possible values: <code>nodownload</code>, <code>nofullscreen</code>, and <code>noremoteplayback</code>.</dd>
<dt>{{domxref("HTMLMediaElement.crossOrigin")}}</dt>
<dd>Is a {{domxref("DOMString")}} indicating the <a href="/en-US/docs/Web/HTML/CORS_settings_attributes">CORS setting</a> for this media element.</dd>
<dt>{{domxref("HTMLMediaElement.currentSrc")}} {{readonlyinline}}</dt>
<dd>Returns a {{domxref("DOMString")}} with the absolute URL of the chosen media resource.</dd>
<dt>{{domxref("HTMLMediaElement.currentTime")}}</dt>
<dd>Is a <code>double</code> indicating the current playback time in seconds. Setting this value seeks the media to the new time.</dd>
<dt>{{domxref("HTMLMediaElement.defaultMuted")}}</dt>
<dd>Is a {{jsxref('Boolean')}} that reflects the {{htmlattrxref("muted", "video")}} HTML attribute, which indicates whether the media element's audio output should be muted by default.</dd>
<dt>{{domxref("HTMLMediaElement.defaultPlaybackRate")}}</dt>
<dd>Is a <code>double</code> indicating the default playback rate for the media.</dd>
<dt>{{domxref("HTMLMediaElement.disableRemotePlayback")}}</dt>
<dd>Is a {{jsxref('Boolean')}} that sets or returns the remote playback state, indicating whether the media element is allowed to have a remote playback UI.</dd>
<dt>{{domxref("HTMLMediaElement.duration")}} {{readonlyinline}}</dt>
<dd>Returns a <code>double</code> indicating the length of the media in seconds, or 0 if no media data is available.</dd>
<dt>{{domxref("HTMLMediaElement.ended")}} {{readonlyinline}}</dt>
<dd>Returns a {{jsxref('Boolean')}} that indicates whether the media element has finished playing.</dd>
<dt>{{domxref("HTMLMediaElement.error")}} {{readonlyinline}}</dt>
<dd>Returns a {{domxref("MediaError")}} object for the most recent error, or <code>null</code> if there has not been an error.</dd>
<dt>{{domxref("HTMLMediaElement.loop")}}</dt>
<dd>Is a {{jsxref('Boolean')}} that reflects the {{htmlattrxref("loop", "video")}} HTML attribute, which indicates whether the media element should start over when it reaches the end.</dd>
<dt>{{domxref("HTMLMediaElement.mediaGroup")}}</dt>
<dd>Is a {{domxref("DOMString")}} that reflects the {{ htmlattrxref("mediagroup", "video")}} HTML attribute, which indicates the name of the group of elements it belongs to. A group of media elements shares a common {{domxref('MediaController')}}.</dd>
<dt>{{domxref("HTMLMediaElement.mediaKeys")}} {{readonlyinline}} {{experimental_inline}}</dt>
<dd>Returns a {{domxref("MediaKeys")}} object or <code>null</code>. MediaKeys is a set of keys that an associated HTMLMediaElement can use for decryption of media data during playback.</dd>
<dt>{{domxref("HTMLMediaElement.mozAudioCaptured")}} {{readonlyinline}} {{non-standard_inline}}</dt>
<dd>Returns a {{jsxref('Boolean')}}. Related to audio stream capture.</dd>
<dt>{{domxref("HTMLMediaElement.mozFragmentEnd")}} {{non-standard_inline}}</dt>
<dd>Is a <code>double</code> that provides access to the fragment end time if the media element has a fragment URI for <code>currentSrc</code>, otherwise it is equal to the media duration.</dd>
<dt>{{domxref("HTMLMediaElement.mozFrameBufferLength")}} {{non-standard_inline}} {{deprecated_inline}}</dt>
<dd>
<p>Is a <code>unsigned long</code> that indicates the number of samples that will be returned in the framebuffer of each <code>MozAudioAvailable</code> event. This number is a total for all channels, and by default is set to be the number of channels * 1024 (e.g., 2 channels * 1024 samples = 2048 total).</p>
<p>The <code>mozFrameBufferLength</code> property can be set to a new value for lower latency, larger amounts of data, etc. The size given <em>must</em> be a number between 512 and 16384. Using any other size results in an exception being thrown. The best time to set a new length is after the <a href="/en-US/docs/Web/Events/loadedmetadata">loadedmetadata</a> event fires, when the audio info is known, but before the audio has started or <code>MozAudioAvailable</code> events have begun firing.</p>
</dd>
<dt>{{domxref("HTMLMediaElement.mozSampleRate")}} {{readonlyinline}} {{non-standard_inline}} {{deprecated_inline}}</dt>
<dd>Returns a <code>double</code> representing the number of samples per second that will be played. For example, 44100 samples per second is the sample rate used by CD audio.</dd>
<dt>{{domxref("HTMLMediaElement.muted")}}</dt>
<dd>Is a {{jsxref('Boolean')}} that determines whether audio is muted. <code>true</code> if the audio is muted and <code>false</code> otherwise.</dd>
<dt>{{domxref("HTMLMediaElement.networkState")}} {{readonlyinline}}</dt>
<dd>Returns a <code>unsigned short</code> (enumeration) indicating the current state of fetching the media over the network.</dd>
<dt>{{domxref("HTMLMediaElement.paused")}} {{readonlyinline}}</dt>
<dd>Returns a {{jsxref('Boolean')}} that indicates whether the media element is paused.</dd>
<dt>{{domxref("HTMLMediaElement.playbackRate")}}</dt>
<dd>Is a <code>double</code> that indicates the rate at which the media is being played back. </dd>
<dt>{{domxref("HTMLMediaElement.played")}} {{readonlyinline}}</dt>
<dd>Returns a {{domxref('TimeRanges')}} object that contains the ranges of the media source that the browser has played, if any.</dd>
<dt>{{domxref("HTMLMediaElement.preload")}}</dt>
<dd>Is a {{domxref("DOMString")}} that reflects the {{htmlattrxref("preload", "video")}} HTML attribute, indicating what data should be preloaded, if any. Possible values are: <code>none</code>, <code>metadata</code>, <code>auto</code>.</dd>
<dt>{{domxref("HTMLMediaElement.preservesPitch")}} {{non-standard_inline}}</dt>
<dd>Is a {{jsxref('Boolean')}} that determines if the pitch of the sound will be preserved. If set to <code>false</code>, the pitch will adjust to the speed of the audio. This is implemented with prefixes in Firefox (<code>mozPreservesPitch</code>) and WebKit (<code>webkitPreservesPitch</code>).</dd>
<dt>{{domxref("HTMLMediaElement.readyState")}} {{readonlyinline}}</dt>
<dd>Returns a <code>unsigned short</code> (enumeration) indicating the readiness state of the media.</dd>
<dt>{{domxref("HTMLMediaElement.seekable")}} {{readonlyinline}}</dt>
<dd>Returns a {{domxref('TimeRanges')}} object that contains the time ranges that the user is able to seek to, if any.</dd>
<dt>{{domxref("HTMLMediaElement.seeking")}} {{readonlyinline}}</dt>
<dd>Returns a {{jsxref('Boolean')}} that indicates whether the media is in the process of seeking to a new position.</dd>
<dt>{{domxref("HTMLMediaElement.sinkId")}} {{readonlyinline}} {{experimental_inline}}</dt>
<dd>Returns a {{domxref("DOMString")}} that is the unique ID of the audio device delivering output, or an empty string if it is using the user agent default. This ID should be one of the <code>MediaDeviceInfo.deviceid</code> values returned from {{domxref("MediaDevices.enumerateDevices()")}}, <code>id-multimedia</code>, or <code>id-communications</code>.</dd>
<dt>{{domxref("HTMLMediaElement.src")}}</dt>
<dd>Is a {{domxref("DOMString")}} that reflects the {{htmlattrxref("src", "video")}} HTML attribute, which contains the URL of a media resource to use.</dd>
<dt>{{domxref("HTMLMediaElement.srcObject")}}</dt>
<dd>Is a {{domxref('MediaStream')}} representing the media to play or that has played in the current <code>HTMLMediaElement</code>, or <code>null</code> if not assigned.</dd>
<dt>{{domxref("HTMLMediaElement.textTracks")}} {{readonlyinline}}</dt>
<dd>Returns the list of {{domxref("TextTrack")}} objects contained in the element.</dd>
<dt>{{domxref("HTMLMediaElement.videoTracks")}} {{readonlyinline}}</dt>
<dd>Returns the list of {{domxref("VideoTrack")}} objects contained in the element.
<div class="note">
<p>Gecko supports only single track playback, and the parsing of tracks' metadata is only available for media with the Ogg container format.</p>
</div>
</dd>
<dt>{{domxref("HTMLMediaElement.volume")}}</dt>
<dd>Is a <code>double</code> indicating the audio volume, from 0.0 (silent) to 1.0 (loudest).</dd>
</dl>
<h3 id="Event_handlers">Event handlers</h3>
<dl>
<dt> </dt>
<dt>{{domxref("HTMLMediaElement.onencrypted")}}</dt>
<dd>Sets the {{domxref('EventHandler')}} called when the media is encrypted.</dd>
<dt>{{domxref("HTMLMediaElement.onwaitingforkey")}}</dt>
<dd>Sets the {{domxref('EventHandler')}} called when playback is blocked while waiting for an encryption key.</dd>
</dl>
<h2 id="Obsolete_attributes">Obsolete attributes</h2>
<p>These attributes are obsolete and should not be used, even if a browser still supports them.</p>
<p> </p>
<dl>
<dt>{{domxref("HTMLMediaElement.initialTime")}} {{readonlyinline}} {{non-standard_inline}} {{obsolete_inline}}</dt>
<dd>Returns a <code>double</code> that indicates the initial playback position in seconds.</dd>
<dt>{{domxref("HTMLMediaElement.mozChannels")}} {{readonlyinline}} {{non-standard_inline}} {{deprecated_inline}}</dt>
<dd>Returns a <code>double</code> representing the number of channels in the audio resource (e.g., <code>2</code> for stereo).</dd>
</dl>
<h3 id="Obsolete_event_handlers">Obsolete event handlers</h3>
<p> </p>
<dl>
<dt>{{domxref("HTMLMediaElement.onmozinterruptbegin")}} {{non-standard_inline}} {{obsolete_inline}}</dt>
<dd>Sets the {{domxref("EventHandler")}} called when the media element is interrupted because of the Audio Channel manager. This was Firefox-specific, having been implemented for Firefox OS, and was removed in Firefox 55.</dd>
<dt>{{domxref("HTMLMediaElement.onmozinterruptend")}} {{non-standard_inline}} {{obsolete_inline}}</dt>
<dd>Sets the {{domxref('EventHandler')}} called when the interruption is concluded. This was Firefox-specific, having been implemented for Firefox OS, and was removed in Firefox 55.</dd>
</dl>
<p> </p>
<p> </p>
<h2 id="Methods">Methods</h2>
<p><em>This interface also inherits methods from its ancestors {{domxref("HTMLElement")}}, {{domxref('Element')}}, {{domxref('Node')}}, and {{domxref('EventTarget')}}.</em></p>
<dl>
<dt>{{domxref("HTMLMediaElement.addTextTrack()")}}</dt>
<dd>Adds a text track (such as a track for subtitles) to a media element.</dd>
<dt>{{domxref("HTMLMediaElement.captureStream()")}} {{experimental_inline}}</dt>
<dd>Returns {{domxref("MediaStream")}}, captures a stream of the media content.</dd>
<dt>{{domxref("HTMLMediaElement.canPlayType()")}}</dt>
<dd>Determines whether the specified media type can be played back.</dd>
<dt>{{domxref("HTMLMediaElement.fastSeek()")}}</dt>
<dd>Directly seeks to the given time.</dd>
<dt>{{domxref("HTMLMediaElement.load()")}}</dt>
<dd>Resets the media element and restarts the media resource. Any pending events are discarded. How much media data is fetched is still affected by the <code>preload</code> attribute. This method can be useful for releasing resources after any <code>src</code> attribute and <code>source</code> element descendants have been removed. Otherwise, it is usually unnecessary to use this method, unless required to rescan <code>source</code> element children after dynamic changes.</dd>
<dt>{{domxref("HTMLMediaElement.mozCaptureStream()")}} {{non-standard_inline}}</dt>
<dd>[enter description]</dd>
<dt>{{domxref("HTMLMediaElement.mozCaptureStreamUntilEnded()")}} {{non-standard_inline}}</dt>
<dd>[enter description]</dd>
<dt>{{domxref("HTMLMediaElement.mozGetMetadata()")}} {{non-standard_inline}}</dt>
<dd>Returns {{jsxref('Object')}}, which contains properties that represent metadata from the playing media resource as <code>{key: value}</code> pairs. A separate copy of the data is returned each time the method is called. This method must be called after the <a href="/en-US/docs/Web/Events/loadedmetadata">loadedmetadata</a> event fires.</dd>
<dt>{{domxref("HTMLMediaElement.pause()")}}</dt>
<dd>Pauses the media playback.</dd>
<dt>{{domxref("HTMLMediaElement.play()")}}</dt>
<dd>Begins playback of the media.</dd>
<dt>{{domxref("HTMLMediaElement.seekToNextFrame()")}} {{non-standard_inline}} {{experimental_inline}}</dt>
<dd>Seeks to the next frame in the media. This non-standard, experimental method makes it possible to manually drive reading and rendering of media at a custom speed, or to move through the media frame-by-frame to perform filtering or other operations.</dd>
<dt>{{domxref("HTMLMediaElement.setMediaKeys()")}} {{experimental_inline}}</dt>
<dd>Returns {{jsxref("Promise")}}. Sets the {{domxref("MediaKeys")}} keys to use when decrypting media during playback.</dd>
<dt>{{domxref("HTMLMediaElement.setSinkId()")}} {{experimental_inline}}</dt>
<dd>Sets the ID of the audio device to use for output and returns a {{jsxref("Promise")}}. This only works when the application is authorized to use the specified device.</dd>
</dl>
<h2 id="Obsolete_methods">Obsolete methods</h2>
<p>These methods are obsolete and should not be used, even if a browser still supports them.</p>
<p> </p>
<dl>
<dt>{{domxref("HTMLMediaElement.mozLoadFrom()")}} {{non-standard_inline}} {{deprecated_inline}}</dt>
<dd>This method, available only in Mozilla's implementation, loads data from another media element. This works similarly to <code>load()</code> except that instead of running the normal resource selection algorithm, the source is simply set to the <code>other</code> element's <code>currentSrc</code>. This is optimized so this element gets access to all of the <code>other</code> element's cached and buffered data; in fact, the two elements share downloaded data, so data downloaded by either element is available to both.</dd>
</dl>
<p> </p>
<h2 id="Specifications">Specifications</h2>
<table class="standard-table">
<tbody>
<tr>
<th scope="col">Specification</th>
<th scope="col">Status</th>
<th scope="col">Comment</th>
</tr>
<tr>
<td>{{SpecName('HTML WHATWG', "the-video-element.html#htmlmediaelement", "HTMLMediaElement")}}</td>
<td>{{Spec2('HTML WHATWG')}}</td>
<td>No change from {{SpecName('HTML5 W3C')}}</td>
</tr>
<tr>
<td>{{SpecName('HTML5 W3C', "embedded-content-0.html#htmlmediaelement", "HTMLMediaElement")}}</td>
<td>{{Spec2('HTML5 W3C')}}</td>
<td>Initial definition.</td>
</tr>
<tr>
<td>{{SpecName('EME', '#introduction', 'Encrypted Media Extensions')}}</td>
<td>{{Spec2('EME')}}</td>
<td>Adds {{domxref("MediaKeys")}}, {{domxref("MediaEncryptedEvent")}}, {{domxref("setMediaKeys")}}, {{domxref("onencrypted")}}, and {{domxref("onwaitingforkey")}}.</td>
</tr>
<tr>
<td>{{SpecName('Media Capture','#htmlmediaelement-extensions','HTMLMediaElement')}}</td>
<td>{{Spec2('Media Capture')}}</td>
<td>Adds <code>sinkId</code> and <code>setSinkId()</code>, and <code>captureStream()</code>.</td>
</tr>
</tbody>
</table>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<p>{{Compat("api.HTMLMediaElement")}}</p>
<h2 id="See_also">See also</h2>
<ul>
<li>References
<ul>
<li>{{HTMLElement("video")}} and {{HTMLElement("audio")}} HTML elements.</li>
<li>{{domxref("HTMLVideoElement")}} and {{domxref("HTMLAudioElement")}} interfaces, derived from <code>HTMLMediaElement</code>.</li>
</ul>
</li>
<li>Articles
<ul>
<li><a class="internal" href="/en-US/docs/Using_HTML5_audio_and_video">Using HTML5 audio and video</a></li>
<li><a class="internal" href="/en-US/docs/Media_formats_supported_by_the_audio_and_video_elements">Media formats supported by the audio and video elements</a></li>
<li><a href="/en-US/docs/Web_Audio_API">Web Audio API</a></li>
</ul>
</li>
</ul>
|
