docs: Fix CefAudioHandler behavior descriptions (fixes #3010)

include/cef_audio_handler.h

@@ -42,7 +42,10 @@
 #include "include/cef_browser.h"
 
 ///
-/// Implement this interface to handle audio events.
+/// Implement this interface to receive captured audio from Alloy style
+/// browsers. The browser's audio output is muted during capture. Clients
+/// that require audible playback must provide their own playback of the
+/// audio data received via OnAudioStreamPacket.
 ///
 /*--cef(source=client)--*/
 class CefAudioHandler : public virtual CefBaseRefCounted {
@@ -51,9 +54,10 @@ class CefAudioHandler : public virtual CefBaseRefCounted {
 
   ///
   /// Called on the UI thread to allow configuration of audio stream parameters.
-  /// Return true to proceed with audio stream capture, or false to cancel it.
-  /// All members of |params| can optionally be configured here, but they are
-  /// also pre-filled with some sensible defaults.
+  /// Return true to proceed with audio stream capture and mute the browser's
+  /// audio output, or false to cancel capture and leave normal audio playback
+  /// unchanged. All members of |params| can optionally be configured here, but
+  /// they are also pre-filled with some sensible defaults.
   ///
   /*--cef()--*/
   virtual bool GetAudioParameters(CefRefPtr<CefBrowser> browser,
@@ -90,7 +94,7 @@ class CefAudioHandler : public virtual CefBaseRefCounted {
                                    int64_t pts) = 0;
 
   ///
-  /// Called on the UI thread when the stream has stopped. OnAudioSteamStopped
+  /// Called on the UI thread when the stream has stopped. OnAudioStreamStopped
   /// will always be called after OnAudioStreamStarted; both methods may be
   /// called multiple times for the same stream.
   ///

include/cef_browser.h

@@ -997,14 +997,19 @@ class CefBrowserHost : public virtual CefBaseRefCounted {
                                     const CefSize& max_size) = 0;
 
   ///
-  /// Set whether the browser's audio is muted.
+  /// Set whether the browser's audio is muted. This method does not affect the
+  /// muting of audio output caused by capture via CefAudioHandler. Calling this
+  /// method with false will not restore normal audio playback while capture is
+  /// active.
   ///
   /*--cef()--*/
   virtual void SetAudioMuted(bool mute) = 0;
 
   ///
-  /// Returns true if the browser's audio is muted.  This method can only be
-  /// called on the UI thread.
+  /// Returns true if the browser's audio is muted. This method can only be
+  /// called on the UI thread. The returned value does not reflect the muting of
+  /// audio output caused by capture via CefAudioHandler and may be false while
+  /// capture is active.
   ///
   /*--cef()--*/
   virtual bool IsAudioMuted() = 0;

include/cef_client.h

@@ -66,7 +66,9 @@
 class CefClient : public virtual CefBaseRefCounted {
  public:
   ///
-  /// Return the handler for audio rendering events.
+  /// Return the handler for audio capture events. Only supported with Alloy
+  /// style browsers. If no handler is provided normal audio playback will be
+  /// used. See CefAudioHandler for audio capture behavior.
   ///
   /*--cef()--*/
   virtual CefRefPtr<CefAudioHandler> GetAudioHandler() { return nullptr; }