1 /* 2 * Copyright (c) 2020-2021 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 MultiMedia_AudioCapturer 18 * @{ 19 * 20 * @brief Declares APIs in the <b>AudioCapturer</b> class for audio capture. 21 * 22 * 23 * @since 1.0 24 * @version 1.0 25 */ 26 27 /** 28 * @file audio_capturer.h 29 * 30 * @brief Provides the <b>AudioCapturer</b> class to implement operations related to audio capture. 31 * 32 * 33 * @since 1.0 34 * @version 1.0 35 */ 36 37 #ifndef AUDIO_CAPTURER_H 38 #define AUDIO_CAPTURER_H 39 40 #include <cstddef> 41 #include <cstdint> 42 #include <time.h> 43 #include <memory> 44 45 #include "media_errors.h" 46 #include "media_info.h" 47 48 namespace OHOS { 49 namespace Audio { 50 /** 51 * @brief Defines information about audio capture parameters, including the input source, audio codec format,sampling 52 * rate (Hz), number of audio channels, bit rate, and bit width. 53 * 54 * @since 1.0 55 * @version 1.0 56 */ 57 struct AudioCapturerInfo { 58 /** Audio source type */ 59 AudioSourceType inputSource = AUDIO_MIC; 60 /** Audio codec format */ 61 AudioCodecFormat audioFormat = AUDIO_DEFAULT; 62 /** Sampling rate */ 63 int32_t sampleRate = 0; 64 /** Number of audio channels */ 65 int32_t channelCount = 0; 66 /** Bit rate */ 67 int32_t bitRate = 0; 68 /** Audio stream type */ 69 AudioStreamType streamType = TYPE_MEDIA; 70 /** Bit width */ 71 AudioBitWidth bitWidth = BIT_WIDTH_16; 72 }; 73 74 /** 75 * @brief Represents timestamp information, including the frame position information and high-resolution time source. 76 * 77 * @since 1.0 78 * @version 1.0 79 */ 80 class Timestamp { 81 public: Timestamp()82 Timestamp() : framePosition(0) 83 { 84 time.tv_sec = 0; 85 time.tv_nsec = 0; 86 } 87 ~Timestamp() = default; 88 uint32_t framePosition; 89 struct timespec time; 90 91 /** 92 * @brief Enumerates the time base of this <b>Timestamp</b>. Different timing methods are supported. 93 * 94 */ 95 enum class Timebase : int32_t { 96 /** Monotonically increasing time, excluding the system sleep time */ 97 MONOTONIC = 0, 98 /** Monotonically increasing time, including the system sleep time */ 99 BOOTTIME = 1 100 }; 101 }; 102 103 /** 104 * @brief Enumerates the recording states of the current device. 105 * 106 * @since 1.0 107 * @version 1.0 108 */ 109 enum State : uint32_t { 110 /** Initialized */ 111 INITIALIZED, 112 /** Prepared */ 113 PREPARED, 114 /** Recording */ 115 RECORDING, 116 /** Stopped */ 117 STOPPED, 118 /** Released */ 119 RELEASED 120 }; 121 122 /** 123 * @brief Provides functions for applications to implement audio capturing. 124 * 125 * @since 1.0 126 * @version 1.0 127 */ 128 class AudioCapturer { 129 public: 130 AudioCapturer(); 131 virtual ~AudioCapturer(); 132 133 /** 134 * @brief Obtains the minimum number of frames required in a specified condition, in bytes per sample. 135 * 136 * @param sampleRate Indicates the audio sampling rate, in Hz. 137 * @param channelCount Indicates the number of audio recording channels. 138 * @param audioFormat Indicates the audio data format. 139 * @param frameCount Indicates the minimum number of frames, in bytes per sample. 140 * @return Returns <b>true</b> if the minimum number of frames is successfully obtained; returns <b>false</b> 141 * otherwise. 142 * @since 1.0 143 * @version 1.0 144 */ 145 static bool GetMinFrameCount(int32_t sampleRate, int32_t channelCount, AudioCodecFormat audioFormat, 146 size_t &frameCount); 147 148 /** 149 * @brief Obtains the number of frames required in the current condition, in bytes per sample. 150 * 151 * @return Returns the number of frames (in bytes per sample) if the operation is successful; returns <b>-1</b> 152 * if an exception occurs. 153 * @since 1.0 154 * @version 1.0 155 */ 156 uint64_t GetFrameCount(); 157 158 /** 159 * @brief Sets audio capture parameters. 160 * 161 * @param info Indicates information about audio capture parameters to set. For details, see 162 * {@link AudioCapturerInfo}. 163 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 164 * in {@link media_errors.h} otherwise. 165 * @since 1.0 166 * @version 1.0 167 */ 168 int32_t SetCapturerInfo(const AudioCapturerInfo info); 169 170 /** 171 * @brief Obtains audio capture parameters. 172 * 173 * This function can be called after {@link SetCapturerInfo} is successful. 174 * 175 * @param info Indicates information about audio capture parameters. For details, see {@link AudioCapturerInfo}. 176 * @return Returns {@link SUCCESS} if the parameter information is successfully obtained; returns an error code 177 * defined in {@link media_errors.h} otherwise. 178 * @since 1.0 179 * @version 1.0 180 */ 181 int32_t GetCapturerInfo(AudioCapturerInfo &info); 182 183 /** 184 * @brief Starts audio recording. 185 * 186 * @return Returns <b>true</b> if the recording is successfully started; returns <b>false</b> otherwise. 187 * @since 1.0 188 * @version 1.0 189 */ 190 bool Start(); 191 192 /** 193 * @brief Reads audio data. 194 * 195 * @param buffer Indicates the pointer to the buffer into which the audio data is to be written. 196 * @param userSize Indicates the size of the buffer into which the audio data is to be written, in bytes. 197 * <b>userSize >= frameCount * channelCount * BytesPerSample</b> must evaluate to <b>true</b>. You can call 198 * {@link GetFrameCount} to obtain the <b>frameCount</b> value. 199 * @param isBlockingRead Specifies whether data reading will be blocked. 200 * @return Returns the size of the audio data read from the device. The value ranges from <b>0</b> to 201 * <b>userSize</b>. If the reading fails, one of the following error codes is returned: 202 * <b>ERR_INVALID_PARAM</b>: The input parameter is incorrect. 203 * <b>ERR_ILLEGAL_STATE</b>: The <b>AudioCapturer</b> instance is not initialized. 204 * <b>ERR_SOURCE_NOT_SET</b>: The state of hardware device instance is abnormal. 205 * @since 1.0 206 * @version 1.0 207 */ 208 int32_t Read(uint8_t *buffer, size_t userSize, bool isBlockingRead); 209 210 /** 211 * @brief Obtains the audio capture state. 212 * 213 * @return Returns the audio capture state defined in {@link State}. 214 * @since 1.0 215 * @version 1.0 216 */ 217 State GetStatus(); 218 219 /** 220 * @brief Obtains the timestamp. 221 * 222 * @param timestamp Indicates a {@link Timestamp} instance reference provided by the caller. 223 * @param base Indicates the time base, which can be {@link Timestamp.Timebase#BOOTTIME Timestamp.Timebase.BOOTTIME} 224 * or {@link Timestamp.Timebase#MONOTONIC Timestamp.Timebase.MONOTONIC}. 225 * @return Returns <b>true</b> if the timestamp is successfully obtained; returns <b>false</b> otherwise. 226 * @since 1.0 227 * @version 1.0 228 */ 229 bool GetAudioTime(Timestamp ×tamp, Timestamp::Timebase base); 230 231 /** 232 * @brief Stops audio recording. 233 * 234 * @return Returns <b>true</b> if the recording is successfully stopped; returns <b>false</b> otherwise. 235 * @since 1.0 236 * @version 1.0 237 */ 238 bool Stop(); 239 240 /** 241 * @brief Releases a local <b>AudioCapturer</b> object. 242 * 243 * @return Returns <b>true</b> if the object is successfully released; returns <b>false</b> otherwise. 244 * @since 1.0 245 * @version 1.0 246 */ 247 bool Release(); 248 249 private: 250 class AudioCapturerClient; 251 std::unique_ptr<AudioCapturerClient> impl_; 252 }; 253 } // namespace Audio 254 } // namespace OHOS 255 #endif // AUDIO_CAPTURER_H 256