# 使用命令行录制 (/zh-CN/realtime-media/local-server-recording/build/legacy/record-by-cmd) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 声网服务端录制 SDK 支持使用命令行或调用 API 的方式实现录制。 你可以根据自己的开发习惯选择一种方式。本文介绍如何通过命令行实现录制。 ## 前提条件 [#前提条件] 开始前请确保你已经完成录制 SDK 的环境准备和集成工作,且编译了 SDK 包中的代码示例,详见[集成客户端](/zh-CN/realtime-media/local-server-recording/build/legacy/integrate-sdk)。 :::info[信息] 当录制 SDK 加入频道时,相当于一个哑客户端加入频道,因此需要跟声网 RTC SDK 加入相同的频道,并使用相同的 App ID 和频道场景。 ::: ## 开始录制 [#开始录制] 参考如下步骤,选择一种编程语言开始录制。 在命令行中输入 `./recorder_local` 加上必要的参数设置,即可快速开始录制,例如: ```shell ./recorder_local --appId {你的 App ID} --channel {频道名} --uid 0 --channelProfile {0 通信模式,1 直播模式} --appliteDir Agora_Recording_SDK_for_Linux_FULL/bin ``` 打开命令行工具,在 **/samples/java/bin** 目录下执行 `java RecordingSample` 并加上必要的参数设置,即可快速开始录制,例如: ```shell java RecordingSample --appId {你的 App ID} --channel {频道名} --uid 0 --channelProfile {0 通信模式,1 直播模式} --appliteDir Agora_Recording_SDK_for_Linux_FULL/bin ``` 其中: - `appId`,`channel` 和 `channelProfile` 的设置必须与声网 RTC SDK 中设置的一致。 - `appliteDir` 必须设置为 `AgoraCoreServices` 存放的路径,SDK 包内该文件位于 `bin` 文件夹下。 ## 设置录制选项 [#设置录制选项] 除上面示例中的参数外,示例项目还提供很多参数设置选项。 在 **samples/cpp** 目录下执行 `./recorder_local` 命令,即可看到录制 Demo 全部的参数和选项,你可以参考下表根据需要自行设置。 在 **/samples/java/bin** 目录下执行 `java RecordingSample` 命令,即可看到录制 Demo 全部的参数和选项,你可以参考下表根据需要自行设置。 :::warning[注意] `appId`,`uid`,`channel` 和 `appliteDir` 这几个参数必须设置,如不设置则无法录制。 ::: 以下参数为必填。请确保你在命令行中对其设值: - `appId`:App ID,必须和声网 RTC SDK 的 App ID 一致,详见[获取 App ID](/zh-CN/realtime-media/local-server-recording/build/recording-preparation/enable-service)。 - `uid`:标识录制实例的用户 ID,32 位无符号整数。建议设置范围:1 到(2³² - 1),并保证唯一性。有两种设置方式: - 设置为 `0`,系统将自动分配一个用户 ID。 - 设置一个唯一的用户 ID(不能与频道内的任何用户 ID 重复)。 - `channel`:希望录制的通话或直播的频道名。 - `appliteDir`:必须设置为 `AgoraCoreServices` 存放的目录,SDK 包内该文件路径为:`Agora_Recording_SDK_for_Linux_FULL/bin/`。 以下参数不是必填,但是要根据实际情况确认是否需要设置: - `channelKey`:动态密钥。如果待录制频道设置了 Token,该参数必须设置。 - `channelProfile`:频道场景,必须和待录制频道使用相同的频道场景,否则可能导致问题。 - `0`:(默认)通信场景 - `1`:直播场景 - `decryptionMode`:频道加密时,录制 SDK 可以启用内置的解密功能。解密方式必须与频道设置的加密方式一致。 - `secret`:启用解密模式后,设置的解密密码。 ### 设置端口范围 [#设置端口范围] 我们建议指定录制进程使用端口的范围。你可以为多个录制进程统一配置较大的端口范围(建议 40000 - 41000 或更大)。此时,录制 SDK 会在指定范围内为每个录制进程分配端口,并避免端口的冲突。 :::warning[注意] 如果不指定参数 `lowUdpPort` 和 `highUdpPort`,录制进程所使用的端口为随机端口,会有端口冲突的风险。 - `lowUdpPort`:最低 UDP 端口。所设置的端口必须为正整数,且最高 UDP 端口与最低 UDP 端口差值不能小于 6。 - `highUdpPort`:最高 UDP 端口。所设置的端口必须为正整数,且最高 UDP 端口与最低 UDP 端口差值不能小于 6。 ::: ### 控制录制进程 [#控制录制进程] 通过如下字段来控制录制进程: - `triggerMode`:选择录制启动模式。 - 0:(默认)自动模式,加入频道自动开始录制,离开频道自动停止录制。 - 1:手动模式,手动输入命令开始和结束录制。详见[当使用命令行录制时,如何控制录制进程?](/zh-CN/reference/faq/integration/cmd_control_record)。 - `idle`:设置空闲频道超时退出时间,单位为秒,最小值为 3 秒,默认值为 300 秒。如果频道空闲的状态持续超过该时间,录制程序会自动退出。`idle` 的时间也会纳入计费。频道空闲包括以下情况: - 通信场景下频道内没有用户发布流。 - 直播场景下频道内没有主播。 ### 选择录制内容 [#选择录制内容] 通过如下字段对录制内容进行设置: - `isAudioOnly`:是否仅录制音频。 - `0`:(默认)音视频同时录制。 - `1`:仅启用音频录制功能,关闭视频录制。 - `isVideoOnly`:是否仅录制视频。 - `0`:(默认)音视频同时录制。 - `1`:仅启用视频录制功能,关闭音频录制。 - `streamType`:设置录制的视频流类型,只有在待录制频道开启了双流模式时该设置才会生效。 - `0`:(默认)录制视频大流。 - `1`:录制视频小流。 - `autoSubscribe`:设置录制全部用户还是指定用户: - `0`:录制指定用户。该参数设为 `0` 后,必须设置 `subscribeVideoUids` 或 `subscribeAudioUids` 参数选择音频流或视频流进行录制,否则就不会录制。 - `1`:(默认)录制所有用户。 - `subscribeVideoUids`:录制指定用户的视频流。仅在 `autoSubscribe` 为 `0` 时生效。填入需要录制视频的用户的 UID,用逗号隔开,不要加空格,例如 --`subscribeVideoUids 123,456,789`。 - `subscribeAudioUids`:录制指定用户的音频流。仅在 `autoSubscribe` 为 `0` 时生效。填入需要录制音频的用户的 UID,用逗号隔开,不要加空格,例如 --`subscribeAudioUids 123,456,789`。 :::warning[注意] `isAudioOnly` 和 `isVideoOnly` 不能同时设置为 `1`。 ::: ### 设置录制格式 [#设置录制格式] 通过如下参数设置录制输出的数据格式: - `getAudioFrame`:录制音频格式。该参数设为 `1`,`2` 或 `3` (即录制原始音频数据)时,不可将 `isMixingEnabled` 设为 `1`。 - `0`:默认音频文件格式。 - `1`:原始音频数据 AAC 帧格式。 - `2`:原始音频数据 PCM 帧格式。 - `3`:原始音频数据 PCM 帧混音格式。 :::info[信息] - 支持设置录制 PCM 帧格式的原始音频数据(`getAudioFrame` 为 `2` 或 `3`)的采样率。通过配置 `cfgFilePath` 参数指定 JSON 配置文件路径,JSON 配置文件示例:`{"Pcm_Sample_Rate":16000}`。 - `Pcm_Sample_Rate` 支持 8000 Hz, 16000 Hz, 32000 Hz。如果设置的采样率不在上述范围内,则配置不生效。 ::: - `getVideoFrame`:录制视频格式。该参数设为 1,2,3 或 4 时,不可将 `isMixingEnabled` 设为 1。 - `0`:默认视频文件格式。 - `1`:原始视频数据 H.264 帧格式。 - `2`:原始视频数据 YUV 帧格式。 - `3`:原始视频数据 JPG 帧格式。 - `4`:JPG 文件格式。 - `5`:JPG 文件格式 + MP4 视频文件格式。 - 单流模式(`isMixingEnabled` 为 0)下,录制得到多个 MP4 视频文件,并截图获得多个 JPG 文件。 - 合流模式(`isMixingEnabled` 为 1)下,对合流录制,得到一个 MP4 视频文件。 - `captureInterval`:截图的时间间隔,最小值为 1 秒,默认值为 5 秒,只有在 `getVideoFrame` 设为 `3`、`4` 或 `5`(单流模式)时生效。 ### 合流模式录制 [#合流模式录制] 使用如下参数对合流录制进行设置: - `isMixingEnabled`:是否启用合流模式。 - `0`:(默认)启用单流模式录制。一个 UID 对应一个音频文件和一个视频文件。录制文件的音频属性为:采样率固定为 48 kHz,声道数和码率与原始音频流保持一致。录制文件的视频属性与原始视频流保持一致。 - `1`:启用合流模式录制。多个 UID 的音频混合成一个纯音频文件,多个 UID 的视频混合成一个纯视频文件。无论频道内有多少用户,都只生成 1 个混合音频文件和 1 个混合视频文件。混合文件的音频属性通过 `audioProfile` 参数进行设置,视频属性通过 `mixResolution`参数进行设置。 - `mixedVideoAudio`:如果 `isMixingEnabled` 设为 `1` ,该参数可以设置是否实时混合语音和视频: - `0`:(默认)不混合音频和视频。 - `1`:音频和视频混合成一个文件,录制文件格式为 MP4,但播放器支持有限。 - `2`:音频和视频混合成一个文件,录制文件格式为 MP4,支持更多播放器。 - `6`:音频和视频混合成一个文件,仅生成 TS 格式文件。 - `7`:音频和视频混合成一个文件,同时生成 MP4 和 TS 格式文件。录制成功后 SDK 会删除 TS 格式文件。 具体的播放器支持请参考[录制生成的文件支持哪些播放器?](/zh-CN/reference/faq/integration/recording_player)。 - `layoutMode`:设置视频合流布局。详见[设置合流布局](/zh-CN/realtime-media/local-server-recording/build/legacy/set-layout)。 - `0`:(默认)悬浮布局。第一个加入频道的用户在屏幕上会显示为大视窗,铺满整个画布,其他用户的视频画面会显示为小视窗,从下到上水平排列,最多 4 行,每行 4 个画面,最多支持共 17 个录制画面。 - `1`:自适应布局。根据用户的数量自动调整每个画面的大小,每个用户的画面大小一致,最多支持 17 个录制画面。 - `2`:垂直布局。指定一个用户在屏幕左侧显示大视窗画面,其他用户的小视窗画面在右侧垂直排列,最多两列,一列 8 个画面,最多支持共 17 个录制画面。 - `maxResolutionUid`:如果 `layoutMode` 设为 `2`(垂直布局),用该参数设置显示大流画面的用户 UID。 - `audioProfile`:设置音频编码配置,包括采样率、码率和声道数。仅在 `isMixingEnabled` 设为 `1` 时生效。 - `0`:音频默认设置,采样率 48 kHz,单声道,编码码率为 48 Kbps。 - `1`:高音质,采样率 48 kHz,单声道,编码码率 128 Kbps。 - `2`:高音质立体声,采样率 48 kHz,双声道,编码码率 192 Kbps。双声道不支持原始音频数据。 - `mixResolution`:如果 `isMixingEnabled` 设为 1,可以通过该参数设置合流视频的分辨率,格式为:`width`,`height`,`fps`,`Kbps`,从左至右分别对应合图的宽、高、帧率和码率。你可以参考[视频属性表](/zh-CN/realtime-media/local-server-recording/build/legacy/set-output-video#分辨率帧率码率对照表)进行设置。 - `defaultVideoBg`:设置合流模式下画布的默认背景图片的路径,仅支持本地 JPEG 文件。如不设置会显示黑色。 - `defaultUserBg`:设置合流模式下用户的默认背景图片的路径,仅支持本地 JPEG 文件。如不设置会显示黑色。合流模式下,如果某用户没有视频流,就会显示该图片。 :::warning[注意] 该设置对声网 RTC Web SDK 的用户无效。 ::: - `keepLastFrame`:合流模式下用户离开频道后,是否显示其视频的最后一帧: - `0`:(默认)不显示视频的最后一帧。 - `1`:显示视频最后一帧。 - `cfgFilePath`:录制音频时(`isAudioOnly(1)`, `isMixingEnabled(1)`),生成的音频文件新增 MP3 格式,且支持只生成 MP3 格式音频文件。通过配置 `cfgFilePath` 参数指定 JSON 配置文件路径,JSON 配置文件示例代码如下: - 录制 AAC 和 MP3 格式音频文件 ```shell { # 生成音频文件增加 MP3 格式 "Secondary_Recorder":"mp3", # 设置音频采样率 "Audio_Sample_Rate":16000 } ``` - 只录制 MP3 格式音频文件 ```shell { # 只录制 MP3 格式音频文件 "Audio_Only_Record":"mp3", # 设置音频采样率 "Audio_Sample_Rate":16000 } ``` ### 录制文件路径 [#录制文件路径] 以下两个参数都可以设置录制文件保存的路径,两个参数只能选择一个设置,不能同时使用。 - `recordFileRootDir`:设置录制文件存放的根目录。设置该参数后,会按照录制日期自动生成子目录保存录制文件。 - `cfgFilePath`:指定配置文件的路径。在该配置文件里,你可以设置保存录制文件的绝对路径,但不会自动生成子目录。配置文件的内容必须为 JSON 格式,例如:`{"Recording_Dir" : "recording path"}`,其中 `"Recording_Dir"` 是固定的,不能改动。 ### 其他设置 [#其他设置] - `proxyServer`:代理服务器的 IP 地址和端口号,如 `127.0.0.1:1080`。成功部署声网混合云、私有化平台后,你需要指定 Local Access Point 来设置本地代理。你可以联系 sales@shengwang.cn 了解和部署声网混合云或声网私有化平台。 - `enableCloudProxy`:是否启用云代理服务。使用云代理需要先联系声网申请开通,详见[应对防火墙限制](/zh-CN/realtime-media/local-server-recording/build/recording-preparation/cloud-proxy)。 - `0`:(默认)关闭云代理服务。 - `1`:启用云代理服务。 - `audioIndicationInterval`:说话者监测的时间间隔。默认禁用。 - `0`:(默认)禁用说话者监测的功能。 - `> 0`:说话者监测的时间间隔,单位为 ms。建议设置时间间隔大于 200 ms。一旦检测到频道内有人说话,命令行中会打印出当前时间段内声音最大的用户的 UID 以及当前时间段内所有说话者的 UID 和音量。 - `logLevel`:设置日志过滤等级。设置完成后,只有低于和等于所设等级的日志才会被生成。默认值为 `5`。 - `1`:日志等级为 `Fatal`。 - `2`:日志等级为 `Error`。 - `3`:日志等级为 `Warn`。 - `4`:日志等级为 `Notice`。 - `5`:日志等级为 `Info`。 - `6`:日志等级为 `Debug`。 - `enableIntraRequest`:是否启用关键帧请求。该参数默认为 `1`,可改善弱网下的音视频体验。如需使单流模式下录制的视频可指定播放位置,须将 `enableIntraRequest` 设为 `0`。 - `0`:禁用关键帧请求,频道内的所有发流端均每 2 秒发送一次关键帧。禁用后,单流模式下录制的视频可指定播放位置。 - `1`:(默认)由发流端控制是否启用关键帧请求。启用后,单流模式下录制的视频文件播放时无法指定播放位置。 :::warning[注意] 如发流端使用的是声网 Native SDK v2.9.2 及之前的版本,通信场景下设置该参数将无效,仅在直播场景下生效。 ::: - `enableH265Support`:设置是否支持录制 H.265 视频流: - `0`:(默认)不支持录制 H.265 视频流。频道内的远端用户无法发 H.265 视频流。 - `1`:支持录制 H.265 视频流。 - `localAp`:配置与声网私有媒体服务器 Native 接入模块的连接。你需要传入 Local Access Point 的域名和 IP 信息,如:`localAp [ IP1 | Domain1 ], [ IP2 | Domain2 ],...[ IPN | DomainN ]` ## 相关文档 [#相关文档] 在录制过程中,你还可以参考如下文档: - 录制完成后,你可能需要使用转码脚本将录制的文件进行合成,详见[使用转码脚本](/zh-CN/realtime-media/local-server-recording/build/legacy/merge-files)。 - 如果你希望了解如何通过调用 API 实现录制,可以参考[调用 API 录制](/zh-CN/realtime-media/local-server-recording/build/legacy/record-by-api)。 - 录制过程中,如果出现错误码或警告码,请参考[警告码](/zh-CN/api-reference/local-server-recording/cpp/legacy/namespaceagora-1-1linuxsdk#a467894afed372a4fe76594a6223869a0)。 - 录制过程中,如果出现错误码或警告码,请参考[警告码](/zh-CN/api-reference/local-server-recording/java/legacy/enumio-1-1agora-1-1recording-1-1common-1-1-common-1-1-e-r-r-o-r-c-o-d-e-t-y-p-e)和[错误码](/zh-CN/api-reference/local-server-recording/java/legacy/enumio-1-1agora-1-1recording-1-1common-1-1-common-1-1-e-r-r-o-r-c-o-d-e-t-y-p-e)。 - 如果录制文件或状态出现异常,你还可以参考[录制文件异常](/zh-CN/reference/faq/quality/record_file_issue)和[录制状态异常](/zh-CN/reference/faq/quality/record_status_error)定位和排查问题。