dom/webidl/HTMLMediaElement.webidl

   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   void 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   void 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<void> play();
  73   [Throws]
  74   void 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 void mozEnableDebugLog();
 112   [Func="HasDebuggerOrTabsPrivilege", NewObject]
 113   Promise<DOMString> mozRequestDebugLog();
 114
 115   attribute MediaStream? srcObject;
 116
 117   // TODO: Remove mozPreservesPitch. (bug 1765201)
 118   [Deprecated="MozPreservesPitchDeprecatedPrefix", BinaryName="preservesPitch"]
 119   attribute boolean mozPreservesPitch;
 120   attribute boolean preservesPitch;
 121
 122   // NB: for internal use with the video controls:
 123   [Func="IsChromeOrUAWidget"] attribute boolean mozAllowCasting;
 124   [Func="IsChromeOrUAWidget"] attribute boolean mozIsCasting;
 125
 126   // Mozilla extension: stream capture
 127   [Throws]
 128   MediaStream mozCaptureStream();
 129   [Throws]
 130   MediaStream mozCaptureStreamUntilEnded();
 131   readonly attribute boolean mozAudioCaptured;
 132
 133   // Mozilla extension: return embedded metadata from the stream as a
 134   // JSObject with key:value pairs for each tag. This can be used by
 135   // player interfaces to display the song title, artist, etc.
 136   [Throws]
 137   object? mozGetMetadata();
 138
 139   // Mozilla extension: provides access to the fragment end time if
 140   // the media element has a fragment URI for the currentSrc, otherwise
 141   // it is equal to the media duration.
 142   readonly attribute double mozFragmentEnd;
 143 };
 144
 145 // Encrypted Media Extensions
 146 partial interface HTMLMediaElement {
 147   readonly attribute MediaKeys? mediaKeys;
 148
 149   // void, not any: https://www.w3.org/Bugs/Public/show_bug.cgi?id=26457
 150   [NewObject]
 151   Promise<void> setMediaKeys(MediaKeys? mediaKeys);
 152
 153   attribute EventHandler onencrypted;
 154
 155   attribute EventHandler onwaitingforkey;
 156 };
 157
 158 /**
 159  * These attributes are general testing attributes and they should only be used
 160  * in tests.
 161  */
 162 partial interface HTMLMediaElement {
 163   [Pref="media.useAudioChannelService.testing"]
 164   readonly attribute double computedVolume;
 165
 166   [Pref="media.useAudioChannelService.testing"]
 167   readonly attribute boolean computedMuted;
 168
 169   // Return true if the media is suspended because its document is inactive or
 170   // the docshell is inactive and explicitly being set to prohibit all media
 171   // from playing.
 172   [ChromeOnly]
 173   readonly attribute boolean isSuspendedByInactiveDocOrDocShell;
 174 };
 175
 176 /*
 177  * HTMLMediaElement::seekToNextFrame() is a Mozilla experimental feature.
 178  *
 179  * The SeekToNextFrame() method provides a way to access a video element's video
 180  * frames one by one without going through the realtime playback. So, it lets
 181  * authors use "frame" as unit to access the video element's underlying data,
 182  * instead of "time".
 183  *
 184  * The SeekToNextFrame() is a kind of seek operation, so normally, once it is
 185  * invoked, a "seeking" event is dispatched. However, if the media source has no
 186  * video data or is not seekable, the operation is ignored without filing the
 187  * "seeking" event.
 188  *
 189  * Once the SeekToNextFrame() is done, a "seeked" event should always be filed
 190  * and a "ended" event might also be filed depends on where the media element's
 191  * position before seeking was. There are two cases:
 192  * Assume the media source has n+1 video frames where n is a non-negative
 193  * integers and the frame sequence is indexed from zero.
 194  * (1) If the currentTime is at anywhere smaller than the n-th frame's beginning
 195  *     time, say the currentTime is now pointing to a position which is smaller
 196  *     than the x-th frame's beginning time and larger or equal to the (x-1)-th
 197  *     frame's beginning time, where x belongs to [1, n], then the
 198  *     SeekToNextFrame() operation seeks the media to the x-th frame, sets the
 199  *     media's currentTime to the x-th frame's beginning time and dispatches a
 200  *     "seeked" event.
 201  * (2) Otherwise, if the currentTime is larger or equal to the n-th frame's
 202  *     beginning time, then the SeekToNextFrame() operation sets the media's
 203  *     currentTime to the duration of the media source and dispatches a "seeked"
 204  *     event and an "ended" event.
 205  */
 206 partial interface HTMLMediaElement {
 207   [NewObject, Pref="media.seekToNextFrame.enabled"]
 208   Promise<void> seekToNextFrame();
 209 };
 210
 211 /* Internal testing only API */
 212 partial interface HTMLMediaElement {
 213   // These APIs are used to simulate visibility changes to help debug and write
 214   // tests about suspend-video-decoding.
 215   // - SetVisible() is for simulating visibility changes.
 216   // - HasSuspendTaint() is for querying that the element's decoder cannot suspend
 217   //   video decoding because it has been tainted by an operation, such as
 218   //   drawImage().
 219   // - isInViewPort is a boolean value which indicate whether media element is
 220   //   in view port.
 221   // - isVideoDecodingSuspended() is used to know whether video decoding has
 222   //   suspended.
 223   [Pref="media.test.video-suspend"]
 224   void setVisible(boolean aVisible);
 225
 226   [Pref="media.test.video-suspend"]
 227   boolean hasSuspendTaint();
 228
 229   [ChromeOnly]
 230   readonly attribute boolean isInViewPort;
 231
 232   [ChromeOnly]
 233   readonly attribute boolean isVideoDecodingSuspended;
 234
 235   [ChromeOnly]
 236   readonly attribute double totalVideoPlayTime;
 237
 238   [ChromeOnly]
 239   readonly attribute double totalVideoHDRPlayTime;
 240
 241   [ChromeOnly]
 242   readonly attribute double visiblePlayTime;
 243
 244   [ChromeOnly]
 245   readonly attribute double invisiblePlayTime;
 246
 247   [ChromeOnly]
 248   readonly attribute double videoDecodeSuspendedTime;
 249
 250   [ChromeOnly]
 251   readonly attribute double totalAudioPlayTime;
 252
 253   [ChromeOnly]
 254   readonly attribute double audiblePlayTime;
 255
 256   [ChromeOnly]
 257   readonly attribute double inaudiblePlayTime;
 258
 259   [ChromeOnly]
 260   readonly attribute double mutedPlayTime;
 261
 262   // These APIs are used for decoder doctor tests.
 263   [ChromeOnly]
 264   void setFormatDiagnosticsReportForMimeType(DOMString mimeType, DecoderDoctorReportType error);
 265
 266   [Throws, ChromeOnly]
 267   void setDecodeError(DOMString error);
 268
 269   [ChromeOnly]
 270   void setAudioSinkFailedStartup();
 271 };
 272
 273 /* Audio Output Devices API
 274  * https://w3c.github.io/mediacapture-output/
 275  */
 276 partial interface HTMLMediaElement {
 277   [SecureContext, Pref="media.setsinkid.enabled"]
 278   readonly attribute DOMString sinkId;
 279   [NewObject, SecureContext, Pref="media.setsinkid.enabled"]
 280   Promise<void> setSinkId(DOMString sinkId);
 281 };
 282
 283 /*
 284  * API that exposes whether a call to HTMLMediaElement.play() would be
 285  * blocked by autoplay policies; whether the promise returned by play()
 286  * would be rejected with NotAllowedError.
 287  */
 288 partial interface HTMLMediaElement {
 289   [Pref="media.allowed-to-play.enabled"]
 290   readonly attribute boolean allowedToPlay;
 291 };