@tencent-classroom/device-check-sdk

中文 | English

腾讯云实时互动-教育版设备检测 SDK，提供完整的设备检测底层能力，包括设备管理、网络检测、Native 通信和日志收集。

功能特性

• 🎤 麦克风检测 — 设备枚举、切换、音量监测、录音与回放
• 🔊 扬声器检测 — 设备枚举、切换、音频播放测试
• 📷 摄像头检测 — 设备枚举、切换、画面预览
• 🌐 网络检测 — 多域名并行检测、CDN/课堂接口/IM 信令/TRTC 音视频连通性检测、域名选优
• 💻 系统环境检测 — WebRTC 支持、浏览器兼容性、硬件能力检查
• 📱 多端适配 — 支持 Web、Electron、移动端（通过 JSBridge）
• 📝 全链路日志 — 完整的运行日志记录与导出

安装

npm install @tencent-classroom/device-check-sdk
# 或
pnpm add @tencent-classroom/device-check-sdk

Peer Dependencies

# Web 端需要安装 TRTC SDK（可选）
npm install trtc-sdk-v5

快速开始

import { DeviceCheckSDK } from '@tencent-classroom/device-check-sdk';

// 1. 创建 SDK 实例
const sdk = new DeviceCheckSDK({
  language: 'zh',                    // 语言：'zh' | 'en'
  logger: { enableConsole: true }    // 日志配置
});

// 2. 初始化
// 方式一：完整初始化（等待鉴权 + 设备进房），适合移动端
await sdk.init();

// 方式二：快速初始化（仅设备枚举，鉴权在后台异步进行），适合 Web 端
await sdk.init({ deviceOnly: true });

// 3. 使用完毕后销毁
sdk.destroy();

API 参考

DeviceCheckSDK

核心门面类，对外暴露的唯一入口。

构造函数

interface DeviceCheckSDKOptions {
  logger?: LogCollectorOptions;   // 日志配置
  language?: 'zh' | 'en';        // 语言配置
}

const sdk = new DeviceCheckSDK(options?: DeviceCheckSDKOptions);

属性

| 属性 | 类型 | 说明 | |------|------|------| | device | DeviceManager | 设备管理器，操作麦克风/扬声器/摄像头 | | logger | LogCollector | 日志收集器 | | channel | WebViewChannel | WebView 通信通道（Native JSBridge） | | platform | PlatformInfo | 平台信息（只读） | | initialized | boolean | 是否已初始化 |

// 平台信息
sdk.platform.isElectron  // 是否为 Electron 环境
sdk.platform.isMac       // 是否为 Mac 系统
sdk.platform.isWindows   // 是否为 Windows 系统
sdk.platform.isMobile    // 是否为移动端
sdk.platform.osType      // 'mac' | 'windows' | 'linux' | 'unknown'

静态属性

// 获取当前活跃的 SDK 实例（单例引用，方便组件层访问）
const sdk = DeviceCheckSDK.current;

生命周期方法

// 初始化
await sdk.init();                        // 完整初始化
await sdk.init({ deviceOnly: true });    // 快速初始化（仅设备枚举）

// 销毁，释放所有资源
sdk.destroy();

// 关闭（销毁 + 关闭窗口/WebView）
sdk.close();

事件系统

type SDKEventType = 'deviceChange' | 'volumeUpdate' | 'networkResult' | 'error';

// 监听事件，返回取消监听函数
const unsubscribe = sdk.on('error', (error) => {
  console.error('SDK 错误:', error);
});

// 取消监听
unsubscribe();
// 或
sdk.off('error', callback);

日志导出

// 导出为格式化文本
const logText = sdk.exportLogs();

// 导出为 JSON 对象
const logJSON = sdk.exportLogsJSON();
// { sessionId, startTime, exportTime, duration, logs: LogEntry[] }

DeviceManager（设备管理器）

通过 sdk.device 访问，提供所有设备操作能力。

设备列表

interface DeviceInfo {
  deviceId: string;
  deviceName: string;
  type: 'microphone' | 'speaker' | 'camera';
}

// 获取设备列表
const mics: DeviceInfo[]     = sdk.device.getMicrophones();
const speakers: DeviceInfo[] = sdk.device.getSpeakers();
const cameras: DeviceInfo[]  = sdk.device.getCameras();

// 获取当前选中的设备 ID
const { micId, speakerId, cameraId } = sdk.device.getCurrentDeviceIds();

// 获取当前选中的设备标签
const { micLabel, speakerLabel, cameraLabel } = sdk.device.getCurrentDeviceLabels();

扬声器测试

// 开始播放测试音频
await sdk.device.startSpeakerTest();
// 或指定音频 URL
await sdk.device.startSpeakerTest({ audioUrl: 'https://example.com/test.mp3' });

// 停止播放
await sdk.device.stopSpeakerTest();

// 切换扬声器设备
await sdk.device.switchSpeaker(deviceId);

麦克风测试

// 开始麦克风测试（带音量回调）
await sdk.device.startMicTest({
  dom: document.getElementById('audio-container'),  // Web 端需要
  onVolume: (volume: number) => {
    console.log('当前音量:', volume);  // 0-100
  }
});

// 停止麦克风测试
await sdk.device.stopMicTest();

// 切换麦克风设备
await sdk.device.switchMic(deviceId);

// 录音功能
await sdk.device.startMicRecording();
const result = await sdk.device.stopMicRecording();
if (result) {
  // 播放录音
  await result.play(() => console.log('播放结束'));
  // 停止播放
  result.stop();
}

摄像头测试

// 开始摄像头预览
await sdk.device.startCameraTest({
  dom: document.getElementById('video-container')
});

// 停止摄像头预览
await sdk.device.stopCameraTest();

// 切换摄像头设备
await sdk.device.switchCamera(deviceId);

系统检测

// 检测 WebRTC 支持
const supported = await sdk.device.checkSystemRequirements();

// 获取系统能力详情
const capability = await sdk.device.getSystemCapability();

// 检测 TRTC 域名连通性
const connectivity = await sdk.device.checkDomainConnectivity();

// 执行完整 TRTC 检测（系统能力 + 域名连通性）
const fullCheck = await sdk.device.runFullTRTCCheck();

设备变更监听

// 监听设备热插拔
const unsubscribe = sdk.device.onDeviceChange((event) => {
  console.log('设备变更:', event.type, event.state);
});

// 监听音量更新
const unsubVolume = sdk.device.onVolumeUpdate((data) => {
  console.log('音量:', data.volume);
});

// 启用音量评估（interval 为回调间隔毫秒，0 表示关闭）
sdk.device.enableAudioVolumeEvaluation(300);

网络检测

import { CheckItemStatus, CheckItemResult } from '@tencent-classroom/device-check-sdk';

// 启动网络检测
const { items, report } = sdk.startNetworkCheck({
  // 检测项状态实时更新回调
  onItemUpdate: (item) => {
    console.log(`${item.name}: ${item.status}`);
    // item.status: 'pending' | 'checking' | 'completed'
    // item.result: 'success' | 'fixed' | 'warning' | 'failed'
  },
  // 全部检测完成回调
  onComplete: (report) => {
    console.log('检测完成:', report.summary);
  }
});

// items 是检测项初始列表，可立即用于 UI 渲染
// 包含: 网络状态、CDN资源、课堂接口、信令接口、音视频接口、系统环境

// report 是 Promise，resolve 后得到完整检测报告
const fullReport = await report;
console.log('成功:', fullReport.summary.successCount);
console.log('警告:', fullReport.summary.warningCount);
console.log('失败:', fullReport.summary.failedCount);
console.log('耗时:', fullReport.summary.totalDuration, 'ms');
console.log('域名偏好:', fullReport.domainPreference);

工具函数

import {
  detectBrowser,         // 检测浏览器信息
  isWebRTCSupported,     // 是否支持 WebRTC
  isAudioContextSupported, // 是否支持 AudioContext
  isMobile,              // 是否为移动端
  generateId,            // 生成唯一 ID
  formatTimestamp,        // 格式化时间戳
  safeAsync,             // 安全的异步调用包装
  delay                  // 延迟函数
} from '@tencent-classroom/device-check-sdk';

const browserInfo = detectBrowser();
// { name: 'Chrome', version: '120.0.0', os: 'macOS', ... }

与 UI 层配合使用

本 SDK 是底层能力包，通常配合 @tencent-classroom/device-check-ui 使用：

import TCICDeviceCheck from '@tencent-classroom/device-check-ui';

const checker = new TCICDeviceCheck({
  container: '#app',
  stepList: '1111',       // 4 位掩码：扬声器/麦克风/摄像头/网络
  theme: 'light',
  language: 'auto',
  onResult: (result) => console.log('检测结果:', result)
});

await checker.mount();

// 获取底层 SDK 实例进行高级操作
const sdk = checker.getSDK();

环境要求

• Node.js >= 16.0.0
• 浏览器：Chrome 80+（需支持 WebRTC）
• 可选：Electron 环境、移动端 WebView

English

Tencent Cloud Real-Time Interactive - Education Edition Device Check SDK. Provides complete underlying capabilities for device detection, including device management, network detection, native communication, and log collection.

Features

• 🎤 Microphone Detection — Device enumeration, switching, volume monitoring, recording & playback
• 🔊 Speaker Detection — Device enumeration, switching, audio playback testing
• 📷 Camera Detection — Device enumeration, switching, video preview
• 🌐 Network Detection — Multi-domain parallel detection, CDN/Classroom API/IM Signaling/TRTC connectivity, domain optimization
• 💻 System Environment Detection — WebRTC support, browser compatibility, hardware capability check
• 📱 Multi-platform — Supports Web, Electron, and Mobile (via JSBridge)
• 📝 Full-chain Logging — Complete runtime log recording and export

Installation

npm install @tencent-classroom/device-check-sdk
# or
pnpm add @tencent-classroom/device-check-sdk

Quick Start

import { DeviceCheckSDK } from '@tencent-classroom/device-check-sdk';

const sdk = new DeviceCheckSDK({
  language: 'en',
  logger: { enableConsole: true }
});

// Full initialization (wait for auth + device room entry) — for mobile
await sdk.init();

// Quick initialization (device enumeration only, auth runs in background) — for Web
await sdk.init({ deviceOnly: true });

// Get device list
const mics = sdk.device.getMicrophones();
const speakers = sdk.device.getSpeakers();
const cameras = sdk.device.getCameras();

// Start speaker test
await sdk.device.startSpeakerTest();

// Start mic test with volume callback
await sdk.device.startMicTest({
  onVolume: (volume) => console.log('Volume:', volume)
});

// Start camera preview
await sdk.device.startCameraTest({
  dom: document.getElementById('video-container')
});

// Start network check
const { items, report } = sdk.startNetworkCheck({
  onItemUpdate: (item) => console.log(item.name, item.status),
  onComplete: (report) => console.log('Done:', report.summary)
});

// Cleanup
sdk.destroy();

Requirements

• Node.js >= 16.0.0
• Browser: Chrome 80+ (WebRTC required)
• Optional: Electron, Mobile WebView

License

MIT