Add watch time metrics for HTML5 media playback.

tools/metrics/histograms/histograms.xml

Index: tools/metrics/histograms/histograms.xml
diff --git a/tools/metrics/histograms/histograms.xml b/tools/metrics/histograms/histograms.xml
index 41d9d2185ad12396f0720b5b113db432ff2839a1..0b3a94cbe15e97cac8521c5e66d7bb5b06760c25 100644
--- a/tools/metrics/histograms/histograms.xml
+++ b/tools/metrics/histograms/histograms.xml
@@ -23477,6 +23477,26 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
   </summary>
 </histogram>
 
+<histogram name="Media.WatchTime">
+  <owner>dalecurtis@chromium.org</owner>
+  <summary>
+    Watch time is defined as the amount of elapsed media time for audio+video
+    media aggregated per player instance. A minimum of 7 seconds of unmuted,
+    foreground media must be watched to start watch time monitoring. Watch time
+    is checked on a regular basis from then on and reported to multiple buckets.

[sandersd (OOO until July 31), 2016/08/17 01:11:25]

Nit: "multiple buckets" is ambiguous (although I suppose we always call the
histogram components "bins").

[DaleCurtis, 2016/08/17 20:30:44]

Done; removed bucket terminology.

+
+    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 some time, 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.

[sandersd (OOO until July 31), 2016/08/17 01:11:25]

I had assumed that what we wanted to record was the total time each player
played for. What's the intuition for why this approach (breaking on seek) is
better for our analysis?

[DaleCurtis, 2016/08/17 20:30:44]

I think this is worth exploring more, but for the first cut capping to
[seek_time, duration] simplifies the metrics collection by avoiding any additive
metrics.

We can change this later without any harm or decide that these metrics should
always be bounded by the duration of the clip (common) and only have aggregate
metrics at the scope of media internals. I prefer the latter but am happy to
debate.

+  </summary>
+</histogram>
+
 <histogram name="Media.WindowsCoreAudioInput" enum="BooleanSuccess">
   <owner>henrika@chromium.org</owner>
   <summary>
@@ -99098,6 +99118,24 @@ To add a new entry, add it with any value and run test to compute valid value.
   <affected-histogram name="Media.VideoCaptureManager"/>
 </histogram_suffixes>
 
+<histogram_suffixes name="MediaWatchTimeCategories" separator=".">
+  <suffix name="AudioVideo.All"
+      label="Watch time for all media with both an audio and video track."/>
+  <suffix name="AudioVideo.AC"
+      label="Watch time for all media with both an audio and video track on
+             AC power."/>
+  <suffix name="AudioVideo.Battery"
+      label="Watch time for all media with both an audio and video track on
+             battery power."/>
+  <suffix name="AudioVideo.MSE"
+      label="Watch time for MSE media with both an audio and video track."/>
+  <suffix name="AudioVideo.SRC"
+      label="Watch time for SRC media with both an audio and video track."/>
+  <suffix name="AudioVideo.EME"
+      label="Watch time for EME media with both an audio and video track."/>
+  <affected-histogram name="Media.WatchTime"/>
+</histogram_suffixes>
+
 <histogram_suffixes name="MobileDownloadBytesDownloadedTypes" separator=".">
   <suffix name="ChromeNetworkStack.Failure"/>
   <suffix name="ChromeNetworkStack.Success"/>