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