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
5## Prerequisites
6
7To use the playback or recording capability of **OHAudio**, you must first import the corresponding header files.
8
9### Linking the Dynamic Library in the CMake Script
10
11``` cmake
12target_link_libraries(sample PUBLIC libohaudio.so)
13```
14### Adding Header Files
15To 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)>.
16
17```cpp
18#include <ohaudio/native_audiocapturer.h>
19#include <ohaudio/native_audiostreambuilder.h>
20```
21## Audio Stream Builder
22
23**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.
24
25**OH_AudioStream_Type** can be set to either of the following:
26
27- AUDIOSTREAM_TYPE_RENDERER
28- AUDIOSTREAM_TYPE_CAPTURER
29
30The 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:
31
32```
33OH_AudioStreamBuilder* builder;
34OH_AudioStreamBuilder_Create(&builder, streamType);
35```
36
37After the audio service is complete, call [OH_AudioStreamBuilder_Destroy](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiostreambuilder_destroy) to destroy the builder.
38
39```
40OH_AudioStreamBuilder_Destroy(builder);
41```
42
43## How to Develop
44
45Read [OHAudio](../../reference/apis-audio-kit/_o_h_audio.md) for the API reference.
46
47The following walks you through how to implement simple recording:
48
49
501. Create an audio stream builder.
51
52    ```c++
53    OH_AudioStreamBuilder* builder;
54    OH_AudioStreamBuilder_Create(&builder, AUDIOSTREAM_TYPE_CAPTURER);
55    ```
56
572. Set audio stream parameters.
58
59    After creating the builder for audio recording, set the parameters required.
60
61    ```c++
62    // Set the audio sampling rate.
63    OH_AudioStreamBuilder_SetSamplingRate(builder, 48000);
64    // Set the number of audio channels.
65    OH_AudioStreamBuilder_SetChannelCount(builder, 2);
66    // Set the audio sampling format.
67    OH_AudioStreamBuilder_SetSampleFormat(builder, AUDIOSTREAM_SAMPLE_S16LE);
68    // Set the encoding type of the audio stream.
69    OH_AudioStreamBuilder_SetEncodingType(builder, AUDIOSTREAM_ENCODING_TYPE_RAW);
70    // Set the usage scenario of the audio capturer.
71    OH_AudioStreamBuilder_SetCapturerInfo(builder, AUDIOSTREAM_SOURCE_TYPE_MIC);
72    ```
73
74    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).
75
763. Set the callback functions.
77
78    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.
79
80    ```c++
81    // Customize a data writing function.
82    int32_t MyOnReadData(
83        OH_AudioCapturer* capturer,
84        void* userData,
85        void* buffer,
86        int32_t length)
87    {
88        // Obtain the recording data of the specified length from the buffer.
89        return 0;
90    }
91    // Customize an audio stream event function.
92    int32_t MyOnStreamEvent(
93        OH_AudioCapturer* capturer,
94        void* userData,
95        OH_AudioStream_Event event)
96    {
97        // Update the player status and UI based on the audio stream event information indicated by the event.
98        return 0;
99    }
100    // Customize an audio interruption event function.
101    int32_t MyOnInterruptEvent(
102        OH_AudioCapturer* capturer,
103        void* userData,
104        OH_AudioInterrupt_ForceType type,
105        OH_AudioInterrupt_Hint hint)
106    {
107        // Update the capturer status and UI based on the audio interruption information indicated by type and hint.
108        return 0;
109    }
110    // Customize an exception callback function.
111    int32_t MyOnError(
112        OH_AudioCapturer* capturer,
113        void* userData,
114        OH_AudioStream_Result error)
115    {
116        // Perform operations based on the audio exception information indicated by error.
117        return 0;
118    }
119
120    OH_AudioCapturer_Callbacks callbacks;
121    // Set the callbacks.
122    callbacks.OH_AudioCapturer_OnReadData = MyOnReadData;
123    callbacks.OH_AudioCapturer_OnStreamEvent = MyOnStreamEvent;
124    callbacks.OH_AudioCapturer_OnInterruptEvent = MyOnInterruptEvent;
125    callbacks.OH_AudioCapturer_OnError = MyOnError;
126
127    // Set the callbacks for audio input streams.
128    OH_AudioStreamBuilder_SetCapturerCallback(builder, callbacks, nullptr);
129    ```
130
131    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.
132
133    ```c++
134    // Customize a data writing function.
135    int32_t MyOnReadData(
136        OH_AudioCapturer* capturer,
137        void* userData,
138        void* buffer,
139        int32_t length)
140    {
141        // Obtain the recording data of the specified length from the buffer.
142        return 0;
143    }
144    // Customize an audio interruption event function.
145    int32_t MyOnInterruptEvent(
146        OH_AudioCapturer* capturer,
147        void* userData,
148        OH_AudioInterrupt_ForceType type,
149        OH_AudioInterrupt_Hint hint)
150    {
151        // Update the capturer status and UI based on the audio interruption information indicated by type and hint.
152        return 0;
153    }
154    OH_AudioCapturer_Callbacks callbacks;
155
156    // Configure a callback function. If listening is required, assign a value.
157    callbacks.OH_AudioCapturer_OnReadData = MyOnReadData;
158    callbacks.OH_AudioCapturer_OnInterruptEvent = MyOnInterruptEvent;
159
160    // (Mandatory) If listening is not required, use a null pointer for initialization.
161    callbacks.OH_AudioCapturer_OnStreamEvent = nullptr;
162    callbacks.OH_AudioCapturer_OnError = nullptr;
163    ```
164
1654. Create an audio capturer instance.
166
167    ```c++
168    OH_AudioCapturer* audioCapturer;
169    OH_AudioStreamBuilder_GenerateCapturer(builder, &audioCapturer);
170    ```
171
1725. Use the audio capturer.
173
174    You can use the APIs listed below to control the audio streams.
175
176    | API                                                        | Description        |
177    | ------------------------------------------------------------ | ------------ |
178    | OH_AudioStream_Result OH_AudioCapturer_Start(OH_AudioCapturer* capturer) | Starts the audio capturer.    |
179    | OH_AudioStream_Result OH_AudioCapturer_Pause(OH_AudioCapturer* capturer) | Pauses the audio capturer.    |
180    | OH_AudioStream_Result OH_AudioCapturer_Stop(OH_AudioCapturer* capturer) | Stops the audio capturer.    |
181    | OH_AudioStream_Result OH_AudioCapturer_Flush(OH_AudioCapturer* capturer) | Flushes obtained audio data.|
182    | OH_AudioStream_Result OH_AudioCapturer_Release(OH_AudioCapturer* capturer) | Releases the audio capturer instance.|
183
1846. Destroy the audio stream builder.
185
186    When the builder is no longer used, release related resources.
187
188    ```c++
189    OH_AudioStreamBuilder_Destroy(builder);
190    ```
191
192## Setting the Low Latency Mode
193
194If 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.
195
196The 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.
197
198Code snippet:
199
200```C
201OH_AudioStream_LatencyMode latencyMode = AUDIOSTREAM_LATENCY_MODE_FAST;
202OH_AudioStreamBuilder_SetLatencyMode(builder, latencyMode);
203```
204