PjTRTC Web - 腾讯云实时音视频组件库

[TOC]

基于腾讯云 TRTC Web SDK 的 Vue 3 实时音视频通话组件库，支持音视频通话、屏幕共享、美颜等功能。

✨ 特性

• 🎥 支持本地视频预览和远程视频显示
• 🎤 支持音视频开关控制
• 📱 自适应布局：1x1、2x2、3x3 宫格布局
• 🖥️ 支持点击全屏显示
• 💻 支持屏幕共享（PC端）
• ✨ 支持基础美颜效果
• 🎯 远端用户控制（摄像头、麦克风、闪光灯等）
• 📸 支持视频截图
• 🔧 完善的错误处理和事件通知
• 🎨 现代化 UI 设计

📦 安装

npm install pj-trtc-web2

🚀 快速开始

1. 在 main.js 中引入

import { createApp } from 'vue'
import App from './App.vue'
import PjTrtcWeb from 'pj-trtc-web2'
import 'pj-trtc-web2/dist/style.css'

const app = createApp(App)
app.use(PjTrtcWeb)
app.mount('#app')

2. 在 Vue 组件中使用

<template>
  <div class="container">
    <PjTrtcWeb 
      ref="trtcRef" 
      :params="trtcParams"
      :autoEnterRoom="false"
      :showRemoteUserControl="true"
      @roomEvent="handleRoomEvent" 
      @error="handleError" 
    />
    
    <div class="controls">
      <button @click="enterRoom">进入房间</button>
      <button @click="exitRoom">退出房间</button>
      <button @click="takeSnapshot">截图</button>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { RoomEvents } from "pj-trtc-web";

const trtcRef = ref();
const trtcParams = {
  sdkAppId: "1400000123", // 腾讯云 SDKAppId
  roomId: "123456",       // 房间号
  userId: "user-001",    // 用户ID
  userSig: "your-user-sig", // 用户签名
  cameraId: "",          // 摄像头ID（可选）
  microphoneId: "",      // 麦克风ID（可选）
  speakerId: "",         // 扬声器ID（可选）
  openCamera: true,      // 是否开启摄像头（默认false）
  openMicrophone: true,  // 是否开启麦克风（默认false）
};

const handleRoomEvent = (event: RoomEvents, ...args: any[]) => {
  switch (event) {
    case RoomEvents.EnterRoom:
      console.log("进入房间成功");
      break;
    case RoomEvents.ExitRoom:
      console.log("退出房间成功");
      break;
    case RoomEvents.RemoteUserEnter:
      console.log("用户进入房间:", args[0]);
      break;
    case RoomEvents.RemoteUserExit:
      console.log("用户退出房间:", args[0]);
      break;
    case RoomEvents.NetworkQuality:
      console.log("网络质量:", args[0]);
      break;
    case RoomEvents.CustomMessage:
      console.log("收到自定义消息:", args[0]);
      break;
    // ... 处理其他事件
  }
};

const handleError = (error: Error) => {
  console.error("TRTC错误:", error.message);
};

const enterRoom = () => {
  trtcRef.value.start(trtcParams);
};

const exitRoom = () => {
  trtcRef.value.exit();
};

const takeSnapshot = async () => {
  try {
    const snapshot = await trtcRef.value.snapshot('remote-user-id', 'main');
    // 保存截图到本地
    await trtcRef.value.saveSnapshotToLocal(snapshot, `snapshot-${Date.now()}`);
  } catch (error) {
    console.error('截图失败:', error);
  }
};
</script>

<style scoped>
.container {
  width: 100%;
  height: 100vh;
  position: relative;
}

.controls {
  position: fixed;
  bottom: 100px;
  left: 50%;
  transform: translateX(-50%);
  display: flex;
  gap: 12px;
  z-index: 1000;
}

button {
  padding: 8px 16px;
  background: #3b82f6;
  color: white;
  border: none;
  border-radius: 6px;
  cursor: pointer;
}

button:hover {
  background: #2563eb;
}
</style>

📖 API 文档

Props

| 属性名 | 类型 | 必填 | 默认值 | 说明 | |--------|------|------|--------|------| | params | Object | 否 | null | TRTC 参数配置对象 | | autoEnterRoom | Boolean | 否 | false | 是否自动进入房间 | | splitScreenMode | String | 否 | Normal | 屏幕切割模式：Normal-普通模式；SubPriority-辅流优先 | | disableControlBar | Boolean | 否 | false | 隐藏底部控制栏 | | showRemoteUserControl | Boolean | 否 | false | 是否显示远端用户控制按钮 |

params 对象属性

| 属性名 | 类型 | 必填 | 说明 | |--------|------|------|------| | sdkAppId | String/Number | 是 | 腾讯云 SDKAppId | | roomId | String/Number | 是 | 房间号 | | userId | String | 是 | 用户 ID | | userSig | String | 是 | 用户签名 | | privateMapKey | String | 否 | 权限密钥 | | videoProfile | String | 否 | 视频采集分辨率：'480p'、'720p'、'1080p' | | cameraId | String | 否 | 摄像头 ID | | microphoneId | String | 否 | 麦克风 ID | | speakerId | String | 否 | 扬声器 ID | | openCamera | Boolean | 否 | 是否开启摄像头（默认 false） | | openMicrophone | Boolean | 否 | 是否开启麦克风（默认 false） |

事件

| 事件名 | 参数 | 说明 | |--------|------|------| | roomEvent | event: RoomEvents, ...args | 房间相关事件 | | error | error: Error | 错误事件 |

RoomEvents 事件类型

• EnterRoom - 进入房间成功
• ExitRoom - 退出房间成功
• KickedOut - 被踢出房间
• RemoteUserEnter - 远端用户进入房间
• RemoteUserExit - 远端用户退出房间
• RemoteVideoAvailable - 远端视频可用
• RemoteVideoUnavailable - 远端视频不可用
• RemoteAudioAvailable - 远端音频可用
• RemoteAudioUnavailable - 远端音频不可用
• ScreenShareStopped - 屏幕分享停止
• CustomMessage - 收到房间内自定义消息
• NetworkQuality - 网络质量报告
• ConnectionStateChanged - TRTC 连接状态变化
• AudioPlayStateChanged - 音频播放状态变化
• VideoPlayStateChanged - 视频播放状态变化

实例方法

| 方法名 | 参数 | 返回值 | 说明 | |--------|------|--------|------| | start | params?: TRTCParams | void | 进入房间 | | exit | - | void | 退出房间 | | setVideoDisplayName | userId: string, displayName: string | void | 设置远端用户显示名称 | | getCameraList | - | Promise<DeviceInfo[]> | 获取摄像头列表 | | getMicrophoneList | - | Promise<DeviceInfo[]> | 获取麦克风列表 | | getSpeakerList | - | Promise<DeviceInfo[]> | 获取扬声器列表 | | switchCamera | deviceId: string | void | 切换摄像头 | | switchMicrophone | deviceId: string | void | 切换麦克风 | | setSpeaker | deviceId: string | void | 设置扬声器 | | setVideoProfile | profile: string | void | 设置推流视频分辨率 | | sendCustomMessage | cmdId: number, message: string | void | 发送房间内自定义消息 | | sendSEIMessage | message: string | Promise | 发送 SEI 消息（需开启推流） | | switchFrontCamera | - | void | 切换前后摄像头（移动端） | | toggleVideo | - | Promise | 切换摄像头开关 | | toggleAudio | - | Promise | 切换麦克风开关 | | toggleScreenShare | - | Promise | 切换屏幕分享 | | setBasicBeauty | beauty: number, brightness: number, ruddy: number | Promise | 设置美颜参数 | | snapshot | userId: string, streamType: TRTCStreamType | Promise | 视频截图（返回 base64） | | saveSnapshotToLocal | frameData: string, suggestedName?: string | Promise | 保存截图到本地 |

远端用户控制

组件支持通过 SEI 消息控制远端用户，支持的控制类型：

// 发送 SEI 控制消息示例
const controlCommands = {
  // 视频控制
  RemoteUserControlProtocol.Video: 'video',        // 开关摄像头
  RemoteUserControlProtocol.Camera: 'camera',       // 切换摄像头
  RemoteUserControlProtocol.Torch: 'torch',        // 开关闪光灯
  RemoteUserControlProtocol.PlusZoom: 'zoom-in',   // 镜头拉近
  RemoteUserControlProtocol.MinusZoom: 'zoom-out',  // 镜头拉远
  RemoteUserControlProtocol.VideoOrientation: 'orientation', // 镜头旋转
  
  // 其他
  RemoteUserControlProtocol.Snapshot: 'snapshot'   // 视频截图
};

// 发送控制消息
await trtcRef.value.sendSEIMessage(JSON.stringify({
  cmd: controlCommands.RemoteUserControlProtocol.Video,
  userId: 'target-user-id'
}));

🔧 配置说明

1. 获取腾讯云 TRTC 配置

1. 登录 腾讯云 TRTC 控制台
2. 创建应用，获取 SDKAppId
3. 生成 UserSig（参考官方文档）

2. UserSig 生成

// 简单示例（实际生产环境请使用服务端生成）
function generateUserSig SDKAppId, userId, secretKey) {
  const timestamp = Math.floor(Date.now() / 1000);
  const signature = `TLS:${timestamp}:`;
  // 实际项目中应该使用服务端生成
  return signature;
}

🎨 自定义样式

组件支持通过 CSS 变量自定义样式：

:root {
  --main-background-color: #1a1a2e;
  --control-bar-bottom: 24px;
  --video-border-radius: 16px;
  --control-bar-bg: rgba(15, 23, 42, 0.85);
}

.trtc-container {
  /* 自定义样式 */
}

📱 移动端适配

组件自动检测移动端环境，并适配以下特性：

• 显示切换前后摄像头按钮
• 优化控制按钮大小
• 自适应布局调整

⚠️ 注意事项

1. 环境要求：

   • HTTPS 环境（本地开发可使用 HTTP）
   • 支持 WebRTC 的现代浏览器
   • 移动端需 iOS 11+ 或 Android 67+

2. 权限处理：

   • 首次使用需要授权摄像头和麦克风
   • 建议在用户交互后（如点击按钮）再请求权限

3. 性能优化：

   • 多人通话时注意网络带宽
   • 可根据网络状况调整视频分辨率
   • 及时清理不用的流和资源

4. 错误处理：

   • 建议完整处理 error 事件
   • 注意房间状态管理
   • 处理被踢出房间的情况

🔄 版本历史

v26.5.1

• 屏幕共享中增加状态显示
• 挂断时如果处于屏幕共享中先退出屏幕共享
• 支持虚拟背景（需要开通TRTC 旗舰版包月套餐）

v26.4.6

• 修复已知问题

v26.4.5

• 添加远端用户 SEI 消息控制功能
• 支持控制摄像头、麦克风、闪光灯等

v26.4.4

• 修改截图返回 base64 数据格式

v26.4.3

• 添加发送 SEI 消息时必须开启推流的限制

v26.4.2

• 添加远端视频截图功能
• 添加发送 SEI 消息接口

v26.1.3

• 修复进入房间错误码返回问题

v26.1.1

• 支持进入房间时不必须开启摄像头和麦克风
• 优化退出房间时的资源清理
• 改进屏幕共享用户体验

v25.11.2

• 添加基础美颜设置功能

v25.11.1

• 增加音量回调功能

v25.10.1

• 支持设备管理（摄像头、麦克风测试）

v1.0.19

• 支持外部配置隐藏控制栏
• 增加音视频状态切换接口

更多版本历史

• 参考 CHANGELOG.md

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

📞 支持

如有问题，请提交 Issues