API 概览

/* SDK 配置项 */
struct SDKConfigs
{
    XYString cloudServer = "";      /* 云服务地址, 私有云地址非标端口需要带端口 i.e. private.cloud.com:9443, 123.123.123.123:9773 */
    XYString openapiServer = "";    /* 开放平台地址 */
    XYString openapiToken = "";     /* 开放平台口令 */
    XYString logFolder = "";        /* 日志路径 */
    XYString clientId = "";         /* 应用clientId */
    XYString clientSecret = "";     /* 应用clientSecret */
    SDKSoftSysType sysType;         /* 终端类型(会根据终端类型做性能优化) */
    bool enablePushVideo = true;    /* 使能SDK主动回调裸流给用户 */
    bool enableBulkRoster = false;  /* 暂未使用 */
};

virtual bool startup(INemoSDKCallbacks *cb, const SDKConfigs& sdkConfigs) = 0;

/* 停止SDK，关闭应用前调用该方法 */
virtual void shutdown() = 0; // tear down all internal resources

virtual void loginXYLinkAccount(const char* userName, const char* password) = 0;

virtual void loginExternalAccount(const char* extID, const char* extUserId, const char* displayName) = 0;

virtual void loginEnterpriseAccount(const char* extID, const char* account) = 0;

virtual void logout() = 0;

virtual void refreshToken(const char* refreshToken) = 0;

virtual void makeCall(const char* number, const char* meetingPwd, SDKCallMode mode, 
                      const char* displayName = "", bool isVideoMute = false, 
                      bool isAudioMute = false) = 0;

virtual void hangup() = 0;

virtual void acceptCall() = 0;

virtual void rejectCall() = 0;

virtual void sendSpeakingRequest() = 0;

virtual void sendSpeakingEnd() = 0;

virtual void cancelSpeakingRequest() = 0;

virtual void subscribeRoster(const XYArray<XYString>& uriList) = 0;

/* 自定义布局请求 */
struct SDKLayoutReq
{
    int pageIndex = 0;                  /* 0表示非对称布局，1表示对称第一屏 */
    int maxViewCountPerPage;            /* 每一屏最大清流数量 */
    XYArray<SDKViewReqInfo> reqList;    /* 清流列表 */
};

virtual void requestLayout(const SDKLayoutReq& layoutReq) = 0;

/* 视频帧率 */
enum SDKVideoFrameRate
{
    VideoFrameRate375,          /* 3.75fps */
    VideoFrameRate500,          /* 5.00fps */
    VideoFrameRate750,          /* 7.50fps */
    VideoFrameRate1500,         /* 15.00fps */
    VideoFrameRate3000,         /* 30.00fps */
    VideoFrameRate6000,         /* 60.00fps */
};

virtual bool getVideoFrame(const char* sourceId, int sourceKey, SDKVideoFrame& frame) = 0;

virtual void setVideoMute(bool bMute) = 0;

virtual void setMicMute(bool bMute) = 0;

/* 视频配置 */
struct SDKVideoProfile
{
    SDKVideoResolution maxResPvtx;          /* 最大发送(编码)分辨率 */
    SDKVideoResolution maxResPvrx;          /* 最大接收(解码)分辨率 */
    SDKVideoFrameRate maxFpsPvtx;           /* 最大发送(编码)帧率 */
    SDKVideoFrameRate maxFpsPvrx;           /* 最大接收(解码)帧率 */
};

virtual void setVideoProfile(const SDKVideoProfile& videoProfile) = 0;

virtual void switchCallMode(bool audioMode, bool audioMute, bool videoMute) = 0;

/* 视频分辨率 : 16/9 */
enum SDKVideoResolution
{
    VideoResolution90P,         /* 暂不支持 */
    VideoResolution180P,        /* 有效帧率:15fps */
    VideoResolution360P,        /* 有效帧率:15fps|30fps */
    VideoResolution720P,        /* 有效帧率:15fps|30fps */
    VideoResolution1080P,       /* 有效帧率:15fps|30fps|60fps */
    VideoResolution4K,          /* 有效帧率:30fps */
    VideoResolutionUnknown
};

virtual void setLocalPreviewResolution(SDKVideoResolution res) = 0;

/*
 * !!!废弃!!!
 * startContentSharing: 开启内容共享
 * win 默认全屏
 * linux 默认起始坐标(0, 0), 1920 x 1080
 */
virtual void startContentSharing(bool withDesktopAudio) = 0;

/* 
 * !!!废弃!!!
 * startContentSharing: 开启内容共享 - linux only, win not support
 * 区域: 起始位置(startX, startY), rectWidth x rectHeight
 */
virtual void startContentSharing(bool withDesktopAudio, int startX, int startY, 
                                 int rectWidth, int rectHeight) = 0;
struct SDKRegion {
  int x = 0;      // the X-coordinate of the top-left point of region
  int y = 0;      // the Y-coordinate of the top-left point of region
  int width = 0;  // width of region
  int height = 0; // height of region
};

// It used to startContentCapture function as a param.
struct SDKContentInfo {
  int64_t viewId = 0;     // not used
  bool withAudio = false; // content audio
  SDKRegion region;       // for region share, fullscreen share not need this
};

/*
 * 屏幕共享
 */
virtual void startContentSharing(const char *monitor, const SDKContentInfo &contentInfo) = 0;

  /// @brief 更新共享内容采集的区域
  /// @param monitor 显示器名称
  /// @param x 采集区域的x坐标
  /// @param y 采集区域的y坐标
  /// @param width 采集区域的宽度
  /// @param height 采集区域的高度
  virtual void updateContentCaptureRegion(int x, int y, int width, int height) = 0;

virtual void suspendContentShare() = 0;

virtual void restartContentShare() = 0;

virtual void stopContentSharing() = 0;

virtual void broadcastEletronicBadge(bool enable) = 0;

enum SDKFaceType
{
    SDKFaceType_Detect, // face detect 扫描模式
    SDKFaceType_Tracker, // face tracker
    SDKFaceType_EletronicBadge, // eletronic badge 铭牌模式
};

virtual void enableFaceDetectMode(SDKFaceType faceType, bool enable) = 0;

virtual void getFaceInfo(const XYArray<int32_t>& faceId) = 0;

virtual void setEnableGPUs(const XYArray<XYString> &enableGPUs) = 0;

enum SDKVirtualBgMode
{
    VirtualBgMode_None = 0,     /* 无 */
    VirtualBgMode_BgBlur,   /* 背景虚化 */
    VirtualBgMode_BgImage   /* 虚拟背景 */
};

virtual void setVirtualBgMode(SDKVirtualBgMode mode) = 0;

virtual void setVirtualBgImage(const char* imgPath) = 0;

enum SDKBeautyStyle
{
    BeautyStyle_None = 0,       /* 无 */
    BeautyStyle_Smooth,         /* 磨皮 */
    BeautyStyle_Whiten,         /* 美白 */
    BeautyStyle_Blush           /* 红润 */
};

virtual void setVideoBeautyEffect(SDKBeautyStyle style, int effectLevel) = 0;

enum SDKFilterStyle
{
    FilterStyle_None = 0,       /* 无 */
    FilterStyle_Concise,        /* 简洁 */
    FilterStyle_Natural,        /* 自然 */
    FilterStyle_Exquisite,      /* 精致 */
    FilterStyle_Peaceful,       /* 宁静 */
    FilterStyle_Soft,           /* 柔和 */
    FilterStyle_LightLuxury,    /* 轻奢 */
    FilterStyle_Youth,          /* 青春 */
    FilterStyle_Rain,           /* 雨后 */
    FilterStyle_Campus,         /* 校园 */
    FilterStyle_Warmth,         /* 热情 */
    FilterStyle_Refreshing,     /* 清新 */
    FilterStyle_Galaxy,         /* 银河 */
    FilterStyle_Pure,           /* 清澈 */
    FilterStyle_Dawn,           /* 清晨 */
    FilterStyle_Dream,          /* 梦幻 */
    FilterStyle_Highlight,      /* 高光 */
    FilterStyle_Elegant,        /* 典雅 */
    FilterStyle_Nostalgia,      /* 怀旧 */
    FilterStyle_Dark,           /* 暗调 */
    FilterStyle_Retro           /* 老电影 */
};

virtual void setVideoFilterEffect(SDKFilterStyle style, int effectLevel) = 0;

/*呼叫中统计信息 */
struct SDKStatistics
{
    SDKAVSessionStatistics people;          /* 与会人媒体统计信息 */
    SDKAVSessionStatistics content;         /* 共享内容媒体统计信息 */
    SDKNetworkStatistics network;           /* 网络状况统计 */
    XYString encrypt;
};

virtual const SDKStatistics& getStatistics() = 0;

virtual const SDKDetailStatistics& getDetailStatistics() = 0;

virtual void startCamera() = 0;

virtual void stopCamera() = 0;

/* 显示器大小 */
struct SDKRect
{
    float x;
    float y;
    float width;
    float height;
};

/* 显示器信息 */
struct SDKMonitorInfo
{
    XYString monitorName;
    SDKRect minitorRect;
};

virtual const XYArray<SDKMonitorInfo>& getMonitorList() = 0;

/* 音视频设备类型 */
enum SDKMediaDevType
{
    SDKMediaDevType_Camera,
    SDKMediaDevType_Microphone,
    SDKMediaDevType_Speaker
};

/* 媒体设备信息 */
struct SDKMediaDevInfo
{
    XYString devId;
    XYString devName;
    bool isSelected;
};

virtual const XYArray<SDKMediaDevInfo>& getDevList(SDKMediaDevType t) = 0;

/* 通用选择设备 (Linux平台通话中选择设备, 调用chooseDev(SDKMediaDevType, const char*, bool)接口, 通话外两者都行) */
virtual void chooseDev(SDKMediaDevType t, const char* devId) = 0;

/* Linux平台选择设备, isInConf: 是否在会中, 用于会中切换设备 */
virtual void chooseDev(SDKMediaDevType t, const char* devId, bool isInConf) = 0;

virtual int getMicPeakMeter() = 0;

virtual int getSpeakerPeakMeter() = 0;

virtual int getSpeakerVolume() = 0;

virtual void setSpeakerVolume(int volume) = 0;

virtual void setMicVolume(int value) = 0;

virtual void startPlayWavFile(const char* wavfile, int loopTimes) = 0;

virtual void stopPlayWavfile() = 0;

virtual void enableMicTest(bool enable) = 0;

virtual void logUpload(const char* comments) = 0;

virtual void setMicDataByAEEnabled(bool enabled) = 0;

virtual void enableAudioDump() = 0;

virtual void enableAECMode(bool enable) = 0;

virtual void setAudioAutoGainCtrl(int gain) = 0;

enum SDKFECCCommand
{
    FECC_TURN_LEFT,           /* 连续左转 */
    FECC_STEP_LEFT,           /* 向左步进 */
    FECC_TURN_RIGHT,          /* 连续右转 */
    FECC_STEP_RIGHT,          /* 向右步进 */
    FECC_TURN_STOP,           /* 水平转动停止。停止 FECC_TURN_ */
    TILT_CAMERA_TURN_UP,      /* 向上抬起 */
    TILT_CAMERA_STEP_UP,
    TILT_CAMERA_TURN_DOWN,    /* 向下低头 */
    TILT_CAMERA_STEP_DOWN,
    TILT_CAMERA_TURN_STOP,
    FECC_ZOOM_IN,             /* 放大 */
    FECC_ZOOM_OUT,            /* 缩小 */
    FECC_STEP_ZOOM_IN,
    FECC_STEP_ZOOM_OUT,
    FECC_ZOOM_TURN_STOP,
    MOVE_LEFT_TURN,
    MOVE_LEFT_STEP,
    MOVE_RIGHT_TURN,
    MOVE_RIGHT_STEP,
    MOVE_UP_TURN,
    MOVE_UP_STEP,
    MOVE_DOWN_TURN,
    MOVE_DOWN_STEP,
    MOVE_STOP,
    FECC_UNKNOWN
};

virtual void farEndHardwareControl(const char* callUri, SDKFECCCommand command, int angle) = 0;

virtual void getGPUInfo() = 0;

virtual void setAudioPeakMeterEnabled(bool enable) = 0;

virtual const XYArray<SDKAudioMeterInfo>& getAudioPeakMeters() = 0;

/// @brief 设置代理
/// @param type - 代理类型
/// @param proxy - 代理配置
virtual void setProxy(ProxyType type, const ProxyNetAddress& proxy) = 0;

/// @brief 验证socksProxy连通性
/// @param proxy - 代理配置
virtual void validateSocksProxy(const ProxyNetAddress& proxy) = 0;

virtual void checkAiCaptionSupport() = 0;

/**
  * 设置同传字幕语言类型
  * @param type 语言类型
  */
virtual void setSubtitleLanguage(SDKLanguageType type) = 0;

/* 登录状态 */
enum SDKLoginState
{
    SDKLoginState_LoggedIn,    /* 登录完成 */
    SDKLoginState_LoggingIn,   /* 正在登录 */
    SDKLoginState_LoggingOut,  /* 正在登出 */
    SDKLoginState_LoggedOut    /* 登出完成 */
};

struct SDKTokenInfo
{
    XYString accessToken = "";
    XYString refreshToken = "";
    long expires = 0;
};

/* 登录后的用户信息 */
struct SDKLoginInfo
{
    XYString callUri;           /* 终端标志，小鱼后台给登陆账号分配的唯一呼叫号码，如：123456@DESK， 123456为小鱼系统ID，DESK为终端类型 */
    XYString displayName;       /* 用户名称 */
    XYString extUserId;         /* 三方用户ID，同用户登录注册时提供的一样 */
    long userId;                /* 小鱼系统用户ID */
    long deviceId;              /* 软终端无需关注 */
    XYString email;             /* 邮箱 */
    XYString peerNumber;        /* 用于点对点呼叫号码 */
    SDKTokenInfo tokenInfo;     /* 统一鉴权信息 */
};

virtual void onLoginStateChanged(SDKLoginState state, SDKError error, const SDKLoginInfo& info) = 0;

virtual void onKickOut(const XYString& code) = 0;

/* 呼叫状态信息 */
struct SDKCallStateInfo
{
  SDKCallState callState = SDKCallState_Disconnected;
  XYString sdkError = "";
  XYString disconnectReason = "";
  XYString meetingNumber = "";
  XYString numberType = "";
  XYString displayName = "";
  bool isOnhold = false; // 是否是等候室模式, 等候室模式需要主持人同意,才能进入当前会议室
  uint32_t onHoldCount = 0;
  XYString waitingReason = "";
};

virtual void onCallStateChanged(const SDKCallStateInfo &callStateInfo) = 0;

/* 会议信息 */
struct SDKCallInfo
{
    int callMode;
    XYString remoteUri;
    XYString remoteName;
    XYString remoteNumber;
    XYString remoteAlias;
    XYString remoteType;
};

virtual void onCallInvited(const SDKCallInfo &info) = 0;

virtual void onHowlingDetected(bool detected) = 0;

virtual void onNetworkStateChanged(bool connected) = 0;

virtual void onConfInfoChanged(const SDKConfInfo &info) = 0;

/**
 * @param SDKConfMgmtInfo#muteMic:      mute/unmute
 * @param SDKConfMgmtInfo#disableMute:  是否为强制静音 true强制静音
 */
virtual void onConfMgmtChanged(const SDKConfMgmtInfo & info) = 0;

/* 内容共享状态 */
enum SDKContentState
{
    SDKContentState_Idle,
    SDKContentState_Sending,
    SDKContentState_Receiving,
    SDKContentState_NoBandwidth,
    SDKContentState_Error
};

virtual void onContentStateChanged(SDKContentState state) = 0;

/* 呼叫中的远端的视频流信息 */
struct SDKVideoStreamInfo
{
    SDKVideoState videoState;
    XYString videoSourceId;
    XYString displayName;
    XYString userNumber;
    XYString extUserId;             /* 三方用户ID，同用户登录注册时提供的一样 */
    XYString callUri;
    XYString Alias;
    uint32_t videoWidth;
    uint32_t videoHeight;
    uint32_t oriWidth;
    uint32_t oriHeight;
    bool audioMute;
    bool isContent;
    bool isActiveSpeaker;
    uint32_t feccOri;  /* 远端摄像头所具备的能力 */
    void* renderWnd;
    int pid;
};

virtual void onVideoStreamChanged(const XYArray<SDKVideoStreamInfo>& streamArray) = 0;

virtual void onVideoFrameReady(const char* dataSourceId, const SDKVideoFrame& videoFrame) = 0;

/* 视频状态 */
enum SDKVideoStatus
{
    SDKVideoStatus_Normal,
    SDKVideoStatus_LowAsLocalBw,
    SDKVideoStatus_LowAsLocalHardware,
    SDKVideoStatus_LowAsRemote,
    SDKVideoStatus_NetworkError,
    SDKVideoStatus_LocalWifiIssue
};

virtual void onVideoStatusChanged(SDKVideoStatus status) = 0;

virtual void onNetworkIndicatorLevel(int level) = 0;

virtual void onDeviceChanged(const SDKMediaDevType& devType) = 0;

virtual void onMicMuted(bool muted) = 0;

virtual void onMicEnergyReported(int energy) = 0;

virtual void onError(SDKError error) = 0;

virtual void onMicDataByAEReady(const void* data, int length, int formatType, 
                                int samplesPerSec, int numChannels, int bitsPerSample) {};

struct SDKConfCaption
{
    XYString action;
    XYString content;
    XYString location;
    bool scroll;
    XYString fontSize;
    XYString backgroundAlpha;
    XYString backgroundRGB;
    XYString fontRGB;
    XYString scrollSpeed;
    XYString fontFamily;
};

virtual void onConfCaptionChanged(const SDKConfCaption& notify) {};

struct SDKInOutInfo
{
    XYString displayName;
    XYString action; // in or out
    XYString extUserId;
};

virtual void onInOutReminder(const XYArray<SDKInOutInfo>& info) {};

virtual void onConfHandupCancelled() {};

/* 远端音频能量信息 */
struct SDKAudioMeterInfo
{
    XYString callUri;   /* 参会者标记(123456@DESK) */
    int energy;         /* 声音能量(0-100)*/
    uint32_t pid;
};

virtual void onSpeakersChanged(const XYArray<SDKAudioMeterInfo> &meters) {};

/* @link: refreshToken回调 */
virtual void onRefreshTokenResult(SDKError error, const SDKTokenInfo& token) {};

struct SDKAIParam
{
    bool isLocal;
    XYString calluri;
    uint32_t participantId;
    uint8_t type;
    uint8_t seq;
    XYArray<SDKFacePosition> positionArr;
};

virtual void onAIFaceRecv(const SDKAIParam& info) {};

/* @link: getFaceInfo回调 */
virtual void onAIFaceInfo(const XYString& data) {};

/* @link: getGPUInfo回调 */
virtual void onGPUInfoResult(const XYArray<XYString> &gInfo) {};

virtual void onMeetingMuteQuery(const XYString& meetingId, const XYString& key) {};

struct SDKRestApiResult
{
    XYString code;
    XYString body;
};

virtual void onLoguploadResult(const SDKRestApiResult& result) {};

/* 同传字母是否支持回调 */
virtual void onSupportAiCaptionResult(bool isSupport) {};

struct SDKAiCaptionInfo
{
  XYString src;
  XYString target;
  bool isEnd;
  bool isActive;
  XYString srcLang;
  XYString targetLang;
  XYString dn;
  uint64_t seTime;
  uint64_t endTime;
  uint64_t startTime;
  XYString url;
  XYString meetingId;
  uint32_t pid;
};
virtual void onAiCaptionInfoChanged(const SDKAiCaptionInfo& info) {};

/// @brief socksProxy验证连通性回调
/// @param errorCode 错误码
virtual void onSocksProxyValidateCompleted(SDKSocksValidateError error) {};

/* 参会人员 详细信息 */
struct SDKRosterInfo
{
  XYArray<SDKRosterElement> addParticipants;    /* 增加的参会方列表， 全量时也包含全部参会方 */
  XYArray<SDKRosterElement> changeParticipants; /* 有状态变化的参会方，增量时使用 */
  XYArray<XYString> delParticipants;            /* 删除的参会方（callUri），增量时使用 */
  SDKRosterType rosterType;                     /* 参会人员类型，全量还是增量 */
  uint32_t totalEpNum;                          /* 总参会人数  */
};
virtual void onRosterChanged(const SDKRosterInfo &info) = 0;