Skip to main content
SDK Introduction

iOS SDK

AOQ iOS SDK API reference

API index

Engine lifecycle

APIDescription
createEngine:delegate:Create the engine instance (singleton)
destroyDestroy the engine instance
getVersionGet the SDK version string
connect:Connect to the Relay server
disconnectDisconnect from the server

Audio device management

APIDescription
startAudioCapture:Open the audio capture device (microphone)
stopAudioCaptureClose the audio capture device
muteAudioCapture:Mute or unmute audio capture
startAudioPlayer:Start audio playback (play remote audio)
stopAudioPlayerStop audio playback
pauseAudioPlayer:Pause audio playback with optional fade-out
resumeAudioPlayer:Resume audio playback with optional fade-in
interruptAudioPlayer:fadeMs:Interrupt the current audio call turn
enableSpeakerphone:Switch audio output between speaker and earpiece
isSpeakerphoneEnabledQuery whether the speaker is currently active
setAudioSessionRestriction:Set AVAudioSession control permissions
enableLocalAudioVolumeIndication:Configure local capture volume indication

Audio codec configuration

APIDescription
setAudioEncoderConfig:Set audio encoding parameters
setAudioDecoderConfig:Set audio decoding parameters

Video device management

APIDescription
startVideoCapture:Open the video capture device (camera)
stopVideoCaptureClose the video capture device
switchCamera:Switch between front and rear cameras
setLocalView:canvas:Set or remove the local video rendering view
setRemoteView:canvas:Set or remove the remote video rendering view
startScreenCapture:Start screen capture
stopScreenCaptureStop screen capture

Video encoding and external input

APIDescription
setVideoEncoderConfig:Set video encoding parameters
pushExternalVideoCapturedFrame:frame:Push an externally captured raw video frame
pushExternalVideoEncodedFrame:frame:Push an externally encoded video frame
setVideoDecoderConfig:Set video decoding parameters

Media stream control

APIDescription
enableSendMediaStream:enable:Enable or disable local media stream sending

Audio file playback

APIDescription
startAudioFile:config:Start streaming a local audio file
stopAudioFile:Stop audio file playback
pauseAudioFile:Pause audio file playback
resumeAudioFile:Resume audio file playback
getAudioFileDuration:Get the total duration of the audio file
getAudioFileCurrentPosition:Get the current playback position
setAudioFilePositionMillis:positionMillis:Seek to a position in the audio file
setAudioFileVolume:type:volume:Set the audio file volume
getAudioFileVolume:type:Get the current audio file volume

External audio streams

APIDescription
addAudioExternalStream:config:Add an external audio stream
removeAudioExternalStream:Remove an external audio stream
pushAudioExternalStreamData:data:Push external PCM audio data
setAudioExternalStreamVolume:type:volume:Set the volume for an external audio stream
getAudioExternalStreamVolume:type:Get the volume for an external audio stream
clearAudioExternalStreamBuffer:fadeoutMs:Clear the buffer for an external audio stream

Real-time messaging

APIDescription
sendDataMsg:Send a real-time data message

Audio frame callbacks

APIDescription
setAudioFrameObserver:Set the audio frame data callback delegate
enableAudioFrameObserver:audioSource:config:Enable or disable audio frame callbacks at a specified point

Video frame callbacks

APIDescription
setVideoFrameObserver:Set the video frame data callback delegate
enableVideoFrameObserver:videoSource:config:Enable or disable video frame callbacks at a specified point

AoqEngineDelegate callbacks

CallbackDescription
onError:message:Engine error callback
onWarning:message:Engine warning callback
onConnectionStatusChange:Connection state change callback
onStats:Statistics callback
onAudioDeviceStateChanged:Audio device state change callback
onAudioDeviceRouteChanged:Audio output route change callback
onAudioDeviceInterrupted:Audio device interruption callback
onVideoDeviceStateChanged:Video device state change callback
onAudioFileState:Audio file playback state callback
onDataMsg:Real-time data message received callback
AoqAudioFrameDelegateAudio frame data listener protocol
AoqVideoFrameDelegateVideo frame data listener protocol
onLocalAudioVolumeIndicationLocal capture volume callback
onScreenCaptureStateChangedScreen capture state callback

API details

Screen capture

- (int)startScreenCapture:(AoqScreenCaptureConfig * _Nonnull)config;
- (int)stopScreenCapture;
config specifies screen capture settings. Screen content is sent on the AoqTrackTypeScreen track. For start, 0 means that the request is accepted; onScreenCaptureStateChanged reports the result asynchronously. A nonzero return rejects the request synchronously without a duplicate failure event. Stop returns 0 on success or a nonzero value on failure, and reports the stopped state through this callback. With isExternal=NO, capture uses a Broadcast Upload Extension. Integrate and configure AoqScreenShare.framework and display the system broadcast picker. On timeout, the onScreenCaptureStateChanged: callback reports failure with AoqECScreenStartFailed. You do not need to wait for Started before enabling transmission. For external raw frames, set isExternal=YES. This does not enable the Extension receiving channel. Supply raw Screen frames through pushExternalVideoCapturedFrame for SDK encoding. For external encoded frames, configure the Screen track for external encoding with setVideoEncoderConfig, then call pushExternalVideoEncodedFrame; startScreenCapture is not required.

onScreenCaptureStateChanged

@optional
- (void)onScreenCaptureStateChanged:(AoqScreenCaptureState * _Nonnull)state;
state contains the screen capture state. Started means capture or external input is ready, not that media has been sent. Screen capture failures are not also reported through onError.

setVideoDecoderConfig:

- (int)setVideoDecoderConfig:(AoqVideoCodecConfig * _Nonnull)config;
config specifies video decoding settings. Only the following fields take effect: trackType, codecType, width, height, fps, bitrate. Other fields apply only to encoding. Screen does not support downstream decoding. If config.trackType is Screen, the method returns AoqECUnSupport without applying the configuration. Returns 0 on success or a nonzero value on failure.

enableLocalAudioVolumeIndication:

- (int)enableLocalAudioVolumeIndication:(AoqAudioVolumeIndicationConfig * _Nonnull)config;
config specifies volume indication settings. Callbacks are emitted at config.interval. Call this method after startAudioCapture. Returns 0 on success or a nonzero value on failure.
- (void)onLocalAudioVolumeIndication:(AoqAudioVolume * _Nonnull)volume;
The volume callback argument contains the local capture volume.

Engine lifecycle

createEngine:delegate:

Create the engine instance. The SDK holds the engine as a global singleton.
+ (instancetype _Nonnull)createEngine:(AoqCreateConfig * _Nonnull)config
                             delegate:(id<AoqEngineDelegate> _Nonnull)delegate;

destroy

+ (int)destroy;

getVersion

+ (NSString * _Nonnull)getVersion;

connect:

- (int)connect:(AoqConnectConfig * _Nonnull)config;

disconnect

- (int)disconnect;

Audio device management

- (int)startAudioCapture:(AoqAudioCaptureConfig * _Nonnull)config;
- (int)stopAudioCapture;
- (int)muteAudioCapture:(BOOL)mute;
- (int)startAudioPlayer:(AoqAudioPlaybackConfig * _Nonnull)config;
- (int)stopAudioPlayer;
- (int)pauseAudioPlayer:(NSInteger)fadeMs;
- (int)resumeAudioPlayer:(NSInteger)fadeMs;
- (int)interruptAudioPlayer:(AoqTrackType)trackType fadeMs:(NSInteger)fadeMs;
- (int)enableSpeakerphone:(BOOL)enable;
- (BOOL)isSpeakerphoneEnabled;
- (int)setAudioSessionRestriction:(int)restriction;

Audio codec configuration

- (int)setAudioEncoderConfig:(AoqAudioCodecConfig * _Nonnull)config;
- (int)setAudioDecoderConfig:(AoqAudioCodecConfig * _Nonnull)config;

Video device management

- (int)startVideoCapture:(AoqVideoCaptureConfig * _Nonnull)config;
- (int)stopVideoCapture;
- (int)switchCamera:(AoqCameraDirection)direction;
- (int)setLocalView:(AoqTrackType)trackType canvas:(AoqVideoCanvas * _Nullable)canvas;
- (int)setRemoteView:(AoqTrackType)trackType canvas:(AoqVideoCanvas * _Nullable)canvas;
Pass AoqTrackTypeVideo as the trackType parameter for setLocalView and setRemoteView.

Video encoding and external input

- (int)setVideoEncoderConfig:(AoqVideoCodecConfig * _Nonnull)config;
- (int)pushExternalVideoCapturedFrame:(AoqTrackType)trackType frame:(AoqVideoFrame * _Nonnull)frame;
- (int)pushExternalVideoEncodedFrame:(AoqTrackType)trackType frame:(AoqVideoEncodedFrame * _Nonnull)frame;
Pass AoqTrackTypeVideo as the trackType parameter.

Media stream control

- (int)enableSendMediaStream:(AoqTrackType)trackType enable:(BOOL)enable;
trackType accepts AoqTrackTypeAudio or AoqTrackTypeVideo or AoqTrackTypeScreen.

Audio file playback

- (int)startAudioFile:(NSString * _Nonnull)fileId config:(AoqAudioFileMixConfig * _Nonnull)config;
- (int)stopAudioFile:(NSString * _Nonnull)fileId;
- (int)pauseAudioFile:(NSString * _Nonnull)fileId;
- (int)resumeAudioFile:(NSString * _Nonnull)fileId;
- (long long)getAudioFileDuration:(NSString * _Nonnull)fileId;
- (long long)getAudioFileCurrentPosition:(NSString * _Nonnull)fileId;
- (int)setAudioFilePositionMillis:(NSString * _Nonnull)fileId positionMillis:(long long)positionMillis;
- (int)setAudioFileVolume:(NSString * _Nonnull)fileId type:(AoqAudioStreamDirection)type volume:(NSInteger)volume;
- (int)getAudioFileVolume:(NSString * _Nonnull)fileId type:(AoqAudioStreamDirection)type;

External audio streams

- (int)addAudioExternalStream:(NSString * _Nonnull)streamId config:(AoqAudioExternalStreamConfig * _Nonnull)config;
- (int)pushAudioExternalStreamData:(NSString * _Nonnull)streamId data:(AoqAudioFrameData * _Nonnull)data;
- (int)setAudioExternalStreamVolume:(NSString * _Nonnull)streamId type:(AoqAudioStreamDirection)type volume:(NSInteger)volume;
- (int)getAudioExternalStreamVolume:(NSString * _Nonnull)streamId type:(AoqAudioStreamDirection)type;
- (void)clearAudioExternalStreamBuffer:(NSString * _Nonnull)streamId fadeoutMs:(NSInteger)fadeoutMs;
- (int)removeAudioExternalStream:(NSString * _Nonnull)streamId;

Real-time messaging

- (int)sendDataMsg:(AoqDataMsg * _Nonnull)msg;

Audio frame callbacks

- (int)setAudioFrameObserver:(id<AoqAudioFrameDelegate> _Nullable)delegate;
- (int)enableAudioFrameObserver:(BOOL)enabled audioSource:(AoqAudioSource)audioSource config:(AoqAudioObserverConfig * _Nonnull)config;

Video frame callbacks

- (int)setVideoFrameObserver:(id<AoqVideoFrameDelegate> _Nullable)delegate;
- (int)enableVideoFrameObserver:(BOOL)enabled videoSource:(AoqVideoSource)videoSource config:(AoqVideoObserverConfig * _Nonnull)config;

AoqEngineDelegate callbacks

All callback methods are @required.
- (void)onError:(NSInteger)code message:(NSString * _Nonnull)message;
- (void)onWarning:(NSInteger)code message:(NSString * _Nonnull)message;
- (void)onConnectionStatusChange:(AoqConnectionStatus)status;
- (void)onStats:(AoqStats * _Nonnull)stats;
- (void)onAudioDeviceStateChanged:(AoqAudioDeviceState * _Nonnull)state;
- (void)onAudioDeviceRouteChanged:(NSInteger)routeType;
- (void)onAudioDeviceInterrupted:(BOOL)interrupt;
- (void)onAudioFileState:(AoqAudioFileState * _Nonnull)state;
- (void)onVideoDeviceStateChanged:(AoqVideoDeviceState * _Nonnull)state;
- (void)onDataMsg:(AoqDataMsg * _Nonnull)msg;

AoqAudioFrameDelegate (@optional)

- (void)onCapturedAudioFrame:(AoqAudioFrameData * _Nonnull)frame;
- (void)onProcessCapturedAudioFrame:(AoqAudioFrameData * _Nonnull)frame;
- (void)onPublishAudioFrame:(AoqTrackType)trackType frame:(AoqAudioFrameData * _Nonnull)frame;
- (void)onPlaybackAudioFrame:(AoqAudioFrameData * _Nonnull)frame;

AoqVideoFrameDelegate (@optional)

- (BOOL)onCapturedVideoFrame:(AoqTrackType)trackType frame:(AoqVideoFrame * _Nonnull)frame;
- (BOOL)onPreEncodeVideoFrame:(AoqTrackType)trackType frame:(AoqVideoFrame * _Nonnull)frame;
- (BOOL)onRemoteVideoFrame:(AoqTrackType)trackType frame:(AoqVideoFrame * _Nonnull)frame;

Data types and enumerations

AoqScreenCaptureState

FieldTypeDefaultDescription
stateAoqScreenCaptureStateCodeAoqScreenCaptureNoneScreen capture state.
reasonNSInteger00 for normal states; an AoqErrorCode on failure.

AoqScreenCaptureStateCode

ValueNumberDescription
AoqScreenCaptureNone0None
AoqScreenCaptureStarting1Starting
AoqScreenCaptureStarted2Input ready; does not indicate transmission
AoqScreenCaptureStopping3Stopping
AoqScreenCaptureStopped4Stopped
AoqScreenCaptureFail5Start or runtime failure

AoqScreenCaptureConfig

FieldTypeDefaultDescription
isExternalBOOLNOWhether the application supplies raw screen frames.
appGroupNSString *nilOptional AppGroup ID shared by the app and Broadcast Extension. If nil, settings are delivered through the socket handshake and neither target needs the App Groups capability. Ignored for external capture.

AoqVideoCodecConfig

FieldTypeDefaultDescription
trackTypeAoqTrackTypeAoqTrackTypeVideoTrack type
codecTypeAoqEncoderTypeAoqEncoderTypeVideoH264Codec
widthNSInteger540Width in pixels
heightNSInteger960Height in pixels
fpsNSInteger5Frame rate
bitrateNSInteger500000Bitrate in bps
minBitrateNSInteger128000Minimum bitrate in bps
keyframeIntervalNSInteger2Keyframe interval in seconds
mirrorModeAoqMirrorModeAoqMirrorModeDisabledMirror mode
orientationModeAoqOrientationModeAoqOrientationModeAutoOrientation mode
isExternalBOOLNOWhether the application supplies encoded frames.

AoqAudioVolume

FieldTypeDefaultDescription
isSpeechBOOLNOWhether speech is detected.
volumeNSInteger0Smoothed instantaneous volume, from 0 to 255.

AoqAudioVolumeIndicationConfig

FieldTypeDefaultDescription
reportSpeechBOOLNOWhether to detect speech.
intervalNSInteger0Callback interval in milliseconds. Values of 0 or less disable callbacks; values between 0 and 10 use 10.
smoothNSInteger3Smoothing factor, from 0 to 10. Higher values produce smoother results.

AoqTrackParam.trackMode

FieldTypeDefaultDescription
trackModeAoqTrackModeAoqTrackModeSegmentApplies only to downstream audio.

AoqTrackMode

ValueNumberDescription
AoqTrackModeSegment0Segment mode: delivers data in semantic segments, such as sentences. Applies only to downstream audio.
AoqTrackModeStream1Stream mode: delivers data continuously. Applies only to downstream audio.

AoqCreateConfig (fields added in v1.3.0)

FieldTypeDefaultDescription
maxEncodedVideoFrameBytesNSInteger190 × 1024Maximum encoded frame size in bytes. Applies only to the SDK internal JPEG encoder.
enableDropOversizedVideoFrameBOOLNOFor the SDK internal JPEG encoder, whether to drop a frame that remains oversized at the lowest quality.

AoqErrorCode

Enum valueValueDescription
AoqErrorCodeOK0Success
AoqErrorCodeParamInvalid1Invalid parameter
AoqErrorCodeStateInvalid2Invalid state
AoqErrorCodeUnSupport3Unsupported operation
AoqErrorCodeAudio100Audio generic error
AoqErrorCodeAudioExternalBufferFull110External audio buffer full
AoqErrorCodeAudioDevice120Audio device generic error
AoqErrorCodeAudioDeviceRecordingAuthFailed121Recording permission not granted
AoqErrorCodeAudioDeviceRecordingOccupied122Recording device in use
AoqErrorCodeAudioDeviceRecordingBackgroundStart123Failed to start recording in background
AoqErrorCodeAudioDeviceRecordingStartFail124Recording start failed
AoqErrorCodeAudioDevicePlayoutOccupied125Playback device in use
AoqErrorCodeAudioDevicePlayoutBackgroundStart126Failed to start playback in background
AoqErrorCodeAudioDevicePlayoutStartFail127Playback start failed
AoqErrorCodeAudioDeviceEarpieceRequiresVoipMode128Earpiece requires VoIP mode
AoqErrorCodeVideo200Video generic error
AoqErrorCodeVideoExternalBufferFull210External video buffer full
AoqErrorCodeVideoExternalCaptureNotEnabled211External video capture not enabled
AoqErrorCodeVideoExternalEncoderNotEnabled212External video encoder not enabled
AoqErrorCodeVideoDevice220Video device generic error
AoqErrorCodeVideoDeviceCameraOpenFail221Camera open failed
AoqErrorCodeVideoDeviceCameraAuthFailed222Camera permission not granted
AoqErrorCodeVideoDeviceCameraOccupied223Camera in use
AoqErrorCodeVideoDeviceCameraRunningError224Camera runtime error
AoqErrorCodeVideoCodec230Video codec generic error
AoqErrorCodeVideoCodecEncoderInitFail231Video encoder initialization failed
AoqErrorCodeVideoRender240Video rendering generic error
AoqErrorCodeVideoRenderCreateFail241Video renderer creation failed
AoqErrorCodeVideoRenderDrawError242Video rendering draw error
AoqECScreen300General screen sharing error
AoqECScreenAuthFailed310Screen sharing permission denied
AoqECScreenStartFailed311Failed to start screen sharing

AoqTrackType

Enum valueValueDescription
AoqTrackTypeAudio0Audio track
AoqTrackTypeVideo1Video track
AoqTrackTypeData2Data messaging track
AoqTrackTypeScreen3Screen sharing track. Uplink only.

AoqConnectConfig

subscribeTracks must not include AoqTrackTypeScreen; otherwise, connect returns AoqECUnSupport without starting a connection. setRemoteView also returns AoqECUnSupport for Screen.
FieldTypeDescription
tokenNSString *Authentication token
sidNSString *Session ID
certFingerprintNSString *Server certificate fingerprint
relayEndpointsNSArray<AoqRelayEndpoint *> *List of Relay endpoints
workspaceIdHashNSString *Workspace ID hash
publishTracksNSArray<AoqTrackParam *> *Local tracks to publish
subscribeTracksNSArray<AoqTrackParam *> *Remote tracks to subscribe to

AoqAudioPlaybackConfig

FieldTypeDefaultDescription
isVoipModeBOOLNOYES: enable VoIP mode (hardware AEC); applies to mobile
isDefaultSpeakerBOOLYESYES: default to speaker; NO: earpiece
isExternalBOOLNOYES: external audio output
channelNSInteger1Channel count: 1 or 2

Statistics types

AoqStats

FieldTypeDescription
audioPublishStatsNSArray<AoqAudioPublishStats *> *Audio publish statistics
videoPublishStatsNSArray<AoqVideoPublishStats *> *Video publish statistics
dataMsgPublishStatsNSArray<AoqDataMsgPublishStats *> *Data message publish statistics
audioSubscribeStatsNSArray<AoqAudioSubscribeStats *> *Audio subscribe statistics
videoSubscribeStatsNSArray<AoqVideoSubscribeStats *> *Video subscribe statistics
dataMsgSubscribeStatsNSArray<AoqDataMsgSubscribeStats *> *Data message subscribe statistics
networkStatsAoqNetworkStats *Network statistics

AoqNetworkStats

FieldTypeDescription
sendBitrateNSUIntegerSend bitrate (bps)
sendBytesNSUIntegerCumulative bytes sent
recvBitrateNSUIntegerReceive bitrate (bps)
recvBytesNSUIntegerCumulative bytes received
lossNSUIntegerPacket loss rate
rttNSUIntegerRound-trip time (ms)

AoqAudioPublishStats

trackType / bitrate / bytes / encodeVolume

AoqVideoPublishStats

trackType / bitrate / bytes / encodeFps

AoqAudioSubscribeStats

trackType / bitrate / bytes / playVolume

AoqVideoSubscribeStats

trackType / bitrate / bytes / decodeFps / renderFps

AoqDataMsgPublishStats / AoqDataMsgSubscribeStats

trackType / bitrate / bytes

Key differences from the Android SDK

DifferenceiOSAndroid
Callback pattern@protocol delegateAbstract class listener
AVAudioSession controlsetAudioSessionRestriction: (iOS only)No equivalent
Audio focus callbackNone (uses onAudioDeviceInterrupted: instead)onAudioDeviceFocusChanged
Video pixel formatSupports CVPixelBuffer zero-copySupports TextureOES / Texture2D
Video rendering viewUIViewSurfaceView / TextureView
Bluetooth mode configNo isBTScoMode (managed by the OS)AoqCreateConfig.isBTScoMode
Video frame callback write-backI420 / CVPixelBufferI420