HTMLMediaElement.webidl (9775B)
1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2 /* This Source Code Form is subject to the terms of the Mozilla Public 3 * License, v. 2.0. If a copy of the MPL was not distributed with this file, 4 * You can obtain one at http://mozilla.org/MPL/2.0/. 5 * 6 * The origin of this IDL file is 7 * http://www.whatwg.org/specs/web-apps/current-work/#media-elements 8 * 9 * © Copyright 2004-2011 Apple Computer, Inc., Mozilla Foundation, and 10 * Opera Software ASA. You are granted a license to use, reproduce 11 * and create derivative works of this document. 12 */ 13 14 [Exposed=Window] 15 interface HTMLMediaElement : HTMLElement { 16 17 // error state 18 readonly attribute MediaError? error; 19 20 // network state 21 [CEReactions, SetterNeedsSubjectPrincipal=NonSystem, SetterThrows] 22 attribute DOMString src; 23 readonly attribute DOMString currentSrc; 24 25 [CEReactions, SetterThrows] 26 attribute DOMString? crossOrigin; 27 const unsigned short NETWORK_EMPTY = 0; 28 const unsigned short NETWORK_IDLE = 1; 29 const unsigned short NETWORK_LOADING = 2; 30 const unsigned short NETWORK_NO_SOURCE = 3; 31 readonly attribute unsigned short networkState; 32 [CEReactions, SetterThrows] 33 attribute DOMString preload; 34 [NewObject] 35 readonly attribute TimeRanges buffered; 36 undefined load(); 37 DOMString canPlayType(DOMString type); 38 39 // ready state 40 const unsigned short HAVE_NOTHING = 0; 41 const unsigned short HAVE_METADATA = 1; 42 const unsigned short HAVE_CURRENT_DATA = 2; 43 const unsigned short HAVE_FUTURE_DATA = 3; 44 const unsigned short HAVE_ENOUGH_DATA = 4; 45 readonly attribute unsigned short readyState; 46 readonly attribute boolean seeking; 47 48 // playback state 49 [SetterThrows] 50 attribute double currentTime; 51 [Throws] 52 undefined fastSeek(double time); 53 readonly attribute unrestricted double duration; 54 [ChromeOnly] 55 readonly attribute boolean isEncrypted; 56 // TODO: Bug 847376 - readonly attribute any startDate; 57 readonly attribute boolean paused; 58 [SetterThrows] 59 attribute double defaultPlaybackRate; 60 [SetterThrows] 61 attribute double playbackRate; 62 [NewObject] 63 readonly attribute TimeRanges played; 64 [NewObject] 65 readonly attribute TimeRanges seekable; 66 readonly attribute boolean ended; 67 [CEReactions, SetterThrows] 68 attribute boolean autoplay; 69 [CEReactions, SetterThrows] 70 attribute boolean loop; 71 [NewObject] 72 Promise<undefined> play(); 73 [Throws] 74 undefined pause(); 75 76 // TODO: Bug 847377 - mediaGroup and MediaController 77 // media controller 78 // attribute DOMString mediaGroup; 79 // attribute MediaController? controller; 80 81 // controls 82 [CEReactions, SetterThrows] 83 attribute boolean controls; 84 [SetterThrows] 85 attribute double volume; 86 attribute boolean muted; 87 [CEReactions, SetterThrows] 88 attribute boolean defaultMuted; 89 90 // TODO: Bug 847379 91 // tracks 92 [Pref="media.track.enabled"] 93 readonly attribute AudioTrackList audioTracks; 94 [Pref="media.track.enabled"] 95 readonly attribute VideoTrackList videoTracks; 96 readonly attribute TextTrackList? textTracks; 97 TextTrack addTextTrack(TextTrackKind kind, 98 optional DOMString label = "", 99 optional DOMString language = ""); 100 }; 101 102 // Mozilla extensions: 103 partial interface HTMLMediaElement { 104 [Func="HasDebuggerOrTabsPrivilege"] 105 readonly attribute MediaSource? mozMediaSourceObject; 106 107 [Func="HasDebuggerOrTabsPrivilege", NewObject] 108 Promise<HTMLMediaElementDebugInfo> mozRequestDebugInfo(); 109 110 [Func="HasDebuggerOrTabsPrivilege", NewObject] 111 static undefined mozEnableDebugLog(); 112 [Func="HasDebuggerOrTabsPrivilege", NewObject] 113 Promise<DOMString> mozRequestDebugLog(); 114 115 attribute MediaStream? srcObject; 116 117 attribute boolean preservesPitch; 118 119 // NB: for internal use with the video controls: 120 [Func="IsChromeOrUAWidget"] attribute boolean mozAllowCasting; 121 [Func="IsChromeOrUAWidget"] attribute boolean mozIsCasting; 122 123 // Mozilla extension: stream capture 124 [Throws] 125 MediaStream mozCaptureStream(); 126 [Throws] 127 MediaStream mozCaptureStreamUntilEnded(); 128 readonly attribute boolean mozAudioCaptured; 129 130 // Mozilla extension: return embedded metadata from the stream as a 131 // JSObject with key:value pairs for each tag. This can be used by 132 // player interfaces to display the song title, artist, etc. 133 [Throws] 134 object? mozGetMetadata(); 135 136 // Mozilla extension: provides access to the fragment end time if 137 // the media element has a fragment URI for the currentSrc, otherwise 138 // it is equal to the media duration. 139 readonly attribute double mozFragmentEnd; 140 }; 141 142 // Encrypted Media Extensions 143 partial interface HTMLMediaElement { 144 readonly attribute MediaKeys? mediaKeys; 145 146 // undefined, not any: https://www.w3.org/Bugs/Public/show_bug.cgi?id=26457 147 [NewObject] 148 Promise<undefined> setMediaKeys(MediaKeys? mediaKeys); 149 150 attribute EventHandler onencrypted; 151 152 attribute EventHandler onwaitingforkey; 153 }; 154 155 /** 156 * These attributes are general testing attributes and they should only be used 157 * in tests. 158 */ 159 partial interface HTMLMediaElement { 160 [Pref="media.useAudioChannelService.testing"] 161 readonly attribute double computedVolume; 162 163 [Pref="media.useAudioChannelService.testing"] 164 readonly attribute boolean computedMuted; 165 166 // Return true if the media is suspended because its document is inactive or 167 // the docshell is inactive and explicitly being set to prohibit all media 168 // from playing. 169 [ChromeOnly] 170 readonly attribute boolean isSuspendedByInactiveDocOrDocShell; 171 }; 172 173 /* 174 * HTMLMediaElement::seekToNextFrame() is a Mozilla experimental feature. 175 * 176 * The SeekToNextFrame() method provides a way to access a video element's video 177 * frames one by one without going through the realtime playback. So, it lets 178 * authors use "frame" as unit to access the video element's underlying data, 179 * instead of "time". 180 * 181 * The SeekToNextFrame() is a kind of seek operation, so normally, once it is 182 * invoked, a "seeking" event is dispatched. However, if the media source has no 183 * video data or is not seekable, the operation is ignored without filing the 184 * "seeking" event. 185 * 186 * Once the SeekToNextFrame() is done, a "seeked" event should always be filed 187 * and a "ended" event might also be filed depends on where the media element's 188 * position before seeking was. There are two cases: 189 * Assume the media source has n+1 video frames where n is a non-negative 190 * integers and the frame sequence is indexed from zero. 191 * (1) If the currentTime is at anywhere smaller than the n-th frame's beginning 192 * time, say the currentTime is now pointing to a position which is smaller 193 * than the x-th frame's beginning time and larger or equal to the (x-1)-th 194 * frame's beginning time, where x belongs to [1, n], then the 195 * SeekToNextFrame() operation seeks the media to the x-th frame, sets the 196 * media's currentTime to the x-th frame's beginning time and dispatches a 197 * "seeked" event. 198 * (2) Otherwise, if the currentTime is larger or equal to the n-th frame's 199 * beginning time, then the SeekToNextFrame() operation sets the media's 200 * currentTime to the duration of the media source and dispatches a "seeked" 201 * event and an "ended" event. 202 */ 203 partial interface HTMLMediaElement { 204 [NewObject, Pref="media.seekToNextFrame.enabled"] 205 Promise<undefined> seekToNextFrame(); 206 }; 207 208 /* Internal testing only API */ 209 partial interface HTMLMediaElement { 210 // These APIs are used to simulate visibility changes to help debug and write 211 // tests about suspend-video-decoding. 212 // - SetVisible() is for simulating visibility changes. 213 // - HasSuspendTaint() is for querying that the element's decoder cannot suspend 214 // video decoding because it has been tainted by an operation, such as 215 // drawImage(). 216 // - isInViewPort is a boolean value which indicate whether media element is 217 // in view port. 218 // - isVideoDecodingSuspended() is used to know whether video decoding has 219 // suspended. 220 [Pref="media.test.video-suspend"] 221 undefined setVisible(boolean aVisible); 222 223 [Pref="media.test.video-suspend"] 224 boolean hasSuspendTaint(); 225 226 [ChromeOnly] 227 readonly attribute boolean isInViewPort; 228 229 [ChromeOnly] 230 readonly attribute boolean isVideoDecodingSuspended; 231 232 [ChromeOnly] 233 readonly attribute double totalVideoPlayTime; 234 235 [ChromeOnly] 236 readonly attribute double totalVideoHDRPlayTime; 237 238 [ChromeOnly] 239 readonly attribute double visiblePlayTime; 240 241 [ChromeOnly] 242 readonly attribute double invisiblePlayTime; 243 244 [ChromeOnly] 245 readonly attribute double totalAudioPlayTime; 246 247 [ChromeOnly] 248 readonly attribute double audiblePlayTime; 249 250 [ChromeOnly] 251 readonly attribute double inaudiblePlayTime; 252 253 [ChromeOnly] 254 readonly attribute double mutedPlayTime; 255 256 // These APIs are used for decoder doctor tests. 257 [ChromeOnly] 258 undefined setFormatDiagnosticsReportForMimeType(DOMString mimeType, DecoderDoctorReportType error); 259 260 [Throws, ChromeOnly] 261 undefined setDecodeError(DOMString error); 262 263 [ChromeOnly] 264 undefined setAudioSinkFailedStartup(); 265 }; 266 267 /* Audio Output Devices API 268 * https://w3c.github.io/mediacapture-output/ 269 */ 270 partial interface HTMLMediaElement { 271 [SecureContext, Pref="media.setsinkid.enabled"] 272 readonly attribute DOMString sinkId; 273 [NewObject, SecureContext, Pref="media.setsinkid.enabled"] 274 Promise<undefined> setSinkId(DOMString sinkId); 275 }; 276 277 /* 278 * API that exposes whether a call to HTMLMediaElement.play() would be 279 * blocked by autoplay policies; whether the promise returned by play() 280 * would be rejected with NotAllowedError. 281 */ 282 partial interface HTMLMediaElement { 283 [Pref="media.allowed-to-play.enabled"] 284 readonly attribute boolean allowedToPlay; 285 };