media/mojo/interfaces/watch_time_recorder.mojom

// Copyright 2017 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.

module media.mojom;

import "media/mojo/interfaces/media_types.mojom";
import "mojo/common/time.mojom";
import "ui/gfx/geometry/mojo/geometry.mojom";
import "url/mojo/origin.mojom";

// Structure describing immutable properties for the current watch time report.
// If any of these properties change a new WatchTimeRecorder will be requested.
struct PlaybackProperties {
  AudioCodec audio_codec;  // Note: We may not know the codec during all
  VideoCodec video_codec;  // playbacks (HLS, remoting, etc).
  bool has_audio;          // Note: Due to the above, we also need these bools
  bool has_video;          // for audio and video presence.
  bool is_mse;
  bool is_eme;
  bool is_embedded_media_experience;  // Playback from 'Downloads' on Android.
  gfx.mojom.Size natural_size;  // Size of video frame; (0, 0) if audio only.
  url.mojom.Origin origin;
};

// Interface by which the WatchTimeReporter reports watch time. This is used to
// cache the reported values in a process without fast shutdown since we would
// otherwise lose watch time data. See the WatchTimeReporter for more details on
// how and when watch time is reported.
//
// Values will be recorded to UMA and UKM upon requesting finalization or the
// destruction of the WatchTimeRecorder binding.
//
// Note: There are some UMA values that the WatchTimeRecorder will generate
// based on the recorded keys and values. Such metrics will only be generated
// when finalizing everything via FinalizeWatchTime({}) or destruction.
interface WatchTimeRecorder {
  // Reports |watch_time| for |key|. Note this should be an absolute value and
  // not a delta since the last call. Any necessary relative processing should
  // be handled prior to calling this method. As described in WatchTimeReporter,
  // |watch_time| is the elapsed media (not wall clock) time for |key|.
  RecordWatchTime(WatchTimeKey key, mojo.common.mojom.TimeDelta watch_time);

  // Request finalization (recording to UMA and UKM) for the given keys.
  // If no keys are specified, all currently held keys will be finalized.
  FinalizeWatchTime(array<WatchTimeKey> watch_time_keys);

  // Called when a playback ends in error. The status is reported to UKM when
  // finalizing UKM watch time.
  OnError(PipelineStatus status);

  // Indicates that an underflow event has occurred while collecting watch time.
  // Used to report mean values for rebuffering metrics. As with watch time,
  // this is an absolute count and not relative since the last call.
  UpdateUnderflowCount(int32 count);
};

// Provider interface used to avoid having a SetPlaybackProperties() type method
// on the WatchTimeRecorder interface.
interface WatchTimeRecorderProvider {
  // Creates a WatchTimeRecorder instance using |properties|. If any of those
  // properties changes, a new recorder should be requested.
  AcquireWatchTimeRecorder(PlaybackProperties properties,
                           WatchTimeRecorder& recorder);
};