# 开始录制音视频 (/zh-CN/realtime-media/local-server-recording/get-started/start-recording/cpp)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## 前提条件 [#前提条件]
本文介绍如何使用声网服务端 SDK 在实时音视频频道中实现录制功能。开始前请确保你的本地开发环境满足以下条件:
* 参考[开通本地服务端录制服务](/zh-CN/realtime-media/local-server-recording/build/recording-preparation/enable-service)在控制台创建一个声网项目,并获取项目的 App ID。
* 在项目中实现了基础的音视频互动场景。
* 服务器硬件条件:
* CPU:8 核,1.8 GHz 主频
* 内存:推荐 4 GB 或更高
* 服务器软件环境:
* 操作系统:Ubuntu(18.04 版本及以上)或 CentOS(7.0 版本及以上)
* CPU 架构:arm64 或 x86-64
* glibc 2.18 或更高版本
* gcc 4.8 或更高版本
* 网络要求:
* 服务器接入公网,有公网 IP
* 服务器允许访问 `.agora.io` 以及 `.agoralab.co`
## 集成 SDK [#集成-sdk]
1. 前往[下载](/zh-CN/realtime-media/local-server-recording/reference/downloads)获取最新的声网本地服务端录制 SDK 软件包。解压后的 SDK 包目录结构如下:
```shell
.
├── agora_sdk
│ ├── include
│ ├── libagora-fdkaac.so
│ ├── libagora_rtc_sdk.so
│ └── libaosl.so
└── example
├── CMakeLists.txt
├── build.sh
├── out
├── recorder
├── recorder.json
├── singleVideo.json
├── scripts
└── third-party
```
2. 将下载下来的 SDK 文件集成到你的项目中:
- 将 `agora_sdk/include` 目录中的头文件导入到你的开发工程中
- 将 `agora_sdk/` 目录下的如下动态库文件链接到你的工程:
- `libagora-fdkaac.so`
- `libagora_rtc_sdk.so`
- `libaosl.so`
:::info[信息]
SDK 包中的 `example` 路径下是完整的本地录制示例项目。你可以参考[编译示例项目并运行](#run-example)跑通并体验。
:::
## 调用 API 实现录制 [#调用-api-实现录制]
实现录制的 API 时序如下图所示:
### 初始化服务资源 [#初始化服务资源]
首先,你需要调用 [`createAgoraService`](/zh-CN/api-reference/local-server-recording/cpp/iagoraservice.cpp#createagoraservice) 创建服务实例,并使用 [`initialize`](/zh-CN/api-reference/local-server-recording/cpp/iagoraservice.cpp#initialize) 方法进行初始化,设置 App ID 和音视频相关的配置。
```cpp
// 初始化 Service 资源,设置 log
auto service = createAgoraService();
agora::base::AgoraServiceConfiguration service_config;
service_config.enableAudioDevice = false;
service_config.enableAudioProcessor = true;
service_config.enableVideo = true;
service_config.appId = config.appId.c_str();
service_config.useStringUid = config.UseStringUid;
service->initialize(service_config);
service->setLogFile("./io.agora.rtc_sdk/agorasdk.log", 1024*1024*5);
```
### 创建 Recorder [#创建-recorder]
调用 [`createAgoraMediaComponentFactory`](/zh-CN/api-reference/local-server-recording/cpp/iagoramediacomponentfactory.cpp#createagoramediacomponentfactory) 和 [`createMediaRtcRecorder`](/zh-CN/api-reference/local-server-recording/cpp/iagoramediacomponentfactory.cpp#createmediartcrecorder) 创建录制实例,然后使用 [`IAgoraMediaRtcRecorder::initialize`](/zh-CN/api-reference/local-server-recording/cpp/iagoramediartcrecorder.cpp#initialize) 方法初始化录制实例。
```cpp
// 创建 recorder
agora::rtc::IMediaComponentFactory* factory = createAgoraMediaComponentFactory();
agora::agora_refptr recorder = factory->createMediaRtcRecorder();
// 初始化 recorder
// isMix 设置录制模式
// - false 表示分开录制每个用户的音视频流,即单流录制
// - true 表示将所有用户的音视频混合录制,即合流录制
bool isMix = false;
// service 为上一步初始化的 AgoraService 对象
recorder->initialize(service, isMix);
```
### 注册事件处理器 [#注册事件处理器]
使用 [`registerRecorderEventHandler`](/zh-CN/api-reference/local-server-recording/cpp/iagoramediartcrecorder.cpp#registerrecordereventhandle) 注册录制事件的回调处理器,以便接收和处理录制过程中的事件通知。
```cpp
// 注册回调
std::unique_ptr eventHandler{new RecorderEventHandler(recorder, config)};
recorder->registerRecorderEventHandle(eventHandler.get());
```
### 订阅音视频流 [#订阅音视频流]
调用 [`subscribeAllAudio`](/zh-CN/api-reference/local-server-recording/cpp/iagoramediartcrecorder.cpp#subscribeallaudio) 和 [`subscribeAllVideo`](/zh-CN/api-reference/local-server-recording/cpp/iagoramediartcrecorder.cpp#subscribeallvideo) 方法来订阅频道内的所有音频和视频流。
```cpp
// 订阅流
recorder->subscribeAllAudio();
recorder->subscribeAllVideo(options);
```
### 配置录制参数 [#配置录制参数]
使用 [`setRecorderConfig`](/zh-CN/api-reference/local-server-recording/cpp/iagoramediartcrecorder.cpp#setrecorderconfig) 方法设置录制的相关配置,包括视频分辨率、帧率、存储路径等。
:::warning[注意]
请确保你设置的录制文件存储路径 `storagePath` 存在。如果指定的目录不存在,会导致录制失败。
:::
```cpp
// 设置录制相关配置
agora::media::MediaRecorderConfiguration recorder_config;
recorder_config.width = config.video.width;
recorder_config.height = config.video.height;
recorder_config.fps = config.video.fps;
recorder_config.storagePath = config.recorderPath.c_str();
recorder_config.sample_rate = config.audio.sampleRate;
recorder_config.channel_num = config.audio.numOfChannels;
// 设置录制音频流、视频流、音视频流
recorder_config.streamType = static_cast(config.recorderStreamType);
// 设置最大录制时长
recorder_config.maxDurationMs = config.maxDuration * 1000;
recorder->setRecorderConfig(recorder_config);
```
### 加入频道并开始录制 [#加入频道并开始录制]
调用 [`joinChannel`](/zh-CN/api-reference/local-server-recording/cpp/legacy/classagora-1-1recording-1-1-i-recording-engine#joinchannel) 加入指定的频道,然后使用 [`startRecording`](/zh-CN/api-reference/local-server-recording/cpp/iagoramediartcrecorder.cpp#startrecording) 开始录制。
```cpp
// 加入频道并开始录制
recorder->joinChannel(config.token.c_str(), config.ChannelName.c_str(), config.UserId.c_str());
recorder->startRecording();
```
### 结束录制和释放资源 [#结束录制和释放资源]
录制完成后,需要调用相应的方法来取消订阅流、停止录制、退出频道并释放资源。你会在[配置录制参数](#配置录制参数)时指定的存储路径下找到 MP4 格式的录制文件。
```cpp
// 结束录制 清理资源 退出频道
recorder->unsubscribeAllAudio();
recorder->unsubscribeAllVideo();
recorder->stopRecording();
recorder->unregisterRecorderEventHandle(eventHandler.get());
eventHandler = nullptr;
recorder->leavelChannel();
recorder = nullptr;
service->release();
```
### 完整示例代码 [#完整示例代码]
以下是使用声网服务端 SDK 进行视频录制的完整示例代码:
```cpp
// 初始化 Service 资源,设置 log
auto service = createAgoraService();
agora::base::AgoraServiceConfiguration service_config;
service_config.enableAudioDevice = false;
service_config.enableAudioProcessor = true;
service_config.enableVideo = true;
service_config.appId = config.appId.c_str();
service_config.useStringUid = config.UseStringUid;
service->initialize(service_config);
service->setLogFile("./io.agora.rtc_sdk/agorasdk.log", 1024*1024*5);
// 创建 recorder
agora::rtc::IMediaComponentFactory* factory = createAgoraMediaComponentFactory();
agora::agora_refptr recorder = factory->createMediaRtcRecorder();
// 初始化 recorder
bool isMix = false;
recorder->initialize(service, isMix);
// 注册回调
std::unique_ptr eventHandler{new RecorderEventHandler(recorder, config)};
recorder->registerRecorderEventHandle(eventHandler.get());
// 订阅流
recorder->subscribeAllAudio();
recorder->subscribeAllVideo(options);
// 设置录制相关配置
agora::media::MediaRecorderConfiguration recorder_config;
recorder_config.width = config.video.width;
recorder_config.height = config.video.height;
recorder_config.fps = config.video.fps;
recorder_config.storagePath = config.recorderPath.c_str();
recorder_config.sample_rate = config.audio.sampleRate;
recorder_config.channel_num = config.audio.numOfChannels;
recorder_config.streamType = static_cast(config.recorderStreamType);
recorder_config.maxDurationMs = config.maxDuration * 1000;
recorder->setRecorderConfig(recorder_config);
// 加入频道并开始录制
recorder->joinChannel(config.token.c_str(), config.ChannelName.c_str(), config.UserId.c_str());
recorder->startRecording();
// 结束录制 清理资源 退出频道
recorder->unsubscribeAllAudio();
recorder->unsubscribeAllVideo();
recorder->stopRecording();
recorder->unregisterRecorderEventHandle(eventHandler.get());
eventHandler = nullptr;
recorder->leavelChannel();
recorder = nullptr;
service->release();
```
## 后续步骤 [#后续步骤]
完成基本录制功能后,你可以进一步探索以下功能:
- [单流录制和合流录制](/zh-CN/realtime-media/local-server-recording/build/configure-recording-output/recording-mode)
- [自定义合流录制视频布局](/zh-CN/realtime-media/local-server-recording/build/configure-recording-output/set-layout)
- [配置水印](/zh-CN/realtime-media/local-server-recording/build/configure-recording-output/watermark)
- [录制崩溃后修复录制文件](/zh-CN/realtime-media/local-server-recording/build/best-practices/restore-files)
## 参考信息 [#参考信息]
### 编译示例项目并运行 [#编译示例项目并运行]
声网在 SDK 下载包中提供了完整的录制示例项目。获取并解压下载包后,你可以参考如下步骤编译并运行项目:
1. 运行如下命令行,前往示例项目所在路径:
```shell
cd agora_rtc_sdk/example
```
2. 运行命令行,构建示例项目:
```shell
./build.sh
```
3. 将 SDK 包中的库文件添加到 LD_LIBRARY_PATH:
```shell
export LD_LIBRARY_PATH=../../agora_sdk:$LD_LIBRARY_PATH
```
4. 按照场景需要填写 `recorder.json`(合流录制的配置文件)或 `singleVideo.json`(单流录制的配置文件)。单流和合流的场景区别可以参考[单流录制和合流录制](/zh-CN/realtime-media/local-server-recording/build/configure-recording-output/recording-mode)。
5. 运行如下命令行,示例程序会根据你在指定 json 文件中的配置进行录制:
```shell
# 假定进行单流录制
./out/sample_recorder singleVideo.json
```
### API 参考 [#api-参考]
本文介绍实现一个极简的录制任务需要调用的核心 API。你可以参考[录制 API](/zh-CN/api-reference/local-server-recording/cpp/api-overview) 了解完整的功能列表和对应的 API。