• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 使用OHAudio开发音频录制功能(C/C++)
2
3OHAudio是系统在API version 10中引入的一套C API，此API在设计上实现归一，同时支持普通音频通路和低时延通路。仅支持PCM格式，适用于依赖Native层实现音频输入功能的场景。
4
5OHAudio音频录制状态变化示意图：
6![OHAudioCapturer status change](figures/ohaudiocapturer-status-change.png)
7
8## 使用入门
9
10开发者要使用OHAudio提供的录制能力，需要添加对应的头文件。
11
12### 在 CMake 脚本中链接动态库
13
14``` cmake
15target_link_libraries(sample PUBLIC libohaudio.so)
16```
17### 添加头文件
18开发者通过引入<[native_audiostreambuilder.h](../../reference/apis-audio-kit/native__audiostreambuilder_8h.md)>和<[native_audiocapturer.h](../../reference/apis-audio-kit/native__audiocapturer_8h.md)>头文件，使用音频录制相关API。
19
20```cpp
21#include <ohaudio/native_audiocapturer.h>
22#include <ohaudio/native_audiostreambuilder.h>
23```
24## 音频流构造器
25
26OHAudio提供OH_AudioStreamBuilder接口，遵循构造器设计模式，用于构建音频流。开发者需要根据业务场景，指定对应的[OH_AudioStream_Type](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiostream_type)。
27
28`OH_AudioStream_Type`包含两种类型：
29
30- AUDIOSTREAM_TYPE_RENDERER
31- AUDIOSTREAM_TYPE_CAPTURER
32
33使用[OH_AudioStreamBuilder_Create](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiostreambuilder_create)创建构造器示例：
34
35```cpp
36OH_AudioStreamBuilder* builder;
37OH_AudioStreamBuilder_Create(&builder, streamType);
38```
39
40在音频业务结束之后，开发者应该执行[OH_AudioStreamBuilder_Destroy](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiostreambuilder_destroy)接口来销毁构造器。
41
42```cpp
43OH_AudioStreamBuilder_Destroy(builder);
44```
45
46## 开发步骤及注意事项
47
48详细的API说明请参考[OHAudio API参考](../../reference/apis-audio-kit/_o_h_audio.md)。
49
50开发者可以通过以下几个步骤来实现一个简单的录制功能。
51
521. 创建构造器。
53
54    ```cpp
55    OH_AudioStreamBuilder* builder;
56    OH_AudioStreamBuilder_Create(&builder, AUDIOSTREAM_TYPE_CAPTURER);
57    ```
58
592. 配置音频流参数。
60
61    创建音频录制构造器后，可以设置音频流所需要的参数，可以参考下面的案例。
62
63    ```cpp
64    // 设置音频采样率。
65    OH_AudioStreamBuilder_SetSamplingRate(builder, 48000);
66    // 设置音频声道。
67    OH_AudioStreamBuilder_SetChannelCount(builder, 2);
68    // 设置音频采样格式。
69    OH_AudioStreamBuilder_SetSampleFormat(builder, AUDIOSTREAM_SAMPLE_S16LE);
70    // 设置音频流的编码类型。
71    OH_AudioStreamBuilder_SetEncodingType(builder, AUDIOSTREAM_ENCODING_TYPE_RAW);
72    // 设置输入音频流的工作场景。
73    OH_AudioStreamBuilder_SetCapturerInfo(builder, AUDIOSTREAM_SOURCE_TYPE_MIC);
74    ```
75
76    同样，音频录制的音频数据要通过回调接口读入，开发者要实现回调接口，使用`OH_AudioStreamBuilder_SetCapturerCallback`设置回调函数。回调函数的声明请查看[OH_AudioCapturer_Callbacks](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiocapturer_callbacks)。
77
783. 设置音频回调函数。
79
80    多音频并发处理可参考文档[处理音频焦点事件](audio-playback-concurrency.md)，仅接口语言差异。
81
82    ```cpp
83    // 自定义读入数据函数。
84    int32_t MyOnReadData(
85        OH_AudioCapturer* capturer,
86        void* userData,
87        void* buffer,
88        int32_t length)
89    {
90        // 从buffer中取出length长度的录音数据。
91        return 0;
92    }
93    // 自定义音频流事件函数。
94    int32_t MyOnStreamEvent(
95        OH_AudioCapturer* capturer,
96        void* userData,
97        OH_AudioStream_Event event)
98    {
99        // 根据event表示的音频流事件信息，更新播放器状态和界面。
100        return 0;
101    }
102    // 自定义音频中断事件函数。
103    int32_t MyOnInterruptEvent(
104        OH_AudioCapturer* capturer,
105        void* userData,
106        OH_AudioInterrupt_ForceType type,
107        OH_AudioInterrupt_Hint hint)
108    {
109        // 根据type和hint表示的音频中断信息，更新录制器状态和界面。
110        return 0;
111    }
112    // 自定义异常回调函数。
113    int32_t MyOnError(
114        OH_AudioCapturer* capturer,
115        void* userData,
116        OH_AudioStream_Result error)
117    {
118        // 根据error表示的音频异常信息，做出相应的处理。
119        return 0;
120    }
121
122    OH_AudioCapturer_Callbacks callbacks;
123
124    // 配置回调函数。
125    callbacks.OH_AudioCapturer_OnReadData = MyOnReadData;
126    callbacks.OH_AudioCapturer_OnStreamEvent = MyOnStreamEvent;
127    callbacks.OH_AudioCapturer_OnInterruptEvent = MyOnInterruptEvent;
128    callbacks.OH_AudioCapturer_OnError = MyOnError;
129
130    // 设置音频输入流的回调。
131    OH_AudioStreamBuilder_SetCapturerCallback(builder, callbacks, nullptr);
132    ```
133
134    为了避免不可预期的行为，在设置音频回调函数时，可以通过下面两种方式中的任意一种来设置音频回调函数：
135
136    - 请确保[OH_AudioCapturer_Callbacks](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiocapturer_callbacks)的每一个回调都被**自定义的回调方法**或**空指针**初始化。
137
138      ```cpp
139      // 自定义读入数据函数。
140      int32_t MyOnReadData(
141          OH_AudioCapturer* capturer,
142          void* userData,
143          void* buffer,
144          int32_t length)
145      {
146          // 从buffer中取出length长度的录音数据。
147          return 0;
148      }
149      // 自定义音频中断事件函数。
150      int32_t MyOnInterruptEvent(
151          OH_AudioCapturer* capturer,
152          void* userData,
153          OH_AudioInterrupt_ForceType type,
154          OH_AudioInterrupt_Hint hint)
155      {
156          // 根据type和hint表示的音频中断信息，更新录制器状态和界面。
157          return 0;
158      }
159      OH_AudioCapturer_Callbacks callbacks;
160
161      // 配置回调函数，如果需要监听，则赋值。
162      callbacks.OH_AudioCapturer_OnReadData = MyOnReadData;
163      callbacks.OH_AudioCapturer_OnInterruptEvent = MyOnInterruptEvent;
164
165      // （必选）如果不需要监听，使用空指针初始化。
166      callbacks.OH_AudioCapturer_OnStreamEvent = nullptr;
167      callbacks.OH_AudioCapturer_OnError = nullptr;
168      ```
169
170    - 使用前，初始化并清零结构体。
171
172      ```cpp
173      // 自定义读入数据函数。
174      int32_t MyOnReadData(
175          OH_AudioCapturer* capturer,
176          void* userData,
177          void* buffer,
178          int32_t length)
179      {
180          // 从buffer中取出length长度的录音数据。
181          return 0;
182      }
183      // 自定义音频中断事件函数。
184      int32_t MyOnInterruptEvent(
185          OH_AudioCapturer* capturer,
186          void* userData,
187          OH_AudioInterrupt_ForceType type,
188          OH_AudioInterrupt_Hint hint)
189      {
190          // 根据type和hint表示的音频中断信息，更新录制器状态和界面。
191          return 0;
192      }
193      OH_AudioCapturer_Callbacks callbacks;
194
195      // 使用前，初始化并清零结构体。
196      memset(&callbacks, 0, sizeof(OH_AudioCapturer_Callbacks));
197
198      // 配置需要的回调函数。
199      callbacks.OH_AudioCapturer_OnReadData = MyOnReadData;
200      callbacks.OH_AudioCapturer_OnInterruptEvent = MyOnInterruptEvent;
201      ```
202
2034. 构造录制音频流。
204
205    ```cpp
206    OH_AudioCapturer* audioCapturer;
207    OH_AudioStreamBuilder_GenerateCapturer(builder, &audioCapturer);
208    ```
209
2105. 使用音频流。
211
212    录制音频流包含下面接口，用来实现对音频流的控制。
213
214    | 接口                                                         | 说明         |
215    | ------------------------------------------------------------ | ------------ |
216    | OH_AudioStream_Result OH_AudioCapturer_Start(OH_AudioCapturer* capturer) | 开始录制。    |
217    | OH_AudioStream_Result OH_AudioCapturer_Pause(OH_AudioCapturer* capturer) | 暂停录制。     |
218    | OH_AudioStream_Result OH_AudioCapturer_Stop(OH_AudioCapturer* capturer) | 停止录制。     |
219    | OH_AudioStream_Result OH_AudioCapturer_Flush(OH_AudioCapturer* capturer) | 释放缓存数据。 |
220    | OH_AudioStream_Result OH_AudioCapturer_Release(OH_AudioCapturer* capturer) | 释放录制实例。 |
221
2226. 释放构造器。
223
224    构造器不再使用时，需要释放相关资源。
225
226    ```cpp
227    OH_AudioStreamBuilder_Destroy(builder);
228    ```
229
230## 设置低时延模式
231
232当设备支持低时延通路时，开发者可以使用低时延模式创建音频录制构造器，获得更高质量的音频体验。
233
234开发流程与普通录制场景一致，仅需要在创建音频录制构造器时，调用[OH_AudioStreamBuilder_SetLatencyMode()](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiostreambuilder_setlatencymode)设置低时延模式。
235
236> **注意：**
237> 当音频录制场景[OH_AudioStream_SourceType](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiostream_sourcetype)为`AUDIOSTREAM_SOURCE_TYPE_VOICE_COMMUNICATION`时，不支持主动设置低时延模式，系统会根据设备的能力，决策输出的音频通路。
238
239开发示例
240
241```cpp
242OH_AudioStream_LatencyMode latencyMode = AUDIOSTREAM_LATENCY_MODE_FAST;
243OH_AudioStreamBuilder_SetLatencyMode(builder, latencyMode);
244```
245
246## 相关实例
247
248针对OHAudio开发音频录制，有以下相关实例可供参考：
249
250- [OHAudio录制和播放](https://gitee.com/openharmony/applications_app_samples/tree/master/code/DocsSample/Media/Audio/OHAudio)
251
252<!--RP1-->
253<!--RP1End-->