• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Using OHAudio for Audio Recording (C/C++)
2
3**OHAudio** is a set of C APIs introduced in API version 10. These APIs are normalized in design and support both common and low-latency audio channels. They support the PCM format only. They are suitable for playback applications that implement audio input at the native layer.
4
5OHAudio audio recording state transition
6
7![OHAudioCapturer status change](figures/ohaudiocapturer-status-change.png)
8
9## Prerequisites
10
11To use the recording capability of **OHAudio**, you must first import the corresponding header files.
12
13### Linking the Dynamic Library in the CMake Script
14
15``` cmake
16target_link_libraries(sample PUBLIC libohaudio.so)
17```
18### Adding Header Files
19To use APIs for audio recording, import <[native_audiostreambuilder.h](../../reference/apis-audio-kit/native__audiostreambuilder_8h.md)> and <[native_audiocapturer.h](../../reference/apis-audio-kit/native__audiocapturer_8h.md)>.
20
21```cpp
22#include <ohaudio/native_audiocapturer.h>
23#include <ohaudio/native_audiostreambuilder.h>
24```
25## Audio Stream Builder
26
27**OHAudio** provides the **OH_AudioStreamBuilder** class, which complies with the builder design pattern and is used to build audio streams. You need to specify [OH_AudioStream_Type](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiostream_type) based on your service scenarios.
28
29**OH_AudioStream_Type** can be set to either of the following:
30
31- AUDIOSTREAM_TYPE_RENDERER
32- AUDIOSTREAM_TYPE_CAPTURER
33
34The following code snippet shows how to use [OH_AudioStreamBuilder_Create](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiostreambuilder_create) to create a builder:
35
36```
37OH_AudioStreamBuilder* builder;
38OH_AudioStreamBuilder_Create(&builder, streamType);
39```
40
41After the audio service is complete, call [OH_AudioStreamBuilder_Destroy](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiostreambuilder_destroy) to destroy the builder.
42
43```
44OH_AudioStreamBuilder_Destroy(builder);
45```
46
47## How to Develop
48
49Read [OHAudio](../../reference/apis-audio-kit/_o_h_audio.md) for the API reference.
50
51The following walks you through how to implement simple recording:
52
53
541. Create an audio stream builder.
55
56    ```c++
57    OH_AudioStreamBuilder* builder;
58    OH_AudioStreamBuilder_Create(&builder, AUDIOSTREAM_TYPE_CAPTURER);
59    ```
60
612. Set audio stream parameters.
62
63    After creating the builder for audio recording, set the parameters required.
64
65    ```c++
66    // Set the audio sampling rate.
67    OH_AudioStreamBuilder_SetSamplingRate(builder, 48000);
68    // Set the number of audio channels.
69    OH_AudioStreamBuilder_SetChannelCount(builder, 2);
70    // Set the audio sampling format.
71    OH_AudioStreamBuilder_SetSampleFormat(builder, AUDIOSTREAM_SAMPLE_S16LE);
72    // Set the encoding type of the audio stream.
73    OH_AudioStreamBuilder_SetEncodingType(builder, AUDIOSTREAM_ENCODING_TYPE_RAW);
74    // Set the usage scenario of the audio capturer.
75    OH_AudioStreamBuilder_SetCapturerInfo(builder, AUDIOSTREAM_SOURCE_TYPE_MIC);
76    ```
77
78    Note that the audio data to record is written through callbacks. You must call **OH_AudioStreamBuilder_SetCapturerCallback** to implement the callbacks. For details about the declaration of the callback functions, see [OH_AudioCapturer_Callbacks](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiocapturer_callbacks).
79
803. Set the callback functions.
81
82    For details about concurrent processing of multiple audio streams, see [Processing Audio Interruption Events](audio-playback-concurrency.md). The procedure is similar, and the only difference is the API programming language in use.
83
84    ```c++
85    // Customize a data writing function.
86    int32_t MyOnReadData(
87        OH_AudioCapturer* capturer,
88        void* userData,
89        void* buffer,
90        int32_t length)
91    {
92        // Obtain the recording data of the specified length from the buffer.
93        return 0;
94    }
95    // Customize an audio stream event function.
96    int32_t MyOnStreamEvent(
97        OH_AudioCapturer* capturer,
98        void* userData,
99        OH_AudioStream_Event event)
100    {
101        // Update the player status and UI based on the audio stream event information indicated by the event.
102        return 0;
103    }
104    // Customize an audio interruption event function.
105    int32_t MyOnInterruptEvent(
106        OH_AudioCapturer* capturer,
107        void* userData,
108        OH_AudioInterrupt_ForceType type,
109        OH_AudioInterrupt_Hint hint)
110    {
111        // Update the capturer status and UI based on the audio interruption information indicated by type and hint.
112        return 0;
113    }
114    // Customize an exception callback function.
115    int32_t MyOnError(
116        OH_AudioCapturer* capturer,
117        void* userData,
118        OH_AudioStream_Result error)
119    {
120        // Perform operations based on the audio exception information indicated by error.
121        return 0;
122    }
123
124    OH_AudioCapturer_Callbacks callbacks;
125    // Set the callbacks.
126    callbacks.OH_AudioCapturer_OnReadData = MyOnReadData;
127    callbacks.OH_AudioCapturer_OnStreamEvent = MyOnStreamEvent;
128    callbacks.OH_AudioCapturer_OnInterruptEvent = MyOnInterruptEvent;
129    callbacks.OH_AudioCapturer_OnError = MyOnError;
130
131    // Set the callbacks for audio input streams.
132    OH_AudioStreamBuilder_SetCapturerCallback(builder, callbacks, nullptr);
133    ```
134
135    To avoid unexpected behavior, ensure that each callback of [OH_AudioCapturer_Callbacks](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiocapturer_callbacks) is initialized by a custom callback method or null pointer when being set.
136
137    ```c++
138    // Customize a data writing function.
139    int32_t MyOnReadData(
140        OH_AudioCapturer* capturer,
141        void* userData,
142        void* buffer,
143        int32_t length)
144    {
145        // Obtain the recording data of the specified length from the buffer.
146        return 0;
147    }
148    // Customize an audio interruption event function.
149    int32_t MyOnInterruptEvent(
150        OH_AudioCapturer* capturer,
151        void* userData,
152        OH_AudioInterrupt_ForceType type,
153        OH_AudioInterrupt_Hint hint)
154    {
155        // Update the capturer status and UI based on the audio interruption information indicated by type and hint.
156        return 0;
157    }
158    OH_AudioCapturer_Callbacks callbacks;
159
160    // Configure a callback function. If listening is required, assign a value.
161    callbacks.OH_AudioCapturer_OnReadData = MyOnReadData;
162    callbacks.OH_AudioCapturer_OnInterruptEvent = MyOnInterruptEvent;
163
164    // (Mandatory) If listening is not required, use a null pointer for initialization.
165    callbacks.OH_AudioCapturer_OnStreamEvent = nullptr;
166    callbacks.OH_AudioCapturer_OnError = nullptr;
167    ```
168
1694. Create an audio capturer instance.
170
171    ```c++
172    OH_AudioCapturer* audioCapturer;
173    OH_AudioStreamBuilder_GenerateCapturer(builder, &audioCapturer);
174    ```
175
1765. Use the audio capturer.
177
178    You can use the APIs listed below to control the audio streams.
179
180    | API                                                        | Description        |
181    | ------------------------------------------------------------ | ------------ |
182    | OH_AudioStream_Result OH_AudioCapturer_Start(OH_AudioCapturer* capturer) | Starts the audio capturer.    |
183    | OH_AudioStream_Result OH_AudioCapturer_Pause(OH_AudioCapturer* capturer) | Pauses the audio capturer.    |
184    | OH_AudioStream_Result OH_AudioCapturer_Stop(OH_AudioCapturer* capturer) | Stops the audio capturer.    |
185    | OH_AudioStream_Result OH_AudioCapturer_Flush(OH_AudioCapturer* capturer) | Flushes obtained audio data.|
186    | OH_AudioStream_Result OH_AudioCapturer_Release(OH_AudioCapturer* capturer) | Releases the audio capturer instance.|
187
1886. Destroy the audio stream builder.
189
190    When the builder is no longer used, release related resources.
191
192    ```c++
193    OH_AudioStreamBuilder_Destroy(builder);
194    ```
195
196## Setting the Low Latency Mode
197
198If the device supports the low-latency channel, you can use the low-latency mode to create an audio capturer for a higher-quality audio experience.
199
200The development process is similar to that in the common recording scenario. The only difference is that you need to set the low delay mode by calling [OH_AudioStreamBuilder_SetLatencyMode()](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiostreambuilder_setlatencymode) when creating an audio stream builder.
201
202Code snippet:
203
204```C
205OH_AudioStream_LatencyMode latencyMode = AUDIOSTREAM_LATENCY_MODE_FAST;
206OH_AudioStreamBuilder_SetLatencyMode(builder, latencyMode);
207```
208<!--RP1-->
209<!--RP1End-->
210