media/filters/audio_clock.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_FILTERS_AUDIO_CLOCK_H_
   6 #define MEDIA_FILTERS_AUDIO_CLOCK_H_
   7
   8 #include <deque>
   9
  10 #include "base/time/time.h"
  11 #include "media/base/media_export.h"
  12
  13 namespace media {
  14
  15 // Models a queue of buffered audio in a playback pipeline for use with
  16 // estimating the amount of delay in wall clock time. Takes changes in playback
  17 // rate into account to handle scenarios where multiple rates may be present in
  18 // a playback pipeline with large delay.
  19 //
  20 //
  21 // USAGE
  22 //
  23 // Prior to starting audio playback, construct an AudioClock with an initial
  24 // media timestamp and a sample rate matching the sample rate the audio device
  25 // was opened at.
  26 //
  27 // Each time the audio rendering callback is executed, call WroteAudio() once
  28 // (and only once!) containing information on what was written:
  29 //   1) How many frames of audio data requested
  30 //   2) How many frames of audio data provided
  31 //   3) The playback rate of the audio data provided
  32 //   4) The current amount of delay
  33 //
  34 // After a call to WroteAudio(), clients can inspect the resulting media
  35 // timestamp. This can be used for UI purposes, synchronizing video, etc...
  36 //
  37 //
  38 // DETAILS
  39 //
  40 // Silence (whether caused by the initial audio delay or failing to write the
  41 // amount of requested frames due to underflow) is also modeled and will cause
  42 // the media timestamp to stop increasing until all known silence has been
  43 // played. AudioClock's model is initialized with silence during the first call
  44 // to WroteAudio() using the delay value.
  45 //
  46 // Playback rates are tracked for translating frame durations into media
  47 // durations. Since silence doesn't affect media timestamps, it also isn't
  48 // affected by playback rates.
  49 class MEDIA_EXPORT AudioClock {
  50  public:
  51   AudioClock(base::TimeDelta start_timestamp, int sample_rate);
  52   ~AudioClock();
  53
  54   // |frames_written| amount of audio data scaled to |playback_rate| written.
  55   // |frames_requested| amount of audio data requested by hardware.
  56   // |delay_frames| is the current amount of hardware delay.
  57   void WroteAudio(int frames_written,
  58                   int frames_requested,
  59                   int delay_frames,
  60                   double playback_rate);
  61
  62   // If WroteAudio() calls are suspended (i.e. due to playback being paused) the
  63   // AudioClock will not properly advance time (even though all data up until
  64   // back_timestamp() will playout on the physical device).
  65   //
  66   // To compensate for this, when calls resume, before the next WroteAudio(),
  67   // callers should call CompensateForSuspendedWrites() to advance the clock for
  68   // audio which continued playing out while WroteAudio() calls were suspended.
  69   //
  70   // |delay_frames| must be provided to properly prime the clock to compensate
  71   // for a new initial delay.
  72   void CompensateForSuspendedWrites(base::TimeDelta elapsed, int delay_frames);
  73
  74   // Returns the bounds of media data currently buffered by the audio hardware,
  75   // taking silence and changes in playback rate into account. Buffered audio
  76   // structure and timestamps are updated with every call to WroteAudio().
  77   //
  78   //  start_timestamp = 1000 ms                           sample_rate = 40 Hz
  79   // +-----------------------+-----------------------+-----------------------+
  80   // |   10 frames silence   |   20 frames @ 1.0x    |   20 frames @ 0.5x    |
  81   // |      = 250 ms (wall)  |      = 500 ms (wall)  |      = 500 ms (wall)  |
  82   // |      =   0 ms (media) |      = 500 ms (media) |      = 250 ms (media) |
  83   // +-----------------------+-----------------------+-----------------------+
  84   // ^                                                                       ^
  85   // front_timestamp() is equal to               back_timestamp() is equal to
  86   // |start_timestamp| since no                  amount of media frames tracked
  87   // media data has been played yet.             by AudioClock, which would be
  88   //                                             1000 + 500 + 250 = 1750 ms.
  89   base::TimeDelta front_timestamp() const { return front_timestamp_; }
  90   base::TimeDelta back_timestamp() const { return back_timestamp_; }
  91
  92   // Returns the amount of wall time until |timestamp| will be played by the
  93   // audio hardware.
  94   //
  95   // |timestamp| must be within front_timestamp() and back_timestamp().
  96   base::TimeDelta TimeUntilPlayback(base::TimeDelta timestamp) const;
  97
  98   void ContiguousAudioDataBufferedForTesting(
  99       base::TimeDelta* total,
 100       base::TimeDelta* same_rate_total) const;
 101
 102  private:
 103   // Even with a ridiculously high sample rate of 256kHz, using 64 bits will
 104   // permit tracking up to 416999965 days worth of time (that's 1141 millenia).
 105   //
 106   // 32 bits on the other hand would top out at measly 2 hours and 20 minutes.
 107   struct AudioData {
 108     AudioData(int64_t frames, double playback_rate);
 109
 110     int64_t frames;
 111     double playback_rate;
 112   };
 113
 114   // Helpers for operating on |buffered_|.
 115   void PushBufferedAudioData(int64_t frames, double playback_rate);
 116   void PopBufferedAudioData(int64_t frames);
 117   base::TimeDelta ComputeBufferedMediaDuration() const;
 118
 119   const base::TimeDelta start_timestamp_;
 120   const double microseconds_per_frame_;
 121
 122   std::deque<AudioData> buffered_;
 123   int64_t total_buffered_frames_;
 124
 125   base::TimeDelta front_timestamp_;
 126   base::TimeDelta back_timestamp_;
 127
 128   DISALLOW_COPY_AND_ASSIGN(AudioClock);
 129 };
 130
 131 }  // namespace media
 132
 133 #endif  // MEDIA_FILTERS_AUDIO_CLOCK_H_