media/base/time_source.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef MEDIA_BASE_TIME_SOURCE_H_
   6 #define MEDIA_BASE_TIME_SOURCE_H_
   7
   8 #include <vector>
   9
  10 #include "base/callback.h"
  11 #include "base/time/time.h"
  12 #include "media/base/media_export.h"
  13
  14 namespace media {
  15
  16 // A TimeSource is capable of providing the current media time.
  17 class MEDIA_EXPORT TimeSource {
  18  public:
  19   // Helper alias for converting media timestamps into a wall clock timestamps.
  20   using WallClockTimeCB =
  21       base::Callback<bool(const std::vector<base::TimeDelta>&,
  22                           std::vector<base::TimeTicks>*)>;
  23
  24   TimeSource() {}
  25   virtual ~TimeSource() {}
  26
  27   // Signal the time source to start ticking. It is expected that values from
  28   // CurrentMediaTime() will start increasing.
  29   virtual void StartTicking() = 0;
  30
  31   // Signal the time source to stop ticking. It is expected that values from
  32   // CurrentMediaTime() will remain constant.
  33   virtual void StopTicking() = 0;
  34
  35   // Updates the current playback rate. It is expected that values from
  36   // CurrentMediaTime() will eventually reflect the new playback rate (e.g., the
  37   // media time will advance at half speed if the rate was set to 0.5).
  38   virtual void SetPlaybackRate(double playback_rate) = 0;
  39
  40   // Sets the media time to start ticking from. Only valid to call while the
  41   // time source is not ticking.
  42   virtual void SetMediaTime(base::TimeDelta time) = 0;
  43
  44   // Returns the current media timestamp relative to the timestamp set by
  45   // SetMediaTime().
  46   //
  47   // Values returned are intended for informational purposes, such as displaying
  48   // UI with the current minute and second count. While it is guaranteed values
  49   // will never go backwards, the frequency at which they update may be low.
  50   virtual base::TimeDelta CurrentMediaTime() = 0;
  51
  52   // Converts a vector of media timestamps into a vector of wall clock times. If
  53   // the media time is stopped, returns false and does not modify the output
  54   // vector. Returns true and converts all timestamps otherwise. Guarantees that
  55   // wall clock time does not go backwards for monotonically increasing media
  56   // timestamps.
  57   //
  58   // Each timestamp converted from |media_timestamps| will be pushed into
  59   // |wall_clock_times| such that after all timestamps are converted, the two
  60   // vectors are parallel (media_timestamps[i] -> wall_clock_times[i]).
  61   //
  62   // |media_timestamps| values too far ahead of the current media time will
  63   // be converted to an estimated value; as such, these values may go backwards
  64   // in time slightly between calls to GetWallClockTimes().
  65   //
  66   // |media_timestamps| values behind the current media time may be
  67   // significantly incorrect if the playback rate has changed recently. The only
  68   // guarantee is that the returned time will be less than the current wall
  69   // clock time.
  70   virtual bool GetWallClockTimes(
  71       const std::vector<base::TimeDelta>& media_timestamps,
  72       std::vector<base::TimeTicks>* wall_clock_times) = 0;
  73 };
  74
  75 }  // namespace media
  76
  77 #endif  // MEDIA_BASE_TIME_SOURCE_H_