# Guiji Duix-SDK V1.2.0 Documentation
Last Updated: November 15, 2024
This document introduces how to use the SAAS DUIX iOS SDK, including installation, download, key interfaces, and code examples.
# Material Preparation
GJDigitalSDK.framework, WebRTC.framework Download: duix_sample_ios_1.2.0.zip
The config.json in Resources.bundle inside GJDigitalSDK.framework contains the main domain configuration, which generally can use the default configuration.
# Development Environment
Development Tool: Xcode
# Quick Start
#pragma mark -Start Session
- (void)toStart {
[[DigitalManager manager] initWithAppId:AppId appKey:AppKey conversationId:ConversationId block:^(BOOL isSuccee, NSString *errorMsg) {
if (isSuccee) {
[[DigitalManager manager] toStart];
} else {
NSLog(@"GJDigitalDemo==errorMsg==%@",errorMsg);
}
}];
}
# Call Flow
1. Prepare authorized appId, appKey, conversationId before starting DUIX service;
2. Authorize microphone permission;
3. Initialize digital human rendering, ASR, and dialogue interaction service with init, start initializing communication;
4. Call toStart function to begin rendering the digital human;
5. Call text driving, audio driving, text Q&A, interruption based on your needs;
6. Call toStop to end and release digital human rendering.
# SDK Integration (Reference GJDigitalSDKDemo)
1. Drag and drop GJDigitalSDK.framework and webrtc files into the project's resource directory:
Project-General-Frameworks,Libraries,and Embedded Content, set the following frameworks to
GJDigitalSDK.framework
WebRTC.framework
Change to Embed & Sign
2. Add recording permission and local network permission in Info.plist file
<key>NSLocalNetworkUsageDescription</key>
<string>Request local network permission</string>
<key>NSMicrophoneUsageDescription</key>
<string>Need recording permission for voice recognition</string>
<key>NSCameraUsageDescription</key>
<string>Request camera permission</string>
# SDK Configuration Properties
/**
* Open microphone (default YES)
*/
@property (nonatomic, assign) BOOL isOpenMicrophone;
/**
* openAsr whether to open asr recognition, default YES
*/
@property (nonatomic, assign) BOOL openAsr;
/**
* Minimum bitrate, default 2000
*/
@property (nonatomic, strong) NSString *minBitrate;
/**
* Maximum bitrate, default 4000
*/
@property (nonatomic, strong) NSString *maxBitrate;
/**
* Retry interval time, default 0
*/
@property (nonatomic, assign) NSInteger timeToReconnected;
/**
* Connection timeout, default 60000
*/
@property (nonatomic, assign) NSInteger timeToConnected;
/**
* 0: Remote audio/video, 1: Only remote audio
*/
@property (nonatomic, assign) NSInteger rtc_audio_type;
/**
* Enable remote screen recording, default NO
*/
@property (nonatomic, assign) BOOL enableRec;
/**
* One-shot recognition (not using audio/video): no, long link recognition: yes, default no
*/
@property (nonatomic, assign) BOOL isAsr;
/**
* Enable local microphone (default YES)
*/
@property (nonatomic, assign) BOOL isShowLocalAudio;
/**
* Show local video (default NO)
*/
@property (nonatomic, assign) BOOL isShowLocalVideo;
/**
* Open local camera (default NO)
*/
@property (nonatomic, assign) BOOL isOpenCamera;
/**
* Close camera when ending session (default YES)
*/
@property (nonatomic, assign) BOOL isStopCamera;
/**
* Front or rear camera, default YES means front camera
*/
@property (nonatomic, assign) BOOL usingFrontCamera;
/**
* Digital human configuration
*/
@property (nonatomic, strong) NSDictionary *humanConfig;
/**
* Session ID
*/
@property (nonatomic, strong) NSString *sessionId;
/**
* User ID (for troubleshooting)
*/
@property (nonatomic, strong) NSString *userId;
/**
* App name (for troubleshooting)
*/
@property (nonatomic, strong) NSString *appName;
/**
* Extension field
*/
@property (nonatomic, strong) NSDictionary *extContext;
/**
* Support live mode, default NO
*/
@property (nonatomic, assign) BOOL isLive;
/**
* Nation 0 China, 1 Overseas, configured from Resources.bundle
*/
@property (nonatomic, assign) NSInteger nation;
/**
* Default domain, configured from Resources.bundle
*/
@property (nonatomic, strong) NSString *baseUrl;
/**
* Default 540
*/
@property (nonatomic, assign)NSInteger cameara_width;
/**
* Default 960
*/
@property (nonatomic, assign)NSInteger cameara_height;
/**
* Default 25
*/
@property (nonatomic, assign)NSInteger cameara_fps;
/**
* Support multimodal 0 no 1 yes, default takes backend configuration parameters, manual setting takes effect after initWithAppId
*/
@property (nonatomic, assign)NSInteger multimodal;
####SDK key interfaces
/**
*SDK initialization
*
* - Parameters:
* - appId: appId
* - appKey: appkey
*- conversionId: Conversation Id
*- Block: callback
*/
- (void)initWithAppId:(NSString *)appId appKey:(NSString *)appKey conversationId:(NSString *)conversationId block:(void (^)(BOOL isSuccee, NSString *errorMsg))block;
/**
*Start communication
*/
- (void)toStart;
/**
*End communication
*/
- (void)toStop;
/**
*Text driven digital humans
*
* - Parameters:
*- text: Text content
*- Interrupt: Do you want to interrupt the previous sentence
*/
- (void)commandEventWithText:(NSString *)text interrupt:(BOOL)interrupt;
/**
*Audio driven digital human
*
* - Parameters:
*- AudioURL: Audio address
*- Interrupt: Do you want to interrupt the previous sentence
*/
- (void)commandEventWithAudioUrl:(NSString *)audioUrl interrupt:(BOOL)interrupt;
/**
*Text Q&A
*
* - Parameters:
*- text: Text content
*- Interrupt: Do you want to interrupt the previous sentence
*/
- (void)commandAskWithText:(NSString *)text interrupt:(BOOL)interrupt;
/**
*Interrupt the digital person's broadcast
*/
- (void)toBreakDigital;
/**
*Microphone reception
*
*- Parameter isEnabled: YES indicates reception, NO indicates mute
*/
- (void)setMute:(BOOL)isEnabled;
/**
*Digital Person Mute
*
*- Parameter enable: YES indicates mute, NO indicates sound reception
*/
- (void)toSpeakerMute:(BOOL)enable;
####SDK Proxy
------------------ DigitalViewDelegate -----------------------
/**
*Load digital human resources
*
* - Parameters:
*- isSuccess: Whether it was successful or not
*- progress: loading progress
*/
- (void)onVideoShow:(BOOL)isSuccess progress:(float)progress;
/**
*Abnormal callback
*
* - Parameters:
*- ErrerCode: Error code
*- ErrrMsg: Error message
*/
- (void)onError:(NSInteger)errorCode errorMsg:(NSString *)errorMsg;
@optional
/**
*ASR begins to recognize
*/
- (void)toWebrtcAsrStart;
/**
*ASR recognition
*
* - Parameters:
*- asrText: Recognized Text
*- isFinnish: Is it over
*/
- (void)toWebrtcAsrText:(NSString *)asrText isFinish:(BOOL)isFinish;
/**
*Start talking
*
*- Parameter dict: Dictionary information for starting to speak
*/
- (void)toSpeakStart:(NSDictionary *)dict;
/**
*End speaking
*
*- Parameter dict: End of speech dictionary information
*/
- (void)toSpeakStop:(NSDictionary *)dict;
/**
*The audio version starts speaking
*
*- Parameter dict: Dictionary information for starting to speak
*/
- (void)toTTSSpeakStart:(NSDictionary *)dict;
/**
*Audio version ends speaking
*
*- Parameter dict: End of speech dictionary information
*/
- (void)toTTSSpeakStop:(NSDictionary *)dict;
/**
*Central control ends call, sends bye event
*/
- (void)onByeBye;
/**
*Remote video communication completed
*/
- (void)onRTCReomteSuccess;
/**
*Did the audio load successfully
*
*- Parameter isSuccess: Success or not
*/
- (void)onAudioShow:(BOOL)isSuccess;
/**
*WebRTC connection status callback
*
* - Parameter state: RTCIceConnectionState
*/
- (void)didIceConnectionChange:(RTCIceConnectionState)state;
/**
*After obtaining the rendering information, the central control notifies the client
*
* - Parameters:
* - ID: id
* - name: name
*/
- (void)onRender:(NSString *)ID name:(NSString *)name;
/**
*Obtain the video stream of local videos
*
* - Parameters:
* - capturer: capturer
*- frame: video frame
*/
- (void)capturer:(RTCVideoCapturer *)capturer didCaptureVideoFrame:(RTCVideoFrame *)frame;
/**
*Obtain remote audio stream
*
* - Parameter sampleBuffer: Buffer
*/
- (void)onRemoteAudioBuffer:(CMSampleBufferRef)sampleBuffer;
/**
*
* Flip camera
*/
- (void)swichCamera;
@end
####Module Usage Code Sample Detailed demo final code,:
///Set custom View
[DigitalManager manager].remote_view = self.customView;
#Pragma mark SDK initialization
[[GJAccess manager] getCamerapermissions:^(bool isPermis) {
if (isPermis) {
[[DigitalManager manager] initWithAppId:AppId appKey:AppKey conversationId:ConversationId block:^(BOOL isSuccee, NSString *errorMsg) {
if (isSuccee) {
[[DigitalManager manager] toStart];
} else {
NSLog(@"GJDigitalDemo==errorMsg==%@",errorMsg);
}
}];
}
}];
#Pragma mark - End session
- (void)toStop {
self.digitalShow = NO;
[[DigitalManager manager] toStop];
}
#Pragma mark SDK agent DigitalViewDelegate
#Pragma mark - Display whether the video has been loaded completely
- (void)onVideoShow:(BOOL)isSuccess progress:(float)progress {
if (isSuccess) {
self.digitalShow = YES;
NSLog (@ "GJDigitalDemo==loading completed");
} else {
NSLog (@ "GJDigitalDemo==loading -% lf", progress);
}
}
#Pragma mark - Abnormal scenario error message
- (void)onError:(NSInteger)error_code errorMsg:(NSString *)errorMsg {
if (error_code == -1 || error_code == -2) {
//MQTT connection exception
} else if (error_code == 50001) {
//Wrong or empty appId
} else if (error_code == 50002) {
//Resource check failed, please contact the administrator
} else if (error_code == 50003) {
//Resource usage, please check and try again~
} else if (error_code == 50004) {
//Human request timeout~
} else if (error_code == 50005) {
//Abnormal retrieval of resources from the resource group
} else if (error_code == 50006) {
//Signature failed
} else if (error_code == 50007) {
//Total concurrency of resources is insufficient, please check and try again~
} else if (error_code == 50009) {
//Resource timeout or not configured~
}
NSLog(@"GJDigitalDemo==errorMsg==%@",errorMsg);
}
####Common errors
| Error code | Description |
|---|---|
| -1 | MQTT connection exception |
| -2 | The client interface requests an HTTP status code exception |
| -3 | Client obtains DUIX resources abnormally |
| -4 | Client MQTT connection failed |
| -5 | Client WebRTC SDP creation failed, usually due to iceServer exception |
| -6 | Client WebRTC SDP setting failed, usually due to iceServer exception |
| -7 | Abnormal client session interaction, common examples include authentication failure, ASR resource startup failure, etc |
| 1005 | Server token cannot be empty |
| 1006 | Server token failure |
| 1007 | Server script information does not exist |
| 1009 | Insufficient number of available server users |
| 2002 | Server session information does not exist |
| 40001 | Invalid server appid or appscrect |
| 40002 | Internal server error |
| 50001 | Incorrect or empty appId |
| 50002 | Resource check failed, please contact the administrator |
| 50003 | Resource usage, please check and try again~ |
| 50004 | Human request timeout~ |
| 50005 | Abnormal retrieval of resources from resource group |
| 50006 | Signature failed |
| 50007 | Total concurrency of resources is insufficient, please check and try again~ |
| 50009 | Resource timeout or not configured~ |