---
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 {{event("Event_handlers", "event handler")}} 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>