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
20namespace base {
21class TickClock;
22}
23
24namespace content {
25class 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.
36class 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