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