Add watch time metrics for HTML5 media playback.

media/blink/watch_time_reporter.h

Index: media/blink/watch_time_reporter.h
diff --git a/media/blink/watch_time_reporter.h b/media/blink/watch_time_reporter.h
new file mode 100644
index 0000000000000000000000000000000000000000..e1fd7e8bf52ddbde2554717289ad693fc6d4acd4
--- /dev/null
+++ b/media/blink/watch_time_reporter.h
@@ -0,0 +1,154 @@
+// Copyright 2016 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef MEDIA_BLINK_WATCH_TIME_REPORTER_H_
+#define MEDIA_BLINK_WATCH_TIME_REPORTER_H_
+
+#include "base/callback.h"
+#include "base/power_monitor/power_observer.h"
+#include "base/time/time.h"
+#include "base/timer/timer.h"
+#include "media/base/timestamp_constants.h"
+#include "media/blink/media_blink_export.h"
+#include "ui/gfx/geometry/size.h"
+
+namespace media {
+
+// Class for monitoring and reporting watch time in response to various state
+// changes during the playback of media. At present we are only recording the
+// watch time for audio+video playbacks.
+// TODO(dalecurtis): We want to introduce a similar "listening time" metric in
+// the near future to track audio only cases.
+//
+// Watch time for our purposes is defined as the amount of elapsed media time
+// for audio+video media. A minimum of 7 seconds of unmuted, foreground media
+// must be watched to start watch time monitoring. Watch time is checked every
+// 5 seconds from then on and reported to multiple buckets: All, MSE, SRC, EME,
+// AC, and battery.
+//
+// Any one of paused, hidden, or muted is sufficient to stop watch time metric
+// reports. Each of these has a hysteresis where if the state change is undone
+// within 5 seconds, the watch time will be counted as uninterrupted.
+//
+// Power events (on/off battery power) have a similar hysteresis, but unlike
+// the aforementioned properties, will not stop metric collection.
+//
+// Each seek event will result in a new watch time metric being started and the
+// old metric finalized as accurately as possible.
+class MEDIA_BLINK_EXPORT WatchTimeReporter : base::PowerObserver {
+ public:
+  // Constructor for the reporter; all requested metadata should be fully known
+  // before attempting construction as incorrect values will result in the wrong
+  // watch time metrics being reported.
+  //
+  // |initial_video_size| required to ensure that the video track has sufficient
+  // size for watch time reporting.
+  //
+  // |get_media_time_cb| must return the current playback time in terms of media
+  // time, not wall clock time! Using media time instead of wall clock time
+  // allows us to avoid a whole class of issues around clock changes during
+  // suspend and resume.
+  // TODO(dalecurtis): Should we only report when rate == 1.0? Should we scale
+  // the elapsed media time instead?
+  using GetMediaTimeCB = base::Callback<base::TimeDelta(void)>;

[sandersd (OOO until July 31), 2016/08/04 23:06:26]

Move above comment.

[DaleCurtis, 2016/08/08 23:16:42]

Done.

+  WatchTimeReporter(bool has_audio,
+                    bool has_video,
+                    bool is_mse,
+                    bool is_encrypted,
+                    const gfx::Size& initial_video_size,
+                    const GetMediaTimeCB& get_media_time_cb);
+  ~WatchTimeReporter() override;
+
+  // These methods are used to ensure that watch time is only reported for
+  // media that is actually playing. They should be called whenever the media
+  // starts or stops playing for any reason.
+  void OnPlaying();
+  void OnPaused();
+
+  // This will finalize any outstanding watch time reports and start a new
+  // reporting session beginning from |seek_timestamp|.
+  void OnSeeking(base::TimeDelta seek_timestamp);
+
+  // This method is used to ensure that watch time is only reported for media
+  // that is actually audible to the user. It should be called whenever the
+  // volume changes.
+  //
+  // Note: This does not catch all cases. E.g., headphones that are being
+  // listened too, or even OS level volume state.
+  void OnVolumeChange(double volume);
+
+  // These methods are used to ensure that watch time is only reported for
+  // videos that are actually visible to the user. They should be called when
+  // the video is shown or hidden respectively.
+  //
+  // TODO(dalecurtis): At present, this is only called when the entire content
+  // window goes into the foreground or background respectively; i.e. it does
+  // not catch cases where the video is in the foreground but out of the view
+  // port. We need a method for rejecting out of view port videos.
+  void OnShown();
+  void OnHidden();
+
+ private:
+  friend class WatchTimeReporterTest;
+
+  // Histogram names used for reporting. Exported for testing purposes only.
+  static const char kHistogramAudioVideoAll[];
+  static const char kHistogramAudioVideoMse[];
+  static const char kHistogramAudioVideoEme[];
+  static const char kHistogramAudioVideoSrc[];
+  static const char kHistogramAudioVideoBattery[];
+  static const char kHistogramAudioVideoAc[];
+
+  // base::PowerObserver implementation.
+  //
+  // We only observe power source changes. We don't need to observe suspend and
+  // resume events because we report watch time in terms of elapsed media time
+  // and not in terms of elapsed real time.
+  void OnPowerStateChange(bool on_battery_power) override;
+
+  bool ShouldReportWatchTime();
+  void StartReportingTimer(base::TimeDelta start_timestamp);

[sandersd (OOO until July 31), 2016/08/04 23:06:26]

nit: MaybeStart/MaybeFinalize?

[DaleCurtis, 2016/08/08 23:16:42]

Done.

+  enum class FinalizeTime { IMMEDIATELY, ON_NEXT_UPDATE };
+  void FinalizeWatchTime(FinalizeTime finalize_time);
+  void UpdateWatchTime();
+
+  // Initialized during construction.
+  const bool has_audio_;
+  const bool has_video_;
+  const bool is_mse_;
+  const bool is_encrypted_;
+  const gfx::Size initial_video_size_;
+  const GetMediaTimeCB get_media_time_cb_;
+
+  // The amount of time between each UpdateWatchTime(); this is the frequency by
+  // which the histograms are updated. In the event of a process crash or kill
+  // this is also the most amount of watch time that we might lose.
+  base::TimeDelta reporting_interval_ = base::TimeDelta::FromSeconds(5);
+
+  base::RepeatingTimer reporting_timer_;
+
+  // Updated by the OnXXX() methods above.
+  bool is_on_battery_power_ = false;
+  bool is_playing_ = false;
+  bool is_visible_ = true;
+  double volume_ = 1.0;
+
+  // The last media timestamp seen by UpdateWatchTime().
+  base::TimeDelta last_media_timestamp_ = kNoTimestamp;
+
+  // The starting and ending timestamps used for reporting watch time.
+  base::TimeDelta start_timestamp_;
+  base::TimeDelta end_timestamp_ = kNoTimestamp;
+
+  // Similar to the above but tracks watch time relative to whether or not
+  // battery or AC power is being used.
+  base::TimeDelta start_timestamp_for_power_;
+  base::TimeDelta end_timestamp_for_power_ = kNoTimestamp;
+
+  DISALLOW_COPY_AND_ASSIGN(WatchTimeReporter);
+};
+
+}  // namespace media
+
+#endif  // MEDIA_BLINK_WATCH_TIME_REPORTER_H_