diff options
Diffstat (limited to 'files/zh-tw/web/api/htmlmediaelement/index.html')
| -rw-r--r-- | files/zh-tw/web/api/htmlmediaelement/index.html | 243 |
1 files changed, 243 insertions, 0 deletions
diff --git a/files/zh-tw/web/api/htmlmediaelement/index.html b/files/zh-tw/web/api/htmlmediaelement/index.html new file mode 100644 index 0000000000..68d1122e81 --- /dev/null +++ b/files/zh-tw/web/api/htmlmediaelement/index.html @@ -0,0 +1,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> |