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_ 154