AudioRecord.h revision 95634c8b6ad5419e310a5196bcc37f5988ed82da
1/* 2 * Copyright (C) 2008 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17#ifndef AUDIORECORD_H_ 18#define AUDIORECORD_H_ 19 20#include <stdint.h> 21#include <sys/types.h> 22 23#include <media/IAudioFlinger.h> 24#include <media/IAudioRecord.h> 25#include <media/AudioTrack.h> 26 27#include <utils/RefBase.h> 28#include <utils/Errors.h> 29#include <binder/IInterface.h> 30#include <binder/IMemory.h> 31#include <utils/threads.h> 32 33 34namespace android { 35 36// ---------------------------------------------------------------------------- 37 38class AudioRecord 39{ 40public: 41 42 // input sources values must always be defined in the range 43 // [AudioRecord::DEFAULT_INPUT, AudioRecord::NUM_INPUT_SOURCES[ 44 enum input_source { 45 DEFAULT_INPUT =-1, 46 MIC_INPUT = 0, 47 VOICE_UPLINK_INPUT = 1, 48 VOICE_DOWNLINK_INPUT = 2, 49 VOICE_CALL_INPUT = 3, 50 NUM_INPUT_SOURCES 51 }; 52 53 static const int DEFAULT_SAMPLE_RATE = 8000; 54 55 /* Events used by AudioRecord callback function (callback_t). 56 * 57 * to keep in sync with frameworks/base/media/java/android/media/AudioRecord.java 58 */ 59 enum event_type { 60 EVENT_MORE_DATA = 0, // Request to reqd more data from PCM buffer. 61 EVENT_OVERRUN = 1, // PCM buffer overrun occured. 62 EVENT_MARKER = 2, // Record head is at the specified marker position 63 // (See setMarkerPosition()). 64 EVENT_NEW_POS = 3, // Record head is at a new position 65 // (See setPositionUpdatePeriod()). 66 }; 67 68 /* Create Buffer on the stack and pass it to obtainBuffer() 69 * and releaseBuffer(). 70 */ 71 72 class Buffer 73 { 74 public: 75 enum { 76 MUTE = 0x00000001 77 }; 78 uint32_t flags; 79 int channelCount; 80 int format; 81 size_t frameCount; 82 size_t size; 83 union { 84 void* raw; 85 short* i16; 86 int8_t* i8; 87 }; 88 }; 89 90 /* These are static methods to control the system-wide AudioFlinger 91 * only privileged processes can have access to them 92 */ 93 94// static status_t setMasterMute(bool mute); 95 96 /* As a convenience, if a callback is supplied, a handler thread 97 * is automatically created with the appropriate priority. This thread 98 * invokes the callback when a new buffer becomes ready or an overrun condition occurs. 99 * Parameters: 100 * 101 * event: type of event notified (see enum AudioRecord::event_type). 102 * user: Pointer to context for use by the callback receiver. 103 * info: Pointer to optional parameter according to event type: 104 * - EVENT_MORE_DATA: pointer to AudioRecord::Buffer struct. The callback must not read 105 * more bytes than indicated by 'size' field and update 'size' if less bytes are 106 * read. 107 * - EVENT_OVERRUN: unused. 108 * - EVENT_MARKER: pointer to an uin32_t containing the marker position in frames. 109 * - EVENT_NEW_POS: pointer to an uin32_t containing the new position in frames. 110 */ 111 112 typedef void (*callback_t)(int event, void* user, void *info); 113 114 /* Constructs an uninitialized AudioRecord. No connection with 115 * AudioFlinger takes place. 116 */ 117 AudioRecord(); 118 119 /* Creates an AudioRecord track and registers it with AudioFlinger. 120 * Once created, the track needs to be started before it can be used. 121 * Unspecified values are set to the audio hardware's current 122 * values. 123 * 124 * Parameters: 125 * 126 * inputSource: Select the audio input to record to (e.g. AudioRecord::MIC_INPUT). 127 * sampleRate: Track sampling rate in Hz. 128 * format: PCM sample format (e.g AudioSystem::PCM_16_BIT for signed 129 * 16 bits per sample). 130 * channelCount: Number of PCM channels (e.g 2 for stereo). 131 * frameCount: Total size of track PCM buffer in frames. This defines the 132 * latency of the track. 133 * flags: A bitmask of acoustic values from enum record_flags. It enables 134 * AGC, NS, and IIR. 135 * cbf: Callback function. If not null, this function is called periodically 136 * to provide new PCM data. 137 * notificationFrames: The callback function is called each time notificationFrames PCM 138 * frames are ready in record track output buffer. 139 * user Context for use by the callback receiver. 140 */ 141 142 enum record_flags { 143 RECORD_AGC_ENABLE = AudioSystem::AGC_ENABLE, 144 RECORD_NS_ENABLE = AudioSystem::NS_ENABLE, 145 RECORD_IIR_ENABLE = AudioSystem::TX_IIR_ENABLE 146 }; 147 148 AudioRecord(int inputSource, 149 uint32_t sampleRate = 0, 150 int format = 0, 151 int channelCount = 0, 152 int frameCount = 0, 153 uint32_t flags = 0, 154 callback_t cbf = 0, 155 void* user = 0, 156 int notificationFrames = 0); 157 158 159 /* Terminates the AudioRecord and unregisters it from AudioFlinger. 160 * Also destroys all resources assotiated with the AudioRecord. 161 */ 162 ~AudioRecord(); 163 164 165 /* Initialize an uninitialized AudioRecord. 166 * Returned status (from utils/Errors.h) can be: 167 * - NO_ERROR: successful intialization 168 * - INVALID_OPERATION: AudioRecord is already intitialized or record device is already in use 169 * - BAD_VALUE: invalid parameter (channelCount, format, sampleRate...) 170 * - NO_INIT: audio server or audio hardware not initialized 171 * - PERMISSION_DENIED: recording is not allowed for the requesting process 172 * */ 173 status_t set(int inputSource = 0, 174 uint32_t sampleRate = 0, 175 int format = 0, 176 int channelCount = 0, 177 int frameCount = 0, 178 uint32_t flags = 0, 179 callback_t cbf = 0, 180 void* user = 0, 181 int notificationFrames = 0, 182 bool threadCanCallJava = false); 183 184 185 /* Result of constructing the AudioRecord. This must be checked 186 * before using any AudioRecord API (except for set()), using 187 * an uninitialized AudioRecord produces undefined results. 188 * See set() method above for possible return codes. 189 */ 190 status_t initCheck() const; 191 192 /* Returns this track's latency in milliseconds. 193 * This includes the latency due to AudioRecord buffer size 194 * and audio hardware driver. 195 */ 196 uint32_t latency() const; 197 198 /* getters, see constructor */ 199 200 uint32_t sampleRate() const; 201 int format() const; 202 int channelCount() const; 203 uint32_t frameCount() const; 204 int frameSize() const; 205 int inputSource() const; 206 207 208 /* After it's created the track is not active. Call start() to 209 * make it active. If set, the callback will start being called. 210 */ 211 status_t start(); 212 213 /* Stop a track. If set, the callback will cease being called and 214 * obtainBuffer returns STOPPED. Note that obtainBuffer() still works 215 * and will fill up buffers until the pool is exhausted. 216 */ 217 status_t stop(); 218 bool stopped() const; 219 220 /* get sample rate for this track 221 */ 222 uint32_t getSampleRate(); 223 224 /* Sets marker position. When record reaches the number of frames specified, 225 * a callback with event type EVENT_MARKER is called. Calling setMarkerPosition 226 * with marker == 0 cancels marker notification callback. 227 * If the AudioRecord has been opened with no callback function associated, 228 * the operation will fail. 229 * 230 * Parameters: 231 * 232 * marker: marker position expressed in frames. 233 * 234 * Returned status (from utils/Errors.h) can be: 235 * - NO_ERROR: successful operation 236 * - INVALID_OPERATION: the AudioRecord has no callback installed. 237 */ 238 status_t setMarkerPosition(uint32_t marker); 239 status_t getMarkerPosition(uint32_t *marker); 240 241 242 /* Sets position update period. Every time the number of frames specified has been recorded, 243 * a callback with event type EVENT_NEW_POS is called. 244 * Calling setPositionUpdatePeriod with updatePeriod == 0 cancels new position notification 245 * callback. 246 * If the AudioRecord has been opened with no callback function associated, 247 * the operation will fail. 248 * 249 * Parameters: 250 * 251 * updatePeriod: position update notification period expressed in frames. 252 * 253 * Returned status (from utils/Errors.h) can be: 254 * - NO_ERROR: successful operation 255 * - INVALID_OPERATION: the AudioRecord has no callback installed. 256 */ 257 status_t setPositionUpdatePeriod(uint32_t updatePeriod); 258 status_t getPositionUpdatePeriod(uint32_t *updatePeriod); 259 260 261 /* Gets record head position. The position is the total number of frames 262 * recorded since record start. 263 * 264 * Parameters: 265 * 266 * position: Address where to return record head position within AudioRecord buffer. 267 * 268 * Returned status (from utils/Errors.h) can be: 269 * - NO_ERROR: successful operation 270 * - BAD_VALUE: position is NULL 271 */ 272 status_t getPosition(uint32_t *position); 273 274 275 276 /* obtains a buffer of "frameCount" frames. The buffer must be 277 * filled entirely. If the track is stopped, obtainBuffer() returns 278 * STOPPED instead of NO_ERROR as long as there are buffers availlable, 279 * at which point NO_MORE_BUFFERS is returned. 280 * Buffers will be returned until the pool (buffercount()) 281 * is exhausted, at which point obtainBuffer() will either block 282 * or return WOULD_BLOCK depending on the value of the "blocking" 283 * parameter. 284 */ 285 286 enum { 287 NO_MORE_BUFFERS = 0x80000001, 288 STOPPED = 1 289 }; 290 291 status_t obtainBuffer(Buffer* audioBuffer, int32_t waitCount); 292 void releaseBuffer(Buffer* audioBuffer); 293 294 295 /* As a convenience we provide a read() interface to the audio buffer. 296 * This is implemented on top of lockBuffer/unlockBuffer. 297 */ 298 ssize_t read(void* buffer, size_t size); 299 300private: 301 /* copying audio tracks is not allowed */ 302 AudioRecord(const AudioRecord& other); 303 AudioRecord& operator = (const AudioRecord& other); 304 305 /* a small internal class to handle the callback */ 306 class ClientRecordThread : public Thread 307 { 308 public: 309 ClientRecordThread(AudioRecord& receiver, bool bCanCallJava = false); 310 private: 311 friend class AudioRecord; 312 virtual bool threadLoop(); 313 virtual status_t readyToRun() { return NO_ERROR; } 314 virtual void onFirstRef() {} 315 AudioRecord& mReceiver; 316 Mutex mLock; 317 }; 318 319 bool processAudioBuffer(const sp<ClientRecordThread>& thread); 320 321 sp<IAudioRecord> mAudioRecord; 322 sp<IMemory> mCblkMemory; 323 sp<ClientRecordThread> mClientRecordThread; 324 Mutex mRecordThreadLock; 325 326 uint32_t mSampleRate; 327 uint32_t mFrameCount; 328 329 audio_track_cblk_t* mCblk; 330 uint8_t mFormat; 331 uint8_t mChannelCount; 332 uint8_t mInputSource; 333 uint8_t mReserved; 334 status_t mStatus; 335 uint32_t mLatency; 336 337 volatile int32_t mActive; 338 339 callback_t mCbf; 340 void* mUserData; 341 uint32_t mNotificationFrames; 342 uint32_t mRemainingFrames; 343 uint32_t mMarkerPosition; 344 bool mMarkerReached; 345 uint32_t mNewPosition; 346 uint32_t mUpdatePeriod; 347}; 348 349}; // namespace android 350 351#endif /*AUDIORECORD_H_*/ 352