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, otherwise returns true. Even if
  54   // time is stopped, timestamps will be converted.
  55   //
  56   // Passing an empty |media_timestamps| vector will return the last known media
  57   // time as a wall clock time.
  58   //
  59   // Within a single call to GetWallClockTimes() the returned wall clock times
  60   // are a strictly increasing function of the given media times. There is no
  61   // such guarantee between calls though; e.g., playback rate or audio delay may
  62   // change on other threads within the pipeline.
  63   //
  64   // Each timestamp converted from |media_timestamps| will be pushed into
  65   // |wall_clock_times| such that after all timestamps are converted, the two
  66   // vectors are parallel (media_timestamps[i] -> wall_clock_times[i]).
  67   //
  68   // |media_timestamps| values too far ahead of the current media time will
  69   // be converted to an estimated value; as such, these values may go backwards
  70   // in time slightly between calls to GetWallClockTimes().
  71   //
  72   // |media_timestamps| values behind the current media time may be
  73   // significantly incorrect if the playback rate has changed recently. The only
  74   // guarantee is that the returned time will be less than the current wall
  75   // clock time.
  76   virtual bool GetWallClockTimes(
  77       const std::vector<base::TimeDelta>& media_timestamps,
  78       std::vector<base::TimeTicks>* wall_clock_times) = 0;
  79 };
  80
  81 }  // namespace media
  82
  83 #endif  // MEDIA_BASE_TIME_SOURCE_H_