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 ANDROID_AUDIORECORD_H 18 #define ANDROID_AUDIORECORD_H 19 20 #include <memory> 21 #include <vector> 22 23 #include <binder/IMemory.h> 24 #include <cutils/sched_policy.h> 25 #include <media/AudioSystem.h> 26 #include <media/AudioTimestamp.h> 27 #include <media/MediaMetricsItem.h> 28 #include <media/Modulo.h> 29 #include <media/RecordingActivityTracker.h> 30 #include <utils/RefBase.h> 31 #include <utils/threads.h> 32 33 #include "android/media/IAudioRecord.h" 34 #include <android/content/AttributionSourceState.h> 35 36 namespace android { 37 38 // ---------------------------------------------------------------------------- 39 40 struct audio_track_cblk_t; 41 class AudioRecordClientProxy; 42 // ---------------------------------------------------------------------------- 43 44 class AudioRecord : public AudioSystem::AudioDeviceCallback 45 { 46 public: 47 48 class Buffer 49 { 50 friend AudioRecord; 51 public: size()52 size_t size() const { return mSize; } getFrameCount()53 size_t getFrameCount() const { return frameCount; } data()54 uint8_t* data() const { return ui8; } 55 // Leaving public for now to assist refactoring. This class will 56 // be replaced. 57 size_t frameCount; // number of sample frames corresponding to size; 58 // on input to obtainBuffer() it is the number of frames desired 59 // on output from obtainBuffer() it is the number of available 60 // frames to be read 61 // on input to releaseBuffer() it is currently ignored 62 63 private: 64 size_t mSize; // input/output in bytes == frameCount * frameSize 65 // on input to obtainBuffer() it is ignored 66 // on output from obtainBuffer() it is the number of available 67 // bytes to be read, which is frameCount * frameSize 68 // on input to releaseBuffer() it is the number of bytes to 69 // release 70 // FIXME This is redundant with respect to frameCount. Consider 71 // removing size and making frameCount the primary field. 72 73 union { 74 void* raw; 75 int16_t* i16; // signed 16-bit 76 uint8_t* ui8; // unsigned 8-bit, offset by 0x80 77 // input to obtainBuffer(): unused, output: pointer to buffer 78 }; 79 80 uint32_t sequence; // IAudioRecord instance sequence number, as of obtainBuffer(). 81 // It is set by obtainBuffer() and confirmed by releaseBuffer(). 82 // Not "user-serviceable". 83 // TODO Consider sp<IMemory> instead, or in addition to this. 84 }; 85 86 /* As a convenience, if a callback is supplied, a handler thread 87 * is automatically created with the appropriate priority. This thread 88 * invokes the callback when a new buffer becomes available or various conditions occur. 89 * Parameters: 90 * 91 * event: type of event notified (see enum AudioRecord::event_type). 92 * user: Pointer to context for use by the callback receiver. 93 * info: Pointer to optional parameter according to event type: 94 * - EVENT_MORE_DATA: pointer to AudioRecord::Buffer struct. The callback must not read 95 * more bytes than indicated by 'size' field and update 'size' if 96 * fewer bytes are consumed. 97 * - EVENT_OVERRUN: unused. 98 * - EVENT_MARKER: pointer to const uint32_t containing the marker position in frames. 99 * - EVENT_NEW_POS: pointer to const uint32_t containing the new position in frames. 100 * - EVENT_NEW_IAUDIORECORD: unused. 101 */ 102 103 104 class IAudioRecordCallback : public virtual RefBase { 105 friend AudioRecord; 106 protected: 107 // Request for client to read newly available data. 108 // Used for TRANSFER_CALLBACK mode. 109 // Parameters: 110 // - buffer : Buffer to read from 111 // Returns: 112 // - Number of bytes actually consumed. onMoreData(const AudioRecord::Buffer & buffer)113 virtual size_t onMoreData([[maybe_unused]] const AudioRecord::Buffer& buffer) { return 0; } 114 // A buffer overrun occurred. onOverrun()115 virtual void onOverrun() {} 116 // Record head is at the specified marker (see setMarkerPosition()). onMarker(uint32_t markerPosition)117 virtual void onMarker([[maybe_unused]] uint32_t markerPosition) {} 118 // Record head is at a new position (see setPositionUpdatePeriod()). onNewPos(uint32_t newPos)119 virtual void onNewPos([[maybe_unused]] uint32_t newPos) {} 120 // IAudioRecord was recreated due to re-routing, server invalidation or 121 // server crash. onNewIAudioRecord()122 virtual void onNewIAudioRecord() {} 123 }; 124 125 /* Returns the minimum frame count required for the successful creation of 126 * an AudioRecord object. 127 * Returned status (from utils/Errors.h) can be: 128 * - NO_ERROR: successful operation 129 * - NO_INIT: audio server or audio hardware not initialized 130 * - BAD_VALUE: unsupported configuration 131 * frameCount is guaranteed to be non-zero if status is NO_ERROR, 132 * and is undefined otherwise. 133 * FIXME This API assumes a route, and so should be deprecated. 134 */ 135 136 static status_t getMinFrameCount(size_t* frameCount, 137 uint32_t sampleRate, 138 audio_format_t format, 139 audio_channel_mask_t channelMask); 140 141 /* Checks for erroneous status, marks error in MediaMetrics, logs the error message. 142 * Updates and returns mStatus. 143 */ 144 status_t logIfErrorAndReturnStatus(status_t status, const std::string& errorMessage, 145 const std::string& func); 146 147 /* How data is transferred from AudioRecord 148 */ 149 enum transfer_type { 150 TRANSFER_DEFAULT, // not specified explicitly; determine from the other parameters 151 TRANSFER_CALLBACK, // callback EVENT_MORE_DATA 152 TRANSFER_OBTAIN, // call obtainBuffer() and releaseBuffer() 153 TRANSFER_SYNC, // synchronous read() 154 }; 155 156 /* Constructs an uninitialized AudioRecord. No connection with 157 * AudioFlinger takes place. Use set() after this. 158 * 159 * Parameters: 160 * 161 * client: The attribution source of the owner of the record 162 */ 163 AudioRecord(const android::content::AttributionSourceState& client); 164 165 /* Creates an AudioRecord object and registers it with AudioFlinger. 166 * Once created, the track needs to be started before it can be used. 167 * Unspecified values are set to appropriate default values. 168 * 169 * Parameters: 170 * 171 * inputSource: Select the audio input to record from (e.g. AUDIO_SOURCE_DEFAULT). 172 * sampleRate: Data sink sampling rate in Hz. Zero means to use the source sample rate. 173 * format: Audio format (e.g AUDIO_FORMAT_PCM_16_BIT for signed 174 * 16 bits per sample). 175 * channelMask: Channel mask, such that audio_is_input_channel(channelMask) is true. 176 * client: The attribution source of the owner of the record 177 * frameCount: Minimum size of track PCM buffer in frames. This defines the 178 * application's contribution to the 179 * latency of the track. The actual size selected by the AudioRecord could 180 * be larger if the requested size is not compatible with current audio HAL 181 * latency. Zero means to use a default value. 182 * cbf: Callback function. If not null, this function is called periodically 183 * to consume new data in TRANSFER_CALLBACK mode 184 * and inform of marker, position updates, etc. 185 * user: Context for use by the callback receiver. 186 * notificationFrames: The callback function is called each time notificationFrames PCM 187 * frames are ready in record track output buffer. 188 * sessionId: Not yet supported. 189 * transferType: How data is transferred from AudioRecord. 190 * flags: See comments on audio_input_flags_t in <system/audio.h> 191 * pAttributes: If not NULL, supersedes inputSource for use case selection. 192 * threadCanCallJava: Not present in parameter list, and so is fixed at false. 193 */ 194 AudioRecord(audio_source_t inputSource, 195 uint32_t sampleRate, 196 audio_format_t format, 197 audio_channel_mask_t channelMask, 198 const android::content::AttributionSourceState& client, 199 size_t frameCount = 0, 200 const wp<IAudioRecordCallback> &callback = nullptr, 201 uint32_t notificationFrames = 0, 202 audio_session_t sessionId = AUDIO_SESSION_ALLOCATE, 203 transfer_type transferType = TRANSFER_DEFAULT, 204 audio_input_flags_t flags = AUDIO_INPUT_FLAG_NONE, 205 const audio_attributes_t* pAttributes = nullptr, 206 audio_port_handle_t selectedDeviceId = AUDIO_PORT_HANDLE_NONE, 207 audio_microphone_direction_t 208 selectedMicDirection = MIC_DIRECTION_UNSPECIFIED, 209 float selectedMicFieldDimension = MIC_FIELD_DIMENSION_DEFAULT); 210 211 212 /* Terminates the AudioRecord and unregisters it from AudioFlinger. 213 * Also destroys all resources associated with the AudioRecord. 214 */ 215 protected: 216 virtual ~AudioRecord(); 217 public: 218 219 /* Initialize an AudioRecord that was created using the AudioRecord() constructor. 220 * Don't call set() more than once, or after an AudioRecord() constructor that takes parameters. 221 * set() is not multi-thread safe. 222 * Returned status (from utils/Errors.h) can be: 223 * - NO_ERROR: successful intialization 224 * - INVALID_OPERATION: AudioRecord is already initialized or record device is already in use 225 * - BAD_VALUE: invalid parameter (channelMask, format, sampleRate...) 226 * - NO_INIT: audio server or audio hardware not initialized 227 * - PERMISSION_DENIED: recording is not allowed for the requesting process 228 * If status is not equal to NO_ERROR, don't call any other APIs on this AudioRecord. 229 * 230 * Parameters not listed in the AudioRecord constructors above: 231 * 232 * threadCanCallJava: Whether callbacks are made from an attached thread and thus can call JNI. 233 */ 234 status_t set(audio_source_t inputSource, 235 uint32_t sampleRate, 236 audio_format_t format, 237 audio_channel_mask_t channelMask, 238 size_t frameCount = 0, 239 const wp<IAudioRecordCallback> &callback = nullptr, 240 uint32_t notificationFrames = 0, 241 bool threadCanCallJava = false, 242 audio_session_t sessionId = AUDIO_SESSION_ALLOCATE, 243 transfer_type transferType = TRANSFER_DEFAULT, 244 audio_input_flags_t flags = AUDIO_INPUT_FLAG_NONE, 245 uid_t uid = AUDIO_UID_INVALID, 246 pid_t pid = -1, 247 const audio_attributes_t* pAttributes = nullptr, 248 audio_port_handle_t selectedDeviceId = AUDIO_PORT_HANDLE_NONE, 249 audio_microphone_direction_t 250 selectedMicDirection = MIC_DIRECTION_UNSPECIFIED, 251 float selectedMicFieldDimension = MIC_FIELD_DIMENSION_DEFAULT, 252 int32_t maxSharedAudioHistoryMs = 0); 253 254 /* Result of constructing the AudioRecord. This must be checked for successful initialization 255 * before using any AudioRecord API (except for set()), because using 256 * an uninitialized AudioRecord produces undefined results. 257 * See set() method above for possible return codes. 258 */ initCheck()259 status_t initCheck() const { return mStatus; } 260 261 /* Returns this track's estimated latency in milliseconds. 262 * This includes the latency due to AudioRecord buffer size, resampling if applicable, 263 * and audio hardware driver. 264 */ latency()265 uint32_t latency() const { return mLatency; } 266 267 /* getters, see constructor and set() */ 268 format()269 audio_format_t format() const { return mFormat; } channelCount()270 uint32_t channelCount() const { return mChannelCount; } frameCount()271 size_t frameCount() const { return mFrameCount; } frameSize()272 size_t frameSize() const { return mFrameSize; } inputSource()273 audio_source_t inputSource() const { return mAttributes.source; } channelMask()274 audio_channel_mask_t channelMask() const { return mChannelMask; } 275 276 /* 277 * Return the period of the notification callback in frames. 278 * This value is set when the AudioRecord is constructed. 279 * It can be modified if the AudioRecord is rerouted. 280 */ getNotificationPeriodInFrames()281 uint32_t getNotificationPeriodInFrames() const { return mNotificationFramesAct; } 282 283 /* 284 * return metrics information for the current instance. 285 */ 286 status_t getMetrics(mediametrics::Item * &item); 287 288 /* 289 * Set name of API that is using this object. 290 * For example "aaudio" or "opensles". 291 * This may be logged or reported as part of MediaMetrics. 292 */ setCallerName(const std::string & name)293 void setCallerName(const std::string &name) { 294 mCallerName = name; 295 } 296 getCallerName()297 std::string getCallerName() const { 298 return mCallerName; 299 }; 300 301 /* After it's created the track is not active. Call start() to 302 * make it active. If set, the callback will start being called. 303 * If event is not AudioSystem::SYNC_EVENT_NONE, the capture start will be delayed until 304 * the specified event occurs on the specified trigger session. 305 */ 306 status_t start(AudioSystem::sync_event_t event = AudioSystem::SYNC_EVENT_NONE, 307 audio_session_t triggerSession = AUDIO_SESSION_NONE); 308 309 /* Stop a track. The callback will cease being called. Note that obtainBuffer() still 310 * works and will drain buffers until the pool is exhausted, and then will return WOULD_BLOCK. 311 */ 312 void stop(); 313 bool stopped() const; 314 315 /* Calls stop() and then wait for all of the callbacks to return. 316 * It is safe to call this if stop() or pause() has already been called. 317 * 318 * This function is called from the destructor. But since AudioRecord 319 * is ref counted, the destructor may be called later than desired. 320 * This can be called explicitly as part of closing an AudioRecord 321 * if you want to be certain that callbacks have completely finished. 322 * 323 * This is not thread safe and should only be called from one thread, 324 * ideally as the AudioRecord is being closed. 325 */ 326 void stopAndJoinCallbacks(); 327 328 /* Return the sink sample rate for this record track in Hz. 329 * If specified as zero in constructor or set(), this will be the source sample rate. 330 * Unlike AudioTrack, the sample rate is const after initialization, so doesn't need a lock. 331 */ getSampleRate()332 uint32_t getSampleRate() const { return mSampleRate; } 333 334 /* Return the sample rate from the AudioFlinger input thread. */ 335 uint32_t getHalSampleRate() const; 336 337 /* Return the channel count from the AudioFlinger input thread. */ 338 uint32_t getHalChannelCount() const; 339 340 /* Return the HAL format from the AudioFlinger input thread. */ 341 audio_format_t getHalFormat() const; 342 343 /* Sets marker position. When record reaches the number of frames specified, 344 * a callback with event type EVENT_MARKER is called. Calling setMarkerPosition 345 * with marker == 0 cancels marker notification callback. 346 * To set a marker at a position which would compute as 0, 347 * a workaround is to set the marker at a nearby position such as ~0 or 1. 348 * If the AudioRecord has been opened with no callback function associated, 349 * the operation will fail. 350 * 351 * Parameters: 352 * 353 * marker: marker position expressed in wrapping (overflow) frame units, 354 * like the return value of getPosition(). 355 * 356 * Returned status (from utils/Errors.h) can be: 357 * - NO_ERROR: successful operation 358 * - INVALID_OPERATION: the AudioRecord has no callback installed. 359 */ 360 status_t setMarkerPosition(uint32_t marker); 361 status_t getMarkerPosition(uint32_t *marker) const; 362 363 /* Sets position update period. Every time the number of frames specified has been recorded, 364 * a callback with event type EVENT_NEW_POS is called. 365 * Calling setPositionUpdatePeriod with updatePeriod == 0 cancels new position notification 366 * callback. 367 * If the AudioRecord has been opened with no callback function associated, 368 * the operation will fail. 369 * Extremely small values may be rounded up to a value the implementation can support. 370 * 371 * Parameters: 372 * 373 * updatePeriod: position update notification period expressed in frames. 374 * 375 * Returned status (from utils/Errors.h) can be: 376 * - NO_ERROR: successful operation 377 * - INVALID_OPERATION: the AudioRecord has no callback installed. 378 */ 379 status_t setPositionUpdatePeriod(uint32_t updatePeriod); 380 status_t getPositionUpdatePeriod(uint32_t *updatePeriod) const; 381 382 /* Return the total number of frames recorded since recording started. 383 * The counter will wrap (overflow) periodically, e.g. every ~27 hours at 44.1 kHz. 384 * It is reset to zero by stop(). 385 * 386 * Parameters: 387 * 388 * position: Address where to return record head position. 389 * 390 * Returned status (from utils/Errors.h) can be: 391 * - NO_ERROR: successful operation 392 * - BAD_VALUE: position is NULL 393 */ 394 status_t getPosition(uint32_t *position) const; 395 396 /* Return the record timestamp. 397 * 398 * Parameters: 399 * timestamp: A pointer to the timestamp to be filled. 400 * 401 * Returned status (from utils/Errors.h) can be: 402 * - NO_ERROR: successful operation 403 * - BAD_VALUE: timestamp is NULL 404 */ 405 status_t getTimestamp(ExtendedTimestamp *timestamp); 406 407 /** 408 * @param transferType 409 * @return text string that matches the enum name 410 */ 411 static const char * convertTransferToText(transfer_type transferType); 412 413 /* Returns a handle on the audio input used by this AudioRecord. 414 * 415 * Parameters: 416 * none. 417 * 418 * Returned value: 419 * handle on audio hardware input 420 */ 421 // FIXME The only known public caller is frameworks/opt/net/voip/src/jni/rtp/AudioGroup.cpp getInput()422 audio_io_handle_t getInput() const __attribute__((__deprecated__)) 423 { return getInputPrivate(); } 424 private: 425 audio_io_handle_t getInputPrivate() const; 426 public: 427 428 /* Returns the audio session ID associated with this AudioRecord. 429 * 430 * Parameters: 431 * none. 432 * 433 * Returned value: 434 * AudioRecord session ID. 435 * 436 * No lock needed because session ID doesn't change after first set(). 437 */ getSessionId()438 audio_session_t getSessionId() const { return mSessionId; } 439 440 /* Public API for TRANSFER_OBTAIN mode. 441 * Obtains a buffer of up to "audioBuffer->frameCount" full frames. 442 * After draining these frames of data, the caller should release them with releaseBuffer(). 443 * If the track buffer is not empty, obtainBuffer() returns as many contiguous 444 * full frames as are available immediately. 445 * 446 * If nonContig is non-NULL, it is an output parameter that will be set to the number of 447 * additional non-contiguous frames that are predicted to be available immediately, 448 * if the client were to release the first frames and then call obtainBuffer() again. 449 * This value is only a prediction, and needs to be confirmed. 450 * It will be set to zero for an error return. 451 * 452 * If the track buffer is empty and track is stopped, obtainBuffer() returns WOULD_BLOCK 453 * regardless of the value of waitCount. 454 * If the track buffer is empty and track is not stopped, obtainBuffer() blocks with a 455 * maximum timeout based on waitCount; see chart below. 456 * Buffers will be returned until the pool 457 * is exhausted, at which point obtainBuffer() will either block 458 * or return WOULD_BLOCK depending on the value of the "waitCount" 459 * parameter. 460 * 461 * Interpretation of waitCount: 462 * +n limits wait time to n * WAIT_PERIOD_MS, 463 * -1 causes an (almost) infinite wait time, 464 * 0 non-blocking. 465 * 466 * Buffer fields 467 * On entry: 468 * frameCount number of frames requested 469 * size ignored 470 * raw ignored 471 * sequence ignored 472 * After error return: 473 * frameCount 0 474 * size 0 475 * raw undefined 476 * sequence undefined 477 * After successful return: 478 * frameCount actual number of frames available, <= number requested 479 * size actual number of bytes available 480 * raw pointer to the buffer 481 * sequence IAudioRecord instance sequence number, as of obtainBuffer() 482 */ 483 484 status_t obtainBuffer(Buffer* audioBuffer, int32_t waitCount, 485 size_t *nonContig = NULL); 486 487 // Explicit Routing 488 /** 489 * TODO Document this method. 490 */ 491 status_t setInputDevice(audio_port_handle_t deviceId); 492 493 /** 494 * TODO Document this method. 495 */ 496 audio_port_handle_t getInputDevice(); 497 498 /* Returns the IDs of the audio devices actually used by the input to which this AudioRecord 499 * is attached. 500 * The device IDs is relevant only if the AudioRecord is active. 501 * When the AudioRecord is inactive, the device IDs returned can be either: 502 * - An empty vector if the AudioRecord is not attached to any output. 503 * - The device IDs used before paused or stopped. 504 * - The device ID selected by audio policy manager of setOutputDevice() if the AudioRecord 505 * has not been started yet. 506 * 507 * Parameters: 508 * none. 509 */ 510 DeviceIdVector getRoutedDeviceIds(); 511 512 /* Add an AudioDeviceCallback. The caller will be notified when the audio device 513 * to which this AudioRecord is routed is updated. 514 * Replaces any previously installed callback. 515 * Parameters: 516 * callback: The callback interface 517 * Returns NO_ERROR if successful. 518 * INVALID_OPERATION if the same callback is already installed. 519 * NO_INIT or PREMISSION_DENIED if AudioFlinger service is not reachable 520 * BAD_VALUE if the callback is NULL 521 */ 522 status_t addAudioDeviceCallback( 523 const sp<AudioSystem::AudioDeviceCallback>& callback); 524 525 /* remove an AudioDeviceCallback. 526 * Parameters: 527 * callback: The callback interface 528 * Returns NO_ERROR if successful. 529 * INVALID_OPERATION if the callback is not installed 530 * BAD_VALUE if the callback is NULL 531 */ 532 status_t removeAudioDeviceCallback( 533 const sp<AudioSystem::AudioDeviceCallback>& callback); 534 535 // AudioSystem::AudioDeviceCallback> virtuals 536 virtual void onAudioDeviceUpdate(audio_io_handle_t audioIo, 537 const DeviceIdVector& deviceIds); 538 539 private: 540 /* If nonContig is non-NULL, it is an output parameter that will be set to the number of 541 * additional non-contiguous frames that are predicted to be available immediately, 542 * if the client were to release the first frames and then call obtainBuffer() again. 543 * This value is only a prediction, and needs to be confirmed. 544 * It will be set to zero for an error return. 545 * FIXME We could pass an array of Buffers instead of only one Buffer to obtainBuffer(), 546 * in case the requested amount of frames is in two or more non-contiguous regions. 547 * FIXME requested and elapsed are both relative times. Consider changing to absolute time. 548 */ 549 status_t obtainBuffer(Buffer* audioBuffer, const struct timespec *requested, 550 struct timespec *elapsed = NULL, size_t *nonContig = NULL); 551 public: 552 553 /* Public API for TRANSFER_OBTAIN mode. 554 * Release an emptied buffer of "audioBuffer->frameCount" frames for AudioFlinger to re-fill. 555 * 556 * Buffer fields: 557 * frameCount currently ignored but recommend to set to actual number of frames consumed 558 * size actual number of bytes consumed, must be multiple of frameSize 559 * raw ignored 560 */ 561 void releaseBuffer(const Buffer* audioBuffer); 562 563 /* As a convenience we provide a read() interface to the audio buffer. 564 * Input parameter 'size' is in byte units. 565 * This is implemented on top of obtainBuffer/releaseBuffer. For best 566 * performance use callbacks. Returns actual number of bytes read >= 0, 567 * or one of the following negative status codes: 568 * INVALID_OPERATION AudioRecord is configured for streaming mode 569 * BAD_VALUE size is invalid 570 * WOULD_BLOCK when obtainBuffer() returns same, or 571 * AudioRecord was stopped during the read 572 * or any other error code returned by IAudioRecord::start() or restoreRecord_l(). 573 * Default behavior is to only return when all data has been transferred. Set 'blocking' to 574 * false for the method to return immediately without waiting to try multiple times to read 575 * the full content of the buffer. 576 */ 577 ssize_t read(void* buffer, size_t size, bool blocking = true); 578 579 /* Return the number of input frames lost in the audio driver since the last call of this 580 * function. Audio driver is expected to reset the value to 0 and restart counting upon 581 * returning the current value by this function call. Such loss typically occurs when the 582 * user space process is blocked longer than the capacity of audio driver buffers. 583 * Units: the number of input audio frames. 584 * FIXME The side-effect of resetting the counter may be incompatible with multi-client. 585 * Consider making it more like AudioTrack::getUnderrunFrames which doesn't have side effects. 586 */ 587 uint32_t getInputFramesLost() const; 588 589 /* Get the flags */ getFlags()590 audio_input_flags_t getFlags() const { AutoMutex _l(mLock); return mFlags; } 591 592 /* Get active microphones. A empty vector of MicrophoneInfoFw will be passed as a parameter, 593 * the data will be filled when querying the hal. 594 */ 595 status_t getActiveMicrophones( 596 std::vector<media::MicrophoneInfoFw>* activeMicrophones); 597 598 /* Set the Microphone direction (for processing purposes). 599 */ 600 status_t setPreferredMicrophoneDirection(audio_microphone_direction_t direction); 601 602 /* Set the Microphone zoom factor (for processing purposes). 603 */ 604 status_t setPreferredMicrophoneFieldDimension(float zoom); 605 606 /* Get the unique port ID assigned to this AudioRecord instance by audio policy manager. 607 * The ID is unique across all audioserver clients and can change during the life cycle 608 * of a given AudioRecord instance if the connection to audioserver is restored. 609 */ getPortId()610 audio_port_handle_t getPortId() const { return mPortId; }; 611 612 /* Sets the LogSessionId field which is used for metrics association of 613 * this object with other objects. A nullptr or empty string clears 614 * the logSessionId. 615 */ 616 void setLogSessionId(const char *logSessionId); 617 618 619 status_t shareAudioHistory(const std::string& sharedPackageName, 620 int64_t sharedStartMs); 621 622 /* 623 * Dumps the state of an audio record. 624 */ 625 status_t dump(int fd, const Vector<String16>& args) const; 626 627 private: 628 /* copying audio record objects is not allowed */ 629 AudioRecord(const AudioRecord& other); 630 AudioRecord& operator = (const AudioRecord& other); 631 632 /* a small internal class to handle the callback */ 633 class AudioRecordThread : public Thread 634 { 635 public: 636 AudioRecordThread(AudioRecord& receiver); 637 638 // Do not call Thread::requestExitAndWait() without first calling requestExit(). 639 // Thread::requestExitAndWait() is not virtual, and the implementation doesn't do enough. 640 virtual void requestExit(); 641 642 void pause(); // suspend thread from execution at next loop boundary 643 void resume(); // allow thread to execute, if not requested to exit 644 void wake(); // wake to handle changed notification conditions. 645 646 private: 647 void pauseInternal(nsecs_t ns = 0LL); 648 // like pause(), but only used internally within thread 649 650 friend class AudioRecord; 651 virtual bool threadLoop(); 652 AudioRecord& mReceiver; 653 virtual ~AudioRecordThread(); 654 Mutex mMyLock; // Thread::mLock is private 655 Condition mMyCond; // Thread::mThreadExitedCondition is private 656 bool mPaused; // whether thread is requested to pause at next loop entry 657 bool mPausedInt; // whether thread internally requests pause 658 nsecs_t mPausedNs; // if mPausedInt then associated timeout, otherwise ignored 659 bool mIgnoreNextPausedInt; // skip any internal pause and go immediately 660 // to processAudioBuffer() as state may have changed 661 // since pause time calculated. 662 }; 663 664 // body of AudioRecordThread::threadLoop() 665 // returns the maximum amount of time before we would like to run again, where: 666 // 0 immediately 667 // > 0 no later than this many nanoseconds from now 668 // NS_WHENEVER still active but no particular deadline 669 // NS_INACTIVE inactive so don't run again until re-started 670 // NS_NEVER never again 671 static const nsecs_t NS_WHENEVER = -1, NS_INACTIVE = -2, NS_NEVER = -3; 672 nsecs_t processAudioBuffer(); 673 674 // caller must hold lock on mLock for all _l methods 675 676 status_t createRecord_l(const Modulo<uint32_t> &epoch); 677 678 // FIXME enum is faster than strcmp() for parameter 'from' 679 status_t restoreRecord_l(const char *from); 680 681 void updateRoutedDeviceIds_l(); 682 683 sp<AudioRecordThread> mAudioRecordThread; 684 mutable Mutex mLock; 685 686 std::unique_ptr<RecordingActivityTracker> mTracker; 687 688 // Current client state: false = stopped, true = active. Protected by mLock. If more states 689 // are added, consider changing this to enum State { ... } mState as in AudioTrack. 690 bool mActive = false; 691 692 // for client callback handler 693 694 wp<IAudioRecordCallback> mCallback; 695 sp<IAudioRecordCallback> mLegacyCallbackWrapper; 696 697 bool mInitialized = false; // Protect against double set 698 // for notification APIs 699 uint32_t mNotificationFramesReq; // requested number of frames between each 700 // notification callback 701 // as specified in constructor or set() 702 uint32_t mNotificationFramesAct; // actual number of frames between each 703 // notification callback 704 bool mRefreshRemaining; // processAudioBuffer() should refresh 705 // mRemainingFrames and mRetryOnPartialBuffer 706 707 // These are private to processAudioBuffer(), and are not protected by a lock 708 uint32_t mRemainingFrames; // number of frames to request in obtainBuffer() 709 bool mRetryOnPartialBuffer; // sleep and retry after partial obtainBuffer() 710 uint32_t mObservedSequence; // last observed value of mSequence 711 712 Modulo<uint32_t> mMarkerPosition; // in wrapping (overflow) frame units 713 bool mMarkerReached; 714 Modulo<uint32_t> mNewPosition; // in frames 715 uint32_t mUpdatePeriod; // in frames, zero means no EVENT_NEW_POS 716 717 status_t mStatus = NO_INIT; 718 719 android::content::AttributionSourceState mClientAttributionSource; // Owner's attribution source 720 721 size_t mFrameCount; // corresponds to current IAudioRecord, value is 722 // reported back by AudioFlinger to the client 723 size_t mReqFrameCount; // frame count to request the first or next time 724 // a new IAudioRecord is needed, non-decreasing 725 726 int64_t mFramesRead; // total frames read. reset to zero after 727 // the start() following stop(). It is not 728 // changed after restoring the track. 729 int64_t mFramesReadServerOffset; // An offset to server frames read due to 730 // restoring AudioRecord, or stop/start. 731 // constant after constructor or set() 732 uint32_t mSampleRate; 733 audio_format_t mFormat; 734 uint32_t mChannelCount; 735 size_t mFrameSize; // app-level frame size == AudioFlinger frame size 736 uint32_t mLatency; // in ms 737 audio_channel_mask_t mChannelMask; 738 739 audio_input_flags_t mFlags; // same as mOrigFlags, except for bits that may 740 // be denied by client or server, such as 741 // AUDIO_INPUT_FLAG_FAST. mLock must be 742 // held to read or write those bits reliably. 743 audio_input_flags_t mOrigFlags; // as specified in constructor or set(), const 744 745 audio_session_t mSessionId = AUDIO_SESSION_ALLOCATE; 746 audio_port_handle_t mPortId = AUDIO_PORT_HANDLE_NONE; 747 748 /** 749 * mLogSessionId is a string identifying this AudioRecord for the metrics service. 750 * It may be unique or shared with other objects. An empty string means the 751 * logSessionId is not set. 752 */ 753 std::string mLogSessionId{}; 754 755 transfer_type mTransfer; 756 757 // Next 5 fields may be changed if IAudioRecord is re-created, but always != 0 758 // provided the initial set() was successful 759 sp<media::IAudioRecord> mAudioRecord; 760 sp<IMemory> mCblkMemory; 761 audio_track_cblk_t* mCblk; // re-load after mLock.unlock() 762 sp<IMemory> mBufferMemory; 763 audio_io_handle_t mInput = AUDIO_IO_HANDLE_NONE; // from AudioSystem::getInputforAttr() 764 765 int mPreviousPriority = ANDROID_PRIORITY_NORMAL; // before start() 766 SchedPolicy mPreviousSchedulingGroup = SP_DEFAULT; 767 bool mAwaitBoost = false; // thread should wait for priority boost before running 768 769 // The proxy should only be referenced while a lock is held because the proxy isn't 770 // multi-thread safe. 771 // An exception is that a blocking ClientProxy::obtainBuffer() may be called without a lock, 772 // provided that the caller also holds an extra reference to the proxy and shared memory to keep 773 // them around in case they are replaced during the obtainBuffer(). 774 sp<AudioRecordClientProxy> mProxy; 775 776 bool mInOverrun; // whether recorder is currently in overrun state 777 778 ExtendedTimestamp mPreviousTimestamp{}; // used to detect retrograde motion 779 bool mTimestampRetrogradePositionReported = false; // reduce log spam 780 bool mTimestampRetrogradeTimeReported = false; // reduce log spam 781 782 // Format conversion. Maybe needed for adding fast tracks whose format is different from server. 783 audio_config_base_t mServerConfig; 784 size_t mServerFrameSize; 785 size_t mServerSampleSize; 786 std::unique_ptr<uint8_t[]> mFormatConversionBufRaw; 787 Buffer mFormatConversionBuffer; 788 uint32_t mHalSampleRate; // AudioFlinger thread sample rate 789 uint32_t mHalChannelCount; // AudioFlinger thread channel count 790 audio_format_t mHalFormat; // AudioFlinger thread format 791 792 private: 793 class DeathNotifier : public IBinder::DeathRecipient { 794 public: DeathNotifier(AudioRecord * audioRecord)795 DeathNotifier(AudioRecord* audioRecord) : mAudioRecord(audioRecord) { } 796 protected: 797 virtual void binderDied(const wp<IBinder>& who); 798 private: 799 const wp<AudioRecord> mAudioRecord; 800 }; 801 802 sp<DeathNotifier> mDeathNotifier; 803 uint32_t mSequence; // incremented for each new IAudioRecord attempt 804 audio_attributes_t mAttributes; 805 806 // For Device Selection API 807 // a value of AUDIO_PORT_HANDLE_NONE indicated default (AudioPolicyManager) routing. 808 809 // Device requested by the application. 810 audio_port_handle_t mSelectedDeviceId = AUDIO_PORT_HANDLE_NONE; 811 // Device actually selected by AudioPolicyManager: This may not match the app 812 // selection depending on other activity and connected devices 813 DeviceIdVector mRoutedDeviceIds; 814 815 wp<AudioSystem::AudioDeviceCallback> mDeviceCallback; 816 817 audio_microphone_direction_t mSelectedMicDirection = MIC_DIRECTION_UNSPECIFIED; 818 float mSelectedMicFieldDimension = MIC_FIELD_DIMENSION_DEFAULT; 819 820 int32_t mMaxSharedAudioHistoryMs = 0; 821 std::string mSharedAudioPackageName = {}; 822 int64_t mSharedAudioStartMs = 0; 823 824 private: 825 class MediaMetrics { 826 public: MediaMetrics()827 MediaMetrics() : mMetricsItem(mediametrics::Item::create("audiorecord")), 828 mCreatedNs(systemTime(SYSTEM_TIME_REALTIME)), 829 mStartedNs(0), mDurationNs(0), mCount(0), 830 mLastError(NO_ERROR) { 831 } ~MediaMetrics()832 ~MediaMetrics() { 833 // mMetricsItem alloc failure will be flagged in the constructor 834 // don't log empty records 835 if (mMetricsItem->count() > 0) { 836 mMetricsItem->selfrecord(); 837 } 838 } 839 void gather(const AudioRecord *record); dup()840 mediametrics::Item *dup() { return mMetricsItem->dup(); } 841 logStart(nsecs_t when)842 void logStart(nsecs_t when) { mStartedNs = when; mCount++; } logStop(nsecs_t when)843 void logStop(nsecs_t when) { mDurationNs += (when-mStartedNs); mStartedNs = 0;} markError(status_t errcode,const char * func)844 void markError(status_t errcode, const char *func) 845 { mLastError = errcode; mLastErrorFunc = func;} 846 private: 847 std::unique_ptr<mediametrics::Item> mMetricsItem; 848 nsecs_t mCreatedNs; // XXX: perhaps not worth it in production 849 nsecs_t mStartedNs; 850 nsecs_t mDurationNs; 851 int32_t mCount; 852 853 status_t mLastError; 854 std::string mLastErrorFunc; 855 }; 856 MediaMetrics mMediaMetrics; 857 std::string mMetricsId; // GUARDED_BY(mLock), could change in createRecord_l(). 858 std::string mCallerName; // for example "aaudio" 859 860 void reportError(status_t status, const char *event, const char *message) const; 861 }; 862 863 }; // namespace android 864 865 #endif // ANDROID_AUDIORECORD_H 866