media/base/audio_shifter.h

   1 // Copyright (c) 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_AUDIO_SHIFTER_H
   6 #define MEDIA_BASE_AUDIO_SHIFTER_H
   7
   8 #include <deque>
   9
  10 #include "base/memory/linked_ptr.h"
  11 #include "base/memory/scoped_ptr.h"
  12 #include "base/time/time.h"
  13 #include "media/base/media_export.h"
  14 #include "media/base/multi_channel_resampler.h"
  15
  16 namespace media {
  17
  18 class AudioBus;
  19 class ClockSmoother;
  20
  21 // This class works like a buffer between a push based audio source
  22 // and a pull-based audio sink. The source and sink should operate
  23 // at nominally the same rate, but since they may run on different
  24 // hardware clocks, the rate may differ a little. If left unchecked,
  25 // this difference will first cause lip sync issues between audio
  26 // and video and eventually it will cause buffer overruns/underruns.
  27 // This class solves all that by dynamically resampling the audio
  28 // so that both input and output sources are happy.
  29 //
  30 // A note about TimeTicks. The playout_time specified in Push and
  31 // Pull calls must come from the same timeline. That timeline can
  32 // be anything you choose as it is never compared to any real-world
  33 // clocks, but they must come from the same clock. Specifically,
  34 // specifying samples / rate as the playout time in Push() or Pull()
  35 // will NOT work.
  36 //
  37 class MEDIA_EXPORT AudioShifter {
  38  public:
  39   // |max_buffer_size| is how much audio we are allowed to buffer.
  40   // Often, this can be set fairly large as Push() will limit the
  41   // size when it specifies when to play the audio.
  42   // |clock_accuracy| is used to determine if a skip has occured
  43   // in the audio (as opposed to an inaccuracy in the timestamp.)
  44   // It also limits the smallest amount of buffering allowed.
  45   // |adjustement_time| specifies how long time should be used
  46   // to adjust the audio. This should normally at least a few
  47   // seconds. The larger the value, the smoother and less audible
  48   // the transitions will be. (But it means that perfect audio
  49   // sync will take longer to achive.)
  50   // |rate| is audio frames per second, eg 48000.
  51   // |channels| is number of channels in input and output audio.
  52   // TODO(hubbe): Allow input rate and output rate to be different
  53   // since we're going to be resampling anyways.
  54   AudioShifter(base::TimeDelta max_buffer_size,
  55                base::TimeDelta clock_accuracy,
  56                base::TimeDelta adjustment_time,
  57                size_t rate,
  58                int channels);
  59   ~AudioShifter();
  60
  61   // Push Audio into the shifter. All inputs must have the same number of
  62   // channels, but bus size can vary. The playout time can be noisy and
  63   // does not have to line up perfectly with the number of samples pushed
  64   // so far. However, the playout_time in Push calls and Pull calls must
  65   // not diverge over time.
  66   // Given audio from an a microphone, a reasonable way to calculate
  67   // playout_time would be now + 30ms.
  68   // Ideally playout_time is some time in the future, in which case
  69   // the samples will be buffered until the approperiate time. If
  70   // playout_time is in the past, everything will still work, and we'll
  71   // try to keep the buffring to a minimum.
  72   void Push(scoped_ptr<AudioBus> input, base::TimeTicks playout_time);
  73
  74   // Fills out |output| with samples. Tries to stretch/shrink the audio
  75   // to compensate for drift between input and output.
  76   // If called from an output device data pull, a reasonable way to
  77   // calculate playout_time would be now + audio pipeline delay.
  78   void Pull(AudioBus* output, base::TimeTicks playout_time);
  79
  80   // Flush audio (but leave timing info)
  81   void Flush();
  82
  83 private:
  84   void Zero(AudioBus* output);
  85   void ResamplerCallback(int frame_delay, AudioBus* destination);
  86
  87   struct AudioQueueEntry {
  88     AudioQueueEntry(base::TimeTicks target_playout_time_,
  89                     scoped_ptr<AudioBus> audio_);
  90     ~AudioQueueEntry();
  91     base::TimeTicks target_playout_time;
  92     linked_ptr<AudioBus> audio;
  93   };
  94
  95   typedef std::deque<AudioQueueEntry> AudioShifterQueue;
  96
  97   // Set from constructor.
  98   const base::TimeDelta max_buffer_size_;
  99   const base::TimeDelta clock_accuracy_;
 100   const base::TimeDelta adjustment_time_;
 101   const size_t rate_;
 102
 103   // The clock smoothers are used to smooth out timestamps
 104   // and adjust for drift and inaccurate clocks.
 105   scoped_ptr<ClockSmoother> input_clock_smoother_;
 106   scoped_ptr<ClockSmoother> output_clock_smoother_;
 107
 108   // Are we currently outputting data?
 109   bool running_;
 110
 111   // Number of frames already consumed from |queue_|.
 112   size_t position_;
 113
 114   // Queue of data provided to us.
 115   AudioShifterQueue queue_;
 116
 117   // Timestamp from alst Pull() call.
 118   base::TimeTicks previous_playout_time_;
 119   // Number of rames requested in last Pull call.
 120   size_t previous_requested_samples_;
 121
 122   // Timestamp at the end of last audio bus
 123   // consumed by resampler.
 124   base::TimeTicks end_of_last_consumed_audiobus_;
 125
 126   // If Push() timestamps are in the past, we have to decidede the playout delay
 127   // ourselves. The delay is then stored here.
 128   base::TimeDelta bias_;
 129
 130   // Resampler.
 131   MultiChannelResampler resampler_;
 132
 133   // Current resampler ratio.
 134   double current_ratio_;
 135 };
 136
 137 }  // namespace media
 138
 139 #endif  // MEDIA_BASE_AUDIO_SHIFTER_H