Support delayed AudioUnit initialization.

webrtc/modules/audio_device/ios/objc/RTCAudioSession.h

 /*
  *  Copyright 2016 The WebRTC Project Authors. All rights reserved.
  *
  *  Use of this source code is governed by a BSD-style license
  *  that can be found in the LICENSE file in the root of the source
  *  tree. An additional intellectual property rights grant can be found
  *  in the file PATENTS.  All contributing project authors may
  *  be found in the AUTHORS file in the root of the source tree.
  */
 
 #import <AVFoundation/AVFoundation.h>
 #import <Foundation/Foundation.h>
 
 NS_ASSUME_NONNULL_BEGIN
 
 extern NSString * const kRTCAudioSessionErrorDomain;
 /** Method that requires lock was called without lock. */
 extern NSInteger const kRTCAudioSessionErrorLockRequired;
 /** Unknown configuration error occurred. */
 extern NSInteger const kRTCAudioSessionErrorConfiguration;
 
 @class RTCAudioSession;
 @class RTCAudioSessionConfiguration;
 
 // Surfaces AVAudioSession events. WebRTC will listen directly for notifications
 // from AVAudioSession and handle them before calling these delegate methods,
 // at which point applications can perform additional processing if required.
 @protocol RTCAudioSessionDelegate <NSObject>
 
-/** Called when AVAudioSession starts an interruption event. */
+@optional
+/** Called on a system notification thread when AVAudioSession starts an
+ *  interruption event on the system.

[Chuck, 2016/03/21 17:12:48]

nit: on the system seems out of place here since the others don't have it.

[tkchin_webrtc, 2016/03/21 18:32:27]

Done.

+ */
 - (void)audioSessionDidBeginInterruption:(RTCAudioSession *)session;
 
-/** Called when AVAudioSession ends an interruption event. */
+/** Called on a system notification thread when AVAudioSession ends an
+ *  interruption event.
+ */
 - (void)audioSessionDidEndInterruption:(RTCAudioSession *)session
                    shouldResumeSession:(BOOL)shouldResumeSession;
 
-/** Called when AVAudioSession changes the route. */
+/** Called on a system notification thread when AVAudioSession changes the
+ *  route.
+ */
 - (void)audioSessionDidChangeRoute:(RTCAudioSession *)session
            reason:(AVAudioSessionRouteChangeReason)reason
     previousRoute:(AVAudioSessionRouteDescription *)previousRoute;
 
-/** Called when AVAudioSession media server terminates. */
+/** Called on a system notification thread when AVAudioSession media server
+ *  terminates.
+ */
 - (void)audioSessionMediaServicesWereLost:(RTCAudioSession *)session;
 
-/** Called when AVAudioSession media server restarts. */
+/** Called on a system notification thread when AVAudioSession media server
+ *  restarts.
+ */
 - (void)audioSessionMediaServicesWereReset:(RTCAudioSession *)session;
 
-/** Called when WebRTC needs to take over audio. Applications should call
- *  -[RTCAudioSession configure] to allow WebRTC to play and record audio.
- *  TODO(tkchin): Implement this behavior in RTCAudioSession.
+// TODO(tkchin): Maybe handle SilenceSecondaryAudioHintNotification.
+
+/** Called on a WebRTC thread when WebRTC needs to take over audio. Applications
+ *  should call -[RTCAudioSession configureWebRTCSession] to allow WebRTC to
+ *  play and record audio. Will only occur if shouldDelayAudioConfiguration is
+ *  set to YES.
  */
 - (void)audioSessionShouldConfigure:(RTCAudioSession *)session;
 
-/** Called when WebRTC no longer requires audio. Applications should restore
- *  their audio state at this point.
- *  TODO(tkchin): Implement this behavior in RTCAudioSession.
+/** Called on a WebRTC thread when WebRTC no longer requires audio. Applications
+ *  should call -[RTCAudioSession unconfigureWebRTCSession] to restore their
+ *  audio session settings. Will only occur if shouldDelayAudioConfiguration is
+ *  set to YES.
  */
 - (void)audioSessionShouldUnconfigure:(RTCAudioSession *)session;
 
-// TODO(tkchin): Maybe handle SilenceSecondaryAudioHintNotification.
+/** Called on a WebRTC thread when WebRTC has configured the audio session for
+ *  WebRTC audio.
+ */
+- (void)audioSessionDidConfigure:(RTCAudioSession *)session;
+
+/** Called on a WebRTC thread when WebRTC has unconfigured the audio session for
+ *  WebRTC audio.
+ */
+- (void)audioSessionDidUnconfigure:(RTCAudioSession *)session;
 
 @end
 
 /** Proxy class for AVAudioSession that adds a locking mechanism similar to
  *  AVCaptureDevice. This is used to that interleaving configurations between
- *  WebRTC and the application layer are avoided. Only setter methods are
- *  currently proxied. Getters can be accessed directly off AVAudioSession.
+ *  WebRTC and the application layer are avoided.
  *
  *  RTCAudioSession also coordinates activation so that the audio session is
  *  activated only once. See |setActive:error:|.
  */
 @interface RTCAudioSession : NSObject
 
 /** Convenience property to access the AVAudioSession singleton. Callers should
  *  not call setters on AVAudioSession directly, but other method invocations
  *  are fine.
  */
 @property(nonatomic, readonly) AVAudioSession *session;
 
 /** Our best guess at whether the session is active based on results of calls to
  *  AVAudioSession.
  */
 @property(nonatomic, readonly) BOOL isActive;
 /** Whether RTCAudioSession is currently locked for configuration. */
 @property(nonatomic, readonly) BOOL isLocked;
 
 /** If YES, WebRTC will not initialize the audio unit automatically when an
  *  audio track is ready for playout or recording. Instead, applications should
  *  listen to the delegate method |audioSessionShouldConfigure| and configure
- *  the session manually. This should be set before making WebRTC media calls.
- *  TODO(tkchin): Implement behavior. Currently this just stores a BOOL.
+ *  the session manually. This should be set before making WebRTC media calls
+ *  and should not be changed while a call is active.
  */
 @property(nonatomic, assign) BOOL shouldDelayAudioConfiguration;
 
 // Proxy properties.
 @property(readonly) NSString *category;
 @property(readonly) AVAudioSessionCategoryOptions categoryOptions;
 @property(readonly) NSString *mode;
 @property(readonly) BOOL secondaryAudioShouldBeSilencedHint;
 @property(readonly) AVAudioSessionRouteDescription *currentRoute;
 @property(readonly) NSInteger maximumInputNumberOfChannels;
@@ skipping 10 matching lines @@
 @property(readonly, nullable)
     AVAudioSessionDataSourceDescription *outputDataSource;
 @property(readonly) double sampleRate;
 @property(readonly) NSInteger inputNumberOfChannels;
 @property(readonly) NSInteger outputNumberOfChannels;
 @property(readonly) float outputVolume;
 @property(readonly) NSTimeInterval inputLatency;
 @property(readonly) NSTimeInterval outputLatency;
 @property(readonly) NSTimeInterval IOBufferDuration;
 
-/** Default constructor. Do not call init. */
+/** Default constructor. */
 + (instancetype)sharedInstance;
+- (instancetype)init NS_UNAVAILABLE;
 
 /** Adds a delegate, which is held weakly. */
 - (void)addDelegate:(id<RTCAudioSessionDelegate>)delegate;
 /** Removes an added delegate. */
 - (void)removeDelegate:(id<RTCAudioSessionDelegate>)delegate;
 
 /** Request exclusive access to the audio session for configuration. This call
  *  will block if the lock is held by another object.
  */
 - (void)lockForConfiguration;
@@ skipping 32 matching lines @@
                     error:(NSError **)outError;
 - (BOOL)setInputDataSource:(AVAudioSessionDataSourceDescription *)dataSource
                      error:(NSError **)outError;
 - (BOOL)setOutputDataSource:(AVAudioSessionDataSourceDescription *)dataSource
                       error:(NSError **)outError;
 
 @end
 
 @interface RTCAudioSession (Configuration)
 
+/** Whether or not |configureWebRTCSession| has been called without a balanced
+ *  call to |unconfigureWebRTCSession|. This is not an indication of whether the
+ *  audio session has the right settings.
+ */
+@property(readonly) BOOL isConfiguredForWebRTC;
+
 /** Applies the configuration to the current session. Attempts to set all
  *  properties even if previous ones fail. Only the last error will be
  *  returned. Also calls setActive with |active|.
  *  |lockForConfiguration| must be called first.
  */
 - (BOOL)setConfiguration:(RTCAudioSessionConfiguration *)configuration
                   active:(BOOL)active
                    error:(NSError **)outError;
 
-/** Configure the audio session for WebRTC. On failure, we will attempt to
- *  restore the previously used audio session configuration.
+/** Configure the audio session for WebRTC. This call will fail if the session
+ *  is already configured. On other failures, we will attempt to restore the
+ *  previously used audio session configuration.
+ *  |lockForConfiguration| must be called first.
+ *  Successful calls to configureWebRTCSession must be matched by calls to
+ *  |unconfigureWebRTCSession|.
+ */
+- (BOOL)configureWebRTCSession:(NSError **)outError;
+
+/** Unconfigures the session for WebRTC. This will attempt to restore the
+ *  audio session to the settings used before |configureWebRTCSession| was
+ *  called.
  *  |lockForConfiguration| must be called first.
  */
-- (BOOL)configureWebRTCSession:(NSError **)outError;
+- (BOOL)unconfigureWebRTCSession:(NSError **)outError;
 
 @end
 
 NS_ASSUME_NONNULL_END