# 录制与回放 (/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/extend-whiteboard/record-and-replay)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
声网互动白板 SDK 提供录制与回放功能,支持将实时房间中的所有互动行为录制下来,并支持高质量回放。相较于传统的录屏模式,白板录制和回放具有以下优势:
- **高效录制**:采用信令记录方式,相比传统录屏模式占用带宽更少、存储空间更小
- **高质量回放**:回放时还原现场效果,画质清晰、动画流畅
- **服务端录制**:录制在服务端自动进行,无需客户端额外处理
- **灵活回放**:支持指定时间范围回放、播放控制、视角跟随等功能
- **完整记录**:录制白板操作、自定义事件、视角变化等所有互动行为
本文介绍如何开启白板录制功能以及如何实现白板内容回放。
## 技术原理 [#技术原理]
### 白板录制 [#白板录制]
声网互动白板录制不是屏幕录制,而是记录信令与数据增量构成的私有二进制数据。录制过程完全在服务端进行,具有以下优势:
- **自动录制**:只需在创建房间时开启录制功能,服务端会自动录制房间内的所有互动行为
- **智能管理**:只有在房间活跃时才会生成录制信息,房间无活动时录制会自动停止
- **数据紧凑**:录制生成的数据相比传统音视频格式更紧凑,占用存储空间更小
### 白板回放 [#白板回放]
白板回放时,SDK 会依照录制的信令与数据增量还原现场,得到的效果和实时互动时一模一样。回放支持:
- 指定时间范围回放
- 播放、暂停、跳转等播放控制
- 视角跟随和自由视角切换
- 自定义事件和全局状态变化的回放
## 前提条件 [#前提条件]
开始前,请确保:
1. 已在项目中集成声网互动白板 SDK。详见[快速开始](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/get-started/join-room-wb)。
2. 已获取有效的 SDK Token 和 Room Token。详见[获取互动白板项目的安全密钥](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/setup-and-access/enable-service#获取互动白板项目的安全密钥)。
3. 如需在业务服务器上创建房间,请参考[房间管理服务端 API](/zh-CN/api-reference/api-ref/whiteboard/restful/create-room)。
## 实现录制功能 [#实现录制功能]
### 开启录制 [#开启录制]
要开启白板录制功能,需要在创建房间时设置 `isRecord: true` 参数。以下示例展示如何通过服务端 API 创建支持录制的房间:
```javascript
// 注意:建议在业务服务器上执行创建房间操作,不要在前端执行
var url = "https://api.netless.link/v5/rooms";
var requestInit = {
method: "POST",
headers: {
"content-type": "application/json",
"token": "NETLESSSDK_YWs9xxxxxxM2MjRi", // 替换为你的 SDK Token
"region": "cn-hz", // 替换为你的数据中心
},
body: JSON.stringify({
name: "我的录制房间",
isRecord: true, // 开启录制功能
}),
};
fetch(url, requestInit).then(function(response) {
return response.json();
}).then(function(roomJSON) {
// 创建房间成功,获取房间信息
console.log("房间 UUID:", roomJSON.uuid);
console.log("房间已开启录制功能");
}).catch(function(err) {
console.error("创建房间失败:", err);
});
```
:::warning[注意]
- SDK Token 是重要的安全凭证,建议在业务服务器中使用,不要写死在前端代码中。
- 开启录制功能后,该房间内的所有互动行为都会被自动录制。
:::
### 录制内容 [#录制内容]
开启录制功能后,以下内容会被自动录制:
- 白板绘制操作(画笔、图形、文字等)
- 场景切换和内容变化
- 图片、MP3、MP4、课件(PPT、DOC)的展示和操作
- 用户视角变化
- 自定义事件(通过 `dispatchMagixEvent` 发送的事件)
- 全局状态变化(`GlobalState` 的修改)
## 实现回放功能 [#实现回放功能]
### 检查录制内容是否可回放 [#检查录制内容是否可回放]
在创建回放播放器之前,建议先检查指定时间段是否有可回放的录制内容:
```javascript
var whiteWebSdk = new WhiteWebSdk({
appIdentifier: "RMxxxAQ", // 替换为你的 App Identifier
});
var playableCheckingParams = {
room: "a7xxx69", // 房间 UUID
roomToken: "NETLESSROOM_YWxxxjk", // Room Token
beginTimestamp: new Date("2023-01-01 08:00:00").getTime(), // 回放开始时间
duration: 45 * 60 * 1000, // 回放持续时间(毫秒),这里是 45 分钟
};
whiteWebSdk.isPlayable(playableCheckingParams).then(function(isPlayable) {
if (isPlayable) {
console.log("该时间段有可回放的录制内容");
// 可以创建回放播放器
} else {
console.log("该时间段没有录制内容");
}
}).catch(function(err) {
console.error("检查回放内容失败:", err);
});
```
### 创建回放播放器 [#创建回放播放器]
使用 `replayRoom` 方法创建回放播放器:
```javascript
var replayRoomParams = {
room: "a7xxx69", // 房间 UUID
roomToken: "NETLESSROOM_YWxxxjk", // Room Token
beginTimestamp: new Date("2023-01-01 08:00:00").getTime(), // 回放开始时间
duration: 45 * 60 * 1000, // 回放持续时间(毫秒)
};
whiteWebSdk.replayRoom(replayRoomParams).then(function(player) {
// 成功创建回放播放器
console.log("回放播放器创建成功");
// 将播放器绑定到页面元素
player.bindHtmlElement(document.getElementById("whiteboard"));
// 开始播放
player.play();
}).catch(function(err) {
console.error("创建回放播放器失败:", err);
});
```
### 播放器控制 [#播放器控制]
回放播放器提供了丰富的播放控制功能:
```javascript
// 播放控制
player.play(); // 开始播放
player.pause(); // 暂停播放
player.stop(); // 停止播放
// 跳转到指定位置(单位:毫秒,相对于回放开始时间)
player.seekToProgressTime(10 * 60 * 1000) // 跳转到第 10 分钟
.then(function(result) {
console.log("跳转结果:", result);
});
// 设置播放倍速
player.playbackSpeed = 1.5; // 1.5 倍速播放
player.playbackSpeed = 1.0; // 恢复正常速度
// 获取播放状态信息
console.log("当前播放进度:", player.progressTime); // 当前播放位置(毫秒)
console.log("总时长:", player.timeDuration); // 回放总时长(毫秒)
console.log("播放状态:", player.phase); // 播放状态
```
### 监听播放器状态变化 [#监听播放器状态变化]
可以通过回调函数监听播放器状态的变化:
```javascript
var playerCallbacks = {
// 播放状态改变回调
onPhaseChanged: function(phase) {
switch(phase) {
case "playing":
console.log("正在播放");
break;
case "pause":
console.log("已暂停");
break;
case "buffering":
console.log("正在缓冲");
break;
case "ended":
console.log("播放结束");
break;
}
},
// 播放进度改变回调
onProgressTimeChanged: function(progressTime) {
console.log("当前播放进度:", progressTime + "ms");
},
// 播放出错回调
onStoppedWithError: function(error) {
console.error("播放出错:", error);
}
};
// 创建播放器时注册回调
whiteWebSdk.replayRoom(replayRoomParams, playerCallbacks).then(function(player) {
// 播放器创建成功
});
```
### 视角控制 [#视角控制]
回放时可以控制观看视角:
```javascript
// 设置观看模式
player.setObserverMode("directory"); // 跟随模式,跟随录制时的视角变化
player.setObserverMode("freedom"); // 自由模式,可以自由调整视角
// 禁止用户调整视角
player.disableCameraTransform = true; // 禁止用户通过手势调整视角
player.disableCameraTransform = false; // 允许用户调整视角
```
### 回放自定义事件 [#回放自定义事件]
如果录制时发送了自定义事件,回放时也可以监听这些事件:
```javascript
// 监听回放中的自定义事件
player.addMagixEventListener("Greetings", function(event) {
console.log("回放中收到自定义事件:", event.payload);
});
// 监听全局状态变化
var playerCallbacks = {
onPlayerStateChanged: function(modifyState) {
if (modifyState.globalState) {
console.log("全局状态发生变化:", modifyState.globalState);
}
}
};
```
### 使用 React 展示回放 [#使用-react-展示回放]
如果你使用 React 框架,可以使用 `white-react-sdk` 更方便地展示回放内容:
```jsx
import React from "react";
import { PlayerWhiteboard } from "white-react-sdk";
class ReplayComponent extends React.Component {
render() {
const style = {
width: "100%",
height: "100vh",
};
return (