Class 及 Enum

Class

AgoraServiceConfig

Python

@dataclass(kw_only=True)
class AgoraServiceConfig:
    log_path: str = ""
    log_size: int = 0
    enable_audio_processor: int = 1
    enable_audio_device: int = 0
    enable_video: int = 0
    context: object = None
    appid: str = ""
    area_code: int = AreaCode.AREA_CODE_GLOB.value
    channel_profile: ChannelProfileType = ChannelProfileType.CHANNEL_PROFILE_LIVE_BROADCASTING
    audio_scenario: AudioScenarioType = AudioScenarioType.AUDIO_SCENARIO_CHORUS
    use_string_uid: int = 0

AgoraServiceConfig 类的全局配置。在调用 initialize 方法时设置。

参数	描述
log_path	日志文件的完整路径。如果该参数设为 None，则日志位于当前应用程序的 pwd 目录。 。
log_size	单个日志文件的大小，单位为 KB。默认值为 1024 KB。如果你将该参数设为 1024 KB，SDK 会最多输出总计 5 MB 的日志文件。如果你将该参数设为小于 1024 KB，设置不生效，单个日志文件最大仍为 1024 KB。
enable_audio_processor	是否开启音频处理模块。 0: 关闭音频处理模块。你将无法创建音频轨道。 1: (默认) 开启音频处理模块。
enable_audio_device	是否开启音频设备模块（Audio Device Module, ADM）。ADM 用来管理音频设备，例如录制和播放音频。 0: 关闭音频设备模块。你无法录制和播放音频。 1: (默认) 开启音频设备模块。你可以录制和播放音频。 注意：如果你将 enable_audio_device 设为 0 且将 enable_audio_processor 设为 1，你将无法使用音频设备，但你可以推送 PCM 音频数据。
enable_video	是否开启视频。 0: (默认) 关闭视频。 1: 开启视频。
context	上下文。
appid	你的声网项目的 App ID。如果你的声网项目开启了 Token 鉴权，你也可以将此参数赋值为 RTC Token。详见获取 App ID。
area_code	服务器的访问区域。该功能为高级设置，适用于有访问安全限制的场景。区域码支持位操作。指定访问区域后，SDK 会连接指定区域内的声网服务器。详见 AreaCode。
channel_profile	频道场景。详见 ChannelProfileType。
audio_scenario	音频编码属性。详见 AudioScenarioType。
use_string_uid	是否使用 String 用户 ID。 0: 不使用。 1: 使用。

AudioEncoderConfiguration

Python

@dataclass(kw_only=True)
class AudioEncoderConfiguration:
    audioProfile: AudioProfileType = AudioProfileType.AUDIO_PROFILE_DEFAULT

音频编码设置。

参数	描述
audioProfile	音频场景。详见 AudioProfileType。

AudioFrame

Python

@dataclass(frozen=True, kw_only=True)
class AudioFrame:
    type: int
    samples_per_channel: int
    bytes_per_sample: int
    channels: int
    samples_per_sec: int
    buffer: bytearray
    render_time_ms: int
    avsync_type: int

AudioFrame 定义。

参数	描述
type	音频帧类型。仅支持填 0，表示 16 位 PCM 数据。
samples_per_channel	每个声道的采样点数。
bytes_per_sample	每个采样点的字节数。对于 PCM 来说，一般使用 16 bit，即两个字节。
channels	声道数量（如果是立体声，数据是交叉的）。
samples_per_sec	每声道每秒的采样点数。
buffer	声音数据缓存区（如果是立体声，数据是交叉存储的）。缓存区数据大小 buffer = samples × channels × bytes_per_sample。
render_time_ms	外部音频帧的渲染时间戳。你可以使用该时间戳还原音频帧顺序；在有视频的场景中（包含使用外部视频源的场景），该参数可以用于实现音视频同步。
avsync_type	预留参数。

AudioSubscriptionOptions

Python

@dataclass(kw_only=True)
class AudioSubscriptionOptions:
    packet_only: int = 0
    pcm_data_only: int = 0
    bytes_per_sample: int = 0
    number_of_channels: int = 0
    sample_rate_hz: int = 0

音频订阅选项。

参数	描述
packet_only	是否仅订阅音频包： 0: (默认) SDK 自动对音频进行解码。 1: 仅订阅音频包。SDK 不会对音频进行解码。 注意：如果该参数设为 1，结构体中的其他参数无效。
pcm_data_only	是否仅订阅 PCM 数据： 0:（默认）SDK 自动对远端音频流进行编码。 1: 仅订阅 PCM 数据。
bytes_per_sample	每个音频采样的字节数。
number_of_channels	音频声道数。
sample_rate_hz	音频采样率（Hz）。

EncodedAudioFrame

Python

@dataclass(kw_only=True)
class EncodedAudioFrameInfo:
    capture_timems: int = 0
    codec: AudioCodecType = AudioCodecType.AUDIO_CODEC_AACLC
    number_of_channels: int = 1
    sample_rate: int = 16000
    samples_per_channel: int = 1024
    send_even_if_empty: int = 1
    speech: int = 1

已编码的音频数据。

参数	描述
capture_timems	音频帧的 Unix 时间戳（毫秒）。
codec	音频编码类型音频编码类型。详见 AudioCodecType。
number_of_channels	音频帧的声道数。
sample_rate	音频帧采样率（Hz）。
samples_per_channel	每个声道的样本数。对于 aac 编码格式，默认为 1024；对于 Opus 编码格式，默认为 960。
send_even_if_empty	是否发送空音频帧： 0: 不发送空音频帧。 1: （默认）发送空音频帧。
speech	音频源是否为语音： 0: 音频源不是语音。 1: （默认）音频源是语音。

EncodedVideoFrameInfo

Python

@dataclass(kw_only=True)
class EncodedVideoFrameInfo:
    codec_type: VideoCodecType = VideoCodecType.VIDEO_CODEC_NONE
    width: int = 0
    height: int = 0
    frames_per_second: int = 0
    frame_type: int = 0
    rotation: int = 0
    track_id: int = 0
    capture_time_ms: int = 0
    decode_time_ms: int = 0
    uid: int = 0
    stream_type: int = 0

已编码的视频数据。

参数	描述
codec_type	视频编码类型。详见 VideoCodecType。
width	视频帧宽度（像素）。
height	视频帧高度（像素）。
frames_per_second	每秒的视频帧数量。用于计算编码视频帧的时间戳。如果设为 0，SDK 会使用真实的时间戳。
frame_type	已编码视频帧类型： 0: 空白帧 3: 关键帧。对于 H.264 编码格式，SDK 把带有 sps 和 pps 信息的 I 帧归类为关键帧。 4: Delta 帧。对于 H.264 编码格式，SDK 把 P 帧和不带 sps 和 pps 信息的 I 帧都归类为 Delta 帧。 5: B 帧 6: 丢弃帧 7: 未知
rotation	已编码视频帧旋转信息： 0: 顺时针旋转 0 度。 90: 顺时针旋转 90 度。 180: 顺时针旋转 180 度。 270: 顺时针旋转 270 度。
track_id	视频帧的轨道 ID。
capture_time_ms	采集外部编码视频帧的 Unix 时间戳（毫秒）。
decode_time_ms	将外部编码视频帧进行解码的时间戳（毫秒）。
uid	用户 ID。
stream_type	视频帧的流类型： 0: 大流。分辨率和码率较高。 1: 小流。分辨率和码率较低。

ExternalVideoFrame

Python

@dataclass(kw_only=True)
class ExternalVideoFrame:
    type: int = 1
    format: int = 0
    buffer: bytearray = None
    stride: int = 0
    height: int = 0
    crop_left: int = 0
    crop_top: int = 0
    crop_right: int = 0
    crop_bottom: int = 0
    rotation: int = 0
    timestamp: int = 0
    egl_context: bytearray = None
    egl_type: int = 0
    texture_id: int = 0
    matrix: list = field(default_factory=list)
    metadata: str = ""
    alpha_buffer: bytearray = None

YUV 格式的视频数据。

参数	描述
type	视频数据类型： 1: 类型为原始数据。 2: 类型为原始数据。 3: 类型为 Texture。
format	像素格式： 0: 原始视频像素格式。 1: I420 格式。 4: RGBA 格式。 16: I422 格式。 17: ID3D11TEXTURE2D 格式。目前支持的类型有 DXGI_FORMAT_B8G8R8A8_UNORM、DXGI_FORMAT_B8G8R8A8_TYPELESS 和 DXGI_FORMAT_NV12。 注意：SDK 目前不支持 Alpha 通道。传入的 Alpha 值将被丢弃。
buffer	视频缓冲区。
stride	传入视频帧的行间距，单位为像素而不是字节。对于 Texture，该值指的是 Texture 的宽度。
height	传入视频帧的高度。
crop_left	原始数据相关字段。指定左边裁剪掉的像素数量。默认为 0。该参数仅适用于原始视频数据。
crop_top	原始数据相关字段。指定顶边裁剪掉的像素数量。默认为 0。该参数仅适用于原始视频数据。
crop_right	原始数据相关字段。指定右边裁剪掉的像素数量。默认为 0。该参数仅适用于原始视频数据。
crop_bottom	原始数据相关字段。指定底边裁剪掉的像素数量。默认为 0。该参数仅适用于原始视频数据。
rotation	原始数据相关字段。指定是否对传入的视频组做顺时针旋转操作，可选值为 0， 90， 180， 270。默认为 0。
timestamp	传入的视频帧的时间戳，以毫秒为单位。不正确的时间戳会导致丢帧或者音视频不同步。
egl_context	该参数仅适用于 Texture 格式的视频数据。 当使用 Khronos 定义的 OpenGL 接口 (javax.microedition.khronos.egl.*)时，需要将 eglContext 设置给这个字段。 当使用 Android 定义的 OpenGL 接口 (android.opengl.*)时，需要将 eglContext 设置给这个字段。
egl_type	该参数仅适用于 Texture 格式的视频数据。指该视频帧的 Texture ID。
texture_id	该参数仅适用于 Texture 格式的视频数据。为一个输入的 4x4 变换矩阵，典型值为一个单位矩阵。
matrix	该参数仅适用于 Texture 格式的视频数据。指 MetaData 的数据缓冲区，默认值为 None。
metadata	该参数仅适用于 Texture 格式的视频数据。指 MetaData 的大小，默认值为 0。
alpha_buffer	采用人像分割算法输出的 Alpha 通道数据。该数据跟视频帧的尺寸一致，每个像素点的取值范围为 [0,255]，其中 0 代表背景；255 代表前景（人像）。你可以通过设置该参数，实现将视频背景自渲染为各种效果，例如：透明、纯色、图片、视频等。

PcmAudioFrame

Python

@dataclass(kw_only=True)
class PcmAudioFrame:
    data: bytearray
    samples_per_channel: int
    bytes_per_sample: int
    number_of_channels: int
    sample_rate: int
    timestamp: int = 0

PCM 音频数据。

参数	描述
data	需要发送的 PCM 音频数据。
timestamp	音频数据采集时间戳（毫秒）。
samples_per_channel	对于每个声道，10 毫秒内采集的音频样本数。
bytes_per_sample	每个样本的字节数。
number_of_channels	每个样本的声道数。
sample_rate	采样率 (Hz)。最小值是 8000。

RTCConnConfig

Python

@dataclass(kw_only=True)
class RTCConnConfig:
    auto_subscribe_audio: int = 0
    auto_subscribe_video: int = 0
    enable_audio_recording_or_playout: int = 0
    max_send_bitrate: int = 0
    min_port: int = 0
    max_port: int = 0
    audio_subs_options: 'AudioSubscriptionOptions' = AudioSubscriptionOptions()
    client_role_type: ClientRoleType = ClientRoleType.CLIENT_ROLE_BROADCASTER
    channel_profile: ChannelProfileType = ChannelProfileType.CHANNEL_PROFILE_LIVE_BROADCASTING
    audio_recv_media_packet: int = 0
    audio_recv_encoded_frame: int = 0
    video_recv_media_packet: int = 0

RTC 连接配置。

参数	描述
auto_subscribe_audio	是否自动订阅所有音频轨道。 0: 不自动订阅所有音频轨道。 1: (默认) 自动订阅所有音频轨道。
auto_subscribe_video	是否自动订阅所有视频轨道。 0: 不自动订阅所有视频轨道。 1: (默认) 自动订阅所有视频轨道。
enable_audio_recording_or_playout	是否开启音频录制或播放。 0: 关闭音频录制或播放。 1: 开启音频录制或播放。
max_send_bitrate	最大发送码率。
min_port	最小端口。
max_port	最大端口。
audio_subs_options	音频订阅选项。详见 AudioSubscriptionOptions。
client_role_type	用户角色。详见 ClientRoleType。
channel_profile	频道场景。详见 ChannelProfileType。
audio_recv_media_packet	是否接收音频媒体包。 0: 不接收。 1: 接收。
video_recv_media_packet	是否接收视频媒体包。 0: 不接收。 1: 接收。

RTCConnInfo

Python

@dataclass(frozen=True, kw_only=True)
class RTCConnInfo():
    id: int
    channel_id: str
    state: int
    local_user_id: str

RTC 连接信息。

参数	描述
id	RTC 连接的 ID。
channel_id	RTC 频道 ID。 如果你没有调用 connect 方法，该参数返回 None。
state	连接状态： 1: 网络连接断开。 2: 建立网络连接中。 3: 网络已连接。 4: 重新建立网络连接中 。 5: 网络连接失败 。
local_user_id	本地用户 ID。

SenderOptions

Python

@dataclass(kw_only=True)
class SenderOptions:
    target_bitrate: int
    cc_mode: TCcMode = TCcMode.CC_ENABLED
    codec_type: VideoCodecType = VideoCodecType.VIDEO_CODEC_NONE

包含发送编码视频数据的视频源的本地视频轨道对象配置。

参数	描述
target_bitrate	当前编码器的目标编码码率 (Kbps)，该码率为 SDK 根据当前网络状况预估的一个值。
cc_mode	拥塞控制模式。详见 TCcMode。
codec_type	视频编码类型。详见 VideoCodecType。

VideoDimensions

Python

@dataclass(kw_only=True)
class VideoDimensions:
    width: int
    height: int

视频编码的分辨率。

参数	描述
width	视频帧宽度（像素）。
height	视频帧高度（像素）。

VideoEncoderConfiguration

Python

@dataclass(kw_only=True)
class VideoEncoderConfiguration:
    dimensions: VideoDimensions
    codec_type: VideoCodecType = VideoCodecType.VIDEO_CODEC_NONE
    frame_rate: int = 15
    bitrate: int = 0
    min_bitrate: int = 0
    orientation_mode: int = 0
    degradation_preference: int = 0
    mirror_mode: int = 0

视频编码属性。

参数	描述
codec_type	视频编码类型。详见 VideoCodecType。
dimensions	视频编码的分辨率 (px)。该参数用于衡量编码质量，以长 × 宽表示，默认值为 640 × 360。用户可以自行设置分辨率。详见 VideoDimensions。
frame_rate	视频编码的帧率(fps)，默认值为 15。
bitrate	视频编码码率，单位为 Kbps。 0 : (推荐) 标准码率模式。该模式下，视频的码率是基准码率的两倍。 -1 : 适配码率模式。该模式下，视频码率与基准码率一致。直播时如果选择该模式，视频帧率可能会低于设置的值。
min_bitrate	最低编码码率，单位为 Kbps。SDK 会根据网络状况自动调整视频编码码率。将参数设为高于默认值可强制视频编码器输出高质量图片，但在网络状况不佳情况下可能导致网络丢包并影响视频播放的流畅度造成卡顿。因此如非对画质有特殊需求，声网建议不要修改该参数的值。 注意: 该参数仅适用于直播场景。
orientation_mode	视频编码的方向模式： 0: （默认）该模式下 SDK 输出的视频方向与采集到的视频方向一致。接收端会根据收到的视频旋转信息对视频进行旋转。该模式适用于接收端可以调整视频方向的场景。如果采集的视频是横屏模式，则输出的视频也是横屏模式。如果采集的视频是竖屏模式，则输出的视频也是竖屏模式。 1: 该模式下 SDK 固定输出风景（横屏）模式的视频。如果采集到的视频是竖屏模式，则视频编码器会对其进行裁剪。该模式适用于接收端无法调整视频方向的场景，如直推 CDN。 2: 该模式下 SDK 固定输出人像（竖屏）模式的视频，如果采集到的视频是横屏模式，则视频编码器会对其进行裁剪。该模式适用于接收端无法调整视频方向的场景，如直推 CDN。
degradation_preference	带宽受限时，视频编码降级偏好： 0: （默认）带宽受限时，视频编码时优先降低视频帧率，维持视频质量不变。该降级偏好适用于画质优先的场景。 1: 带宽受限时，视频编码时优先降低视频质量，维持视频帧率不变。该降级偏好适用于流畅性优先且允许画质降低的场景。 2: 带宽受限时，视频编码时同时降低视频帧率和视频质量。2 的降幅比 0 和 1 降幅更低，适用于流畅性和画质均有限的场景。 3: 带宽受限时，视频编码时优先降低视频帧率。
mirror_mode	发送编码视频时是否开启镜像模式，只影响远端用户看到的视频画面。 0: （默认）由 SDK 决定镜像模式。 1: 启用镜像模式。 2: 关闭镜像模式。

VideoFrame

Python

@dataclass(kw_only=True)
class VideoFrame():
    type: int = 0
    width: int = 0
    height: int = 0
    y_stride: int = 0
    u_stride: int = 0
    v_stride: int = 0
    y_buffer: bytearray = None
    u_buffer: bytearray = None
    v_buffer: bytearray = None
    rotation: int = 0
    render_time_ms: int = 0
    avsync_type: int = 0

视频帧的属性设置。视频数据的格式为 YUV420。缓冲区给出的是指向指针的指针，该接口不能修改缓冲区的指针，只能修改缓冲区的内容。

参数	描述
type	视频数据类型： 1: 原始数据。 2: 原始数据。 3: Texture。
width	视频帧宽度（像素）。
height	视频帧高度（像素）。
y_stride	YUV 数据中的 Y 缓冲区的行跨度。
u_stride	YUV 数据中的 U 缓冲区的行跨度。
v_stride	YUV 数据中的 V 缓冲区的行跨度。
y_buffer	指向 YUV 数据中的 Y 缓冲区指针的指针。
u_buffer	指向 YUV 数据中的 U 缓冲区指针的指针。
v_buffer	指向 YUV 数据中的 V 缓冲区指针的指针。
rotation	在渲染视频前设置该帧的顺时针旋转角度，目前支持 0 度、90 度、180 度，和 270 度。
render_time_ms	外部音频帧的时间戳。该参数为必填。你可以使用该时间戳还原音频帧顺序；在有视频的场景中（包含使用外部视频源的场景），该参数可以帮助实现音视频同步。
avsync_type	预留参数。

VideoSubscriptionOptions

Python

@dataclass(kw_only=True)
class VideoSubscriptionOptions:
    type: VideoStreamType = VideoStreamType.VIDEO_STREAM_HIGH
    encodedFrameOnly: bool = False

视频订阅选项。

参数	描述
type	订阅的视频类型。详见 VideoStreamType。
encodedFrameOnly	是否仅订阅已编码的视频数据： 0: （默认）仅订阅已解码的视频数据。 1: 仅订阅已编码的视频数据。

Enum

AreaCode

服务器的访问区域。该功能为高级设置，适用于有访问安全限制的场景。区域码支持位操作。指定访问区域后，SDK 会连接指定区域内的声网服务器。

枚举值	描述
AREA_CODE_CN	0x00000001: 中国大陆。
AREA_CODE_NA	0x00000002: 北美区域。
AREA_CODE_EU	0x00000004: 欧洲区域。
AREA_CODE_AS	0x00000008: 除中国大陆以外的亚洲区域。
AREA_CODE_JP	0x00000010: 日本。
AREA_CODE_IN	0x00000020: 印度。
AREA_CODE_GLOB	0xFFFFFFFF: （默认）全球。

AudioCodecType

音频编码类型。

枚举值	描述
AUDIO_CODEC_OPUS	1: OPUS
AUDIO_CODEC_PCMA	3: PCMA
AUDIO_CODEC_PCMU	4: PCMU
AUDIO_CODEC_G722	5: G722
AUDIO_CODEC_AACLC	8: AAC LC
AUDIO_CODEC_HEAAC	9: HE AAC
AUDIO_CODEC_HEAAC2	11: HEAAC2

AudioProfileType

音频场景。

枚举值	描述
AUDIO_PROFILE_DEFAULT	0: 默认音频场景。 通信场景下：16 KHz 采样率，语音编码，单声道，编码码率最大值为 16 Kbps。 直播场景下：48 KHz 采样率，音乐编码，单声道，编码码率最大值为 64 Kbps。
AUDIO_PROFILE_SPEECH_STANDARD	1: 指定 32 KHz 采样率，语音编码，单声道，编码码率最大值为 18 Kbps。
AUDIO_PROFILE_MUSIC_STANDARD	2: 指定 48 KHz 采样率，音乐编码，单声道，编码码率最大值为 64 Kbps。
AUDIO_PROFILE_MUSIC_STANDARD_STEREO	3: 指定 48 KHz 采样率，音乐编码，双声道，编码码率最大值为 80 Kbps。
AUDIO_PROFILE_MUSIC_HIGH_QUALITY	4: 指定 48 KHz 采样率，音乐编码，单声道，编码码率最大值为 96 Kbps。
AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO	5: 指定 48 KHz 采样率，音乐编码，双声道，编码码率最大值为 128 Kbps。
AUDIO_PROFILE_IOT	6: 指定 16 kHz 采样率，语音编码，单声道，应用回声消除算法 AES。
AUDIO_PROFILE_NUM	7: 枚举值边界。

AudioScenarioType

音频编码属性。

枚举值	描述
AUDIO_SCENARIO_DEFAULT	0: （默认）自动场景，根据用户角色和音频路由自动匹配合适的音质。
AUDIO_SCENARIO_GAME_STREAMING	3: 高音质场景，适用于音乐为主的场景。
AUDIO_SCENARIO_CHATROOM	5: 聊天室场景，适用于用户需要频繁上下麦的场景。该场景下，观众会收到申请麦克风权限的弹窗提示。
AUDIO_SCENARIO_CHORUS	7: 合唱场景，适用于网络条件良好，要求极低延时的实时合唱场景。
AUDIO_SCENARIO_MEETING	8: 会议场景，适用于人声为主的多人会议。
AUDIO_SCENARIO_NUM	9: 枚举值边界。

ChannelProfileType

频道使用场景。

枚举值	描述
CHANNEL_PROFILE_COMMUNICATION	0: （默认）通信场景。当频道中只有两个用户时，建议使用该场景。
CHANNEL_PROFILE_LIVE_BROADCASTING	1: 直播场景。该场景有主播和观众两种用户角色。主播可以发布和接收音视频流，观众直接接收流。适用于语聊房、视频直播、互动大班课等应用场景。

ClientRoleType

用户角色。

枚举值	描述
CLIENT_ROLE_BROADCASTER	1: 主播。主播可以同时发送和接收媒体流。
CLIENT_ROLE_AUDIENCE	2: 观众。观众只能接收媒体流。

TCcMode

拥塞控制模式。

枚举值	描述
CC_ENABLED	0: 开启拥塞控制模式。
CC_DISABLED	1: 关闭拥塞控制模式。

VideoCodecType

视频编码类型。

枚举值	描述
VIDEO_CODEC_NONE	0: 无
VIDEO_CODEC_VP8	1: VP8
VIDEO_CODEC_H264	2: H.264
VIDEO_CODEC_H265	3: H.265
VIDEO_CODEC_GENERIC	6: Generic
VIDEO_CODEC_GENERIC_H264	7: Generic H264
VIDEO_CODEC_AV1	12: AV1
VIDEO_CODEC_VP9	13: VP9
VIDEO_CODEC_GENERIC_JPEG	20: JPEG

VideoStreamType

视频流类型。

枚举值	描述
VIDEO_STREAM_HIGH	0: （默认）大流。分辨率和码率较高。
VIDEO_STREAM_LOW	1: 小流。分辨率和码率较低。