AOQ iOS SDK API reference
API index
Engine lifecycle
| API | Description |
|---|---|
| createEngine:delegate: | Create the engine instance (singleton) |
| destroy | Destroy the engine instance |
| getVersion | Get the SDK version string |
| connect: | Connect to the Relay server |
| disconnect | Disconnect from the server |
Audio device management
| API | Description |
|---|---|
| startAudioCapture: | Open the audio capture device (microphone) |
| stopAudioCapture | Close the audio capture device |
| muteAudioCapture: | Mute or unmute audio capture |
| startAudioPlayer: | Start audio playback (play remote audio) |
| stopAudioPlayer | Stop 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 |
| isSpeakerphoneEnabled | Query whether the speaker is currently active |
| setAudioSessionRestriction: | Set AVAudioSession control permissions |
| enableLocalAudioVolumeIndication: | Configure local capture volume indication |
Audio codec configuration
| API | Description |
|---|---|
| setAudioEncoderConfig: | Set audio encoding parameters |
| setAudioDecoderConfig: | Set audio decoding parameters |
Video device management
| API | Description |
|---|---|
| startVideoCapture: | Open the video capture device (camera) |
| stopVideoCapture | Close 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 |
| stopScreenCapture | Stop screen capture |
Video encoding and external input
| API | Description |
|---|---|
| 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
| API | Description |
|---|---|
| enableSendMediaStream:enable: | Enable or disable local media stream sending |
Audio file playback
| API | Description |
|---|---|
| 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
| API | Description |
|---|---|
| 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
| API | Description |
|---|---|
| sendDataMsg: | Send a real-time data message |
Audio frame callbacks
| API | Description |
|---|---|
| setAudioFrameObserver: | Set the audio frame data callback delegate |
| enableAudioFrameObserver:audioSource:config: | Enable or disable audio frame callbacks at a specified point |
Video frame callbacks
| API | Description |
|---|---|
| setVideoFrameObserver: | Set the video frame data callback delegate |
| enableVideoFrameObserver:videoSource:config: | Enable or disable video frame callbacks at a specified point |
AoqEngineDelegate callbacks
| Callback | Description |
|---|---|
| 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 |
| AoqAudioFrameDelegate | Audio frame data listener protocol |
| AoqVideoFrameDelegate | Video frame data listener protocol |
| onLocalAudioVolumeIndication | Local capture volume callback |
| onScreenCaptureStateChanged | Screen capture state callback |
API details
Screen capture
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
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:
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:
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.
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.
destroy
getVersion
connect:
disconnect
Audio device management
Audio codec configuration
Video device management
AoqTrackTypeVideo as the trackType parameter for setLocalView and setRemoteView.
Video encoding and external input
AoqTrackTypeVideo as the trackType parameter.
Media stream control
trackType accepts AoqTrackTypeAudio or AoqTrackTypeVideo or AoqTrackTypeScreen.
Audio file playback
External audio streams
Real-time messaging
Audio frame callbacks
Video frame callbacks
AoqEngineDelegate callbacks
All callback methods are @required.
AoqAudioFrameDelegate (@optional)
AoqVideoFrameDelegate (@optional)
Data types and enumerations
AoqScreenCaptureState
| Field | Type | Default | Description |
|---|---|---|---|
| state | AoqScreenCaptureStateCode | AoqScreenCaptureNone | Screen capture state. |
| reason | NSInteger | 0 | 0 for normal states; an AoqErrorCode on failure. |
AoqScreenCaptureStateCode
| Value | Number | Description |
|---|---|---|
| AoqScreenCaptureNone | 0 | None |
| AoqScreenCaptureStarting | 1 | Starting |
| AoqScreenCaptureStarted | 2 | Input ready; does not indicate transmission |
| AoqScreenCaptureStopping | 3 | Stopping |
| AoqScreenCaptureStopped | 4 | Stopped |
| AoqScreenCaptureFail | 5 | Start or runtime failure |
AoqScreenCaptureConfig
| Field | Type | Default | Description |
|---|---|---|---|
| isExternal | BOOL | NO | Whether the application supplies raw screen frames. |
| appGroup | NSString * | nil | Optional 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
| Field | Type | Default | Description |
|---|---|---|---|
| trackType | AoqTrackType | AoqTrackTypeVideo | Track type |
| codecType | AoqEncoderType | AoqEncoderTypeVideoH264 | Codec |
| width | NSInteger | 540 | Width in pixels |
| height | NSInteger | 960 | Height in pixels |
| fps | NSInteger | 5 | Frame rate |
| bitrate | NSInteger | 500000 | Bitrate in bps |
| minBitrate | NSInteger | 128000 | Minimum bitrate in bps |
| keyframeInterval | NSInteger | 2 | Keyframe interval in seconds |
| mirrorMode | AoqMirrorMode | AoqMirrorModeDisabled | Mirror mode |
| orientationMode | AoqOrientationMode | AoqOrientationModeAuto | Orientation mode |
| isExternal | BOOL | NO | Whether the application supplies encoded frames. |
AoqAudioVolume
| Field | Type | Default | Description |
|---|---|---|---|
| isSpeech | BOOL | NO | Whether speech is detected. |
| volume | NSInteger | 0 | Smoothed instantaneous volume, from 0 to 255. |
AoqAudioVolumeIndicationConfig
| Field | Type | Default | Description |
|---|---|---|---|
| reportSpeech | BOOL | NO | Whether to detect speech. |
| interval | NSInteger | 0 | Callback interval in milliseconds. Values of 0 or less disable callbacks; values between 0 and 10 use 10. |
| smooth | NSInteger | 3 | Smoothing factor, from 0 to 10. Higher values produce smoother results. |
AoqTrackParam.trackMode
| Field | Type | Default | Description |
|---|---|---|---|
| trackMode | AoqTrackMode | AoqTrackModeSegment | Applies only to downstream audio. |
AoqTrackMode
| Value | Number | Description |
|---|---|---|
| AoqTrackModeSegment | 0 | Segment mode: delivers data in semantic segments, such as sentences. Applies only to downstream audio. |
| AoqTrackModeStream | 1 | Stream mode: delivers data continuously. Applies only to downstream audio. |
AoqCreateConfig (fields added in v1.3.0)
| Field | Type | Default | Description |
|---|---|---|---|
| maxEncodedVideoFrameBytes | NSInteger | 190 × 1024 | Maximum encoded frame size in bytes. Applies only to the SDK internal JPEG encoder. |
| enableDropOversizedVideoFrame | BOOL | NO | For the SDK internal JPEG encoder, whether to drop a frame that remains oversized at the lowest quality. |
AoqErrorCode
| Enum value | Value | Description |
|---|---|---|
| AoqErrorCodeOK | 0 | Success |
| AoqErrorCodeParamInvalid | 1 | Invalid parameter |
| AoqErrorCodeStateInvalid | 2 | Invalid state |
| AoqErrorCodeUnSupport | 3 | Unsupported operation |
| AoqErrorCodeAudio | 100 | Audio generic error |
| AoqErrorCodeAudioExternalBufferFull | 110 | External audio buffer full |
| AoqErrorCodeAudioDevice | 120 | Audio device generic error |
| AoqErrorCodeAudioDeviceRecordingAuthFailed | 121 | Recording permission not granted |
| AoqErrorCodeAudioDeviceRecordingOccupied | 122 | Recording device in use |
| AoqErrorCodeAudioDeviceRecordingBackgroundStart | 123 | Failed to start recording in background |
| AoqErrorCodeAudioDeviceRecordingStartFail | 124 | Recording start failed |
| AoqErrorCodeAudioDevicePlayoutOccupied | 125 | Playback device in use |
| AoqErrorCodeAudioDevicePlayoutBackgroundStart | 126 | Failed to start playback in background |
| AoqErrorCodeAudioDevicePlayoutStartFail | 127 | Playback start failed |
| AoqErrorCodeAudioDeviceEarpieceRequiresVoipMode | 128 | Earpiece requires VoIP mode |
| AoqErrorCodeVideo | 200 | Video generic error |
| AoqErrorCodeVideoExternalBufferFull | 210 | External video buffer full |
| AoqErrorCodeVideoExternalCaptureNotEnabled | 211 | External video capture not enabled |
| AoqErrorCodeVideoExternalEncoderNotEnabled | 212 | External video encoder not enabled |
| AoqErrorCodeVideoDevice | 220 | Video device generic error |
| AoqErrorCodeVideoDeviceCameraOpenFail | 221 | Camera open failed |
| AoqErrorCodeVideoDeviceCameraAuthFailed | 222 | Camera permission not granted |
| AoqErrorCodeVideoDeviceCameraOccupied | 223 | Camera in use |
| AoqErrorCodeVideoDeviceCameraRunningError | 224 | Camera runtime error |
| AoqErrorCodeVideoCodec | 230 | Video codec generic error |
| AoqErrorCodeVideoCodecEncoderInitFail | 231 | Video encoder initialization failed |
| AoqErrorCodeVideoRender | 240 | Video rendering generic error |
| AoqErrorCodeVideoRenderCreateFail | 241 | Video renderer creation failed |
| AoqErrorCodeVideoRenderDrawError | 242 | Video rendering draw error |
| AoqECScreen | 300 | General screen sharing error |
| AoqECScreenAuthFailed | 310 | Screen sharing permission denied |
| AoqECScreenStartFailed | 311 | Failed to start screen sharing |
AoqTrackType
| Enum value | Value | Description |
|---|---|---|
| AoqTrackTypeAudio | 0 | Audio track |
| AoqTrackTypeVideo | 1 | Video track |
| AoqTrackTypeData | 2 | Data messaging track |
| AoqTrackTypeScreen | 3 | Screen sharing track. Uplink only. |
AoqConnectConfig
subscribeTracks must not include AoqTrackTypeScreen; otherwise, connect returns AoqECUnSupport without starting a connection. setRemoteView also returns AoqECUnSupport for Screen.
| Field | Type | Description |
|---|---|---|
| token | NSString * | Authentication token |
| sid | NSString * | Session ID |
| certFingerprint | NSString * | Server certificate fingerprint |
| relayEndpoints | NSArray<AoqRelayEndpoint *> * | List of Relay endpoints |
| workspaceIdHash | NSString * | Workspace ID hash |
| publishTracks | NSArray<AoqTrackParam *> * | Local tracks to publish |
| subscribeTracks | NSArray<AoqTrackParam *> * | Remote tracks to subscribe to |
AoqAudioPlaybackConfig
| Field | Type | Default | Description |
|---|---|---|---|
| isVoipMode | BOOL | NO | YES: enable VoIP mode (hardware AEC); applies to mobile |
| isDefaultSpeaker | BOOL | YES | YES: default to speaker; NO: earpiece |
| isExternal | BOOL | NO | YES: external audio output |
| channel | NSInteger | 1 | Channel count: 1 or 2 |
Statistics types
AoqStats
| Field | Type | Description |
|---|---|---|
| audioPublishStats | NSArray<AoqAudioPublishStats *> * | Audio publish statistics |
| videoPublishStats | NSArray<AoqVideoPublishStats *> * | Video publish statistics |
| dataMsgPublishStats | NSArray<AoqDataMsgPublishStats *> * | Data message publish statistics |
| audioSubscribeStats | NSArray<AoqAudioSubscribeStats *> * | Audio subscribe statistics |
| videoSubscribeStats | NSArray<AoqVideoSubscribeStats *> * | Video subscribe statistics |
| dataMsgSubscribeStats | NSArray<AoqDataMsgSubscribeStats *> * | Data message subscribe statistics |
| networkStats | AoqNetworkStats * | Network statistics |
AoqNetworkStats
| Field | Type | Description |
|---|---|---|
| sendBitrate | NSUInteger | Send bitrate (bps) |
| sendBytes | NSUInteger | Cumulative bytes sent |
| recvBitrate | NSUInteger | Receive bitrate (bps) |
| recvBytes | NSUInteger | Cumulative bytes received |
| loss | NSUInteger | Packet loss rate |
| rtt | NSUInteger | Round-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
| Difference | iOS | Android |
|---|---|---|
| Callback pattern | @protocol delegate | Abstract class listener |
| AVAudioSession control | setAudioSessionRestriction: (iOS only) | No equivalent |
| Audio focus callback | None (uses onAudioDeviceInterrupted: instead) | onAudioDeviceFocusChanged |
| Video pixel format | Supports CVPixelBuffer zero-copy | Supports TextureOES / Texture2D |
| Video rendering view | UIView | SurfaceView / TextureView |
| Bluetooth mode config | No isBTScoMode (managed by the OS) | AoqCreateConfig.isBTScoMode |
| Video frame callback write-back | I420 / CVPixelBuffer | I420 |