1 /* 2 * Copyright (c) 2023 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup OHAudio 18 * @{ 19 * 20 * @brief Provide the definition of the C interface for the audio module. 21 * 22 * @syscap SystemCapability.Multimedia.Audio.Core 23 * 24 * @since 10 25 * @version 1.0 26 */ 27 28 /** 29 * @file native_audiocapturer.h 30 * 31 * @brief Declare audio stream related interfaces for input type. 32 * 33 * @syscap SystemCapability.Multimedia.Audio.Core 34 * @since 10 35 * @version 1.0 36 */ 37 38 #ifndef NATIVE_AUDIOCAPTURER_H 39 #define NATIVE_AUDIOCAPTURER_H 40 41 #include <time.h> 42 #include "native_audiostream_base.h" 43 #include "native_audio_device_base.h" 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 /* 48 * Request to release the capturer stream. 49 * 50 * @since 10 51 * @permission ohos.permission.MICROPHONE 52 * 53 * @param capturer reference created by OH_AudioStreamBuilder_GenerateCapturer() 54 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 55 */ 56 OH_AudioStream_Result OH_AudioCapturer_Release(OH_AudioCapturer* capturer); 57 58 /* 59 * Request to start the capturer stream. 60 * 61 * @since 10 62 * @permission ohos.permission.MICROPHONE 63 * 64 * @param capturer reference created by OH_AudioStreamBuilder_GenerateCapturer() 65 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 66 */ 67 OH_AudioStream_Result OH_AudioCapturer_Start(OH_AudioCapturer* capturer); 68 69 /* 70 * Request to pause the capturer stream. 71 * 72 * @since 10 73 * @permission ohos.permission.MICROPHONE 74 * 75 * @param capturer reference created by OH_AudioStreamBuilder_GenerateCapturer() 76 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 77 */ 78 OH_AudioStream_Result OH_AudioCapturer_Pause(OH_AudioCapturer* capturer); 79 80 /* 81 * Request to stop the capturer stream. 82 * 83 * @since 10 84 * @permission ohos.permission.MICROPHONE 85 * 86 * @param capturer reference created by OH_AudioStreamBuilder_GenerateCapturer() 87 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 88 */ 89 OH_AudioStream_Result OH_AudioCapturer_Stop(OH_AudioCapturer* capturer); 90 91 /* 92 * Request to flush the capturer stream. 93 * 94 * @since 10 95 * 96 * @param capturer reference created by OH_AudioStreamBuilder_GenerateCapturer() 97 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 98 */ 99 OH_AudioStream_Result OH_AudioCapturer_Flush(OH_AudioCapturer* capturer); 100 101 /* 102 * Query the current state of the capturer client. 103 * 104 * This function will return the capturer state without updating the state. 105 * 106 * @since 10 107 * 108 * @param capturer Reference created by OH_AudioStreamBuilder_GenerateCapturer() 109 * @param state Pointer to a variable that will be set for the state value. 110 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 111 */ 112 OH_AudioStream_Result OH_AudioCapturer_GetCurrentState(OH_AudioCapturer* capturer, OH_AudioStream_State* state); 113 114 /* 115 * Query the latency mode of the capturer client. 116 * 117 * @since 10 118 * 119 * @param capturer Reference created by OH_AudioStreamBuilder_GenerateCapturer() 120 * @param latencyMode Pointer to a variable that will be set for the latency mode. 121 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 122 */ 123 OH_AudioStream_Result OH_AudioCapturer_GetLatencyMode(OH_AudioCapturer* capturer, 124 OH_AudioStream_LatencyMode* latencyMode); 125 126 /* 127 * Query the stream id of the capturer client. 128 * 129 * @since 10 130 * 131 * @param capturer Reference created by OH_AudioStreamBuilder_GenerateCapturer() 132 * @param stramId Pointer to a variable that will be set for the stream id. 133 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 134 */ 135 OH_AudioStream_Result OH_AudioCapturer_GetStreamId(OH_AudioCapturer* capturer, uint32_t* streamId); 136 137 /* 138 * Query the sample rate value of the capturer client. 139 * 140 * This function will return the capturer sample rate value without updating the state. 141 * 142 * @since 10 143 * 144 * @param capturer Reference created by OH_AudioStreamBuilder_GenerateCapturer() 145 * @param rate The state value to be updated 146 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 147 */ 148 OH_AudioStream_Result OH_AudioCapturer_GetSamplingRate(OH_AudioCapturer* capturer, int32_t* rate); 149 150 /* 151 * Query the channel count of the capturer client. 152 * 153 * @since 10 154 * 155 * @param capturer Reference created by OH_AudioStreamBuilder_GenerateCapturer() 156 * @param channelCount Pointer to a variable that will be set for the channel count. 157 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 158 */ 159 OH_AudioStream_Result OH_AudioCapturer_GetChannelCount(OH_AudioCapturer* capturer, int32_t* channelCount); 160 161 /* 162 * Query the sample format of the capturer client. 163 * 164 * @since 10 165 * 166 * @param capturer Reference created by OH_AudioStreamBuilder_GenerateCapturer() 167 * @param sampleFormat Pointer to a variable that will be set for the sample format. 168 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 169 */ 170 OH_AudioStream_Result OH_AudioCapturer_GetSampleFormat(OH_AudioCapturer* capturer, 171 OH_AudioStream_SampleFormat* sampleFormat); 172 173 /* 174 * Query the encoding type of the capturer client. 175 * 176 * @since 10 177 * 178 * @param capturer Reference created by OH_AudioStreamBuilder_GenerateCapturer() 179 * @param encodingType Pointer to a variable that will be set for the encoding type. 180 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 181 */ 182 OH_AudioStream_Result OH_AudioCapturer_GetEncodingType(OH_AudioCapturer* capturer, 183 OH_AudioStream_EncodingType* encodingType); 184 185 /* 186 * Query the capturer info of the capturer client. 187 * 188 * @since 10 189 * 190 * @param capturer Reference created by OH_AudioStreamBuilder_GenerateCapturer() 191 * @param sourceType Pointer to a variable that will be set for the stream sourceType. 192 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 193 */ 194 OH_AudioStream_Result OH_AudioCapturer_GetCapturerInfo(OH_AudioCapturer* capturer, 195 OH_AudioStream_SourceType* sourceType); 196 197 /* 198 * Query the frame size in callback, it is a fixed length of the buffer returned by each callback. 199 * 200 * @since 10 201 * 202 * @param capturer Reference created by OH_AudioStreamBuilder_GenerateCapturer() 203 * @param frameSize Pointer to a variable that will be set for the frame size. 204 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 205 */ 206 OH_AudioStream_Result OH_AudioCapturer_GetFrameSizeInCallback(OH_AudioCapturer* capturer, int32_t* frameSize); 207 208 /* 209 * Query the the time at which a particular frame was presented 210 * 211 * @since 10 212 * 213 * @param capturer Reference created by OH_AudioStreamBuilder_GenerateCapturer() 214 * @param clockId {@link #CLOCK_MONOTONIC} 215 * @param framePosition Pointer to a variable to receive the position 216 * @param timestamp Pointer to a variable to receive the timestamp 217 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 218 */ 219 OH_AudioStream_Result OH_AudioCapturer_GetTimestamp(OH_AudioCapturer* capturer, 220 clockid_t clockId, int64_t* framePosition, int64_t* timestamp); 221 222 /* 223 * Query the the number of frames that have been read since the stream was created. 224 * 225 * @since 10 226 * 227 * @param capturer Reference created by OH_AudioStreamBuilder_GenerateCapturer() 228 * @param frames Pointer to a variable that will be set for the frame count number. 229 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 230 */ 231 OH_AudioStream_Result OH_AudioCapturer_GetFramesRead(OH_AudioCapturer* capturer, int64_t* frames); 232 233 234 /** 235 * @brief Temporarily changes the current audio input device 236 * Setting the device will ony takes effect if no other accessory such as headphoes are in use. 237 * 238 * @param capturer Capturer generated by OH_AudioStreamBuilder_GenerateCapturer() 239 * @param deviceType The target device. 240 * @return result code for this function. 241 * {@link #AUDIOSTREAM_SUCCESS} succeed in setting the default output device 242 * {@link #AUDIOSTREAM_ERROR_INVALID_PARAM}: 243 * 1.The param of Capturer is nullptr; 244 * 2.The param of deviceType is not valid 245 * {@link #AUDIOSTREAM_ERROR_ILLEGAL_STATE} This audioCapturer can not reset the input device 246 * {@link #AUDIOSTREAM_ERROR_SYSTEM} system error when calling this function. 247 * @since 18 248 */ 249 OH_AudioStream_Result OH_AudioCapturer_SetInputDevice(OH_AudioCapturer* capturer, 250 OH_AudioDevice_Type deviceType); 251 252 /** 253 * @brief Gets the overflow count on this stream. 254 * 255 * @since 12 256 * 257 * @param capturer Capturer generated by OH_AudioStreamBuilder_GenerateCapturer() 258 * @param count Pointer to a variable that will be set for the overflow count number. 259 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 260 */ 261 OH_AudioStream_Result OH_AudioCapturer_GetOverflowCount(OH_AudioCapturer* capturer, uint32_t* count); 262 263 /** 264 * @brief Callback function of read data. 265 * 266 * This function is similar with OH_AudioCapturer_Callbacks_Struct.OH_AudioCapturer_OnReadData 267 * 268 * @param capturer AudioCapturer where this callback occurs. 269 * @param userData User data which is passed by user. 270 * @param audioData Audio data pointer, where user should read. 271 * @param audioDataSize Size of audio data that user should read. 272 * @see OH_AudioCapturer_Callbacks_Struct.OH_AudioCapturer_OnReadData 273 * @since 18 274 */ 275 typedef void (*OH_AudioCapturer_OnReadDataCallback)(OH_AudioCapturer* capturer, void* userData, void* audioData, 276 int32_t audioDataSize); 277 278 /** 279 * @brief Callback when input device of an AudioCapturer changes. 280 * 281 * This function is similar with OH_AudioCapturer_Callbacks_Struct.OH_AudioCapturer_OnStreamEvent 282 * 283 * @param capturer AudioCapturer where this callback occurs. 284 * @param userData User data which is passed by user. 285 * @param deviceArray Array of AudioDeviceDescriptor where the capturing data from. 286 * @see OH_AudioCapturer_Callbacks_Struct.OH_AudioCapturer_OnStreamEvent 287 * @since 18 288 */ 289 typedef void (*OH_AudioCapturer_OnDeviceChangeCallback)(OH_AudioCapturer* capturer, void* userData, 290 OH_AudioDeviceDescriptorArray* deviceArray); 291 292 /** 293 * @brief Callback function of interrupt event on AudioCapturer. 294 * 295 * This function is similar with OH_AudioCapturer_Callbacks_Struct.OH_AudioCapturer_OnInterruptEvent. 296 * 297 * @param capturer AudioCapturer where this callback occurs. 298 * @param userData User data which is passed by user. 299 * @param type Force type of this interrupt event. 300 * @param hint Hint of this interrupt event. 301 * @see OH_AudioCapturer_Callbacks_Struct.OH_AudioCapturer_OnInterruptEvent. 302 * @since 18 303 */ 304 typedef void (*OH_AudioCapturer_OnInterruptCallback)(OH_AudioCapturer* capturer, void* userData, 305 OH_AudioInterrupt_ForceType type, OH_AudioInterrupt_Hint hint); 306 307 /** 308 * @brief Callback function of error on AudioCapturer. 309 * 310 * This function is similar with OH_AudioCapturer_Callbacks_Struct.OH_AudioCapturer_OnError. 311 * 312 * @param renderer AudioCapturer where this callback occurs. 313 * @param userData User data which is passed by user. 314 * @param error Error while using AudioCapturer. 315 * @see OH_AudioCapturer_Callbacks_Struct.OH_AudioCapturer_OnError 316 * @since 18 317 */ 318 typedef void (*OH_AudioCapturer_OnErrorCallback)(OH_AudioCapturer* renderer, void* userData, 319 OH_AudioStream_Result error); 320 321 /** 322 * @brief Gets audio capturer running status, check if it works in fast status. 323 * 324 * @param capturer Reference created by OH_AudioStreamBuilder_GenerateCapturer. 325 * @param status Pointer to a variable to receive the status. 326 * @return 327 * {@link AUDIOSTREAM_SUCCESS} if the execution is successful. 328 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} the param of capturer is nullptr. 329 * {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} function called in invalid state, only available before release state. 330 * @since 20 331 */ 332 OH_AudioStream_Result OH_AudioCapturer_GetFastStatus(OH_AudioCapturer* capturer, 333 OH_AudioStream_FastStatus* status); 334 335 /** 336 * @brief Callback function of fast status change event for audio capturer. 337 * 338 * @param capturer Pointer to an audio capturer instance for which this callback occurs. 339 * @param userData Userdata which is passed by register. 340 * @param status Current fast status. 341 * @since 20 342 */ 343 typedef void (*OH_AudioCapturer_OnFastStatusChange)( 344 OH_AudioCapturer* capturer, 345 void* userData, 346 OH_AudioStream_FastStatus status 347 ); 348 349 #ifdef __cplusplus 350 } 351 #endif 352 #endif // NATIVE_AUDIOCAPTURER_H 353