2 * Copyright (C) 2009 Google Inc. All rights reserved.
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are
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
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.
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.
31 #ifndef THIRD_PARTY_BLINK_PUBLIC_PLATFORM_WEB_MEDIA_PLAYER_H_
32 #define THIRD_PARTY_BLINK_PUBLIC_PLATFORM_WEB_MEDIA_PLAYER_H_
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"
57 class PaintCanvasVideoRenderer;
62 class WebContentDecryptionModule;
63 class WebMediaPlayerSource;
66 enum class WebFullscreenVideoStatus;
68 class WebMediaPlayer {
75 kNetworkStateFormatError,
76 kNetworkStateNetworkError,
77 kNetworkStateDecodeError,
81 kReadyStateHaveNothing,
82 kReadyStateHaveMetadata,
83 kReadyStateHaveCurrentData,
84 kReadyStateHaveFutureData,
85 kReadyStateHaveEnoughData,
97 kCorsModeUseCredentials,
100 // Reported to UMA. Do not change existing values.
103 kLoadTypeMediaSource = 1,
104 kLoadTypeMediaStream = 2,
105 kLoadTypeMax = kLoadTypeMediaStream,
108 typedef WebString TrackId;
109 enum TrackType { kTextTrack, kAudioTrack, kVideoTrack };
111 // This must stay in sync with WebGLRenderingContextBase::TexImageFunctionID.
112 enum TexImageFunctionID {
119 // Returned by Load() to signal when a players choose to defer (e.g. as part
121 enum LoadTiming { kImmediate, kDeferred };
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;
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;
137 virtual ~WebMediaPlayer() = default;
139 virtual LoadTiming Load(LoadType,
140 const WebMediaPlayerSource&,
142 bool is_cache_disabled) = 0;
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;
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;
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;
161 // Sets a flag indicating whether the audio stream was played with user
163 virtual void SetWasPlayedWithUserActivation(
164 bool was_played_with_user_activation) = 0;
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;
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() {}
176 virtual void RequestRemotePlaybackDisabled(bool disabled) {}
177 virtual void RequestMediaRemoting() {}
178 virtual void FlingingStarted() {}
179 virtual void FlingingStopped() {}
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() {}
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;
197 // Attempts to switch the audio output device.
198 virtual bool SetSinkId(const WebString& sing_id,
199 WebSetSinkIdCompleteCallback) = 0;
201 // True if the loaded media has a playable video/audio track.
202 virtual bool HasVideo() const = 0;
203 virtual bool HasAudio() const = 0;
205 // Dimension of the video.
206 virtual gfx::Size NaturalSize() const = 0;
208 virtual gfx::Size VisibleSize() const = 0;
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;
220 virtual bool PausedWhenHidden() const { return false; }
222 // Internal states of loading and network.
223 virtual NetworkState GetNetworkState() const = 0;
224 virtual ReadyState GetReadyState() const = 0;
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;
232 virtual bool DidLoadingProgress() = 0;
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;
239 virtual double MediaTimeForTimeValue(double time_value) const = 0;
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;
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;
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;
260 // Set the player as the persistent video. Persistent video should hide its
261 // controls and go fullscreen.
262 virtual void SetPersistentState(bool persistent) {}
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) {}
268 // Suspends the player for the host frame closed.
269 virtual void SuspendForFrameClosed() = 0;
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;
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
278 virtual bool HasReadableVideoFrame() const = 0;
280 // Renders the current frame into the provided cc::PaintCanvas.
281 virtual void Paint(cc::PaintCanvas*, const gfx::Rect&, cc::PaintFlags&) = 0;
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
287 virtual scoped_refptr<media::VideoFrame> GetCurrentFrameThenUpdate() = 0;
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;
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() {
303 virtual scoped_refptr<WebAudioSourceProviderImpl> GetAudioSourceProvider() {
307 virtual void SetContentDecryptionModule(
308 WebContentDecryptionModule* cdm,
309 WebContentDecryptionModuleResult result) {
310 result.CompleteWithError(
311 kWebContentDecryptionModuleExceptionNotSupportedError, 0, "ERROR");
314 // Sets the poster image URL.
315 virtual void SetPoster(const WebURL& poster) {}
317 // Inform WebMediaPlayer when the element has entered/exited fullscreen.
318 virtual void EnteredFullscreen() {}
319 virtual void ExitedFullscreen() {}
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) {}
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.
331 // TODO(zqzhang): merge with BecameDominantVisibleContent(). See
332 // https://crbug.com/696211
333 virtual void SetIsEffectivelyFullscreen(WebFullscreenVideoStatus) {}
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) {}
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) {}
347 // Callback called whenever the media element display type changes. By
348 // default, the display type is `kInline`.
349 virtual void OnDisplayTypeChanged(DisplayType) {}
351 // Test helper methods for exercising media suspension.
352 virtual void ForceStaleStateForTesting(ReadyState target_state) {}
353 virtual bool IsSuspendedForTesting() { return false; }
355 virtual bool DidLazyLoad() const { return false; }
356 virtual void OnBecameVisible() {}
358 virtual bool IsOpaque() const { return false; }
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; }
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;
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(); }
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() {
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() {}
392 virtual base::WeakPtr<WebMediaPlayer> AsWeakPtr() = 0;
394 // Adjusts the frame sink hierarchy for the media frame sink.
395 virtual void RegisterFrameSinkHierarchy() {}
396 virtual void UnregisterFrameSinkHierarchy() {}
398 #if BUILDFLAG(IS_TIZEN_TV)
399 virtual void SetParentalRatingResult(bool is_pass) {}
405 #endif // THIRD_PARTY_BLINK_PUBLIC_PLATFORM_WEB_MEDIA_PLAYER_H_