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 /* Set parameters */ 593 status_t setParameters(const String8& keyValuePairs); 594 595 /* Get parameters */ 596 String8 getParameters(const String8& keys); 597 598 /* Get active microphones. A empty vector of MicrophoneInfoFw will be passed as a parameter, 599 * the data will be filled when querying the hal. 600 */ 601 status_t getActiveMicrophones( 602 std::vector<media::MicrophoneInfoFw>* activeMicrophones); 603 604 /* Set the Microphone direction (for processing purposes). 605 */ 606 status_t setPreferredMicrophoneDirection(audio_microphone_direction_t direction); 607 608 /* Set the Microphone zoom factor (for processing purposes). 609 */ 610 status_t setPreferredMicrophoneFieldDimension(float zoom); 611 612 /* Get the unique port ID assigned to this AudioRecord instance by audio policy manager. 613 * The ID is unique across all audioserver clients and can change during the life cycle 614 * of a given AudioRecord instance if the connection to audioserver is restored. 615 */ getPortId()616 audio_port_handle_t getPortId() const { return mPortId; }; 617 618 /* Sets the LogSessionId field which is used for metrics association of 619 * this object with other objects. A nullptr or empty string clears 620 * the logSessionId. 621 */ 622 void setLogSessionId(const char *logSessionId); 623 624 625 status_t shareAudioHistory(const std::string& sharedPackageName, 626 int64_t sharedStartMs); 627 628 /* 629 * Dumps the state of an audio record. 630 */ 631 status_t dump(int fd, const Vector<String16>& args) const; 632 633 private: 634 /* copying audio record objects is not allowed */ 635 AudioRecord(const AudioRecord& other); 636 AudioRecord& operator = (const AudioRecord& other); 637 638 /* a small internal class to handle the callback */ 639 class AudioRecordThread : public Thread 640 { 641 public: 642 AudioRecordThread(AudioRecord& receiver); 643 644 // Do not call Thread::requestExitAndWait() without first calling requestExit(). 645 // Thread::requestExitAndWait() is not virtual, and the implementation doesn't do enough. 646 virtual void requestExit(); 647 648 void pause(); // suspend thread from execution at next loop boundary 649 void resume(); // allow thread to execute, if not requested to exit 650 void wake(); // wake to handle changed notification conditions. 651 652 private: 653 void pauseInternal(nsecs_t ns = 0LL); 654 // like pause(), but only used internally within thread 655 656 friend class AudioRecord; 657 virtual bool threadLoop(); 658 AudioRecord& mReceiver; 659 virtual ~AudioRecordThread(); 660 Mutex mMyLock; // Thread::mLock is private 661 Condition mMyCond; // Thread::mThreadExitedCondition is private 662 bool mPaused; // whether thread is requested to pause at next loop entry 663 bool mPausedInt; // whether thread internally requests pause 664 nsecs_t mPausedNs; // if mPausedInt then associated timeout, otherwise ignored 665 bool mIgnoreNextPausedInt; // skip any internal pause and go immediately 666 // to processAudioBuffer() as state may have changed 667 // since pause time calculated. 668 }; 669 670 // body of AudioRecordThread::threadLoop() 671 // returns the maximum amount of time before we would like to run again, where: 672 // 0 immediately 673 // > 0 no later than this many nanoseconds from now 674 // NS_WHENEVER still active but no particular deadline 675 // NS_INACTIVE inactive so don't run again until re-started 676 // NS_NEVER never again 677 static const nsecs_t NS_WHENEVER = -1, NS_INACTIVE = -2, NS_NEVER = -3; 678 nsecs_t processAudioBuffer(); 679 680 // caller must hold lock on mLock for all _l methods 681 682 status_t createRecord_l(const Modulo<uint32_t> &epoch); 683 684 // FIXME enum is faster than strcmp() for parameter 'from' 685 status_t restoreRecord_l(const char *from); 686 687 void updateRoutedDeviceIds_l(); 688 689 sp<AudioRecordThread> mAudioRecordThread; 690 mutable Mutex mLock; 691 692 std::unique_ptr<RecordingActivityTracker> mTracker; 693 694 // Current client state: false = stopped, true = active. Protected by mLock. If more states 695 // are added, consider changing this to enum State { ... } mState as in AudioTrack. 696 bool mActive = false; 697 698 // for client callback handler 699 700 wp<IAudioRecordCallback> mCallback; 701 702 bool mInitialized = false; // Protect against double set 703 // for notification APIs 704 uint32_t mNotificationFramesReq; // requested number of frames between each 705 // notification callback 706 // as specified in constructor or set() 707 uint32_t mNotificationFramesAct; // actual number of frames between each 708 // notification callback 709 bool mRefreshRemaining; // processAudioBuffer() should refresh 710 // mRemainingFrames and mRetryOnPartialBuffer 711 712 // These are private to processAudioBuffer(), and are not protected by a lock 713 uint32_t mRemainingFrames; // number of frames to request in obtainBuffer() 714 bool mRetryOnPartialBuffer; // sleep and retry after partial obtainBuffer() 715 uint32_t mObservedSequence; // last observed value of mSequence 716 717 Modulo<uint32_t> mMarkerPosition; // in wrapping (overflow) frame units 718 bool mMarkerReached; 719 Modulo<uint32_t> mNewPosition; // in frames 720 uint32_t mUpdatePeriod; // in frames, zero means no EVENT_NEW_POS 721 722 status_t mStatus = NO_INIT; 723 724 android::content::AttributionSourceState mClientAttributionSource; // Owner's attribution source 725 726 size_t mFrameCount; // corresponds to current IAudioRecord, value is 727 // reported back by AudioFlinger to the client 728 size_t mReqFrameCount; // frame count to request the first or next time 729 // a new IAudioRecord is needed, non-decreasing 730 731 int64_t mFramesRead; // total frames read. reset to zero after 732 // the start() following stop(). It is not 733 // changed after restoring the track. 734 int64_t mFramesReadServerOffset; // An offset to server frames read due to 735 // restoring AudioRecord, or stop/start. 736 // constant after constructor or set() 737 uint32_t mSampleRate; 738 audio_format_t mFormat; 739 uint32_t mChannelCount; 740 size_t mFrameSize; // app-level frame size == AudioFlinger frame size 741 uint32_t mLatency; // in ms 742 audio_channel_mask_t mChannelMask; 743 744 audio_input_flags_t mFlags; // same as mOrigFlags, except for bits that may 745 // be denied by client or server, such as 746 // AUDIO_INPUT_FLAG_FAST. mLock must be 747 // held to read or write those bits reliably. 748 audio_input_flags_t mOrigFlags; // as specified in constructor or set(), const 749 750 audio_session_t mSessionId = AUDIO_SESSION_ALLOCATE; 751 audio_port_handle_t mPortId = AUDIO_PORT_HANDLE_NONE; 752 753 /** 754 * mLogSessionId is a string identifying this AudioRecord for the metrics service. 755 * It may be unique or shared with other objects. An empty string means the 756 * logSessionId is not set. 757 */ 758 std::string mLogSessionId{}; 759 760 transfer_type mTransfer; 761 762 // Next 5 fields may be changed if IAudioRecord is re-created, but always != 0 763 // provided the initial set() was successful 764 sp<media::IAudioRecord> mAudioRecord; 765 sp<IMemory> mCblkMemory; 766 audio_track_cblk_t* mCblk; // re-load after mLock.unlock() 767 sp<IMemory> mBufferMemory; 768 audio_io_handle_t mInput = AUDIO_IO_HANDLE_NONE; // from AudioSystem::getInputforAttr() 769 770 int mPreviousPriority = ANDROID_PRIORITY_NORMAL; // before start() 771 SchedPolicy mPreviousSchedulingGroup = SP_DEFAULT; 772 bool mAwaitBoost = false; // thread should wait for priority boost before running 773 774 // The proxy should only be referenced while a lock is held because the proxy isn't 775 // multi-thread safe. 776 // An exception is that a blocking ClientProxy::obtainBuffer() may be called without a lock, 777 // provided that the caller also holds an extra reference to the proxy and shared memory to keep 778 // them around in case they are replaced during the obtainBuffer(). 779 sp<AudioRecordClientProxy> mProxy; 780 781 bool mInOverrun; // whether recorder is currently in overrun state 782 783 ExtendedTimestamp mPreviousTimestamp{}; // used to detect retrograde motion 784 bool mTimestampRetrogradePositionReported = false; // reduce log spam 785 bool mTimestampRetrogradeTimeReported = false; // reduce log spam 786 787 // Format conversion. Maybe needed for adding fast tracks whose format is different from server. 788 audio_config_base_t mServerConfig; 789 size_t mServerFrameSize; 790 size_t mServerSampleSize; 791 std::unique_ptr<uint8_t[]> mFormatConversionBufRaw; 792 Buffer mFormatConversionBuffer; 793 uint32_t mHalSampleRate; // AudioFlinger thread sample rate 794 uint32_t mHalChannelCount; // AudioFlinger thread channel count 795 audio_format_t mHalFormat; // AudioFlinger thread format 796 797 private: 798 class DeathNotifier : public IBinder::DeathRecipient { 799 public: DeathNotifier(AudioRecord * audioRecord)800 DeathNotifier(AudioRecord* audioRecord) : mAudioRecord(audioRecord) { } 801 protected: 802 virtual void binderDied(const wp<IBinder>& who); 803 private: 804 const wp<AudioRecord> mAudioRecord; 805 }; 806 807 sp<DeathNotifier> mDeathNotifier; 808 uint32_t mSequence; // incremented for each new IAudioRecord attempt 809 audio_attributes_t mAttributes; 810 811 // For Device Selection API 812 // a value of AUDIO_PORT_HANDLE_NONE indicated default (AudioPolicyManager) routing. 813 814 // Device requested by the application. 815 audio_port_handle_t mSelectedDeviceId = AUDIO_PORT_HANDLE_NONE; 816 // Device actually selected by AudioPolicyManager: This may not match the app 817 // selection depending on other activity and connected devices 818 DeviceIdVector mRoutedDeviceIds; 819 820 wp<AudioSystem::AudioDeviceCallback> mDeviceCallback; 821 822 audio_microphone_direction_t mSelectedMicDirection = MIC_DIRECTION_UNSPECIFIED; 823 float mSelectedMicFieldDimension = MIC_FIELD_DIMENSION_DEFAULT; 824 825 int32_t mMaxSharedAudioHistoryMs = 0; 826 std::string mSharedAudioPackageName = {}; 827 int64_t mSharedAudioStartMs = 0; 828 829 private: 830 class MediaMetrics { 831 public: MediaMetrics()832 MediaMetrics() : mMetricsItem(mediametrics::Item::create("audiorecord")), 833 mCreatedNs(systemTime(SYSTEM_TIME_REALTIME)), 834 mStartedNs(0), mDurationNs(0), mCount(0), 835 mLastError(NO_ERROR) { 836 } ~MediaMetrics()837 ~MediaMetrics() { 838 // mMetricsItem alloc failure will be flagged in the constructor 839 // don't log empty records 840 if (mMetricsItem->count() > 0) { 841 mMetricsItem->selfrecord(); 842 } 843 } 844 void gather(const AudioRecord *record); dup()845 mediametrics::Item *dup() { return mMetricsItem->dup(); } 846 logStart(nsecs_t when)847 void logStart(nsecs_t when) { mStartedNs = when; mCount++; } logStop(nsecs_t when)848 void logStop(nsecs_t when) { mDurationNs += (when-mStartedNs); mStartedNs = 0;} markError(status_t errcode,const char * func)849 void markError(status_t errcode, const char *func) 850 { mLastError = errcode; mLastErrorFunc = func;} 851 private: 852 std::unique_ptr<mediametrics::Item> mMetricsItem; 853 nsecs_t mCreatedNs; // XXX: perhaps not worth it in production 854 nsecs_t mStartedNs; 855 nsecs_t mDurationNs; 856 int32_t mCount; 857 858 status_t mLastError; 859 std::string mLastErrorFunc; 860 }; 861 MediaMetrics mMediaMetrics; 862 std::string mMetricsId; // GUARDED_BY(mLock), could change in createRecord_l(). 863 std::string mCallerName; // for example "aaudio" 864 865 void reportError(status_t status, const char *event, const char *message) const; 866 }; 867 868 }; // namespace android 869 870 #endif // ANDROID_AUDIORECORD_H 871