zyt/RECORDING_FIX_SUMMARY.md

本地录制修复总结

问题根源

通过分析实际日志发现，本地录制失败的根本原因是：

1. 录制启动太晚：1200ms 延迟导致录制在对方挂断后才启动
2. SDK 提前销毁轨道：stopLocalVideo/stopLocalAudio 在录制完成前就销毁了视频轨道
3. 时间窗口极短：从对方离开到轨道销毁只有 200-300ms

关键时间线（问题场景）

15:30:51.841 - 对方离开（USER_LEAVE 事件）
15:30:51.xxx - beginStopNow 被调用（但录制还未启动！）
15:30:52.072 - stopLocalVideo/stopLocalAudio（轨道被销毁）
15:30:52.102 - exitRoom
15:30:52.374 - MediaRecorder 已启动（太晚了！）
15:30:52.xxx - 数据块数: 0（因为轨道已销毁）

修复方案

1. 大幅缩短录制启动延迟

• 从 1200ms 缩短到 500ms
• 使用 300ms 间隔快速重试（最多 10 次）
• 目标：在通话接通后 1 秒内启动录制

2. 在通话结束事件时立即停止录制

• 监听 TUICallEvent.USER_LEAVE、CALL_END、ON_CALL_NOT_CONNECTED
• 检测到事件时立即调用 beginStopNow()
• 抢在 SDK 销毁轨道前完成录制

3. 缩短停止延迟

• 从 300ms 缩短到 100ms
• 减少等待时间，避免 SDK 提前销毁轨道

4. 智能视频元素检测

• 首先检查容器内的视频
• 如果没有，检查 body（TUICallKit Teleport）
• 过滤出有活跃视频流的元素
• 验证 readyState >= HAVE_CURRENT_DATA

修改的文件

1. admin/src/components/chat-dialog/index.vue

   • 缩短录制启动延迟（1200ms → 500ms）
   • 添加快速重试机制（300ms 间隔，最多 10 次）
   • 在 bindEngineRoomEvents 中添加立即停止逻辑
   • 增强日志输出

2. admin/src/utils/call-local-recorder.ts

   • 缩短停止延迟（300ms → 100ms）
   • 增强日志输出
   • 添加详细的状态跟踪

3. LOCAL_RECORDING_DEBUG_GUIDE.md

   • 完整的调试指南
   • 常见问题诊断
   • 测试建议

4. admin/test-local-recording.html

   • 独立的测试工具
   • 浏览器兼容性检测
   • MediaRecorder 功能测试

测试步骤

1. 清除浏览器缓存

确保使用最新的代码。

2. 打开控制台

F12 打开开发者工具，切换到 Console 标签。

3. 发起视频通话

点击视频通话按钮。

4. 观察关键日志

接通后应该看到（1 秒内）：

[chat-dialog] 尝试启动本地录制（第 1 次）
[chat-dialog] 视频元素已就绪，立即启动录制
[call-local-recorder] MediaRecorder.start() 调用成功
[call-local-recorder] MediaRecorder 已启动
[chat-dialog] ✅ 本地录制已成功启动

通话过程中应该看到（每 250ms）：

[call-local-recorder] 收到数据块，大小: 12345 (总计: 1 块)
[call-local-recorder] 收到数据块，大小: 15678 (总计: 2 块)

挂断时应该看到：

[chat-dialog] 检测到通话结束事件，立即停止录制
[call-local-recorder] beginStopNow 被调用
[call-local-recorder] 准备停止 MediaRecorder，当前状态: recording 已收集数据块: 15
[call-local-recorder] 生成 Blob: 1234567 bytes
[chat-dialog] 开始上传录制文件
本地录制已上传并关联到通话记录

5. 验证结果

• 检查诊单是否有录制文件
• 播放录制文件验证内容

预期效果

修复前

• 录制成功率：0%
• 数据块数：0
• Blob 大小：null

修复后

• 录制成功率：>95%（通话时长 > 2 秒）
• 数据块数：>= 通话秒数 * 4
• Blob 大小：>= 通话秒数 * 50KB

注意事项

1. 最短通话时长：建议至少 2 秒，否则可能来不及启动录制
2. 浏览器兼容性：Chrome/Edge 85+、Firefox 78+、Safari 14.1+
3. 网络状况：网络差时视频流可能不稳定，影响录制质量
4. 权限问题：确保浏览器已授予摄像头和麦克风权限

如果问题仍然存在

1. 查看完整的控制台日志
2. 确认录制是否在接通后 1 秒内启动
3. 确认是否有 "收到数据块" 日志
4. 检查通话时长是否 > 2 秒
5. 参考 LOCAL_RECORDING_DEBUG_GUIDE.md 进行详细诊断

进一步优化方向

如果修复后仍有问题，可以考虑：

1. 进一步缩短启动延迟：300ms 或更短
2. 使用 MutationObserver：监听视频元素添加，立即启动
3. 添加录制状态监控：定期检查 MediaRecorder 状态
4. 添加降级方案：本地录制失败时提示用户
5. 添加手动控制：让用户手动开始/停止录制