media/mojo/mojom/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/mojom/media_types.mojom";
import "mojo/public/mojom/base/time.mojom";
import "ui/gfx/geometry/mojom/geometry.mojom";
import "url/mojom/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 {
  bool has_audio;
  bool has_video;
  bool is_background;  // Is report for playback in the background?
  bool is_muted;       // Is report for muted playback?
  bool is_mse;
  bool is_eme;
  bool is_embedded_media_experience;  // Playback from 'Downloads' on Android.
};

// Structure describing mutable properties for the current watch time report.
// The WatchTimeRecorder will use changes of these properties only for UKM
// reporting and will not interrupt UMA reporting for changes.
struct SecondaryPlaybackProperties {
  AudioCodec audio_codec;  // Note: We may not know the codec during all
  VideoCodec video_codec;  // playbacks (HLS, remoting, etc).
  VideoCodecProfile video_codec_profile;
  string audio_decoder_name;
  string video_decoder_name;
  EncryptionScheme audio_encryption_scheme;
  EncryptionScheme video_encryption_scheme;
  gfx.mojom.Size natural_size;  // Size of video frame; (0, 0) if audio only.
};

// 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: Not all values recorded by UKM are recorded by UMA. See implementations
// for more details; specifically WatchTimeRecorder::ShouldReportToUma().
//
// 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.
//
// Note: UKM metrics are only reported upon destruction of the recorder.
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_base.mojom.TimeDelta watch_time);

  // Request finalization (recording to UMA) 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);

  // Updates properties that the recorder will create a new UKM BasicPlayback
  // record for, but for which UMA will continue accruing.
  UpdateSecondaryProperties(SecondaryPlaybackProperties secondary_properties);

  // Lazily sets the autoplay status of the player. Must not be called multiple
  // times with different values.
  //
  // Note: this is using a setter because the status is only known when playback
  // starts but the reporter is created before.
  SetAutoplayInitiated(bool value);

  // Updates the duration maintained by the recorder. May be called any number
  // of times during playback. Duration is rounded to the most significant digit
  // when greater than 1 second for privacy protection. E.g., 14s will become
  // 10s, and 15s will become 20s. May be called any number of times.
  OnDurationChanged(mojo_base.mojom.TimeDelta duration);

  // Updates the total number of frames decoded and dropped. As with other
  // values, these are absolute and not relative since the last call.
  UpdateVideoDecodeStats(uint32 frames_decoded, uint32 frames_dropped);

  // 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 total_count);
  UpdateUnderflowDuration(int32 total_completed_count,
                          mojo_base.mojom.TimeDelta total_duration);

  // Updates the last known media timestamp for the video.
  OnCurrentTimestampChanged(mojo_base.mojom.TimeDelta last_timestamp);
};