@seastart/srtc-web-sdk 0.5.2 → 0.5.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,16 @@
2
2
 
3
3
  本文档记录 web SDK 各版本的改动点。遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 风格。
4
4
 
5
+ ## v0.5.4 - 2026-06-03
6
+
7
+ - feat: 新增音视频处理器插件机制
8
+ - feat: 新增wasm降噪插件
9
+
10
+ ## v0.5.3 - 2026-05-08
11
+
12
+ - feat: add local composite recorder (47a20b0)
13
+ - chore: 共享屏幕默认配置优化 (f079eeb)
14
+
5
15
  ## v0.5.2 - 2026-05-08
6
16
 
7
17
  - fix: 恢复音频trackinfo编码参数 (0f694e5)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@seastart/srtc-web-sdk",
3
- "version": "0.5.2",
3
+ "version": "0.5.4",
4
4
  "description": "srtc sdk for web",
5
5
  "main": "srtc.js",
6
6
  "module": "srtc.mjs",
package/srtc.d.mts CHANGED
@@ -1087,6 +1087,15 @@ export declare class ChannelEventType extends CommonChannelEventType {
1087
1087
  */
1088
1088
  export declare class LocalAudioTrack extends BaseWebrtcTrack {
1089
1089
  constructor();
1090
+ /**
1091
+ * 挂载音频处理器(如 RNN 降噪、变声)。传入数组时按顺序串联。
1092
+ * 需先 startCapture 采集到轨道后调用。
1093
+ */
1094
+ setProcessor(processor: TrackProcessor | TrackProcessor[]): Promise<void>;
1095
+ /**
1096
+ * 卸载音频处理器,还原为原始采集轨道。
1097
+ */
1098
+ removeProcessor(): Promise<void>;
1090
1099
  /**
1091
1100
  * 获取音量
1092
1101
  */
@@ -1130,6 +1139,144 @@ export declare class LocalCameraTrack extends LocalVideoTrack {
1130
1139
  */
1131
1140
  switchFacingMode(): Promise<void>;
1132
1141
  }
1142
+ /**
1143
+ * 本地合成录制器。
1144
+ *
1145
+ * 只处理媒体合成与 MediaRecorder 生命周期,不关心会议分页、布局模式、用户名来源等业务语义。
1146
+ * 调用方需要把当前要录制的视频 track、音频 track 以及每个视频在画布上的位置传进来。
1147
+ */
1148
+ export declare class LocalCompositeRecorder {
1149
+ private canvas?;
1150
+ private canvasContext?;
1151
+ private canvasStream?;
1152
+ private recordStream?;
1153
+ private mediaRecorder?;
1154
+ private audioContext?;
1155
+ private audioDestination?;
1156
+ private audioSources;
1157
+ private audioInputTracks;
1158
+ private trackedTrackListeners;
1159
+ private videoElements;
1160
+ private chunks;
1161
+ private videoItems;
1162
+ private width;
1163
+ private height;
1164
+ private fps;
1165
+ private background;
1166
+ private labelBackground;
1167
+ private animationFrameId;
1168
+ private onDataAvailable?;
1169
+ /**
1170
+ * 获取当前录制状态。
1171
+ *
1172
+ * inactive 表示未开始或已结束;recording 表示正在写入文件;paused 表示暂停写入但仍保留同一次录制会话。
1173
+ */
1174
+ getState(): LocalCompositeRecorderState;
1175
+ /**
1176
+ * 开始本地合成录制。
1177
+ *
1178
+ * 会创建内部 canvas、AudioContext、MediaRecorder,并立即开始渲染和写入。
1179
+ * 如果当前不是 inactive 状态,本方法会直接返回,不会重复开启录制。
1180
+ */
1181
+ start(options: LocalCompositeRecorderStartOptions): Promise<void>;
1182
+ /**
1183
+ * 更新视频绘制列表。
1184
+ *
1185
+ * 用于会议翻页、布局变化、主讲人切换等场景。更新后下一帧会按新的 rect/track/label 绘制。
1186
+ */
1187
+ updateVideoItems(items: LocalCompositeRecorderVideoItem[]): void;
1188
+ /**
1189
+ * 更新参与混音的音频轨道。
1190
+ *
1191
+ * 适用于本地麦克风切换、远端混音流重订阅等场景。不会替换 MediaRecorder 持有的输出音频轨。
1192
+ */
1193
+ updateAudioTracks(tracks: LocalCompositeRecorderTrack[]): Promise<void>;
1194
+ /**
1195
+ * 暂停录制写入。
1196
+ *
1197
+ * 暂停期间不会向最终文件写入黑屏或静音片段;只有 recording 状态下调用才生效。
1198
+ */
1199
+ pause(): void;
1200
+ /**
1201
+ * 恢复录制写入。
1202
+ *
1203
+ * 恢复后继续写入同一个输出文件;只有 paused 状态下调用才生效。
1204
+ */
1205
+ resume(): void;
1206
+ /**
1207
+ * 停止录制并返回最终 Blob。
1208
+ *
1209
+ * 会释放录制器内部创建的 canvas stream、AudioContext 和隐藏 video;
1210
+ * 不会停止调用方传入的原始音视频 track。
1211
+ */
1212
+ stop(): Promise<Blob>;
1213
+ /**
1214
+ * 强制销毁录制器内部资源。
1215
+ *
1216
+ * 适用于页面卸载或调用方不再需要输出 Blob 的异常清理场景。
1217
+ */
1218
+ destroy(): void;
1219
+ /**
1220
+ * 初始化混音管线。
1221
+ *
1222
+ * 通过 MediaStreamAudioDestinationNode 生成一条稳定的输出音频轨,供 MediaRecorder 持有。
1223
+ */
1224
+ private initAudio;
1225
+ /**
1226
+ * 重新连接输入音频轨道。
1227
+ *
1228
+ * 只替换 Web Audio 的 source 节点,不替换 destination 输出轨,保证录制过程不中断。
1229
+ */
1230
+ private setAudioTracks;
1231
+ /**
1232
+ * 断开并清空所有输入音频 source。
1233
+ */
1234
+ private clearAudioSources;
1235
+ /**
1236
+ * 从原生 MediaStreamTrack 或 SDK Track 中取出当前实际媒体轨。
1237
+ */
1238
+ private resolveMediaStreamTrack;
1239
+ /**
1240
+ * 判断是否为可监听 MSTRACK_REPLACED 的 SDK Track。
1241
+ */
1242
+ private isTrackLike;
1243
+ /**
1244
+ * 同步 SDK Track 的替换监听。
1245
+ *
1246
+ * 调用方传 SDK Track 时,录制器会监听 MSTRACK_REPLACED,自动把隐藏 video 或混音 source 切到新轨。
1247
+ */
1248
+ private syncTrackedTrackListeners;
1249
+ /**
1250
+ * 解绑所有 SDK Track 替换监听。
1251
+ */
1252
+ private clearTrackedTrackListeners;
1253
+ /**
1254
+ * 同步视频解码元素。
1255
+ *
1256
+ * 每个视频 track 都需要一个隐藏 HTMLVideoElement 作为 canvas.drawImage 的帧来源。
1257
+ */
1258
+ private syncVideoElements;
1259
+ /**
1260
+ * 渲染循环。
1261
+ *
1262
+ * 每帧按最新 videoItems 重绘整张画布,canvas.captureStream 会把这些帧输出给 MediaRecorder。
1263
+ */
1264
+ private render;
1265
+ /**
1266
+ * 绘制单个视频槽位。
1267
+ *
1268
+ * contain 会完整显示视频,cover 会填满槽位并裁剪溢出区域。
1269
+ */
1270
+ private drawVideo;
1271
+ /**
1272
+ * 绘制视频标签。
1273
+ */
1274
+ private drawLabel;
1275
+ /**
1276
+ * 释放内部资源并重置状态。
1277
+ */
1278
+ private cleanup;
1279
+ }
1133
1280
  /**
1134
1281
  * 本地麦克风流轨道
1135
1282
  */
@@ -1185,6 +1332,15 @@ export declare class LocalScreenTrack extends LocalVideoTrack {
1185
1332
  */
1186
1333
  export declare class LocalVideoTrack extends BaseWebrtcTrack {
1187
1334
  constructor();
1335
+ /**
1336
+ * 挂载视频处理器(如美颜、虚化背景)。传入数组时按顺序串联。
1337
+ * 需先 startCapture 采集到轨道后调用。
1338
+ */
1339
+ setProcessor(processor: TrackProcessor | TrackProcessor[]): Promise<void>;
1340
+ /**
1341
+ * 卸载视频处理器,还原为原始采集轨道。
1342
+ */
1343
+ removeProcessor(): Promise<void>;
1188
1344
  setMediaStreamTrack(mediaStreamTrack?: MediaStreamTrack): void;
1189
1345
  /**
1190
1346
  * 获取联播轨道(小流)
@@ -1242,6 +1398,23 @@ export declare class LocalVideoTrack extends BaseWebrtcTrack {
1242
1398
  */
1243
1399
  isPopOut(container: HTMLElement): boolean;
1244
1400
  }
1401
+ /**
1402
+ * 处理器串联组合器:把多个 TrackProcessor 收敛成一个。
1403
+ * 第一性原理——每个处理器都是 track→track 的变换,可逐级串联:
1404
+ * 源 → P1 → P2 → ... → processedTrack。
1405
+ *
1406
+ * 音频链共享一个 AudioContext,避免每级单独创建上下文(浏览器对 AudioContext 数量有限制)。
1407
+ */
1408
+ export declare class ProcessorPipeline implements TrackProcessor {
1409
+ readonly name: string;
1410
+ processedTrack?: MediaStreamTrack;
1411
+ private processors;
1412
+ /** 仅当本组合器自建共享上下文时持有,destroy 时负责关闭 */
1413
+ private ownedAudioContext?;
1414
+ constructor(processors: TrackProcessor[]);
1415
+ init(options: ProcessorOptions): Promise<void>;
1416
+ destroy(): Promise<void>;
1417
+ }
1245
1418
  /**
1246
1419
  * 远端混音流
1247
1420
  */
@@ -1370,6 +1543,13 @@ export declare class SRTC extends BaseSRTC {
1370
1543
  * @returns
1371
1544
  */
1372
1545
  getEnvInfo(): EnvWebInfo;
1546
+ /**
1547
+ * 创建本地合成录制器。
1548
+ *
1549
+ * 该录制器只负责把调用方传入的视频轨道、音频轨道合成为本地文件;
1550
+ * 宫格分页、主讲人切换、共享屏幕优先级等业务视角需要由上层计算后通过 updateVideoItems 传入。
1551
+ */
1552
+ createLocalCompositeRecorder(): LocalCompositeRecorder;
1373
1553
  constructor(initParams: SdkInitParams);
1374
1554
  /**
1375
1555
  * 获取设备列表
@@ -2446,6 +2626,55 @@ export interface JoinOptions {
2446
2626
  */
2447
2627
  adaptiveStream?: boolean | AdaptiveStreamOptions;
2448
2628
  }
2629
+ /** 视频项在录制画布上的绘制区域,单位为 canvas 像素 */
2630
+ export interface LocalCompositeRecorderRect {
2631
+ /** 距离画布左侧的坐标 */
2632
+ x: number;
2633
+ /** 距离画布顶部的坐标 */
2634
+ y: number;
2635
+ /** 绘制区域宽度 */
2636
+ width: number;
2637
+ /** 绘制区域高度 */
2638
+ height: number;
2639
+ }
2640
+ /** 本地合成录制启动参数 */
2641
+ export interface LocalCompositeRecorderStartOptions {
2642
+ /** 初始视频绘制列表;后续可通过 updateVideoItems 跟随业务视角更新 */
2643
+ videoItems: LocalCompositeRecorderVideoItem[];
2644
+ /** 需要混入录制文件的音频轨道;支持原生 MediaStreamTrack 或 SDK 音视频 Track */
2645
+ audioTracks?: LocalCompositeRecorderTrack[];
2646
+ /** 输出视频宽度,单位为像素;默认 1280 */
2647
+ width?: number;
2648
+ /** 输出视频高度,单位为像素;默认 720 */
2649
+ height?: number;
2650
+ /** canvas.captureStream 的帧率;默认 15 */
2651
+ fps?: number;
2652
+ /** MediaRecorder mimeType,未传或不支持时自动选择浏览器支持的 webm 格式 */
2653
+ mimeType?: string;
2654
+ /** MediaRecorder.start(timeslice) 的分片间隔,单位毫秒;不传则浏览器在 stop 时一次性返回 */
2655
+ timeslice?: number;
2656
+ /** 录制画布整体背景色;默认 #101216 */
2657
+ background?: string;
2658
+ /** 标签背景色;默认 rgba(0, 0, 0, 0.58) */
2659
+ labelBackground?: string;
2660
+ /** 每次 MediaRecorder 输出有效分片时触发,可用于边录边上传或保存分片 */
2661
+ onDataAvailable?: (blob: Blob) => void;
2662
+ }
2663
+ /** 单个视频轨道在本地合成录制中的绘制配置 */
2664
+ export interface LocalCompositeRecorderVideoItem {
2665
+ /** 调用方维护的稳定唯一标识;同一个 id 的 track 变更时会复用槽位并替换解码源 */
2666
+ id: string;
2667
+ /** 要绘制的视频轨道;支持原生 MediaStreamTrack 或 SDK 音视频 Track */
2668
+ track?: LocalCompositeRecorderTrack | null;
2669
+ /** 该视频在录制画布上的绘制区域 */
2670
+ rect: LocalCompositeRecorderRect;
2671
+ /** 绘制在视频左下角的标签文本,例如用户名;不传则不绘制标签 */
2672
+ label?: string;
2673
+ /** 视频填充方式:contain 保留完整画面,cover 填满区域并裁剪溢出部分;默认 contain */
2674
+ fit?: "contain" | "cover";
2675
+ /** 单个视频槽位背景色;默认 #1a1c22 */
2676
+ background?: string;
2677
+ }
2449
2678
  /**
2450
2679
  * 麦克风采集配置
2451
2680
  */
@@ -2594,6 +2823,21 @@ export interface PopOutOptions {
2594
2823
  /** 是否隐藏原始播放视图,默认true */
2595
2824
  hideOriginView?: boolean;
2596
2825
  }
2826
+ /**
2827
+ * 处理器初始化参数
2828
+ */
2829
+ export interface ProcessorOptions {
2830
+ /** 源 MediaStreamTrack(采集得到的原始轨道) */
2831
+ track: MediaStreamTrack;
2832
+ /** 轨道类型 audio / video */
2833
+ kind: TrackKind;
2834
+ /**
2835
+ * 可选共享 AudioContext。
2836
+ * 串联多个音频处理器时由 ProcessorPipeline 传入同一个上下文,
2837
+ * 减少多级 destination→source 往返及重复创建 AudioContext 的开销。
2838
+ */
2839
+ audioContext?: AudioContext;
2840
+ }
2597
2841
  /**
2598
2842
  * 属性更改项
2599
2843
  */
@@ -2830,6 +3074,20 @@ export interface TrackMetric {
2830
3074
  /** 其他由 track.getInfo() 展开的字段 */
2831
3075
  [key: string]: any;
2832
3076
  }
3077
+ /**
3078
+ * 轨道处理器接口。
3079
+ * 插件作者实现此接口即可接入 SDK:输入一条轨道,产出一条处理后的轨道。
3080
+ */
3081
+ export interface TrackProcessor {
3082
+ /** 处理器名称,用于日志与串联展示 */
3083
+ readonly name: string;
3084
+ /** 处理后的输出轨道;init 成功后必须可用 */
3085
+ readonly processedTrack?: MediaStreamTrack;
3086
+ /** 初始化:建立内部处理管线,并产出 processedTrack */
3087
+ init(options: ProcessorOptions): Promise<void>;
3088
+ /** 释放资源:断开音频节点、关闭自建的 AudioContext 等 */
3089
+ destroy(): Promise<void>;
3090
+ }
2833
3091
  /**
2834
3092
  * 程博流媒体服务连接信息
2835
3093
  */
@@ -3009,6 +3267,10 @@ export type ImEvent = {
3009
3267
  readonly data: ImEventDataMap[K];
3010
3268
  };
3011
3269
  }[keyof ImEventDataMap];
3270
+ /** 本地合成录制器状态 */
3271
+ export type LocalCompositeRecorderState = "inactive" | "recording" | "paused";
3272
+ /** 本地合成录制器可接受的输入轨道 */
3273
+ export type LocalCompositeRecorderTrack = MediaStreamTrack | LocalVideoTrack | RemoteVideoTrack | LocalAudioTrack | RemoteAudioTrack;
3012
3274
  /**
3013
3275
  * 重试执行器函数:直接调用开始执行,.cancel()取消重试,函数失败会返回maxretry或canceled
3014
3276
  */
package/srtc.d.ts CHANGED
@@ -1087,6 +1087,15 @@ export declare class ChannelEventType extends CommonChannelEventType {
1087
1087
  */
1088
1088
  export declare class LocalAudioTrack extends BaseWebrtcTrack {
1089
1089
  constructor();
1090
+ /**
1091
+ * 挂载音频处理器(如 RNN 降噪、变声)。传入数组时按顺序串联。
1092
+ * 需先 startCapture 采集到轨道后调用。
1093
+ */
1094
+ setProcessor(processor: TrackProcessor | TrackProcessor[]): Promise<void>;
1095
+ /**
1096
+ * 卸载音频处理器,还原为原始采集轨道。
1097
+ */
1098
+ removeProcessor(): Promise<void>;
1090
1099
  /**
1091
1100
  * 获取音量
1092
1101
  */
@@ -1130,6 +1139,144 @@ export declare class LocalCameraTrack extends LocalVideoTrack {
1130
1139
  */
1131
1140
  switchFacingMode(): Promise<void>;
1132
1141
  }
1142
+ /**
1143
+ * 本地合成录制器。
1144
+ *
1145
+ * 只处理媒体合成与 MediaRecorder 生命周期,不关心会议分页、布局模式、用户名来源等业务语义。
1146
+ * 调用方需要把当前要录制的视频 track、音频 track 以及每个视频在画布上的位置传进来。
1147
+ */
1148
+ export declare class LocalCompositeRecorder {
1149
+ private canvas?;
1150
+ private canvasContext?;
1151
+ private canvasStream?;
1152
+ private recordStream?;
1153
+ private mediaRecorder?;
1154
+ private audioContext?;
1155
+ private audioDestination?;
1156
+ private audioSources;
1157
+ private audioInputTracks;
1158
+ private trackedTrackListeners;
1159
+ private videoElements;
1160
+ private chunks;
1161
+ private videoItems;
1162
+ private width;
1163
+ private height;
1164
+ private fps;
1165
+ private background;
1166
+ private labelBackground;
1167
+ private animationFrameId;
1168
+ private onDataAvailable?;
1169
+ /**
1170
+ * 获取当前录制状态。
1171
+ *
1172
+ * inactive 表示未开始或已结束;recording 表示正在写入文件;paused 表示暂停写入但仍保留同一次录制会话。
1173
+ */
1174
+ getState(): LocalCompositeRecorderState;
1175
+ /**
1176
+ * 开始本地合成录制。
1177
+ *
1178
+ * 会创建内部 canvas、AudioContext、MediaRecorder,并立即开始渲染和写入。
1179
+ * 如果当前不是 inactive 状态,本方法会直接返回,不会重复开启录制。
1180
+ */
1181
+ start(options: LocalCompositeRecorderStartOptions): Promise<void>;
1182
+ /**
1183
+ * 更新视频绘制列表。
1184
+ *
1185
+ * 用于会议翻页、布局变化、主讲人切换等场景。更新后下一帧会按新的 rect/track/label 绘制。
1186
+ */
1187
+ updateVideoItems(items: LocalCompositeRecorderVideoItem[]): void;
1188
+ /**
1189
+ * 更新参与混音的音频轨道。
1190
+ *
1191
+ * 适用于本地麦克风切换、远端混音流重订阅等场景。不会替换 MediaRecorder 持有的输出音频轨。
1192
+ */
1193
+ updateAudioTracks(tracks: LocalCompositeRecorderTrack[]): Promise<void>;
1194
+ /**
1195
+ * 暂停录制写入。
1196
+ *
1197
+ * 暂停期间不会向最终文件写入黑屏或静音片段;只有 recording 状态下调用才生效。
1198
+ */
1199
+ pause(): void;
1200
+ /**
1201
+ * 恢复录制写入。
1202
+ *
1203
+ * 恢复后继续写入同一个输出文件;只有 paused 状态下调用才生效。
1204
+ */
1205
+ resume(): void;
1206
+ /**
1207
+ * 停止录制并返回最终 Blob。
1208
+ *
1209
+ * 会释放录制器内部创建的 canvas stream、AudioContext 和隐藏 video;
1210
+ * 不会停止调用方传入的原始音视频 track。
1211
+ */
1212
+ stop(): Promise<Blob>;
1213
+ /**
1214
+ * 强制销毁录制器内部资源。
1215
+ *
1216
+ * 适用于页面卸载或调用方不再需要输出 Blob 的异常清理场景。
1217
+ */
1218
+ destroy(): void;
1219
+ /**
1220
+ * 初始化混音管线。
1221
+ *
1222
+ * 通过 MediaStreamAudioDestinationNode 生成一条稳定的输出音频轨,供 MediaRecorder 持有。
1223
+ */
1224
+ private initAudio;
1225
+ /**
1226
+ * 重新连接输入音频轨道。
1227
+ *
1228
+ * 只替换 Web Audio 的 source 节点,不替换 destination 输出轨,保证录制过程不中断。
1229
+ */
1230
+ private setAudioTracks;
1231
+ /**
1232
+ * 断开并清空所有输入音频 source。
1233
+ */
1234
+ private clearAudioSources;
1235
+ /**
1236
+ * 从原生 MediaStreamTrack 或 SDK Track 中取出当前实际媒体轨。
1237
+ */
1238
+ private resolveMediaStreamTrack;
1239
+ /**
1240
+ * 判断是否为可监听 MSTRACK_REPLACED 的 SDK Track。
1241
+ */
1242
+ private isTrackLike;
1243
+ /**
1244
+ * 同步 SDK Track 的替换监听。
1245
+ *
1246
+ * 调用方传 SDK Track 时,录制器会监听 MSTRACK_REPLACED,自动把隐藏 video 或混音 source 切到新轨。
1247
+ */
1248
+ private syncTrackedTrackListeners;
1249
+ /**
1250
+ * 解绑所有 SDK Track 替换监听。
1251
+ */
1252
+ private clearTrackedTrackListeners;
1253
+ /**
1254
+ * 同步视频解码元素。
1255
+ *
1256
+ * 每个视频 track 都需要一个隐藏 HTMLVideoElement 作为 canvas.drawImage 的帧来源。
1257
+ */
1258
+ private syncVideoElements;
1259
+ /**
1260
+ * 渲染循环。
1261
+ *
1262
+ * 每帧按最新 videoItems 重绘整张画布,canvas.captureStream 会把这些帧输出给 MediaRecorder。
1263
+ */
1264
+ private render;
1265
+ /**
1266
+ * 绘制单个视频槽位。
1267
+ *
1268
+ * contain 会完整显示视频,cover 会填满槽位并裁剪溢出区域。
1269
+ */
1270
+ private drawVideo;
1271
+ /**
1272
+ * 绘制视频标签。
1273
+ */
1274
+ private drawLabel;
1275
+ /**
1276
+ * 释放内部资源并重置状态。
1277
+ */
1278
+ private cleanup;
1279
+ }
1133
1280
  /**
1134
1281
  * 本地麦克风流轨道
1135
1282
  */
@@ -1185,6 +1332,15 @@ export declare class LocalScreenTrack extends LocalVideoTrack {
1185
1332
  */
1186
1333
  export declare class LocalVideoTrack extends BaseWebrtcTrack {
1187
1334
  constructor();
1335
+ /**
1336
+ * 挂载视频处理器(如美颜、虚化背景)。传入数组时按顺序串联。
1337
+ * 需先 startCapture 采集到轨道后调用。
1338
+ */
1339
+ setProcessor(processor: TrackProcessor | TrackProcessor[]): Promise<void>;
1340
+ /**
1341
+ * 卸载视频处理器,还原为原始采集轨道。
1342
+ */
1343
+ removeProcessor(): Promise<void>;
1188
1344
  setMediaStreamTrack(mediaStreamTrack?: MediaStreamTrack): void;
1189
1345
  /**
1190
1346
  * 获取联播轨道(小流)
@@ -1242,6 +1398,23 @@ export declare class LocalVideoTrack extends BaseWebrtcTrack {
1242
1398
  */
1243
1399
  isPopOut(container: HTMLElement): boolean;
1244
1400
  }
1401
+ /**
1402
+ * 处理器串联组合器:把多个 TrackProcessor 收敛成一个。
1403
+ * 第一性原理——每个处理器都是 track→track 的变换,可逐级串联:
1404
+ * 源 → P1 → P2 → ... → processedTrack。
1405
+ *
1406
+ * 音频链共享一个 AudioContext,避免每级单独创建上下文(浏览器对 AudioContext 数量有限制)。
1407
+ */
1408
+ export declare class ProcessorPipeline implements TrackProcessor {
1409
+ readonly name: string;
1410
+ processedTrack?: MediaStreamTrack;
1411
+ private processors;
1412
+ /** 仅当本组合器自建共享上下文时持有,destroy 时负责关闭 */
1413
+ private ownedAudioContext?;
1414
+ constructor(processors: TrackProcessor[]);
1415
+ init(options: ProcessorOptions): Promise<void>;
1416
+ destroy(): Promise<void>;
1417
+ }
1245
1418
  /**
1246
1419
  * 远端混音流
1247
1420
  */
@@ -1370,6 +1543,13 @@ export declare class SRTC extends BaseSRTC {
1370
1543
  * @returns
1371
1544
  */
1372
1545
  getEnvInfo(): EnvWebInfo;
1546
+ /**
1547
+ * 创建本地合成录制器。
1548
+ *
1549
+ * 该录制器只负责把调用方传入的视频轨道、音频轨道合成为本地文件;
1550
+ * 宫格分页、主讲人切换、共享屏幕优先级等业务视角需要由上层计算后通过 updateVideoItems 传入。
1551
+ */
1552
+ createLocalCompositeRecorder(): LocalCompositeRecorder;
1373
1553
  constructor(initParams: SdkInitParams);
1374
1554
  /**
1375
1555
  * 获取设备列表
@@ -2446,6 +2626,55 @@ export interface JoinOptions {
2446
2626
  */
2447
2627
  adaptiveStream?: boolean | AdaptiveStreamOptions;
2448
2628
  }
2629
+ /** 视频项在录制画布上的绘制区域,单位为 canvas 像素 */
2630
+ export interface LocalCompositeRecorderRect {
2631
+ /** 距离画布左侧的坐标 */
2632
+ x: number;
2633
+ /** 距离画布顶部的坐标 */
2634
+ y: number;
2635
+ /** 绘制区域宽度 */
2636
+ width: number;
2637
+ /** 绘制区域高度 */
2638
+ height: number;
2639
+ }
2640
+ /** 本地合成录制启动参数 */
2641
+ export interface LocalCompositeRecorderStartOptions {
2642
+ /** 初始视频绘制列表;后续可通过 updateVideoItems 跟随业务视角更新 */
2643
+ videoItems: LocalCompositeRecorderVideoItem[];
2644
+ /** 需要混入录制文件的音频轨道;支持原生 MediaStreamTrack 或 SDK 音视频 Track */
2645
+ audioTracks?: LocalCompositeRecorderTrack[];
2646
+ /** 输出视频宽度,单位为像素;默认 1280 */
2647
+ width?: number;
2648
+ /** 输出视频高度,单位为像素;默认 720 */
2649
+ height?: number;
2650
+ /** canvas.captureStream 的帧率;默认 15 */
2651
+ fps?: number;
2652
+ /** MediaRecorder mimeType,未传或不支持时自动选择浏览器支持的 webm 格式 */
2653
+ mimeType?: string;
2654
+ /** MediaRecorder.start(timeslice) 的分片间隔,单位毫秒;不传则浏览器在 stop 时一次性返回 */
2655
+ timeslice?: number;
2656
+ /** 录制画布整体背景色;默认 #101216 */
2657
+ background?: string;
2658
+ /** 标签背景色;默认 rgba(0, 0, 0, 0.58) */
2659
+ labelBackground?: string;
2660
+ /** 每次 MediaRecorder 输出有效分片时触发,可用于边录边上传或保存分片 */
2661
+ onDataAvailable?: (blob: Blob) => void;
2662
+ }
2663
+ /** 单个视频轨道在本地合成录制中的绘制配置 */
2664
+ export interface LocalCompositeRecorderVideoItem {
2665
+ /** 调用方维护的稳定唯一标识;同一个 id 的 track 变更时会复用槽位并替换解码源 */
2666
+ id: string;
2667
+ /** 要绘制的视频轨道;支持原生 MediaStreamTrack 或 SDK 音视频 Track */
2668
+ track?: LocalCompositeRecorderTrack | null;
2669
+ /** 该视频在录制画布上的绘制区域 */
2670
+ rect: LocalCompositeRecorderRect;
2671
+ /** 绘制在视频左下角的标签文本,例如用户名;不传则不绘制标签 */
2672
+ label?: string;
2673
+ /** 视频填充方式:contain 保留完整画面,cover 填满区域并裁剪溢出部分;默认 contain */
2674
+ fit?: "contain" | "cover";
2675
+ /** 单个视频槽位背景色;默认 #1a1c22 */
2676
+ background?: string;
2677
+ }
2449
2678
  /**
2450
2679
  * 麦克风采集配置
2451
2680
  */
@@ -2594,6 +2823,21 @@ export interface PopOutOptions {
2594
2823
  /** 是否隐藏原始播放视图,默认true */
2595
2824
  hideOriginView?: boolean;
2596
2825
  }
2826
+ /**
2827
+ * 处理器初始化参数
2828
+ */
2829
+ export interface ProcessorOptions {
2830
+ /** 源 MediaStreamTrack(采集得到的原始轨道) */
2831
+ track: MediaStreamTrack;
2832
+ /** 轨道类型 audio / video */
2833
+ kind: TrackKind;
2834
+ /**
2835
+ * 可选共享 AudioContext。
2836
+ * 串联多个音频处理器时由 ProcessorPipeline 传入同一个上下文,
2837
+ * 减少多级 destination→source 往返及重复创建 AudioContext 的开销。
2838
+ */
2839
+ audioContext?: AudioContext;
2840
+ }
2597
2841
  /**
2598
2842
  * 属性更改项
2599
2843
  */
@@ -2830,6 +3074,20 @@ export interface TrackMetric {
2830
3074
  /** 其他由 track.getInfo() 展开的字段 */
2831
3075
  [key: string]: any;
2832
3076
  }
3077
+ /**
3078
+ * 轨道处理器接口。
3079
+ * 插件作者实现此接口即可接入 SDK:输入一条轨道,产出一条处理后的轨道。
3080
+ */
3081
+ export interface TrackProcessor {
3082
+ /** 处理器名称,用于日志与串联展示 */
3083
+ readonly name: string;
3084
+ /** 处理后的输出轨道;init 成功后必须可用 */
3085
+ readonly processedTrack?: MediaStreamTrack;
3086
+ /** 初始化:建立内部处理管线,并产出 processedTrack */
3087
+ init(options: ProcessorOptions): Promise<void>;
3088
+ /** 释放资源:断开音频节点、关闭自建的 AudioContext 等 */
3089
+ destroy(): Promise<void>;
3090
+ }
2833
3091
  /**
2834
3092
  * 程博流媒体服务连接信息
2835
3093
  */
@@ -3009,6 +3267,10 @@ export type ImEvent = {
3009
3267
  readonly data: ImEventDataMap[K];
3010
3268
  };
3011
3269
  }[keyof ImEventDataMap];
3270
+ /** 本地合成录制器状态 */
3271
+ export type LocalCompositeRecorderState = "inactive" | "recording" | "paused";
3272
+ /** 本地合成录制器可接受的输入轨道 */
3273
+ export type LocalCompositeRecorderTrack = MediaStreamTrack | LocalVideoTrack | RemoteVideoTrack | LocalAudioTrack | RemoteAudioTrack;
3012
3274
  /**
3013
3275
  * 重试执行器函数:直接调用开始执行,.cancel()取消重试,函数失败会返回maxretry或canceled
3014
3276
  */