chrome/browser/media/audio_stream_monitor.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 CHROME_BROWSER_MEDIA_AUDIO_STREAM_MONITOR_H_
   6 #define CHROME_BROWSER_MEDIA_AUDIO_STREAM_MONITOR_H_
   7
   8 #include <map>
   9
  10 #include "base/callback_forward.h"
  11 #include "base/threading/thread_checker.h"
  12 #include "base/time/default_tick_clock.h"
  13 #include "base/time/time.h"
  14 #include "base/timer/timer.h"
  15 #include "content/public/browser/web_contents_user_data.h"
  16
  17 namespace base {
  18 class TickClock;
  19 }
  20
  21 // Repeatedly polls audio streams for their power levels, and "debounces" the
  22 // information into a simple, binary "was recently audible" result for the audio
  23 // indicators in the tab UI.  The debouncing logic is to: 1) Turn on immediately
  24 // when sound is audible; and 2) Hold on for X amount of time after sound has
  25 // gone silent, then turn off.  Said another way, we don't want tab indicators
  26 // to turn on/off repeatedly and annoy the user.  AudioStreamMonitor sends UI
  27 // update notifications only when needed, but may be queried at any time.
  28 //
  29 // There are zero or one instances of AudioStreamMonitor per
  30 // content::WebContents instance (referred to as "the tab" in comments below).
  31 // AudioStreamMonitor is created on-demand, and automatically destroyed when its
  32 // associated WebContents is destroyed.  See content::WebContentsUserData for
  33 // usage.
  34 class AudioStreamMonitor
  35     : public content::WebContentsUserData<AudioStreamMonitor> {
  36  public:
  37   // Returns true if audio has recently been audible from the tab.  This is
  38   // usually called whenever the tab data model is refreshed; but there are
  39   // other use cases as well (e.g., the OOM killer uses this to de-prioritize
  40   // the killing of tabs making sounds).
  41   bool WasRecentlyAudible() const;
  42
  43   // Starts polling the stream for audio stream power levels using |callback|.
  44   typedef base::Callback<std::pair<float, bool>()> ReadPowerAndClipCallback;
  45   void StartMonitoringStream(int stream_id,
  46                              const ReadPowerAndClipCallback& callback);
  47
  48   // Stops polling the stream, discarding the internal copy of the |callback|
  49   // provided in the call to StartMonitoringStream().
  50   void StopMonitoringStream(int stream_id);
  51
  52  private:
  53   friend class content::WebContentsUserData<AudioStreamMonitor>;
  54   friend class AudioStreamMonitorTest;
  55
  56   enum {
  57     // Desired polling frequency.  Note: If this is set too low, short-duration
  58     // "blip" sounds won't be detected.  http://crbug.com/339133#c4
  59     kPowerMeasurementsPerSecond = 15,
  60
  61     // Amount of time to hold a tab indicator on after its last blurt.
  62     kHoldOnMilliseconds = 2000
  63   };
  64
  65   // Invoked by content::WebContentsUserData only.
  66   explicit AudioStreamMonitor(content::WebContents* contents);
  67   virtual ~AudioStreamMonitor();
  68
  69   // Called by |poll_timer_| to sample the power levels from each of the streams
  70   // playing in the tab.
  71   void Poll();
  72
  73   // Compares last known indicator state with what it should be, and triggers UI
  74   // updates through |web_contents_| if needed.  When the indicator is turned
  75   // on, |off_timer_| is started to re-invoke this method in the future.
  76   void MaybeToggle();
  77
  78   // The WebContents instance instance to receive indicator toggle
  79   // notifications.  This pointer should be valid for the lifetime of
  80   // AudioStreamMonitor.
  81   content::WebContents* const web_contents_;
  82
  83   // Note: |clock_| is always |&default_tick_clock_|, except during unit
  84   // testing.
  85   base::DefaultTickClock default_tick_clock_;
  86   base::TickClock* const clock_;
  87
  88   // Confirms single-threaded access in debug builds.
  89   base::ThreadChecker thread_checker_;
  90
  91   // The callbacks to read power levels for each stream.  Only playing (i.e.,
  92   // not paused) streams will have an entry in this map.
  93   typedef std::map<int, ReadPowerAndClipCallback> StreamPollCallbackMap;
  94   StreamPollCallbackMap poll_callbacks_;
  95
  96   // Records the last time at which sound was audible from any stream.
  97   base::TimeTicks last_blurt_time_;
  98
  99   // Set to true if the last call to MaybeToggle() determined the indicator
 100   // should be turned on.
 101   bool was_recently_audible_;
 102
 103   // Calls Poll() at regular intervals while |poll_callbacks_| is non-empty.
 104   base::RepeatingTimer<AudioStreamMonitor> poll_timer_;
 105
 106   // Started only when an indicator is toggled on, to turn it off again in the
 107   // future.
 108   base::OneShotTimer<AudioStreamMonitor> off_timer_;
 109
 110   DISALLOW_COPY_AND_ASSIGN(AudioStreamMonitor);
 111 };
 112
 113 #endif  // CHROME_BROWSER_MEDIA_AUDIO_STREAM_MONITOR_H_