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