结构体

AgoraServiceConfiguration

C++
struct AgoraServiceConfiguration {
  bool enableAudioProcessor;
  bool enableAudioDevice;
  bool enableVideo;
  void* context;
  const char* appId;
  unsigned int areaCode;
  agora::CHANNEL_PROFILE_TYPE channelProfile;
  const char* license;
  rtc::AUDIO_SCENARIO_TYPE audioScenario;
  commons::LogConfig logConfig;
  bool useStringUid;
  IServiceObserver* serviceObserver;
  Optional<rtc::THREAD_PRIORITY_TYPE> threadPriority __deprecated;
  bool useExternalEglContext;
  bool domainLimit;
  AgoraServiceConfiguration() : enableAudioProcessor(true),
                                enableAudioDevice(true),
                                enableVideo(false),
                                context(NULL),
                                appId(NULL),
                                areaCode(rtc::AREA_CODE_GLOB),
                                channelProfile(agora::CHANNEL_PROFILE_LIVE_BROADCASTING),
                                license(NULL),
                                audioScenario(rtc::AUDIO_SCENARIO_DEFAULT),
                                useStringUid(false),
                                serviceObserver(NULL),
                                useExternalEglContext(false),
                                domainLimit(false){}
};

用于配置 IAgoraService 的全局参数。

调用 initialize 时设置这些参数。

成员参数

参数	数据类型	描述
`enableAudioProcessor`	`bool`	是否启用音频处理模块。 `true`：（默认）启用音频处理模块。 `false`：禁用音频处理模块。禁用后无法创建音频轨道。
`enableAudioDevice`	`bool`	是否启用音频设备模块。 `true`：（默认）启用音频设备模块。 `false`：禁用音频设备模块。注意在录制场景中，请确保将 `enableAudioDevice` 设置为 `false`。如果设置为 `true`，SDK 会报错，因为录制器实例没有任何音频设备。
`enableVideo`	`bool`	是否启用视频。 `true`：启用视频。 `false`：（默认）禁用视频。
`appId`	`const char*`	项目的。
`areaCode`	`unsigned int`	支持的区域码，默认值为 `AREA_CODE_GLOB`。
`channelProfile`	`agora::CHANNEL_PROFILE_TYPE`	频道场景。详见 `CHANNEL_PROFILE_TYPE`。
`license`	`const char*`	连接频道时用于验证的 License。根据 License 收费。
`audioScenario`	`rtc::AUDIO_SCENARIO_TYPE`	音频场景。详见 `AUDIO_SCENARIO_TYPE`。
`logConfig`	`commons::LogConfig`	日志配置。用于设置日志路径、日志大小和日志级别。详见 `LogConfig`。
`useStringUid`	`bool`	是否启用字符串类型的用户 ID。 `true`：启用字符串类型的用户 ID。 `false`：（默认）不启用字符串类型的用户 ID。
`domainLimit`	`bool`	是否启用域名限制。 `true`：仅连接已通过 DNS 解析的服务器。 `false`：（默认）连接服务器时不做限制。

VideoSubscriptionOptions

C++
struct VideoSubscriptionOptions {
  Optional<VIDEO_STREAM_TYPE> type;
  Optional<bool> encodedFrameOnly;
  VideoSubscriptionOptions() {}
};

用于设置视频订阅选项。

成员参数

参数数据类型描述

参数	数据类型	描述
`type`	`Optional<VIDEO_STREAM_TYPE>`	要订阅的视频流类型，详见 `VIDEO_STREAM_TYPE`。默认值为 `VIDEO_STREAM_HIGH`，表示高质量视频流。
`encodedFrameOnly`	`Optional<bool>`	是否仅订阅编码后的视频数据： `true`：仅订阅编码后的视频数据。 `false`：（默认）订阅解码后的视频数据。

type

Optional<VIDEO_STREAM_TYPE>

要订阅的视频流类型，详见 VIDEO_STREAM_TYPE。

默认值为 VIDEO_STREAM_HIGH，表示高质量视频流。

encodedFrameOnly

Optional<bool>

是否仅订阅编码后的视频数据：

true：仅订阅编码后的视频数据。
false：（默认）订阅解码后的视频数据。

Rectangle

C++
struct Rectangle {
  int x;
  int y;
  int width;
  int height;

  Rectangle() : x(0), y(0), width(0), height(0) {}
  Rectangle(int xx, int yy, int ww, int hh) : x(xx), y(yy), width(ww), height(hh) {}
};

设置目标区域相对于屏幕或窗口的位置。

如果未设置该参数，SDK 会选择整个屏幕或窗口。

成员参数

参数	数据类型	描述
`x`	`int`	从左上角起的水平偏移量。
`y`	`int`	从左上角起的垂直偏移量。
`width`	`int`	区域的宽度。
`height`	`int`	区域的高度。

WatermarkRatio

C++
struct WatermarkRatio {
  float xRatio;
  float yRatio;
  float widthRatio;

  WatermarkRatio() : xRatio(0.0), yRatio(0.0), widthRatio(0.0) {}
  WatermarkRatio(float x, float y, float width) : xRatio(x), yRatio(y), widthRatio(width) {}
};

用于设置水印在屏幕上的位置和大小。

WatermarkRatio 用于设置水印在屏幕上的位置和大小。

(xRatio, yRatio) 表示水印左上角的坐标，决定水印左上角相对于屏幕左上角的距离。
widthRatio 表示水印的宽度，SDK 会根据该值按比例计算水印高度，确保图像不失真。

成员参数

参数	数据类型	描述
`xRatio`	`float`	水平方向上水印左上角的位置。以屏幕左上角为原点，表示水印左上角相对于原点的水平距离。取值范围为 [0.0, 1.0]。
`yRatio`	`float`	垂直方向上水印左上角的位置。以屏幕左上角为原点，表示水印左上角相对于原点的垂直距离。取值范围为 [0.0, 1.0]。
`widthRatio`	`float`	水印的宽度。SDK 会根据该值按比例计算水印的高度，以保证缩放后图像不失真。取值范围为 [0.0, 1.0]。默认值为 0，表示不显示水印。

WatermarkOptions

C++
struct WatermarkOptions {
  bool visibleInPreview;
  Rectangle positionInLandscapeMode;
  Rectangle positionInPortraitMode;
  WatermarkRatio watermarkRatio;
  WATERMARK_FIT_MODE mode;
  int zOrder;

  WatermarkOptions()
      : visibleInPreview(true),
        positionInLandscapeMode(0, 0, 0, 0),
        positionInPortraitMode(0, 0, 0, 0),
        mode(FIT_MODE_COVER_POSITION),
        zOrder(0) {}
};

用于配置水印图像的显示、位置和适配方式。

成员参数

参数	数据类型	描述
`visibleInPreview`	`bool`	水印图像在本地视频预览中是否可见： `true`：（默认）水印图像在预览中可见。 `false`：水印图像在预览中不可见。
`positionInLandscapeMode`	`Rectangle`	当水印的适配模式为 `FIT_MODE_COVER_POSITION` 时，用于设置水印图像在横屏模式下的位置区域。详见 `Rectangle`。
`positionInPortraitMode`	`Rectangle`	当水印的适配模式为 `FIT_MODE_COVER_POSITION` 时，用于设置水印图像在竖屏模式下的位置区域。详见 `Rectangle`。
`watermarkRatio`	`WatermarkRatio`	当水印的适配模式为 `FIT_MODE_USE_IMAGE_RATIO` 时，用于设置水印的坐标。详见 `WatermarkRatio`。
`mode`	`WATERMARK_FIT_MODE`	水印的适配模式。详见 `WATERMARK_FIT_MODE`。
`zOrder`	`int`	水印图像的图层顺序，默认值为 0。

WatermarkTimestamp

C++
struct WatermarkTimestamp {
  int fontSize;
  const char* fontFilePath;
  WatermarkTimestamp() : fontSize(10), fontFilePath(NULL) {}
};

用于设置时间戳水印的字体大小和字体文件路径。

成员参数

参数	数据类型	描述
`fontSize`	`int`	`timestamp` 的字体大小。默认值为 10。
`fontFilePath`	`const char*`	`timestamp` 字体文件的路径。默认值为 `NULL`，表示使用系统默认字体。

WatermarkLitera

C++
struct WatermarkLitera {
  const char* wmLitera;
  const char* fontFilePath;
  int fontSize;

  WatermarkLitera() : wmLitera(NULL), fontFilePath(NULL), fontSize(10) {}
};

用于设置水印文字的内容、字体路径和字体大小。

成员参数

参数	数据类型	描述
`wmLitera`	`const char*`	`WatermarkLitera` 中的水印文字内容。默认值为 `NULL`。
`fontFilePath`	`const char*`	水印文字所使用的字体文件路径。默认值为 `NULL`，表示使用系统默认字体。
`fontSize`	`int`	水印文字的字体大小。默认值为 10。

WatermarkConfig

C++
struct WatermarkConfig {
  int index;
  WatermarkSourceType type;
  WatermarkTimestamp timestampSource;
  WatermarkLitera literaSource;
  const char* imageUrl;
  WatermarkOptions options;

  WatermarkConfig() : index(0), type(PICTURE), imageUrl(NULL) {}
};

用于配置水印参数。

成员参数

参数	数据类型	描述
`index`	`int`	水印索引，默认值为 0。
`type`	`WatermarkSourceType`	水印来源类型。详见 `WatermarkSourceType`。
`timestampSource`	`WatermarkTimestamp`	水印时间戳。详见 `WatermarkTimestamp`。
`literaSource`	`WatermarkLitera`	水印文字内容。详见 `WatermarkLitera`。
`imageUrl`	`const char*`	水印图片文件的 URL，默认值为 NULL。
`options`	`WatermarkOptions`	水印的选项配置。详见 `WatermarkOptions`。

EncryptionConfig

C++
struct EncryptionConfig {
  ENCRYPTION_MODE encryptionMode;
  const char* encryptionKey;
  uint8_t encryptionKdfSalt[32];
  bool datastreamEncryptionEnabled;
  EncryptionConfig()
      : encryptionMode(AES_128_GCM2),
        encryptionKey(OPTIONAL_NULLPTR),
        datastreamEncryptionEnabled(false) {
    memset(encryptionKdfSalt, 0, sizeof(encryptionKdfSalt));
  }
  const char* getEncryptionString() const {
    switch (encryptionMode) {
      case AES_128_XTS:
        return "aes-128-xts";
      case AES_128_ECB:
        return "aes-128-ecb";
      case AES_256_XTS:
        return "aes-256-xts";
      case SM4_128_ECB:
        return "sm4-128-ecb";
      case AES_128_GCM:
        return "aes-128-gcm";
      case AES_256_GCM:
        return "aes-256-gcm";
      case AES_128_GCM2:
        return "aes-128-gcm-2";
      case AES_256_GCM2:
        return "aes-256-gcm-2";
      default:
        return "aes-128-gcm-2";
    }
    return "aes-128-gcm-2";
  }
};

用于配置内建加密功能。

成员参数

参数	数据类型	描述
`encryptionMode`	`ENCRYPTION_MODE`	内建加密模式。声网建议使用 `AES_128_GCM2` 或 `AES_256_GCM2` 加密模式，这两种模式支持使用 salt 以提高安全性。详见 `ENCRYPTION_MODE`。
`encryptionKey`	`const char*`	字符串类型的加密密钥，长度不受限制。声网建议使用 32 字节的密钥。注意如果未设置加密密钥或将其设置为 NULL，则无法使用内建加密，SDK 会返回 `ERR_INVALID_ARGUMENT`（-2）。
`encryptionKdfSalt`	`uint8_t[32]`	Salt，长度为 32 字节。声网建议你在服务器端使用 OpenSSL 生成。注意该参数仅在 `AES_128_GCM2` 或 `AES_256_GCM2` 加密模式下生效。在这种情况下，请确保该参数不为 0。
`datastreamEncryptionEnabled`	`bool`	是否启用数据流加密。 `true`：启用数据流加密。 `false`：（默认）不启用数据流加密。

LogUploadServerInfo

C++
struct LogUploadServerInfo {
  const char* serverDomain;
  const char* serverPath;
  int serverPort;
  bool serverHttps;

  LogUploadServerInfo() : serverDomain(NULL), serverPath(NULL), serverPort(0), serverHttps(true) {}

  LogUploadServerInfo(const char* domain, const char* path, int port, bool https)
      : serverDomain(domain), serverPath(path), serverPort(port), serverHttps(https) {}
};

LogUploadServerInfo 用于配置日志上传服务器的信息。

成员参数

参数	数据类型	描述
`serverDomain`	`const char*`	日志上传服务器的域名。
`serverPath`	`const char*`	日志上传服务器的路径。
`serverPort`	`int`	日志上传服务器的端口号。
`serverHttps`	`bool`	是否使用 HTTPS 请求： `true`：使用 HTTPS 请求。 `false`：使用 HTTP 请求。

AdvancedConfigInfo

C++
struct AdvancedConfigInfo {
  LogUploadServerInfo logUploadServer;
};

高级配置信息。

成员参数

参数	数据类型	描述
`logUploadServer`	`LogUploadServerInfo`	日志上传服务器信息。详见 `LogUploadServerInfo`。

LocalAccessPointConfiguration

C++
struct LocalAccessPointConfiguration {
  const char** ipList;
  int ipListSize;
  const char** domainList;
  int domainListSize;
  const char* verifyDomainName;
  LOCAL_PROXY_MODE mode;
  AdvancedConfigInfo advancedConfig;
  bool disableAut;
  LocalAccessPointConfiguration()
      : ipList(NULL),
        ipListSize(0),
        domainList(NULL),
        domainListSize(0),
        verifyDomainName(NULL),
        mode(ConnectivityFirst),
        disableAut(true) {}
};

配置本地接入点的连接信息。

成员参数

参数	数据类型	描述
`ipList`	`const char**`	本地接入点的 IP 地址列表。
`ipListSize`	`int`	本地接入点 IP 地址的数量。
`domainList`	`const char**`	本地接入点的域名列表。
`domainListSize`	`int`	本地接入点域名的数量。
`verifyDomainName`	`const char*`	安装在特定本地接入点上的证书域名。传入空字符串 "" 表示使用该接入点上的 SNI（Server Name Indication）域名。SNI 是 TLS 协议的扩展。
`mode`	`LOCAL_PROXY_MODE`	本地代理连接模式。详见 `LOCAL_PROXY_MODE`。
`advancedConfig`	`AdvancedConfigInfo`	本地代理连接的高级配置信息。详见 `AdvancedConfigInfo`。
`disableAut`	`bool`	是否禁用 `vos-aut`： `true`：（默认）禁用 `vos-aut`。 `false`：不禁用 `vos-aut`。

MixerLayoutConfig

C++
struct MixerLayoutConfig {
  int32_t x;
  int32_t y;
  int32_t width;
  int32_t height;
  int32_t zOrder;
  float alpha;
  bool mirror;
  const char* image_path;
  int rotation;

  MixerLayoutConfig() : x(0), y(0), width(0), height(0), zOrder(0), alpha(1.0), mirror(false), image_path(NULL),rotation(0) {}
  MixerLayoutConfig(int ox, int oy, int w, int h, int order) : x(ox), y(oy), width(w), height(h), zOrder(order), alpha(1.0), mirror(false), image_path(NULL), rotation(0) {}
};

用于配置混合视频流中的视频区域布局。

成员参数

参数	数据类型	描述
`x`	`int32_t`	混合视频流中视频区域左上角的 x 坐标。
`y`	`int32_t`	混合视频流中视频区域左上角的 y 坐标。
`width`	`int32_t`	混合视频流中视频区域的宽度。
`height`	`int32_t`	混合视频流中视频区域的高度。
`zOrder`	`int32_t`	混合视频流中视频区域的图层顺序。值越大，图层越靠上。
`alpha`	`float`	混合视频流中视频区域的透明度。
`mirror`	`bool`	是否镜像混合视频流中的视频区域。 `true`：镜像视频区域。 `false`：不镜像视频区域。
`image_path`	`const char*`	占位图的 URL 地址。
`rotation`	`int`	混合视频流中视频区域的旋转角度。 `0`：不旋转。 `1`：顺时针旋转 90°。 `2`：顺时针旋转 180°。 `3`：顺时针旋转 270°。

MediaRecorderConfiguration

C++
struct MediaRecorderConfiguration {
  const char* storagePath;
  MediaRecorderContainerFormat containerFormat;
  MediaRecorderStreamType streamType;
  int maxDurationMs;
  int recorderInfoUpdateInterval;
  int width;
  int height;
  int fps;
  int sample_rate;
  int channel_num;
  agora::rtc::VIDEO_SOURCE_TYPE videoSourceType;

  MediaRecorderConfiguration()
      : storagePath(NULL),
        containerFormat(FORMAT_MP4),
        streamType(STREAM_TYPE_BOTH),
        maxDurationMs(120000),
        recorderInfoUpdateInterval(0),
        width(1280),
        height(720),
        fps(30),
        sample_rate(48000),
        channel_num(1),
        videoSourceType(rtc::VIDEO_SOURCE_CAMERA_PRIMARY) {}

  MediaRecorderConfiguration(const char* path, MediaRecorderContainerFormat format,
                             MediaRecorderStreamType type, int duration, int interval)
      : storagePath(path),
        containerFormat(format),
        streamType(type),
        maxDurationMs(duration),
        recorderInfoUpdateInterval(interval),
        width(1280),
        height(720),
        fps(30),
        sample_rate(48000),
        channel_num(1),
        videoSourceType(rtc::VIDEO_SOURCE_CAMERA_PRIMARY) {}
};

配置本地音视频录制。

成员参数

参数	数据类型	描述
`storagePath`	`const char*`	录制文件的绝对路径（包括文件扩展名）。例如，在 Windows 上为 `C:\Users\<user_name>\AppData\Local\Agora\<process_name>\example.mp4`，在 iOS 上为 `/App Sandbox/Library/Caches/example.mp4`，在 macOS 上为 `/Library/Logs/example.mp4`，在 Android 上为 `/storage/emulated/0/Android/data/<package name>/files/example.mp4`。注意请确保指定路径存在且可写。
`containerFormat`	`MediaRecorderContainerFormat`	录制文件的格式。详见 `MediaRecorderContainerFormat`。
`streamType`	`MediaRecorderStreamType`	录制内容类型。详见 `MediaRecorderStreamType`。
`maxDurationMs`	`int`	最大录制时长，单位为毫秒。默认值为 120000。
`recorderInfoUpdateInterval`	`int`	录制信息更新的时间间隔，单位为毫秒。取值范围为 [1000, 10000]。根据该值，SDK 会触发 `onRecorderInfoUpdated` 回调报告录制信息更新。
`width`	`int`	视频宽度。
`height`	`int`	视频高度。
`fps`	`int`	视频帧率。
`sample_rate`	`int`	音频采样率。
`channel_num`	`int`	音频声道数。
`videoSourceType`	`agora::rtc::VIDEO_SOURCE_TYPE`	仅用于外部频道录制的视频源类型。详见 `VIDEO_SOURCE_TYPE`。

RecorderInfo

C++
struct RecorderInfo {
  const char* fileName;
  unsigned int durationMs;
  unsigned int fileSize;

  RecorderInfo() : fileName(NULL), durationMs(0), fileSize(0) {}
  RecorderInfo(const char* name, unsigned int dur, unsigned int size)
      : fileName(name), durationMs(dur), fileSize(size) {}
};

录制文件的信息。

成员参数

参数	数据类型	描述
`fileName`	`const char*`	录制文件的绝对路径。
`durationMs`	`unsigned int`	录制时长，单位为毫秒。
`fileSize`	`unsigned int`	录制文件的大小，单位为字节。

LogConfig

C++
struct LogConfig {
  const char* filePath;
  uint32_t fileSizeInKB;
  LOG_LEVEL level;

  LogConfig() : filePath(NULL), fileSizeInKB(DEFAULT_LOG_SIZE_IN_KB), level(OPTIONAL_LOG_LEVEL_SPECIFIER LOG_LEVEL_INFO) {}
};

日志配置。

成员参数

参数	数据类型	描述
`filePath`	`const char*`	日志文件路径。默认为 `NULL`，表示使用默认路径。
`fileSizeInKB`	`uint32_t`	日志文件大小，单位为 KB。设置为 2048 表示使用默认大小。
`level`	`LOG_LEVEL`	日志级别。设置为 `LOG_LEVEL_INFO` 表示使用默认级别。详见 `LOG_LEVEL`。

VideoMixingLayout

C++
struct VideoMixingLayout
{
  int canvasWidth;
  int canvasHeight;
  int canvasFps;
  uint32_t backgroundColor;
  const char* backgroundImage;
  uint32_t userLayoutConfigNum;
  const UserMixerLayout* userLayoutConfigs;
};

混合视频流的布局配置。

成员参数

参数	数据类型	描述
`canvasWidth`	`int`	混合视频流画布的宽度，单位为像素。
`canvasHeight`	`int`	混合视频流画布的高度，单位为像素。
`canvasFps`	`int`	混合视频流的帧率（FPS）。
`backgroundColor`	`uint32_t`	混合视频流的背景颜色。使用 RGB 十六进制数值表示，不包含前缀 #。例如：0xFFB6C1 表示浅粉色。默认值为 0x000000（黑色）。
`backgroundImage`	`const char*`	混合视频流的背景图像路径。默认值为 NULL，表示无背景图像。若设置该参数，图像格式必须为 PNG 或 JPG。
`userLayoutConfigNum`	`uint32_t`	混合视频流中用户布局的数量。
`userLayoutConfigs`	`const UserMixerLayout*`	用户布局配置数组。详见 `UserMixerLayout`。

UserMixerLayout

C++
struct UserMixerLayout {
  user_id_t userId;
  MixerLayoutConfig config;
};

用于设置用户视频流在合流视频中的布局。

成员参数

参数	数据类型	描述
`userId`	`user_id_t`	要进行合流的视频流所属用户的用户 ID。
`config`	`MixerLayoutConfig`	该用户视频流在合流视频中的布局配置，详见 `MixerLayoutConfig`。

RemoteVideoStatistics

C++
struct RemoteVideoStatistics {
    int delay;
    int width;
    int height;
    int receivedBitrate;
    int decoderOutputFrameRate;
    VIDEO_STREAM_TYPE rxStreamType;
};

远端视频统计信息。

成员参数

参数	数据类型	描述
`delay`	`int`	视频帧的整体延迟（毫秒）。
`width`	`int`	远端视频轨道的宽度（像素）。
`height`	`int`	远端视频轨道的高度（像素）。
`receivedBitrate`	`int`	统计周期内接收到的码率（Kbps）。
`decoderOutputFrameRate`	`int`	远端视频轨道的解码器输出帧率（fps）。
`rxStreamType`	`VIDEO_STREAM_TYPE`	远端视频流类型。详见 `VIDEO_STREAM_TYPE`。

RemoteAudioStatistics

C++
struct RemoteAudioStatistics {
  int quality;
  int networkTransportDelay;
  int jitterBufferDelay;
  int audioLossRate;
};

远端音频的统计信息。

成员参数

参数	数据类型	描述
`quality`	`int`	远端音频轨道的音频质量。详见 `QUALITY_TYPE`。
`networkTransportDelay`	`int`	从发送端到接收端的网络传输延迟，单位为毫秒。
`jitterBufferDelay`	`int`	从接收端到抖动缓冲区的延迟，单位为毫秒。
`audioLossRate`	`int`	在统计时间间隔内的音频帧丢失率。

SpeakVolumeInfo

C++
struct SpeakVolumeInfo {
  user_id_t userId;
  unsigned int volume;
};

表示说话者的音量信息。

成员参数

参数	数据类型	描述
`userId`	`user_id_t`	说话者的用户 ID。
`volume`	`unsigned int`	说话者的音量，范围为 0 到 255。

AgoraServiceConfiguration

成员参数​

VideoSubscriptionOptions

成员参数​

Rectangle

成员参数​

WatermarkRatio

成员参数​

WatermarkOptions

成员参数​

WatermarkTimestamp

成员参数​

WatermarkLitera

成员参数​

WatermarkConfig

成员参数​

EncryptionConfig

成员参数​

LogUploadServerInfo

成员参数​

AdvancedConfigInfo

成员参数​

LocalAccessPointConfiguration

成员参数​

MixerLayoutConfig

成员参数​

MediaRecorderConfiguration

成员参数​

RecorderInfo

成员参数​

LogConfig

成员参数​

VideoMixingLayout

成员参数​

UserMixerLayout

成员参数​

RemoteVideoStatistics

成员参数​

RemoteAudioStatistics

成员参数​

SpeakVolumeInfo

成员参数​

成员参数

成员参数

成员参数

成员参数

成员参数

成员参数

成员参数

成员参数

成员参数

成员参数

成员参数

成员参数

成员参数

成员参数

成员参数

成员参数

成员参数

成员参数

成员参数

成员参数

成员参数