third_party/blink/public/platform/web_media_player.h

   1 /*
   2  * Copyright (C) 2009 Google Inc. All rights reserved.
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions are
   6  * met:
   7  *
   8  *     * Redistributions of source code must retain the above copyright
   9  * notice, this list of conditions and the following disclaimer.
  10  *     * Redistributions in binary form must reproduce the above
  11  * copyright notice, this list of conditions and the following disclaimer
  12  * in the documentation and/or other materials provided with the
  13  * distribution.
  14  *     * Neither the name of Google Inc. nor the names of its
  15  * contributors may be used to endorse or promote products derived from
  16  * this software without specific prior written permission.
  17  *
  18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  21  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  22  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  23  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  24  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  25  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  26  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  28  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29  */
  30
  31 #ifndef THIRD_PARTY_BLINK_PUBLIC_PLATFORM_WEB_MEDIA_PLAYER_H_
  32 #define THIRD_PARTY_BLINK_PUBLIC_PLATFORM_WEB_MEDIA_PLAYER_H_
  33
  34 #include "base/memory/scoped_refptr.h"
  35 #include "base/memory/weak_ptr.h"
  36 #include "base/time/time.h"
  37 #include "components/viz/common/surfaces/surface_id.h"
  38 #include "media/base/video_frame.h"
  39 #include "media/base/video_frame_metadata.h"
  40 #include "third_party/abseil-cpp/absl/types/optional.h"
  41 #include "third_party/blink/public/common/media/display_type.h"
  42 #include "third_party/blink/public/platform/web_content_decryption_module.h"
  43 #include "third_party/blink/public/platform/web_media_source.h"
  44 #include "third_party/blink/public/platform/web_set_sink_id_callbacks.h"
  45 #include "third_party/blink/public/platform/web_string.h"
  46 #include "third_party/blink/public/platform/webaudiosourceprovider_impl.h"
  47 #include "ui/gfx/geometry/rect.h"
  48 #include "ui/gfx/geometry/size.h"
  49 #include "url/gurl.h"
  50
  51 namespace cc {
  52 class PaintCanvas;
  53 class PaintFlags;
  54 }  // namespace cc
  55
  56 namespace media {
  57 class PaintCanvasVideoRenderer;
  58 }
  59
  60 namespace blink {
  61
  62 class WebContentDecryptionModule;
  63 class WebMediaPlayerSource;
  64 class WebString;
  65 class WebURL;
  66 enum class WebFullscreenVideoStatus;
  67
  68 class WebMediaPlayer {
  69  public:
  70   enum NetworkState {
  71     kNetworkStateEmpty,
  72     kNetworkStateIdle,
  73     kNetworkStateLoading,
  74     kNetworkStateLoaded,
  75     kNetworkStateFormatError,
  76     kNetworkStateNetworkError,
  77     kNetworkStateDecodeError,
  78   };
  79
  80   enum ReadyState {
  81     kReadyStateHaveNothing,
  82     kReadyStateHaveMetadata,
  83     kReadyStateHaveCurrentData,
  84     kReadyStateHaveFutureData,
  85     kReadyStateHaveEnoughData,
  86   };
  87
  88   enum Preload {
  89     kPreloadNone,
  90     kPreloadMetaData,
  91     kPreloadAuto,
  92   };
  93
  94   enum CorsMode {
  95     kCorsModeUnspecified,
  96     kCorsModeAnonymous,
  97     kCorsModeUseCredentials,
  98   };
  99
 100   // Reported to UMA. Do not change existing values.
 101   enum LoadType {
 102     kLoadTypeURL = 0,
 103     kLoadTypeMediaSource = 1,
 104     kLoadTypeMediaStream = 2,
 105     kLoadTypeMax = kLoadTypeMediaStream,
 106   };
 107
 108   typedef WebString TrackId;
 109   enum TrackType { kTextTrack, kAudioTrack, kVideoTrack };
 110
 111   // This must stay in sync with WebGLRenderingContextBase::TexImageFunctionID.
 112   enum TexImageFunctionID {
 113     kTexImage2D,
 114     kTexSubImage2D,
 115     kTexImage3D,
 116     kTexSubImage3D
 117   };
 118
 119   // Returned by Load() to signal when a players choose to defer (e.g. as part
 120   // of pre-rendering)
 121   enum LoadTiming { kImmediate, kDeferred };
 122
 123   // For video.requestVideoFrameCallback(). https://wicg.github.io/video-rvfc/
 124   struct VideoFramePresentationMetadata {
 125     uint32_t presented_frames;
 126     base::TimeTicks presentation_time;
 127     base::TimeTicks expected_display_time;
 128     int width;
 129     int height;
 130     base::TimeDelta media_time;
 131     media::VideoFrameMetadata metadata;
 132     scoped_refptr<media::VideoFrame> frame;
 133     base::TimeDelta rendering_interval;
 134     base::TimeDelta average_frame_duration;
 135   };
 136
 137   virtual ~WebMediaPlayer() = default;
 138
 139   virtual LoadTiming Load(LoadType,
 140                           const WebMediaPlayerSource&,
 141                           CorsMode,
 142                           bool is_cache_disabled) = 0;
 143
 144   // Playback controls.
 145   virtual void Play() = 0;
 146   virtual void Pause() = 0;
 147   virtual void Seek(double seconds) = 0;
 148   virtual void SetRate(double) = 0;
 149   virtual void SetVolume(double) = 0;
 150
 151   // Set a target value for media pipeline latency for post-decode buffering.
 152   // |seconds| is a target value for post-decode buffering latency. As a default
 153   // |seconds| may also be NaN, indicating no preference. NaN will also be the
 154   // value if the hint is cleared.
 155   virtual void SetLatencyHint(double seconds) = 0;
 156
 157   // Sets a flag indicating that the WebMediaPlayer should apply pitch
 158   // adjustments when using a playback rate other than 1.0.
 159   virtual void SetPreservesPitch(bool preserves_pitch) = 0;
 160
 161   // Sets a flag indicating whether the audio stream was played with user
 162   // activation.
 163   virtual void SetWasPlayedWithUserActivation(
 164       bool was_played_with_user_activation) = 0;
 165
 166   // The associated media element is going to enter Picture-in-Picture. This
 167   // method should make sure the player is set up for this and has a SurfaceId
 168   // as it will be needed.
 169   virtual void OnRequestPictureInPicture() = 0;
 170
 171   // Called to notify about changes of the associated media element's media
 172   // time, playback rate, and duration. During uninterrupted playback, the
 173   // calls are still made periodically.
 174   virtual void OnTimeUpdate() {}
 175
 176   virtual void RequestRemotePlaybackDisabled(bool disabled) {}
 177   virtual void RequestMediaRemoting() {}
 178   virtual void FlingingStarted() {}
 179   virtual void FlingingStopped() {}
 180
 181   virtual void SetPreload(Preload) {}
 182   virtual WebTimeRanges Buffered() const = 0;
 183   virtual WebTimeRanges Seekable() const = 0;
 184 #if defined(TIZEN_MULTIMEDIA)
 185   virtual void Suspend() {}
 186   virtual void Resume() {}
 187   virtual bool SuspendedByPlayer() { return false; }
 188   virtual void OnLivePlaybackComplete() {}
 189 #endif
 190
 191   // Called when the backing media element and the page it is attached to is
 192   // frozen, meaning that the page is no longer being rendered but nothing has
 193   // yet been deconstructed. This may occur in several cases, such as bfcache
 194   // for instant backwards and forwards navigation.
 195   virtual void OnFrozen() = 0;
 196
 197   // Attempts to switch the audio output device.
 198   virtual bool SetSinkId(const WebString& sing_id,
 199                          WebSetSinkIdCompleteCallback) = 0;
 200
 201   // True if the loaded media has a playable video/audio track.
 202   virtual bool HasVideo() const = 0;
 203   virtual bool HasAudio() const = 0;
 204
 205   // Dimension of the video.
 206   virtual gfx::Size NaturalSize() const = 0;
 207
 208   virtual gfx::Size VisibleSize() const = 0;
 209
 210   // Getters of playback state.
 211   virtual bool Paused() const = 0;
 212   virtual bool Seeking() const = 0;
 213   // MSE allows authors to assign double values for duration.
 214   // Here, we return double rather than TimeDelta to ensure
 215   // that authors are returned exactly the value that they assign.
 216   virtual double Duration() const = 0;
 217   virtual double CurrentTime() const = 0;
 218   virtual bool IsEnded() const = 0;
 219
 220   virtual bool PausedWhenHidden() const { return false; }
 221
 222   // Internal states of loading and network.
 223   virtual NetworkState GetNetworkState() const = 0;
 224   virtual ReadyState GetReadyState() const = 0;
 225
 226   // Returns an implementation-specific human readable error message, or an
 227   // empty string if no message is available. The message should begin with a
 228   // UA-specific-error-code (without any ':'), optionally followed by ': ' and
 229   // further description of the error.
 230   virtual WebString GetErrorMessage() const = 0;
 231
 232   virtual bool DidLoadingProgress() = 0;
 233
 234   // Returns true if the response is CORS-cross-origin and so we shouldn't be
 235   // allowing media to play through webaudio.
 236   // This should be called after the response has arrived.
 237   virtual bool WouldTaintOrigin() const = 0;
 238
 239   virtual double MediaTimeForTimeValue(double time_value) const = 0;
 240
 241   virtual unsigned DecodedFrameCount() const = 0;
 242   virtual unsigned DroppedFrameCount() const = 0;
 243   virtual unsigned CorruptedFrameCount() const { return 0; }
 244   virtual uint64_t AudioDecodedByteCount() const = 0;
 245   virtual uint64_t VideoDecodedByteCount() const = 0;
 246
 247   // Returns false if any of the HTTP responses which make up the video data
 248   // loaded so far have failed the TAO check as defined by Fetch
 249   // (https://fetch.spec.whatwg.org/#tao-check), or true otherwise. Video
 250   // streams which do not originate from HTTP responses should return true here.
 251   // This check is used to determine if timing information from those responses
 252   // may be exposed to the page in Largest Contentful Paint performance entries.
 253   virtual bool PassedTimingAllowOriginCheck() const = 0;
 254
 255   // Set the volume multiplier to control audio ducking.
 256   // Output volume should be set to |player_volume| * |multiplier|. The range
 257   // of |multiplier| is [0, 1], where 1 indicates normal (non-ducked) playback.
 258   virtual void SetVolumeMultiplier(double multiplier) = 0;
 259
 260   // Set the player as the persistent video. Persistent video should hide its
 261   // controls and go fullscreen.
 262   virtual void SetPersistentState(bool persistent) {}
 263
 264   // Notify the player that it is now eligible to start recording power
 265   // measurements if |state| is true, else it is no longer eligible.
 266   virtual void SetPowerExperimentState(bool enabled) {}
 267
 268   // Suspends the player for the host frame closed.
 269   virtual void SuspendForFrameClosed() = 0;
 270
 271   // Returns true if the player has a frame available for presentation. Usually
 272   // this just means the first frame has been delivered.
 273   virtual bool HasAvailableVideoFrame() const = 0;
 274
 275   // Returns true if the player has a frame available for presentation, and the
 276   // frame is readable, i.e. it's not protected and can be read back into CPU
 277   // memory.
 278   virtual bool HasReadableVideoFrame() const = 0;
 279
 280   // Renders the current frame into the provided cc::PaintCanvas.
 281   virtual void Paint(cc::PaintCanvas*, const gfx::Rect&, cc::PaintFlags&) = 0;
 282
 283   // Similar to Paint(), but just returns the frame directly instead of trying
 284   // to upload or convert it. Note: This may kick off a process to update the
 285   // current frame for a future call in some cases. Returns nullptr if no frame
 286   // is available.
 287   virtual scoped_refptr<media::VideoFrame> GetCurrentFrameThenUpdate() = 0;
 288
 289   // Return current video frame unique id from compositor. The query is readonly
 290   // and should avoid any extra ops. Function returns absl::nullopt if current
 291   // frame is invalid or fails to access current frame.
 292   virtual absl::optional<media::VideoFrame::ID> CurrentFrameId() const = 0;
 293
 294   // Provides a PaintCanvasVideoRenderer instance owned by this WebMediaPlayer.
 295   // Useful for ensuring that the paint/texturing operation for current frame is
 296   // cached in cases of repainting/retexturing (since clients may not know that
 297   // the underlying frame is unchanged). May only be used on the main thread and
 298   // should not be held outside the scope of a single call site.
 299   virtual media::PaintCanvasVideoRenderer* GetPaintCanvasVideoRenderer() {
 300     return nullptr;
 301   }
 302
 303   virtual scoped_refptr<WebAudioSourceProviderImpl> GetAudioSourceProvider() {
 304     return nullptr;
 305   }
 306
 307   virtual void SetContentDecryptionModule(
 308       WebContentDecryptionModule* cdm,
 309       WebContentDecryptionModuleResult result) {
 310     result.CompleteWithError(
 311         kWebContentDecryptionModuleExceptionNotSupportedError, 0, "ERROR");
 312   }
 313
 314   // Sets the poster image URL.
 315   virtual void SetPoster(const WebURL& poster) {}
 316
 317   // Inform WebMediaPlayer when the element has entered/exited fullscreen.
 318   virtual void EnteredFullscreen() {}
 319   virtual void ExitedFullscreen() {}
 320
 321   // Inform WebMediaPlayer when the element starts/stops being the dominant
 322   // visible content. This will only be called after the monitoring of the
 323   // intersection with viewport is activated by calling
 324   // WebMediaPlayerClient::ActivateViewportIntersectionMonitoring().
 325   virtual void BecameDominantVisibleContent(bool is_dominant) {}
 326
 327   // Inform WebMediaPlayer when the element starts/stops being the effectively
 328   // fullscreen video, i.e. being the fullscreen element or child of the
 329   // fullscreen element, and being dominant in the viewport.
 330   //
 331   // TODO(zqzhang): merge with BecameDominantVisibleContent(). See
 332   // https://crbug.com/696211
 333   virtual void SetIsEffectivelyFullscreen(WebFullscreenVideoStatus) {}
 334
 335   virtual void EnabledAudioTracksChanged(
 336       const WebVector<TrackId>& enabled_track_ids) {}
 337   // |selected_track_id| is null if no track is selected.
 338   virtual void SelectedVideoTrackChanged(TrackId* selected_track_id) {}
 339
 340   // Callback called whenever the media element may have received or last native
 341   // controls. It might be called twice with the same value: the caller has to
 342   // check if the value have changed if it only wants to handle this case.
 343   // This method is not used to say express if the native controls are visible
 344   // but if the element is using them.
 345   virtual void OnHasNativeControlsChanged(bool) {}
 346
 347   // Callback called whenever the media element display type changes. By
 348   // default, the display type is `kInline`.
 349   virtual void OnDisplayTypeChanged(DisplayType) {}
 350
 351   // Test helper methods for exercising media suspension.
 352   virtual void ForceStaleStateForTesting(ReadyState target_state) {}
 353   virtual bool IsSuspendedForTesting() { return false; }
 354
 355   virtual bool DidLazyLoad() const { return false; }
 356   virtual void OnBecameVisible() {}
 357
 358   virtual bool IsOpaque() const { return false; }
 359
 360   // Returns the id given by the WebMediaPlayerDelegate. This is used by the
 361   // Blink code to pass a player id to mojo services.
 362   // TODO(mlamouri): remove this and move the id handling to Blink.
 363   virtual int GetDelegateId() { return -1; }
 364
 365   // Returns the SurfaceId the video element is currently using.
 366   // Returns absl::nullopt if the element isn't a video or doesn't have a
 367   // SurfaceId associated to it.
 368   virtual absl::optional<viz::SurfaceId> GetSurfaceId() {
 369     return absl::nullopt;
 370   }
 371
 372   // Provide the media URL, after any redirects are applied.  May return an
 373   // empty GURL, which will be interpreted as "use the original URL".
 374   virtual GURL GetSrcAfterRedirects() { return GURL(); }
 375
 376   // Register a request to be notified the next time a video frame is presented
 377   // to the compositor. The request will be completed via
 378   // WebMediaPlayerClient::OnRequestVideoFrameCallback(). The frame info can be
 379   // retrieved via GetVideoFramePresentationMetadata().
 380   // See https://wicg.github.io/video-rvfc/.
 381   virtual void RequestVideoFrameCallback() {}
 382   virtual std::unique_ptr<VideoFramePresentationMetadata>
 383   GetVideoFramePresentationMetadata() {
 384     return nullptr;
 385   }
 386
 387   // Forces the WebMediaPlayer to update its frame if it is stale. This is used
 388   // during immersive WebXR sessions with the RequestVideoFrameCallback() API,
 389   // when compositors aren't driving frame updates.
 390   virtual void UpdateFrameIfStale() {}
 391
 392   virtual base::WeakPtr<WebMediaPlayer> AsWeakPtr() = 0;
 393
 394   // Adjusts the frame sink hierarchy for the media frame sink.
 395   virtual void RegisterFrameSinkHierarchy() {}
 396   virtual void UnregisterFrameSinkHierarchy() {}
 397
 398 #if BUILDFLAG(IS_TIZEN_TV)
 399   virtual void SetParentalRatingResult(bool is_pass) {}
 400 #endif
 401 };
 402
 403 }  // namespace blink
 404
 405 #endif  // THIRD_PARTY_BLINK_PUBLIC_PLATFORM_WEB_MEDIA_PLAYER_H_