SINAudioController

Objective-C

@protocol SINAudioController <NSObject>

Swift

protocol SINAudioController : NSObjectProtocol

The SINAudioController provides methods for controlling audio related functionality, e.g. enabling the speaker, muting the microphone, and playing sound files.

Playing Sound Files

The audio controller provides a convenience method (startPlayingSoundFile:loop:) for playing sounds that are related to a call, such as ringtones and busy tones.

  • Example:
    id<SINAudioController> audio = [client audioController];
    NSString *soundPath = [[NSBundle mainBundle] pathForResource:@"ringtone" ofType:@"wav"];
    NSError *error;

    [audio startPlayingSoundFile:soundPath loop:YES error:&error];

Applications that prefer to use their own code for playing sounds are free to do so, but they should follow a few guidelines related to audio session categories and audio session activation/deactivation (see Sinch SDK User Guide for details).

Sound File Format

The sound file must be a mono (1 channel), 16-bit, uncompressed (PCM) .wav file with a sample rate of 8kHz, 16kHz, or 32kHz.

  • The object that acts as the delegate of the audio controller.

    The delegate object handles audio related state changes.

    See

    SINAudioControllerDelegate

    Declaration

    Objective-C

    @property (atomic, weak, readwrite) id<SINAudioControllerDelegate> delegate;

    Swift

    weak var delegate: (any SINAudioControllerDelegate)! { get set }

  • Use this method to override the default AVAudioSessionCategoryOptions that will be set for the duration of phone calls. The selected options will be set for each call starting after the method invocation.

    Declaration

    Objective-C

    - (void)setAudioSessionCategoryOptions:(AVAudioSessionCategoryOptions)options;

    Swift

    func setAudioSessionCategoryOptions(_ options: AVAudioSession.CategoryOptions)

  • Mute the microphone.

    Declaration

    Objective-C

    - (void)mute;

    Swift

    func mute()

  • Unmute the microphone.

    Declaration

    Objective-C

    - (void)unmute;

    Swift

    func unmute()

  • Route the call audio through the speaker.

    Note that if this method is invoked at a moment when no established call exists, the current AVAudioSession configuration might be affected.

    This method will affect AVAudioSessionCategoryOptions during the calls even if custom options have been set via -[SINAudioController setAudioSessionCategoryOptions:]

    See

    SINCallStateEstablished

    See

    -[SINCallDelegate callDidEstablish:]

    See

    -[SINAudioController setAudioSessionCategoryOptions:]

    Declaration

    Objective-C

    - (void)enableSpeaker;

    Swift

    func enableSpeaker()

  • Route the call audio through the handset earpiece.

    Note that if this method is invoked at a moment when no established call exists, the current AVAudioSession configuration might be affected.

    This method will affect AVAudioSessionCategoryOptions even if custom options have been set via -[SINAudioController setAudioSessionCategoryOptions:]

    See

    SINCallStateEstablished

    See

    -[SINCallDelegate callDidEstablish:]

    See

    -[SINAudioController setAudioSessionCategoryOptions:]

    Declaration

    Objective-C

    - (void)disableSpeaker;

    Swift

    func disableSpeaker()

  • Play a sound file, for the purpose of playing ringtones, etc.

    This is a simple convenience method for playing sounds associated with a call, such as ringtones. It can only play one sound file at a time.

    Note that if your app integrates with CallKit, the preferred way to specify the ringtone for an incoming audio call is via ringtoneSound property of CXProviderConfiguration.

    For advanced audio, apps that use the SDK should implement their own methods for playing sounds.

    Regardless of whether a sound is looping or not, a corresponding call to the stopPlayingSoundFile method must be done at some point after each invocation of this method.

    Invoking this method could modify AVAudioSession current configuration to route audio to the speakers.

    The sound file must be a mono (1 channel), 16-bit, uncompressed (PCM) .wav file with a sample rate of 8kHz, 16kHz, or 32kHz.

    Declaration

    Objective-C

    - (BOOL)startPlayingSoundFile:(NSString *)path
                         loop:(BOOL)loop
                        error:(NSError **)error;

    Swift

    func startPlayingSoundFile(_ path: String!, loop: Bool) throws

    Parameters

    path

    Full path for the sound file to play.
    loop

    Specifies whether the sound should loop or not.
    error

    Error object that describes the problem in case the method returns NO. It can be nil.

    Return Value

    A boolean value indicating whether the sound file was successfully located. If return value is NO, the value of error will contain more specific info about the failure.

  • Stop playing the sound file.

    Declaration

    Objective-C

    - (void)stopPlayingSoundFile;

    Swift

    func stopPlayingSoundFile()

  • Configure the audio session for an incoming CallKit call.

    Declaration

    Objective-C

    - (void)configureAudioSessionForCallKitCall;

    Swift

    func configureAudioSessionForCallKitCall()