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                   float playback_rate);
  61
  62   // Returns the bounds of media data currently buffered by the audio hardware,
  63   // taking silence and changes in playback rate into account. Buffered audio
  64   // structure and timestamps are updated with every call to WroteAudio().
  65   //
  66   //  start_timestamp = 1000 ms                           sample_rate = 40 Hz
  67   // +-----------------------+-----------------------+-----------------------+
  68   // |   10 frames silence   |   20 frames @ 1.0x    |   20 frames @ 0.5x    |
  69   // |      = 250 ms (wall)  |      = 500 ms (wall)  |      = 500 ms (wall)  |
  70   // |      =   0 ms (media) |      = 500 ms (media) |      = 250 ms (media) |
  71   // +-----------------------+-----------------------+-----------------------+
  72   // ^                                                                       ^
  73   // front_timestamp() is equal to               back_timestamp() is equal to
  74   // |start_timestamp| since no                  amount of media frames tracked
  75   // media data has been played yet.             by AudioClock, which would be
  76   //                                             1000 + 500 + 250 = 1750 ms.
  77   base::TimeDelta front_timestamp() const { return front_timestamp_; }
  78   base::TimeDelta back_timestamp() const { return back_timestamp_; }
  79
  80   // Returns the amount of wall time until |timestamp| will be played by the
  81   // audio hardware.
  82   //
  83   // |timestamp| must be within front_timestamp() and back_timestamp().
  84   base::TimeDelta TimeUntilPlayback(base::TimeDelta timestamp) const;
  85
  86   // Returns the amount of contiguous media time buffered at the head of the
  87   // audio hardware buffer. Silence introduced into the audio hardware buffer is
  88   // treated as a break in media time.
  89   base::TimeDelta contiguous_audio_data_buffered() const {
  90     return contiguous_audio_data_buffered_;
  91   }
  92
  93   // Same as above, but also treats changes in playback rate as a break in media
  94   // time.
  95   base::TimeDelta contiguous_audio_data_buffered_at_same_rate() const {
  96     return contiguous_audio_data_buffered_at_same_rate_;
  97   }
  98
  99  private:
 100   // Even with a ridiculously high sample rate of 256kHz, using 64 bits will
 101   // permit tracking up to 416999965 days worth of time (that's 1141 millenia).
 102   //
 103   // 32 bits on the other hand would top out at measly 2 hours and 20 minutes.
 104   struct AudioData {
 105     AudioData(int64_t frames, float playback_rate);
 106
 107     int64_t frames;
 108     float playback_rate;
 109   };
 110
 111   // Helpers for operating on |buffered_|.
 112   void PushBufferedAudioData(int64_t frames, float playback_rate);
 113   void PopBufferedAudioData(int64_t frames);
 114   base::TimeDelta ComputeBufferedMediaTime(int64_t frames) const;
 115
 116   const base::TimeDelta start_timestamp_;
 117   const int sample_rate_;
 118   const double microseconds_per_frame_;
 119
 120   std::deque<AudioData> buffered_;
 121   int64_t total_buffered_frames_;
 122
 123   base::TimeDelta front_timestamp_;
 124   base::TimeDelta back_timestamp_;
 125
 126   // Cached results of last call to WroteAudio().
 127   base::TimeDelta contiguous_audio_data_buffered_;
 128   base::TimeDelta contiguous_audio_data_buffered_at_same_rate_;
 129
 130   DISALLOW_COPY_AND_ASSIGN(AudioClock);
 131 };
 132
 133 }  // namespace media
 134
 135 #endif  // MEDIA_FILTERS_AUDIO_CLOCK_H_