本页提供 Agora Classroom SDK for Web/Electron 的 TypeScript API 参考。
AgoraEduSDK
是 Agora Classroom SDK 的基础接口类,包含供 App 调用的主要接口。
static config(params: ConfigParams):void
配置 SDK。
参数 | 描述 |
---|---|
params |
全局配置参数,详见 ConfigParams。 |
static launch(dom: Element, option: LaunchOption):Promise<void>
启动课堂。
参数
参数 | 描述 |
---|---|
dom |
详见 Document。 |
option |
课堂启动配置,详见 LaunchOption。 |
SDK 全局配置。用于 AgoraEduSDK.config 方法。
export type ConfigParams = {
appId: string;
region?: string;
};
属性 | 描述 |
---|---|
appId |
(必填)Agora App ID。 |
region |
(选填)区域。建议设置为靠近你的课件或录制文件对象存储服务所在的区域,因为跨区域传输较大的静态资源会造成比较大的延迟。举例来说,如果你的 S3 服务在北美,则建议将 region 也设为北美区域。所有灵动课堂客户端必须设置相同的区域,否则无法互通。支持以下区域:CN : (默认)中国大陆AP : 亚太地区EU : 欧洲NA : 北美 |
课堂启动配置。用于 AgoraEduSDK.launch 方法。
export type LaunchOption = {
userUuid: string;
userName: string;
roomUuid: string;
roleType: EduRoleTypeEnum;
roomType: EduRoomTypeEnum;
roomSubtype?: EduRoomSubtypeEnum;
roomServiceType?: EduRoomServiceTypeEnum;
roomName: string;
listener: ListenerCallback;
pretest: boolean;
rtmToken: string;
language: LanguageEnum;
startTime?: number;
duration: number;
courseWareList: CourseWareList;
personalCourseWareList?: CourseWareList;
recordUrl?: string;
extApps?: IAgoraExtApp[];
region?: AgoraRegion;
widgets?: {[key: string]: IAgoraWidget};
userFlexProperties?: {[key: string]: any};
mediaOptions?: MediaOptions;
latencyLevel?: 1 | 2;
platform?: Platform;
};
参数 | 描述 |
---|---|
rtmToken |
(必填)用于鉴权的 RTM Token。 |
userUuid |
(必填)用户 ID。这是用户的全局唯一标识,需要与你生成 RTM Token 时使用的 UID 一致。长度在 64 字节以内。以下为支持的字符集范围(共 89 个字符):
|
userName |
(必填)用户名,用于课堂内显示,长度在 64 字节以内。 |
roomUuid |
(必填)课堂 ID。这是课堂的全局唯一标识。长度在 64 字节以内。以下为支持的字符集范围(共 89 个字符):
|
roomName |
(必填)课堂名,用于课堂内显示,长度在 64 字节以内。 |
roleType |
(必填)用户在课堂中的角色,详见 EduRoleTypeEnum。 |
roomType |
(必填)课堂类型,详见 EduRoomTypeEnum。 |
roomSubtype |
(选填)课堂子类型,详见 EduRoomSubtypeEnum。默认值为 EduRoomSubtypeEnum.Standard 。 |
roomServiceType |
(选填)职业教育大班课使用的服务类型。详见 EduRoomServiceTypeEnum。 |
listener |
(必填)课堂启动状态:ready : 课堂准备完毕。destroyed : 课堂已销毁。 |
pretest |
(必填)是否开启课前设备检测:true : 开启课前设备检测。开启后,在加入课堂前会弹出设备检测页面,测试终端用户的摄像头、麦克风和扬声器是否能正常工作。false : 不开启课前设备检测。 |
language |
(必填)课堂界面的语言,详见 LanguageEnum。 |
startTime |
(选填)课堂开始时间(毫秒),以第一个进入课堂的用户传入的参数为准。 |
duration |
(必填)课堂持续时间(秒),以第一个进入课堂的用户传入的参数为准。最大值为 86,400 秒,建议根据课堂实际时长设置。 |
recordUrl |
(选填)待录制 URL 地址,开发者需传入自己部署的网页地址,用于页面录制,例如 https://cn.bing.com/recordUrl 。 |
courseWareList |
(选填)教育机构指派的课件配置,客户端无法编辑。详见 CourseWareList。配置后,SDK 会在启动课堂时将相应的课件从 Agora 云盘组件中下载至本地。 |
personalCourseWareList |
(选填)老师端自行上传的课件配置,详见 CourseWareList。配置后,SDK 会在启动课堂时将相应的课件从 Agora 云盘组件中下载至本地。 |
extApps |
(选填)注册扩展应用 ExtApp。ExtApp 是灵动课堂 UIKit 的补充插件。详见通过 ExtApp 自定义插件。 |
userFlexProperties |
(选填)由开发者自定义的用户属性。详见如何设置自定义用户属性? |
mediaOptions |
(选填)媒体流相关设置,包含媒体流加密、摄像头视频流编码参数配置和屏幕共享视频流编码参数配置,详见 MediaOptions 。 |
latencyLevel |
(选填)观众端延时级别:1 : 低延时。发流端与观众端的延时为 1500 ms - 2000 ms。2 :(默认)超低延时。发流端与观众端的延时为 400 ms - 800 ms。 |
platform |
(选填)适用平台,可设为 'PC' 和 'H5' 。 |
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 |
用于配置浏览器编码格式和频道场景:
mode : 频道场景,可以为如下:
|
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)。 |
export declare interface MediaEncryptionConfig {
mode: MediaEncryptionMode;
key: string;
}
媒体流加密配置,用于 MediaOptions。
参数 | 描述 |
---|---|
mode |
媒体流加密模式,详见 MediaEncryptionMode。同一教室内所有老师和学生必须使用相同的加密模式和密钥。 |
key |
加密密钥。 |
export enum ChannelProfile {
Communication = 0,
LiveBroadcasting = 1,
}
频道配置,用于 MediaOptions。
参数 | 描述 |
---|---|
Communication |
通信模式,一般用于一对多或一对一的小班课。 |
LiveBroadcasting |
直播模式,相较于通信模式,更低费用,同时延迟相较于通信模式较大。 |
export enum MediaEncryptionMode {
AES_128_XTS = 1,
AES_128_ECB = 2,
AES_256_XTS = 3,
AES_128_GCM = 5,
AES_256_GCM = 6,
}
媒体流加密模式,用于 MediaEncryptionConfig。
参数 | 描述 |
---|---|
AES_128_XTS |
128 位 AES 加密,XTS 模式。 |
AES_128_ECB |
128 位 AES 加密,ECB 模式。 |
AES_256_XTS |
256 位 AES 加密,XTS 模式。 |
AES_128_GCM |
128 位 AES 加密,GCM 模式。 |
AES_256_GCM |
256 位 AES 加密,GCM 模式。 |
课件预加载配置。用于 AgoraEduSDK.launch 方法。
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[];
CourseWareList
为 CourseWareItem
对象组成的数组。
courseWareList:
[
{
resourceName: "机械能",
resourceUuid: "c06fed32d06268431601b0e0a804e70a",
ext: "mp4",
url: "https://gymoo-project-cdn.oss-cn-shenzhen.aliyuncs.com/hld_education/upload/9f4d3c149e6b3acfef378aca012780b3.mp4",
size: 4560284
}
],
courseWareList:
[
{
resourceName: xxxxxxx,
resourceUuid: xxxxxxxxx,
ext: 'pptx',
url: 'https://xxxxxxxxxxxxxx',
size: 0,
updateTime: xxxxxxxx
taskUuid: 'xxxxxxxxx',
conversion: {
type: 'dynamic',
preview: true,
scale: 2,
outputFormat: 'png',
},
taskProgress: {
totalPageSize: 3,
convertedPageSize: 3,
convertedPercentage: 100,
convertedFileList: [
{
name: '1',
ppt: {
src: 'pptx://convertcdn.netless.link/dynamicConvert/3bxxxxxxx/1.slide',
width: 1280,
height: 720,
preview:'dddddddddddddddurl'
},
},
...
] as any,
currentStep: '',
},
},
],
CourseWareItem
包含以下参数:
参数 | 描述 |
---|---|
resourceName |
课件名称,用于显示,长度在 64 字节以内。 |
resourceUuid |
课件 uuid。这是资源的唯一标识符。长度在 64 字节以内。以下为支持的字符集范围(共 89 个字符):
|
ext |
课件后缀。 |
size |
课件大小,单位为字节。 |
updateTime |
课件最后被修改的时间。 |
taskUuid |
课件转换任务的 uuid。 |
conversion |
包含以下字段:
|
url |
文件访问地址。灵动课堂客户端会对后缀名为 "ppt" 、"pptx" 、"doc" 、"docx" 、"pdf" 的文件默认开启文件转换,以用于课堂内白板展示。如果后缀名非上述所列,必须设置 url 。 |
taskProgress |
文件转换任务进度对象 CloudDriveResourceConvertProgress ,包含以下字段:
|
export enum EduRoleTypeEnum {
audience = 0,
teacher = 1,
student = 2,
assistant = 3,
}
用户在课堂中的角色。在 LaunchOption 中设置。
参数 | 描述 |
---|---|
audience |
0 : 观众,用于页面录制。 |
teacher |
1 : 老师。 |
student |
2 : 学生。 |
assistant |
3 : 助教。 |
export enum EduRoomTypeEnum {
Room1v1Class = 0,
RoomBigClass = 2,
RoomSmallClass = 4,
}
课堂类型。在 LaunchOption 中设置。
参数 | 描述 |
---|---|
Room1v1Class |
0 : 1 对 1 互动教学。1 位老师对 1 名学生进行专属在线辅导教学。 |
RoomBigClass |
2 : 大班课。1 位老师进行在线教学,多名学生实时观看和收听:roomSubtype 为 EduRoomSubtypeEnum.Standard 时,RoomBigClass 代表互动直播大班课。老师和学生均使用声网 RTC 服务,课堂人数上限为 5000。roomSubtype 为 EduRoomSubtypeEnum.Vocational 时,RoomBigClass 代表职业教育大班课。除去声网 RTC 服务外,老师和学生还使用灵动课堂 CDN 推拉流功能,课堂人数无上限。 |
RoomSmallClass |
4 : 在线互动小班课。1 位老师进行在线教学,多名学生实时观看和收听。小班课中课堂人数上限为 200 |
export enum EduRoomSubtypeEnum {
Standard = 0,
Vocational = 1,
}
课堂子类型。在 LaunchOption 中设置。
参数 | 描述 |
---|---|
Standard |
0 : 标准的灵动课堂。 |
Vocational |
1 : 当 roomType 设为 EduRoomTypeEnum.RoomBigClass 时,再将 roomSubtype 设为 EduRoomSubtypeEnum.Vocational ,则为职业教育大班课。 |
export enum EduRoomServiceTypeEnum {
LivePremium = 0,
LiveStandard = 1,
CDN = 2,
Fusion = 3,
MixStreamCDN = 4,
HostingScene = 5,
}
职业教育大班课使用的服务类型。在 LaunchOption 中设置。
注意:EduRoomServiceTypeEnum
仅在 EduRoomTypeEnum
为 RoomBigClass(2)
且 EduRoomSubtypeEnum
为 Vocational(1)
的情况下有效。
参数 | 描述 |
---|---|
LivePremium |
课堂使用 RTC 服务。频道为直播模式,延时为超低延时,约 400 毫秒。与互动直播大班课逻辑一致。 |
LiveStandard |
课堂使用 RTC 服务。频道为直播模式,延时为低延时,约 1 秒。又称极速直播模式。 |
CDN |
课堂使用 CDN 推拉流服务。老师的音视频流推到 CDN 上,学生通过拉取 CDN 流实时观看老师的音视频。CDN 服务延时一般大于 4 秒。 |
Fusion |
课堂使用 RTC 和 CDN 推拉流服务。老师的音视频流既发送到 RTC 频道内,又推到 CDN 上。学生既可以通过拉取 CDN 流实时观看老师的音视频流,又可以通过上台与老师实时互动。CDN 服务的延时比 RTC 服务延时高。 |
MixStreamCDN |
课堂使用 CDN 推拉流服务。老师的音视频流和白板经由页面录制后实时推到 CDN 上,学生通过拉取 CDN 流实时观看老师的音视频和白板。CDN 服务延时一般大于 4 秒。 |
HostingScene |
老师的音视频流和白板的录像文件存放在 CDN 上。学生通过 CDN 地址观看教学。各端的课堂时间通过服务器时间对齐。 |
export type LanguageEnum = "en" | "zh";
界面语言。在 LaunchOption 中设置。
参数 | 描述 |
---|---|
"en" |
英文。 |
"zh" |
中文。 |