• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 使用OHAudio开发音频播放功能(C/C++)
2
3OHAudio是系统在API version 10中引入的一套C API，此API在设计上实现归一，同时支持普通音频通路和低时延通路。仅支持PCM格式，适用于依赖Native层实现音频输出功能的场景。
4
5OHAudio音频播放状态变化示意图：
6![OHAudioRenderer status change](figures/ohaudiorenderer-status-change.png)
7
8## 使用入门
9
10开发者要使用OHAudio提供的播放能力，需要添加对应的头文件。
11
12### 在 CMake 脚本中链接动态库
13
14``` cmake
15target_link_libraries(sample PUBLIC libohaudio.so)
16```
17
18### 添加头文件
19
20开发者通过引入<[native_audiostreambuilder.h](../../reference/apis-audio-kit/native__audiostreambuilder_8h.md)>和<[native_audiorenderer.h](../../reference/apis-audio-kit/native__audiorenderer_8h.md)>头文件，使用音频播放相关API。
21
22```cpp
23#include <ohaudio/native_audiorenderer.h>
24#include <ohaudio/native_audiostreambuilder.h>
25```
26
27## 音频流构造器
28
29OHAudio提供OH_AudioStreamBuilder接口，遵循构造器设计模式，用于构建音频流。开发者需要根据业务场景，指定对应的[OH_AudioStream_Type](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiostream_type) 。
30
31`OH_AudioStream_Type`包含两种类型：
32
33- AUDIOSTREAM_TYPE_RENDERER
34- AUDIOSTREAM_TYPE_CAPTURER
35
36使用[OH_AudioStreamBuilder_Create](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiostreambuilder_create)创建构造器示例：
37
38```
39OH_AudioStreamBuilder* builder;
40OH_AudioStreamBuilder_Create(&builder, streamType);
41```
42
43在音频业务结束之后，开发者应该执行[OH_AudioStreamBuilder_Destroy](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiostreambuilder_destroy)接口来销毁构造器。
44
45```
46OH_AudioStreamBuilder_Destroy(builder);
47```
48
49## 开发步骤及注意事项
50
51详细的API说明请参考[OHAudio API参考](../../reference/apis-audio-kit/_o_h_audio.md)。
52
53开发者可以通过以下几个步骤来实现一个简单的播放功能。
54
551. 创建构造器
56
57    ```c++
58    OH_AudioStreamBuilder* builder;
59    OH_AudioStreamBuilder_Create(&builder, AUDIOSTREAM_TYPE_RENDERER);
60    ```
61
622. 配置音频流参数
63
64    创建音频播放构造器后，可以设置音频流所需要的参数，可以参考下面的案例。
65
66    ```c++
67    // 设置音频采样率
68    OH_AudioStreamBuilder_SetSamplingRate(builder, 48000);
69    // 设置音频声道
70    OH_AudioStreamBuilder_SetChannelCount(builder, 2);
71    // 设置音频采样格式
72    OH_AudioStreamBuilder_SetSampleFormat(builder, AUDIOSTREAM_SAMPLE_S16LE);
73    // 设置音频流的编码类型
74    OH_AudioStreamBuilder_SetEncodingType(builder, AUDIOSTREAM_ENCODING_TYPE_RAW);
75    // 设置输出音频流的工作场景
76    OH_AudioStreamBuilder_SetRendererInfo(builder, AUDIOSTREAM_USAGE_MUSIC);
77    ```
78
79    注意，播放的音频数据要通过回调接口写入，开发者要实现回调接口，使用`OH_AudioStreamBuilder_SetRendererCallback`设置回调函数。回调函数的声明请查看[OH_AudioRenderer_Callbacks](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiorenderer_callbacks) 。
80
81
823. 设置音频回调函数
83
84    多音频并发处理可参考文档[处理音频焦点事件](audio-playback-concurrency.md)，仅接口语言差异。
85
86    ```c++
87    // 自定义写入数据函数
88    int32_t MyOnWriteData(
89        OH_AudioRenderer* renderer,
90        void* userData,
91        void* buffer,
92        int32_t length)
93    {
94        // 将待播放的数据，按length长度写入buffer
95        return 0;
96    }
97    // 自定义音频流事件函数
98    int32_t MyOnStreamEvent(
99        OH_AudioRenderer* renderer,
100        void* userData,
101        OH_AudioStream_Event event)
102    {
103        // 根据event表示的音频流事件信息，更新播放器状态和界面
104        return 0;
105    }
106    // 自定义音频中断事件函数
107    int32_t MyOnInterruptEvent(
108        OH_AudioRenderer* renderer,
109        void* userData,
110        OH_AudioInterrupt_ForceType type,
111        OH_AudioInterrupt_Hint hint)
112    {
113        // 根据type和hint表示的音频中断信息，更新播放器状态和界面
114        return 0;
115    }
116    // 自定义异常回调函数
117    int32_t MyOnError(
118        OH_AudioRenderer* renderer,
119        void* userData,
120        OH_AudioStream_Result error)
121    {
122        // 根据error表示的音频异常信息，做出相应的处理
123        return 0;
124    }
125
126    OH_AudioRenderer_Callbacks callbacks;
127
128    // 配置回调函数
129    callbacks.OH_AudioRenderer_OnWriteData = MyOnWriteData;
130    callbacks.OH_AudioRenderer_OnStreamEvent = MyOnStreamEvent;
131    callbacks.OH_AudioRenderer_OnInterruptEvent = MyOnInterruptEvent;
132    callbacks.OH_AudioRenderer_OnError = MyOnError;
133
134    //设置输出音频流的回调
135    OH_AudioStreamBuilder_SetRendererCallback(builder, callbacks, nullptr);
136    ```
137
138   为了避免不可预期的行为，在设置音频回调函数时，可以通过下面两种方式中的任意一种来设置音频回调函数：
139
140    - 请确保[OH_AudioRenderer_Callbacks](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiorenderer_callbacks)的每一个回调都被**自定义的回调方法**或**空指针**初始化。
141
142      ```c++
143      // 自定义写入数据函数
144      int32_t MyOnWriteData(
145          OH_AudioRenderer* renderer,
146          void* userData,
147          void* buffer,
148          int32_t length)
149      {
150          // 将待播放的数据，按length长度写入buffer
151          return 0;
152      }
153      // 自定义音频中断事件函数
154      int32_t MyOnInterruptEvent(
155          OH_AudioRenderer* renderer,
156          void* userData,
157          OH_AudioInterrupt_ForceType type,
158          OH_AudioInterrupt_Hint hint)
159      {
160          // 根据type和hint表示的音频中断信息，更新播放器状态和界面
161          return 0;
162      }
163
164      OH_AudioRenderer_Callbacks callbacks;
165
166      // 配置回调函数，如果需要监听，则赋值
167      callbacks.OH_AudioRenderer_OnWriteData = MyOnWriteData;
168      callbacks.OH_AudioRenderer_OnInterruptEvent = MyOnInterruptEvent;
169
170      // （必选）如果不需要监听，使用空指针初始化
171      callbacks.OH_AudioRenderer_OnStreamEvent = nullptr;
172      callbacks.OH_AudioRenderer_OnError = nullptr;
173      ```
174
175    - 使用前，初始化并清零结构体。
176
177      ```c++
178      // 自定义写入数据函数
179      int32_t MyOnWriteData(
180          OH_AudioRenderer* renderer,
181          void* userData,
182          void* buffer,
183          int32_t length)
184      {
185          // 将待播放的数据，按length长度写入buffer
186          return 0;
187      }
188      // 自定义音频中断事件函数
189      int32_t MyOnInterruptEvent(
190          OH_AudioRenderer* renderer,
191          void* userData,
192          OH_AudioInterrupt_ForceType type,
193          OH_AudioInterrupt_Hint hint)
194      {
195          // 根据type和hint表示的音频中断信息，更新播放器状态和界面
196          return 0;
197      }
198      OH_AudioRenderer_Callbacks callbacks;
199
200      // 使用前，初始化并清零结构体
201      memset(&callbacks, 0, sizeof(OH_AudioRenderer_Callbacks));
202
203      // 配置需要的回调函数
204      callbacks.OH_AudioRenderer_OnWriteData = MyOnWriteData;
205      callbacks.OH_AudioRenderer_OnInterruptEvent = MyOnInterruptEvent;
206      ```
207
2084. 构造播放音频流
209
210    ```c++
211    OH_AudioRenderer* audioRenderer;
212    OH_AudioStreamBuilder_GenerateRenderer(builder, &audioRenderer);
213    ```
214
2155. 使用音频流
216
217    音频流包含下面接口，用来实现对音频流的控制。
218
219    | 接口                                                         | 说明         |
220    | ------------------------------------------------------------ | ------------ |
221    | OH_AudioStream_Result OH_AudioRenderer_Start(OH_AudioRenderer* renderer) | 开始播放     |
222    | OH_AudioStream_Result OH_AudioRenderer_Pause(OH_AudioRenderer* renderer) | 暂停播放     |
223    | OH_AudioStream_Result OH_AudioRenderer_Stop(OH_AudioRenderer* renderer) | 停止播放     |
224    | OH_AudioStream_Result OH_AudioRenderer_Flush(OH_AudioRenderer* renderer) | 释放缓存数据 |
225    | OH_AudioStream_Result OH_AudioRenderer_Release(OH_AudioRenderer* renderer) | 释放播放实例 |
226
2276. 释放构造器
228
229    构造器不再使用时，需要释放相关资源。
230
231    ```c++
232    OH_AudioStreamBuilder_Destroy(builder);
233    ```
234
235## 设置低时延模式
236
237当设备支持低时延通路时，开发者可以使用低时延模式创建播放器，获得更高质量的音频体验。
238
239开发流程与普通播放场景一致，仅需要在创建音频流构造器时，调用[OH_AudioStreamBuilder_SetLatencyMode()](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiostreambuilder_setlatencymode)设置低时延模式。
240
241开发示例
242
243```C
244OH_AudioStreamBuilder_SetLatencyMode(builder, AUDIOSTREAM_LATENCY_MODE_FAST);
245```
246
247## 设置音频声道布局
248
249播放音频文件时，可以通过设置音频的声道布局信息，指定渲染或播放时的扬声器摆位，使得渲染和播放效果更佳，获得更高质量的音频体验。
250
251开发流程与普通播放场景一致，仅需要在创建音频流构造器时，调用[OH_AudioStreamBuilder_SetChannelLayout()](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiostreambuilder_setchannellayout)设置声道布局信息。
252
253当声道布局与声道数不匹配时，创建音频流会失败。建议在设置声道布局时，确认下发的声道布局信息是正确的。
254
255如果不知道准确的声道布局信息，或者开发者需要使用默认声道布局，可以不调用设置声道布局接口，或者下发CH_LAYOUT_UNKNOWN，以使用基于声道数的默认声道布局。
256
257对于HOA格式的音频，想要获得正确的渲染和播放效果，必须指定声道布局信息。
258
259开发示例
260
261```C
262OH_AudioStreamBuilder_SetChannelLayout(builder, CH_LAYOUT_STEREO);
263```
264
265## 播放AudioVivid格式音源
266
267播放AudioVivid格式音频文件时，需要使用与普通播放不同的数据写入回调函数，该回调可以同时写入PCM数据与元数据。
268
269开发流程与普通播放场景一致，仅需要在创建音频流构造器时，调用[OH_AudioStreamBuilder_SetWriteDataWithMetadataCallback()](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiostreambuilder_setwritedatawithmetadatacallback)设置PCM数据与元数据同时写入的回调函数，同时调用[OH_AudioStreamBuilder_SetEncodingType()](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiostreambuilder_setencodingtype)设置编码类型为AUDIOSTREAM_ENCODING_TYPE_AUDIOVIVID。
270
271在播放AudioVivid时，帧长是固定的，不可通过[OH_AudioStreamBuilder_SetFrameSizeInCallback()](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiostreambuilder_setframesizeincallback)设置回调帧长。同时，在设置播放声道数和声道布局时，需要将写入音源的声床数和对象数相加后进行设置。
272
273开发示例
274
275```C
276// 自定义同时写入PCM数据和元数据函数
277int32_t MyOnWriteDataWithMetadata(
278    OH_AudioRenderer* renderer,
279    void* userData,
280    void* audioData,
281    int32_t audioDataSize,
282    void* metadata,
283    int32_t metadataSize)
284{
285    // 将待播放的PCM数据和元数据，分别按audioDataSize和metadataSize写入buffer
286    return 0;
287}
288
289// 设置编码类型
290OH_AudioStreamBuilder_SetEncodingType(builder, AUDIOSTREAM_ENCODING_TYPE_AUDIOVIVID);
291// 配置回调函数
292OH_AudioRenderer_WriteDataWithMetadataCallback metadataCallback = MyOnWriteDataWithMetadata;
293// 设置同时写入PCM数据和元数据的回调
294OH_AudioStreamBuilder_SetWriteDataWithMetadataCallback(builder, metadataCallback, nullptr);
295```
296
297## 相关实例
298
299针对OHAudio开发音频播放，有以下相关实例可供参考：
300
301- [OHAudio录制和播放](https://gitee.com/openharmony/applications_app_samples/tree/OpenHarmony-5.0.1-Release/code/DocsSample/Media/Audio/OHAudio)
302
303<!--RP1-->
304<!--RP1End-->