content/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 CONTENT_BROWSER_MEDIA_AUDIO_STREAM_MONITOR_H_
   6 #define CONTENT_BROWSER_MEDIA_AUDIO_STREAM_MONITOR_H_
   7
   8 #include <map>
   9 #include <utility>
  10
  11 #include "base/callback_forward.h"
  12 #include "base/threading/thread_checker.h"
  13 #include "base/time/default_tick_clock.h"
  14 #include "base/time/time.h"
  15 #include "base/timer/timer.h"
  16 #include "build/build_config.h"
  17 #include "content/common/content_export.h"
  18 #include "media/audio/audio_output_controller.h"
  19
  20 namespace base {
  21 class TickClock;
  22 }
  23
  24 namespace content {
  25 class WebContents;
  26
  27 // Repeatedly polls audio streams for their power levels, and "debounces" the
  28 // information into a simple, binary "was recently audible" result for the audio
  29 // indicators in the tab UI.  The debouncing logic is to: 1) Turn on immediately
  30 // when sound is audible; and 2) Hold on for X amount of time after sound has
  31 // gone silent, then turn off.  Said another way, we don't want tab indicators
  32 // to turn on/off repeatedly and annoy the user.  AudioStreamMonitor sends UI
  33 // update notifications only when needed, but may be queried at any time.
  34 //
  35 // Each WebContentsImpl owns an AudioStreamMonitor.
  36 class CONTENT_EXPORT AudioStreamMonitor {
  37  public:
  38   explicit AudioStreamMonitor(WebContents* contents);
  39   ~AudioStreamMonitor();
  40
  41   // Indicates if audio stream monitoring is available.  It's only available if
  42   // AudioOutputController can and will monitor output power levels.
  43   static bool monitoring_available() {
  44     return media::AudioOutputController::will_monitor_audio_levels();
  45   }
  46
  47   // Returns true if audio has recently been audible from the tab.  This is
  48   // usually called whenever the tab data model is refreshed; but there are
  49   // other use cases as well (e.g., the OOM killer uses this to de-prioritize
  50   // the killing of tabs making sounds).
  51   bool WasRecentlyAudible() const;
  52
  53   // Starts or stops audio level monitoring respectively for the stream owned by
  54   // the specified renderer.  Safe to call from any thread.
  55   //
  56   // The callback returns the current power level (in dBFS units) and the clip
  57   // status (true if any part of the audio signal has clipped since the last
  58   // callback run).  |stream_id| must be unique within a |render_process_id|.
  59   typedef base::Callback<std::pair<float, bool>()> ReadPowerAndClipCallback;
  60   static void StartMonitoringStream(
  61       int render_process_id,
  62       int render_frame_id,
  63       int stream_id,
  64       const ReadPowerAndClipCallback& read_power_callback);
  65   static void StopMonitoringStream(int render_process_id,
  66                                    int render_frame_id,
  67                                    int stream_id);
  68
  69   void set_was_recently_audible_for_testing(bool value) {
  70     was_recently_audible_ = value;
  71   }
  72
  73  private:
  74   friend class AudioStreamMonitorTest;
  75
  76   enum {
  77     // Desired polling frequency.  Note: If this is set too low, short-duration
  78     // "blip" sounds won't be detected.  http://crbug.com/339133#c4
  79     kPowerMeasurementsPerSecond = 15,
  80
  81     // Amount of time to hold a tab indicator on after its last blurt.
  82     kHoldOnMilliseconds = 2000
  83   };
  84
  85   // Helper methods for starting and stopping monitoring which lookup the
  86   // identified renderer and forward calls to the correct AudioStreamMonitor.
  87   static void StartMonitoringHelper(
  88       int render_process_id,
  89       int render_frame_id,
  90       int stream_id,
  91       const ReadPowerAndClipCallback& read_power_callback);
  92   static void StopMonitoringHelper(int render_process_id,
  93                                    int render_frame_id,
  94                                    int stream_id);
  95
  96   // Starts polling the stream for audio stream power levels using |callback|.
  97   void StartMonitoringStreamOnUIThread(
  98       int render_process_id,
  99       int stream_id,
 100       const ReadPowerAndClipCallback& callback);
 101
 102   // Stops polling the stream, discarding the internal copy of the |callback|
 103   // provided in the call to StartMonitoringStream().
 104   void StopMonitoringStreamOnUIThread(int render_process_id, int stream_id);
 105
 106   // Called by |poll_timer_| to sample the power levels from each of the streams
 107   // playing in the tab.
 108   void Poll();
 109
 110   // Compares last known indicator state with what it should be, and triggers UI
 111   // updates through |web_contents_| if needed.  When the indicator is turned
 112   // on, |off_timer_| is started to re-invoke this method in the future.
 113   void MaybeToggle();
 114
 115   // The WebContents instance instance to receive indicator toggle
 116   // notifications.  This pointer should be valid for the lifetime of
 117   // AudioStreamMonitor.
 118   WebContents* const web_contents_;
 119
 120   // Note: |clock_| is always |&default_tick_clock_|, except during unit
 121   // testing.
 122   base::DefaultTickClock default_tick_clock_;
 123   base::TickClock* const clock_;
 124
 125   // Confirms single-threaded access in debug builds.
 126   base::ThreadChecker thread_checker_;
 127
 128   // The callbacks to read power levels for each stream.  Only playing (i.e.,
 129   // not paused) streams will have an entry in this map.
 130   typedef std::pair<int, int> StreamID;
 131   typedef std::map<StreamID, ReadPowerAndClipCallback> StreamPollCallbackMap;
 132   StreamPollCallbackMap poll_callbacks_;
 133
 134   // Records the last time at which sound was audible from any stream.
 135   base::TimeTicks last_blurt_time_;
 136
 137   // Set to true if the last call to MaybeToggle() determined the indicator
 138   // should be turned on.
 139   bool was_recently_audible_;
 140
 141   // Calls Poll() at regular intervals while |poll_callbacks_| is non-empty.
 142   base::RepeatingTimer<AudioStreamMonitor> poll_timer_;
 143
 144   // Started only when an indicator is toggled on, to turn it off again in the
 145   // future.
 146   base::OneShotTimer<AudioStreamMonitor> off_timer_;
 147
 148   DISALLOW_COPY_AND_ASSIGN(AudioStreamMonitor);
 149 };
 150
 151 }  // namespace content
 152
 153 #endif  // CONTENT_BROWSER_MEDIA_AUDIO_STREAM_MONITOR_H_