Classroom SDK TypeScript API

本页提供声网 Classroom SDK for Web/Electron 的 TypeScript API 参考。

AgoraEduSDK

AgoraEduSDK 是声网 Classroom SDK 的基础接口类，提供教育场景下灵动课堂的核心方法。

config

TypeScript

static config(params: ConfigParams):void

配置 Classroom SDK。

参数	描述
params	全局配置参数，详见 ConfigParams。

launch

TypeScript

static launch(dom: Element, option: LaunchOption):() => void

启动课堂。

参数

参数	描述
dom	详见 Document。
option	课堂启动配置，详见 LaunchOption。

返回值

返回一个函数，用于销毁场景回收资源。

类型定义

ConfigParams

TypeScript

export type ConfigParams = {
    appId: string;
    region?: string;
};

ListenerCallback

TypeScript

export type ListenerCallback = (evt: AgoraEduClassroomEvent, ...args: unknown[]) => void;

SDK 全局配置。用于 AgoraEduSDK.config 方法。

属性	描述
appId	（必填）声网 App ID。
region	（选填）区域。建议设置为靠近你的课件或录制文件对象存储服务所在的区域，因为跨区域传输较大的静态资源会造成比较大的延迟。举例来说，如果你的 S3 服务在北美，则建议将 region 也设为北美区域。所有灵动课堂客户端必须设置相同的区域，否则无法互通。支持以下区域： CN: （默认）中国大陆 AP: 亚太地区 EU: 欧洲 NA: 北美

LaunchOption

TypeScript

export type LaunchOption = {
    userUuid: string;
    userName: string;
    roomUuid: string;
    roleType: EduRoleTypeEnum;
    roomType: EduRoomTypeEnum;
    roomServiceType?: EduRoomServiceTypeEnum;
    roomName: string;
    listener: ListenerCallback;
    pretest: boolean;
    rtmToken: string;
    language: LanguageEnum;
    startTime?: number;
    duration: number;
    courseWareList: CourseWareList;
    recordUrl?: string;
    widgets?: {[key: string]: AgoraWidgetBase};
    userFlexProperties?: {[key: string]: any};
    mediaOptions?: MediaOptions;
    latencyLevel?: 1 | 2;
    platform?: Platform;
    uiMode?: FcrMultiThemeMode;
    virtualBackgroundImages?: string[];
    webrtcExtensionBaseUrl?: string;
    rtcCloudProxyType?: AgoraCloudProxyType;
    rtmCloudProxyEnabled? boolean;
};

课堂启动配置。用于 AgoraEduSDK.launch 方法。

参数	描述
rtmToken	（必填）用于鉴权的 RTM Token。详见使用 Token 鉴权。
userUuid	（必填）用户 ID。这是用户的全局唯一标识，需要与你生成 RTM Token 时使用的 UID 一致。长度在 64 字节以内。 以下为支持的字符集范围（共 89 个字符）: 26 个小写英文字母 a-Z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 !, #, $, %, &, (, ), +, -, :, ;, <, =, ., >, ?, @, [, ], ^, _, {, }, |, ~, ,
userName	（必填）用户名，用于课堂内显示，长度在 64 字节以内。 以下为支持的字符集范围（共 89 个字符）: 26 个小写英文字母 a-Z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 !, #, $, %, &, (, ), +, -, :, ;, <, =, ., >, ?, @, [, ], ^, _, {, }, |, ~, ,
roomUuid	（必填）课堂 ID。这是课堂的全局唯一标识。长度在 64 字节以内。 以下为支持的字符集范围（共 89 个字符）: 26 个小写英文字母 a-Z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 !, #, $, %, &, (, ), +, -, :, ;, <, =, ., >, ?, @, [, ], ^, _, {, }, |, ~, ,
roomName	（必填）课堂名，用于课堂内显示，长度在 64 字节以内。 以下为支持的字符集范围（共 89 个字符）: 26 个小写英文字母 a-Z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 !, #, $, %, &, (, ), +, -, :, ;, <, =, ., >, ?, @, [, ], ^, _, {, }, |, ~, ,
roleType	（必填）用户在课堂中的角色，详见 EduRoleTypeEnum。
roomType	（必填）课堂类型，详见 EduRoomTypeEnum。
roomServiceType	（选填）大班课使用的服务类型。详见 EduRoomServiceTypeEnum。
listener	（必填）教室事件回调，事件类型详见 AgoraEduClassroomEvent。
pretest	（必填）是否开启课前设备检测： true: 开启课前设备检测。开启后，在加入课堂前会弹出设备检测页面，测试终端用户的摄像头、麦克风和扬声器是否能正常工作。 false: 不开启课前设备检测。
language	（必填）课堂界面的语言，详见 LanguageEnum。
startTime	（选填）课堂开始时间（毫秒），以第一个进入课堂的用户传入的参数为准。
duration	（必填）课堂持续时间（秒），以第一个进入课堂的用户传入的参数为准。最大值为 86,400 秒，建议根据课堂实际时长设置。
recordUrl	（选填）待录制 URL 地址，开发者需传入自己部署的网页地址，用于页面录制，例如 https://cn.bing.com/recordUrl。
widgets	（选填）扩展插件集合，扩展教室能力，详见自定义插件。
courseWareList	（选填）教育机构指派的课件配置，客户端无法编辑。详见 CourseWareList。配置后，SDK 会在启动课堂时将相应的课件从声网云盘组件中下载至本地。
userFlexProperties	（选填）由开发者自定义的用户属性。详见如何设置自定义用户属性？。
mediaOptions	（选填）媒体流相关设置，包含媒体流加密、摄像头视频流编码参数配置和屏幕共享视频流编码参数配置，详见 MediaOptions。
latencyLevel	（选填）观众端延时级别： 1: 低延时。发流端与观众端的延时为 1500 ms - 2000 ms。 2:（默认）超低延时。发流端与观众端的延时为 400 ms - 800 ms。
platform	（选填）适用平台，可设为 PC 和 H5。
uiMode	（选填）课堂界面模式，详见 FcrMultiThemeMode。
virtualBackgroundImages	（选填）视频虚拟背景墙图片链接，资源所在域名应与你部署灵动课堂的域名相同。支持 PNG、JPG 格式图片。
webrtcExtensionBaseUrl	（选填）WebRTC 插件部署地址。默认为 https://solutions-apaas.agora.io/static。如果你需要在 Web 端使用虚拟背景、AI 降噪、美颜等高级功能，你需要将 WebRTC 插件和相应的资源文件部署到灵动课堂 SDK 所在域名下。具体使用步骤：当你运行 yarn ci:build 完成打包后，packages/agora-demo-app/build/extensions 目录下会生成对应文件。将 extensions 目录部署到灵动课堂 SDK 所在域名下。
rtcCloudProxyType	（选填）RTC 云代理模式。详见 AgoraCloudProxyType。
rtmCloudProxyEnabled	(选填) 开启 RTM 云代理。

MediaOptions

TypeScript

export type MediaOptions = {
    cameraEncoderConfiguration?: EduVideoEncoderConfiguration;
    screenShareEncoderConfiguration?: EduVideoEncoderConfiguration;
    encryptionConfig?: MediaEncryptionConfig;
    channelProfile?: ChannelProfile;
    web?: {
        codec: SDK_CODEC;
        mode: SDK_MODE;
    };
};

媒体流相关设置。

参数	描述
cameraEncoderConfiguration	摄像头采集视频流编码参数配置，详见 EduVideoEncoderConfiguration。
screenShareEncoderConfiguration	屏幕共享视频流编码参数配置，详见 EduVideoEncoderConfiguration。
encryptionConfig	媒体流加密配置，详见 MediaEncryptionConfig。
channelProfile	频道配置，详见 ChannelProfile。
web	用于配置浏览器编码格式和频道场景： codec: 浏览器编码格式，可以为如下： vp8: VP8 编码。 h264: H.264 编码。 mode: 频道场景，可以为如下： rtc: 通信模式，一般用于一对多或一对一的小班课。 live: 直播模式，相较于通信模式，更低费用，同时延迟相较于通信模式较大。

EduVideoEncoderConfiguration

TypeScript

export interface EduVideoEncoderConfiguration {
    width: number;
    height: number;
    frameRate: number;
    bitrate: number;
}

视频编码参数配置。

• 在小班课中，视频编码参数的默认值为 120p（160×120），200 Kbps，15 fps。
• 在一对一和大班课中，视频编码参数的默认值为 240p（320×240），65 Kbps，15 fps。

参数	描述
width	视频帧宽度(pixel)。
height	视频帧高度 (pixel)。
frameRate	视频帧率 (fps)。
bitrate	视频码率 (Kbps)。

MediaEncryptionConfig

TypeScript

export declare interface MediaEncryptionConfig {
    mode: MediaEncryptionMode;
    key: string;
}

媒体流加密配置，用于 MediaOptions。

参数	描述
mode	媒体流加密模式，详见 MediaEncryptionMode。同一教室内所有老师和学生必须使用相同的加密模式和密钥。
key	加密密钥。

CourseWareList

TypeScript

export type CloudDriveResourceConvertProgress = {
    totalPageSize: number;
    convertedPageSize: number;
    convertedPercentage: number;
    convertedFileList: {
        name: string;
        ppt: {
            width: number;
            height: number;
            preview?: string;
            src: string;
        };
    }[];
    currentStep: string;
};
export type CourseWareItem = {
    resourceName: string;
    resourceUuid: string;
    ext: string;
    url?: string;
    size: number;
    updateTime: number;
    taskUuid: string;
    conversion: {
        type: string;
        preview: boolean;
        scale: number;
        outputFormat: string;
    };
    taskProgress?: CloudDriveResourceConvertProgress;
};
export type CourseWareList = CourseWareItem[];

课件预加载配置。用于 AgoraEduSDK.launch 方法。

CourseWareList 为 CourseWareItem 对象组成的数组。

CourseWareItem 包含以下参数：

参数	描述
resourceName	课件名称，用于显示，长度在 64 字节以内。 以下为支持的字符集范围（共 89 个字符）: 26 个小写英文字母 a-Z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 !, #, $, %, &, (, ), +, -, :, ;, <, =, ., >, ?, @, [, ], ^, _, {, }, |, ~, ,
resourceUuid	课件 uuid。这是资源的唯一标识符。长度在 64 字节以内。 以下为支持的字符集范围（共 89 个字符）: 26 个小写英文字母 a-Z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 !, #, $, %, &, (, ), +, -, :, ;, <, =, ., >, ?, @, [, ], ^, _, {, }, |, ~, ,
ext	课件后缀。
size	课件大小，单位为字节。
updateTime	课件最后被修改的时间。
taskUuid	课件转换任务的 uuid。
conversion	包含以下字段： type: String 型，课件转换方式，可设为： static: 静态转换，是指将 PPT、PPTX、DOC、DOCX、PDF 格式的文件转换成 PNG、JPG/JPEG 或 WEBP 格式的静态图片。转换后的文件不保留源文件的动画效果。 dynamic: 动态转换，是指将用 Microsoft Office 编辑的 PPTX 格式的文件转换成 HTML 网页。转换后的文件会保留源文件里的动画效果。 preview: Boolean 型，是否需要显示左侧预览。 scale: Number 型，转换缩放比例，取值范围为 [0, 3]。 outputFormat: String 型，课件转换后图片资源的输出格式，可设为 png。
url	文件访问地址。灵动课堂客户端会对后缀名为 ppt、pptx、doc、docx、pdf 的文件默认开启文件转换，以用于课堂内白板展示。如果后缀名非上述所列，必须设置 url。
taskProgress	文件转换任务进度对象 CloudDriveResourceConvertProgress，包含以下字段： totalPageSize: 总页数。 convertedPageSize: 已转换的页数。 convertedPercentage: 转换进度（百分比）。 convertedFileList: 已转换的文档页列表，每页文档对应一条数据，每条数据包含以下字段： name: 文档页名称。 ppt: 文档页包含的一个幻灯片的具体信息，包含以下字段： width: 幻灯片页面宽度。 height: 幻灯片页面高度。 src: 完成转换的页面的 URL 下载地址。 preview: 缩略图 URL。 currentStep: 文档转换任务当前的步骤。可为 extracting（正在提取资源）、generatingPreview（正在生成预览图）、mediaTranscode（媒体文件转换）、packaging（打包中）。

ChannelProfile

频道配置，用于 MediaOptions。

参数	描述
Communication	0：通信模式，一般用于一对多或一对一的小班课。
LiveBroadcasting	1：直播模式，相较于通信模式，更低费用，同时延迟相较于通信模式较大。

MediaEncryptionMode

媒体流加密模式，用于 MediaEncryptionConfig。

参数	描述
AES_128_XTS	1：128 位 AES 加密，XTS 模式。
AES_128_ECB	2：128 位 AES 加密，ECB 模式。
AES_256_XTS	3：256 位 AES 加密，XTS 模式。
AES_128_GCM	5：128 位 AES 加密，GCM 模式。
AES_256_GCM	6：256 位 AES 加密，GCM 模式。

FcrMultiThemeMode

课堂界面显示模式。在 LaunchOption 中设置。

参数	描述
light	（默认）明亮模式。
dark	暗黑模式。

EduRoleTypeEnum

用户在课堂中的角色。在 LaunchOption 中设置。

参数	描述
audience	0: 观众，用于页面录制。
teacher	1: 老师。
student	2: 学生。
assistant	3: 助教。

EduRoomTypeEnum

课堂类型。在 LaunchOption 中设置。

参数	描述
Room1v1Class	0: 1 对 1 互动教学。1 位老师对 1 名学生进行专属在线辅导教学。
RoomBigClass	2: 大班课。1 位老师进行在线教学，多名学生实时观看和收听，课堂人数上限为 5000。
RoomSmallClass	4: 在线互动小班课。1 位老师进行在线教学，多名学生实时观看和收听。小班课中课堂人数上限为 200。

EduRoomServiceTypeEnum

大班课使用的服务类型。在 LaunchOption 中设置。

参数	描述
LivePremium	0：课堂使用 RTC 服务。频道为直播模式，延时为超低延时，约 400 毫秒。目前大班课仅支持此类型。

LanguageEnum

界面语言。在 LaunchOption 中设置。

参数	描述
en	英文。
zh	中文。

AgoraCloudProxyType

云代理类型。在 LaunchOption 中设置。

参数	描述
Automatic	0: 自动模式。该模式下，SDK 会首先尝试直接连接到 SD-RTN™。如果尝试失败，SDK 会自动退回到在 TLS 443 上发送媒体。如果你不确定最终用户的网络环境是否有防火墙，Automatic 模式为最佳实践。虽然在 TLS 443 上传输媒体可能不如 UDP 快速高效，但 TLS 443 上的连接可以通过大多数防火墙。
UDP	1: 使用 UDP 云代理。
TCP	2: 使用 TCP 云代理。

AgoraEduClassroomEvent

教室事件监听器。在 LaunchOption 中设置。

参数	描述
Ready	1: 进入教室成功。
Destroyed	2: 教室已销毁。事件参数：离开原因。 1: 正常退出房间 2: 被踢出房间
FailedToJoin	3: 进入教室失败。
KickOut	101: 被踢出房间。
TeacherTurnOnMyMic	102: 被开启音频发流权限。
TeacherTurnOffMyMic	103: 被关闭音频发流权限。
UserAcceptToStage	106: 登上讲台。
UserLeaveStage	107: 离开讲台。
RewardReceived	108: 收到奖励。事件参数：奖励用户列表。
TeacherTurnOnMyCam	109: 被开启视频发流权限。
TeacherTurnOffMyCam	110: 被关闭视频发流权限。
CurrentCamUnplugged	111: 当前摄像头设备拔出。
CurrentMicUnplugged	112: 当前麦克风设备拔出。
CurrentSpeakerUnplugged	113: 当前扬声器拔出。
CaptureScreenPermissionDenied	114: 无屏幕采集权限。
BatchRewardReceived	117: 收到批量奖励。事件参数：奖励用户列表。
InvitedToGroup	118: 收到邀请进入分组。事件参数：分组信息。
MoveToOtherGroup	119: 被移动到其他分组。事件参数： 从分组 ID 至分组 ID
JoinSubRoom	120: 加入分组。
LeaveSubRoom	121: 离开分组。
AcceptedToGroup	122: 用户接受加入分组。事件参数： 分组 ID 接受分组的用户
UserJoinGroup	123: 其他用户加入分组。事件参数： 分组 ID 加入的用户列表
UserLeaveGroup	124: 其他用户离开分组。事件参数： 分组 ID 离开的用户列表
RejectedToGroup	125: 用户拒绝加入分组。事件参数： 分组 ID 拒绝用户
RTCStateChanged	201: RTC 连接状态变更。事件参数：RTC 连接状态。 0: 未连接 1: 连接中 2: 已连接 3: 正在重连
ClassStateChanged	202: 教室状态变更。事件参数：房间状态。 0: 课堂未开始 1: 课堂已开始 2: 课堂拖堂 3: 课堂已结束