# 音视频录制 (/zh-CN/api-reference/rtc/macos/recording)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## createMediaRecorder: [#createmediarecorder]
创建一个媒体录制器实例。
```objc
- (AgoraMediaRecorder * _Nullable)createMediaRecorder:(AgoraRecorderStreamInfo * _Nonnull)info NS_SWIFT_NAME(createMediaRecorder(withInfo:));
```
在开始音视频流录制之前,你需要调用该方法创建一个媒体录制器实例。SDK 支持录制来自本地或远端用户的多个音视频流。你可以多次调用该方法创建多个录制器实例,并使用 `info` 参数指定要录制的频道名和远端用户 ID。
成功创建录制器实例后,你需要调用 [setMediaRecorderDelegate:](/zh-CN/api-reference/rtc/macos/recording#api_imediarecorder_setmediarecorderobserver) 方法为该录制器注册一个观察者,以监听相关回调,然后调用 [startRecording:](/zh-CN/api-reference/rtc/macos/recording#api_imediarecorder_startrecording) 方法开始录制。
### 参数 [#参数]
要录制的音视频流的信息,详见 [AgoraRecorderStreamInfo](/zh-CN/api-reference/rtc/macos/class-recorderstreaminfo)。
### 返回值 [#返回值]
- 方法调用成功,返回 [AgoraMediaRecorder](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediarecorder) 对象。
- 方法调用失败,返回 nil。
### 所属接口类 [#所属接口类]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)
## destroyMediaRecorder: [#destroymediarecorder]
销毁音视频录制器实例。
```objc
- (int)destroyMediaRecorder:(AgoraMediaRecorder * _Nullable)mediaRecorder;
```
当你不再需要录制音视频流时,可以调用此方法销毁对应的音视频录制器实例。如果录制正在进行中,请先调用 [stopRecording](/zh-CN/api-reference/rtc/macos/recording#api_imediarecorder_stoprecording) 停止录制,然后再调用此方法销毁录制器实例。
### 参数 [#参数-1]
要销毁的 [AgoraMediaRecorder](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediarecorder) 实例。详见 [AgoraMediaRecorder](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediarecorder)。
### 返回值 [#返回值-1]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。请参阅错误码获取详细信息和排查建议。
### 所属接口类 [#所属接口类-1]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)
## enableMainQueueDispatch: [#enablemainqueuedispatch]
设置是否将回调方法派发到主线程。
```objc
- (int)enableMainQueueDispatch:(BOOL)enabled NS_SWIFT_NAME(enableMainQueueDispatch(_:));
```
如果不将回调方法派发到主线程,应用应将 UI 操作派发到主线程。
### 参数 [#参数-2]
是否将回调方法派发到主线程:
- YES:将回调方法派发到主线程。
- NO:不将回调方法派发到主线程。
### 返回值 [#返回值-2]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。详见错误码获取详情和排查建议。
### 所属接口类 [#所属接口类-2]
- [AgoraMediaRecorder](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediarecorder)
## setMediaRecorderDelegate: [#setmediarecorderdelegate]
注册 [AgoraMediaRecorderDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediarecorderobserver) 观察者。
```objc
- (int)setMediaRecorderDelegate:(id _Nullable)delegate;
```
:::info[自从]
自 v4.0.0 版本新增。
:::
该方法用于设置音视频录制的回调,使你在录制过程中能够获取音视频流的录制状态和相关信息。
在调用该方法前,请确保已创建并初始化 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 对象,并使用 [createMediaRecorder:](/zh-CN/api-reference/rtc/macos/recording#api_irtcengine_createmediarecorder) 创建录制器实例。
### 参数 [#参数-3]
音视频流录制的回调。详见 [AgoraMediaRecorderDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediarecorderobserver)。
### 返回值 [#返回值-3]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-3]
- [AgoraMediaRecorder](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediarecorder)
## startAudioRecording\:quality: [#startaudiorecordingquality]
开始客户端录音。
```objc
- (int)startAudioRecording:(NSString * _Nonnull)filePath
quality:(AgoraAudioRecordingQuality)quality NS_SWIFT_NAME(startAudioRecording(_:quality:));
```
你可以在通话过程中调用该方法进行客户端录音。该方法会录制频道中所有用户的音频,并生成包含所有用户声音的录音文件。录音文件仅支持以下格式:
- `.wav`:文件体积大,音频保真度高。
- `.aac`:文件体积小,音频保真度有损。
:::note
注: 调用该方法时,默认的录音采样率为 32 kHz,且无法修改。
:::
### 参数 [#参数-4]
录音文件保存的本地绝对路径。路径必须包含文件名和扩展名,例如:/var/mobile/Containers/Data/audio.aac。
:::note
注: 请确保指定路径存在且可写。
:::
录音质量,详见 [AgoraAudioRecordingQuality](/zh-CN/api-reference/rtc/macos/enum-audiorecordingqualitytype)。
### 返回值 [#返回值-4]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-4]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)
## startAudioRecordingWithConfig: [#startaudiorecordingwithconfig]
开始客户端录制并配置录制设置。
```objc
- (int)startAudioRecordingWithConfig:(AgoraAudioRecordingConfiguration * _Nonnull)config NS_SWIFT_NAME(startAudioRecording(withConfig:));
```
调用该方法后,你可以录制频道中用户的音频并生成录音文件。录音文件仅支持以下格式:
- WAV:音频保真度较高但文件较大。例如,采样率为 32000 Hz 的 10 分钟录音文件约为 73 MB。
- AAC:音频保真度较低但文件较小。例如,采样率为 32000 Hz 且录音质量为 `AgoraAudioRecordingQualityMedium` 的 10 分钟录音文件约为 2 MB。
当你离开频道时,录制会自动停止。该方法支持在通话过程中进行客户端录制。
### 调用时机 [#调用时机]
该方法必须在加入频道后调用。
### 参数 [#参数-5]
录制配置,详见 [AgoraAudioRecordingConfiguration](/zh-CN/api-reference/rtc/macos/class-audiorecordingconfiguration)。
### 返回值 [#返回值-5]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-5]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)
## startRecording: [#startrecording]
开始录制音视频流。
```objc
- (int)startRecording:(AgoraMediaRecorderConfiguration* _Nonnull)config NS_SWIFT_NAME(startRecording(_:));
```
:::info[自从]
自 v4.0.0 版本新增。
:::
该方法用于开始录制音频和视频流。声网 SDK 支持同时录制本地和远端用户的音视频流。
在开始录制前,请确保:
- 已调用 [createMediaRecorder:](/zh-CN/api-reference/rtc/macos/recording#api_irtcengine_createmediarecorder) 创建媒体录制器对象。
- 已调用 [setMediaRecorderDelegate:](/zh-CN/api-reference/rtc/macos/recording#api_imediarecorder_setmediarecorderobserver) 注册媒体录制器观察者以监听录制相关的回调。
- 已加入频道。
该方法支持录制以下数据:
- 通过麦克风采集的音频,编码格式为 AAC。
- 通过摄像头采集的视频,编码格式为 H.264 或 H.265。
录制开始后,如果录制过程中视频分辨率发生变化,SDK 会停止录制。如果音频采样率或声道数发生变化,SDK 会继续录制并生成一个 MP4 文件。仅当检测到可录制的音视频流时,才会生成录制文件。如果在录制过程中未检测到可录制的音视频流,或音视频流中断超过 5 秒,SDK 会停止录制并触发 [mediaRecorder\:stateDidChanged\:uid\:state\:reason:](/zh-CN/api-reference/rtc/macos/recording#callback_imediarecorderobserver_onrecorderstatechanged) 回调(`AgoraMediaRecorderStateError`,`AgoraMediaRecorderReasonCodeNoStream`)。
:::note
注:
- 如果需要录制本地音视频流,请确保本地用户角色在开始录制前已设置为主播。
- 如果需要录制远端用户的音视频流,请确保在开始录制前已订阅目标用户的音视频流。
:::
### 参数 [#参数-6]
用于配置音视频流录制的参数,详见 [AgoraMediaRecorderConfiguration](/zh-CN/api-reference/rtc/macos/class-mediarecorderconfiguration)。
### 返回值 [#返回值-6]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。详见错误码:
- -2:参数无效。请确保:
- 指定的录制文件保存路径正确且可写。
- 指定的录制文件格式正确。
- 最大录制时长设置正确。
- -4:当前 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 的状态不支持该操作。可能是由于已有录制任务正在进行,或录制错误导致录制已停止。
- -7:调用该方法时 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 尚未初始化。请确保在调用该方法前已创建 [AgoraMediaRecorder](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediarecorder) 对象。
### 所属接口类 [#所属接口类-6]
- [AgoraMediaRecorder](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediarecorder)
## stopAudioRecording [#stopaudiorecording]
停止客户端录制音频。
```objc
- (int)stopAudioRecording NS_SWIFT_NAME(stopAudioRecording());
```
### 返回值 [#返回值-7]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-7]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)
## stopRecording [#stoprecording]
停止录制音视频流。
```objc
- (int)stopRecording NS_SWIFT_NAME(stopRecording());
```
:::info[自从]
自 v4.0.0 版本新增。
:::
:::note
注: 调用 [startRecording:](/zh-CN/api-reference/rtc/macos/recording#api_imediarecorder_startrecording) 后,如果你想停止录制,必须调用此方法;否则生成的录制文件可能无法正常播放。
:::
### 返回值 [#返回值-8]
- 0:方法调用成功。
- < 0:方法调用失败:
- -7:在初始化 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 之前调用该方法。请确保在调用此方法之前已创建 `Recorder` 对象。
### 所属接口类 [#所属接口类-8]
- [AgoraMediaRecorder](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediarecorder)
## mediaRecorder\:informationDidUpdated\:uid\:info: [#mediarecorderinformationdidupdateduidinfo]
录制信息更新回调。
```objc
- (void)mediaRecorder:(AgoraMediaRecorder* _Nonnull)recorder informationDidUpdated:(NSString * _Nonnull)channelId uid:(NSUInteger)uid info:(AgoraMediaRecorderInfo* _Nonnull)info;
```
:::info[自从]
自 v4.0.0 版本新增。
:::
在你成功注册该回调并开始音视频流录制后,SDK 会根据你在 [AgoraMediaRecorderConfiguration](/zh-CN/api-reference/rtc/macos/class-mediarecorderconfiguration) 中设置的 `recorderInfoUpdateInterval` 的值,周期性地触发该回调,报告当前录制文件的名称、时长和大小。
### 触发时机 [#触发时机]
该回调在你成功注册并开始音视频流录制后,SDK 会周期性地触发。
### 参数 [#参数-7]
[AgoraMediaRecorder](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediarecorder) 实例。详见 [AgoraMediaRecorder](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediarecorder)。
频道名。
用户 ID。
录制文件信息,详见 [AgoraMediaRecorderInfo](/zh-CN/api-reference/rtc/macos/class-recorderinfo)。
### 所属接口类 [#所属接口类-9]
- [AgoraMediaRecorderDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediarecorderobserver)
## mediaRecorder\:stateDidChanged\:uid\:state\:reason: [#mediarecorderstatedidchangeduidstatereason]
录制状态发生变化时的回调。
```objc
- (void)mediaRecorder:(AgoraMediaRecorder* _Nonnull)recorder stateDidChanged:(NSString * _Nonnull)channelId uid:(NSUInteger)uid state:(AgoraMediaRecorderState)state reason:(AgoraMediaRecorderReasonCode)reason;
```
:::info[自从]
自 v4.0.0 版本新增。
:::
### 触发时机 [#触发时机-1]
当音视频流的录制状态发生变化时触发。
### 参数 [#参数-8]
录制器实例。详见 [AgoraMediaRecorder](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediarecorder)。
频道名。
用户 ID。
当前的录制状态,详见 [AgoraMediaRecorderState](/zh-CN/api-reference/rtc/macos/enum-recorderstate)。
录制状态变化的原因,详见 [AgoraMediaRecorderReasonCode](/zh-CN/api-reference/rtc/macos/enum-recorderreasoncode)。
### 所属接口类 [#所属接口类-10]
- [AgoraMediaRecorderDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediarecorderobserver)