1 /*
2  * Copyright (c) 2021-2023 Huawei Device Co., Ltd.
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at
6  *
7  *     http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15 
16 #ifndef AUDIO_CAPTURER_H
17 #define AUDIO_CAPTURER_H
18 
19 #include <memory>
20 
21 #include "audio_info.h"
22 #include "microphone_descriptor.h"
23 #include "timestamp.h"
24 
25 namespace OHOS {
26 namespace AudioStandard {
27 /**
28  * @brief Defines information about audio capturer parameters
29  * @since 8
30  */
31 struct AudioCapturerParams {
32     /** Audio source type */
33     AudioSourceType inputSource = AUDIO_MIC;
34     /** Audio codec format */
35     AudioEncodingType audioEncoding = ENCODING_PCM;
36     /** Sampling rate */
37     AudioSamplingRate samplingRate = SAMPLE_RATE_44100;
38     /** Number of audio channels */
39     AudioChannel audioChannel = MONO;
40     /** Audio stream type */
41     AudioStreamType streamType = STREAM_MEDIA;
42     /** audioSampleFormat */
43     AudioSampleFormat audioSampleFormat = SAMPLE_S16LE;
44     /** Audio Channel Layout */
45     AudioChannelLayout channelLayout = CH_LAYOUT_UNKNOWN;
46 };
47 
48 class AudioCapturerCallback {
49 public:
50     virtual ~AudioCapturerCallback() = default;
51 
52     /**
53      * Called when an interrupt is received.
54      *
55      * @param interruptEvent Indicates the InterruptEvent information needed by client.
56      * For details, refer InterruptEvent struct in audio_info.h
57      * @since 10
58      */
59     virtual void OnInterrupt(const InterruptEvent &interruptEvent) = 0;
60 
61     /**
62     * Called when renderer state is updated.
63      *
64      * @param state Indicates updated state of the capturer.
65      * For details, refer enum CapturerState.
66      * @since 8
67      */
68     virtual void OnStateChange(const CapturerState state) = 0;
69 };
70 
71 class CapturerPositionCallback {
72 public:
73     virtual ~CapturerPositionCallback() = default;
74 
75     /**
76      * Called when the requested frame number is read.
77      *
78      * @param framePosition requested frame position.
79      * @since 8
80      */
81     virtual void OnMarkReached(const int64_t &framePosition) = 0;
82 };
83 
84 class CapturerPeriodPositionCallback {
85 public:
86     virtual ~CapturerPeriodPositionCallback() = default;
87 
88     /**
89      * Called when the requested frame count is read.
90      *
91      * @param frameCount requested frame frame count for callback.
92      * @since 8
93      */
94     virtual void OnPeriodReached(const int64_t &frameNumber) = 0;
95 };
96 
97 class AudioCapturerReadCallback {
98 public:
99     virtual ~AudioCapturerReadCallback() = default;
100 
101     /**
102      * Called when buffer to be enqueued.
103      *
104      * @param length Indicates requested buffer length.
105      * @since 9
106      */
107     virtual void OnReadData(size_t length) = 0;
108 };
109 
110 class AudioCapturerDeviceChangeCallback {
111 public:
112     virtual ~AudioCapturerDeviceChangeCallback() = default;
113 
114     /**
115      * Called when capturer device is updated.
116      *
117      * @param state Indicates updated device of the capturer.
118      * since 11
119      */
120     virtual void OnStateChange(const DeviceInfo &deviceInfo) = 0;
121 };
122 
123 class AudioCapturerInfoChangeCallback {
124 public:
125     virtual ~AudioCapturerInfoChangeCallback() = default;
126 
127     /**
128      * Called when capturer info is updated.
129      *
130      * @param state Indicates info of the capturer.
131      * since 11
132      */
133     virtual void OnStateChange(const AudioCapturerChangeInfo &capturerChangeInfo) = 0;
134 };
135 
136 /**
137  * @brief Provides functions for applications to implement audio capturing.
138  */
139 class AudioCapturer {
140 public:
141     /**
142      * @brief create capturer instance.
143      *
144      * @param options The audio capturer configuration to be used while creating capturer instance.
145      * refer AudioCapturerOptions in audio_info.h.
146      * @return Returns unique pointer to the AudioCapturer object
147      * @since 8
148      */
149     static std::unique_ptr<AudioCapturer> Create(AudioStreamType audioStreamType);
150 
151     /**
152      * @brief create capturer instance.
153      *
154      * @param options The audio capturer configuration to be used while creating capturer instance.
155      * refer AudioCapturerOptions in audio_info.h.
156      * @param appInfo Originating application's uid and token id can be passed here
157      * @return Returns unique pointer to the AudioCapturer object
158      * @since 9
159      */
160     static std::unique_ptr<AudioCapturer> Create(AudioStreamType audioStreamType, const AppInfo &appInfo);
161 
162     /**
163      * @brief create capturer instance.
164      *
165      * @param options The audio capturer configuration to be used while creating capturer instance.
166      * refer AudioCapturerOptions in audio_info.h.
167      * @return Returns unique pointer to the AudioCapturer object
168      * @since 8
169      */
170     static std::unique_ptr<AudioCapturer> Create(const AudioCapturerOptions &options);
171 
172     /**
173      * @brief create capturer instance.
174      *
175      * @param options The audio capturer configuration to be used while creating capturer instance.
176      * refer AudioCapturerOptions in audio_info.h.
177      * @param appInfo Originating application's uid and token id can be passed here
178      * @return Returns unique pointer to the AudioCapturer object
179      * @since 9
180      */
181     static std::unique_ptr<AudioCapturer> Create(const AudioCapturerOptions &options, const AppInfo &appInfo);
182 
183     /**
184      * @brief create capturer instance.
185      *
186      * @param options The audio capturer configuration to be used while creating capturer instance.
187      * refer AudioCapturerOptions in audio_info.h.
188      * @param cachePath Application cache path
189      * @return Returns unique pointer to the AudioCapturer object
190      * @since 9
191      */
192     static std::unique_ptr<AudioCapturer> Create(const AudioCapturerOptions &options, const std::string cachePath);
193 
194     /**
195      * @brief create capturer instance.
196      *
197      * @param capturerOptions The audio capturer configuration to be used while creating capturer instance.
198      * refer AudioCapturerOptions in audio_info.h.
199      * @param cachePath Application cache path
200      * @param appInfo Originating application's uid and token id can be passed here
201      * @return Returns unique pointer to the AudioCapturer object
202      * @since 9
203      */
204     static std::unique_ptr<AudioCapturer> Create(const AudioCapturerOptions &options, const std::string cachePath,
205         const AppInfo &appInfo);
206 
207     /**
208      * @brief Sets audio capture parameters.
209      *
210      * @param params Indicates information about audio capture parameters to set. For details, see
211      * {@link AudioCapturerParams}.
212      * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined
213      * in {@link audio_errors.h} otherwise.
214      * @since 8
215      */
216     virtual int32_t SetParams(const AudioCapturerParams params) = 0;
217 
218     /**
219      * @brief Update AudioPlaybackCaptureConfig, only for Inner-Cap records.
220      *
221      * @param config Indicates information about audio capture parameters to set. For details, see
222      * {@link CaptureFilterOptions}.
223      * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined
224      * in {@link audio_errors.h} otherwise.
225      * @since 12
226      */
227     virtual int32_t UpdatePlaybackCaptureConfig(const AudioPlaybackCaptureConfig &config) = 0;
228 
229     /**
230      * @brief Registers the capturer callback listener.
231      * (1)If old SetParams(const AudioCapturerParams params) API,
232      *    this API must be called immediately after SetParams.
233      * (2) Else if using Create(const AudioCapturerOptions &capturerOptions),
234      *    this API must be called immediately  after Create.
235      *
236      * @return Returns {@link SUCCESS} if callback registration is successful; returns an error code
237      * defined in {@link audio_errors.h} otherwise.
238      * @since 8
239      */
240     virtual int32_t SetCapturerCallback(const std::shared_ptr<AudioCapturerCallback> &callback) = 0;
241 
242     /**
243      * @brief Obtains audio capturer parameters.
244      *
245      * This function can be called after {@link SetParams} is successful.
246      *
247      * @param params Indicates information about audio capturer parameters.For details,see
248      * {@link AudioCapturerParams}.
249      * @return Returns {@link SUCCESS} if the parameter information is successfully obtained; returns an error code
250      * defined in {@link audio_errors.h} otherwise.
251      * @since 8
252      */
253     virtual int32_t GetParams(AudioCapturerParams &params) const = 0;
254 
255     /**
256      * @brief Obtains audio capturer information.
257      *
258      * This function can be called after {@link SetParams} is successful.
259      *
260      * @param capturerInfo Indicates information about audio capturer information.For details,see
261      * {@link AudioCapturerInfo}.
262      * @return Returns {@link SUCCESS} if the parameter information is successfully obtained; returns an error code
263      * defined in {@link audio_errors.h} otherwise.
264      * @since 8
265      */
266     virtual int32_t GetCapturerInfo(AudioCapturerInfo &capturerInfo) const = 0;
267 
268     /**
269      * @brief Obtains audio stream information.
270      *
271      * This function can be called after {@link Create} is successful.
272      *
273      * @param streamInfo Indicates information about audio stream information.For details,see
274      * {@link AudioStreamInfo}.
275      * @return Returns {@link SUCCESS} if the parameter information is successfully obtained; returns an error code
276      * defined in {@link audio_errors.h} otherwise.
277      * @since 8
278      */
279     virtual int32_t GetStreamInfo(AudioStreamInfo &streamInfo) const = 0;
280 
281     /**
282      * @brief Starts audio capturing.
283      *
284      * @return Returns <b>true</b> if the capturing is successfully started; returns <b>false</b> otherwise.
285      * @since 8
286      */
287     virtual bool Start() const = 0;
288 
289     /**
290      * @brief capture audio data.
291      *
292      * @param buffer Indicates the pointer to the buffer into which the audio data is to be written.
293      * @param userSize Indicates the size of the buffer into which the audio data is to be written, in bytes.
294      * <b>userSize >= frameCount * channelCount * BytesPerSample</b> must evaluate to <b>true</b>. You can call
295      * {@link GetFrameCount} to obtain the <b>frameCount</b> value.
296      * @param isBlockingRead Specifies whether data reading will be blocked.
297      * @return Returns the size of the audio data read from the device. The value ranges from <b>0</b> to
298      * <b>userSize</b>. If the reading fails, one of the following error codes is returned.
299      * <b>ERR_INVALID_PARAM</b>: The input parameter is incorrect.
300      * <b>ERR_ILLEGAL_STATE</b>: The <b>AudioCapturer</b> instance is not initialized.
301      * <b>ERR_INVALID_READ</b>: The read size < 0.
302      * @since 8
303      */
304     virtual int32_t Read(uint8_t &buffer, size_t userSize, bool isBlockingRead) const = 0;
305 
306     /**
307      * @brief Obtains the audio capture state.
308      *
309      * @return Returns the audio capture state defined in {@link CapturerState}.
310      * @since 9
311      */
312     virtual CapturerState GetStatus() const = 0;
313 
314     /**
315      * @brief Obtains the Timestamp.
316      *
317      * @param timestamp Indicates a {@link Timestamp} instance reference provided by the caller.
318      * @param base Indicates the time base, which can be {@link Timestamp.Timestampbase#BOOTTIME} or
319      * {@link Timestamp.Timestampbase#MONOTONIC}.
320      * @return Returns <b>true</b> if the timestamp is successfully obtained; returns <b>false</b> otherwise.
321      * @since 8
322      */
323     virtual bool GetAudioTime(Timestamp &timestamp, Timestamp::Timestampbase base) const = 0;
324 
325     /**
326      * @brief Pause audio capturing.
327      *
328      * @return Returns <b>true</b> if the capturing is successfully Paused; returns <b>false</b> otherwise.
329      * @since 9
330      */
331     virtual bool Pause() const = 0;
332 
333     /**
334      * @brief Stops audio capturing.
335      *
336      * @return Returns <b>true</b> if the capturing is successfully stopped; returns <b>false</b> otherwise.
337      * @since 8
338      */
339     virtual bool Stop() const = 0;
340     /**
341      * @brief flush capture stream.
342      *
343      * @return Returns <b>true</b> if the object is successfully flushed; returns <b>false</b> otherwise.
344      * @since 8
345      */
346     virtual bool Flush() const = 0;
347 
348     /**
349      * @brief Releases a local <b>AudioCapturer</b> object.
350      *
351      * @return Returns <b>true</b> if the object is successfully released; returns <b>false</b> otherwise.
352      * @since 8
353      */
354     virtual bool Release() = 0;
355 
356     /**
357      * @brief Obtains a reasonable minimum buffer size for capturer, however, the capturer can
358      *        accept other read sizes as well.
359      *
360      * @param bufferSize Indicates a buffersize pointer value that wil be written.
361      * @return Returns {@link SUCCESS} if bufferSize is successfully obtained; returns an error code
362      * @since 8
363      * defined in {@link audio_errors.h} otherwise.
364      */
365     virtual int32_t GetBufferSize(size_t &bufferSize) const = 0;
366 
367     /**
368      * @brief Obtains the capturer stream id.
369      *
370      * @param sessionId Indicates the reference variable into which stream id value will be written.
371      * @return Returns {@link SUCCESS} if stream id is successfully obtained; returns an error code
372      * defined in {@link audio_errors.h} otherwise.
373      * @since 10
374      */
375     virtual int32_t GetAudioStreamId(uint32_t &sessionID) const = 0;
376 
377     /* @brief Obtains the number of frames required in the current condition, in bytes per sample.
378      *
379      * @param frameCount Indicates the pointer in which framecount will be written
380      * @return Returns {@link SUCCESS} if frameCount is successfully obtained; returns an error code
381      * defined in {@link audio_errors.h} otherwise.
382      * @since 8
383      */
384 
385     virtual int32_t GetFrameCount(uint32_t &frameCount) const = 0;
386     /**
387      * @brief Registers the capturer position callback listener
388      *
389      * @return Returns {@link SUCCESS} if callback registration is successful; returns an error code
390      * defined in {@link audio_errors.h} otherwise.
391      * @since 8
392      */
393 
394     virtual int32_t SetCapturerPositionCallback(int64_t markPosition,
395         const std::shared_ptr<CapturerPositionCallback> &callback) = 0;
396 
397     /**
398      * @brief Unregisters the capturer position callback listener
399      *
400      * @since 8
401      */
402     virtual void UnsetCapturerPositionCallback() = 0;
403 
404     /**
405      * @brief Registers the capturer period position callback listener
406      *
407      * @return Returns {@link SUCCESS} if callback registration is successful; returns an error code
408      * defined in {@link audio_errors.h} otherwise.
409      * @since 8
410      */
411     virtual int32_t SetCapturerPeriodPositionCallback(int64_t frameNumber,
412         const std::shared_ptr<CapturerPeriodPositionCallback> &callback) = 0;
413 
414     /**
415      * @brief Unregisters the capturer period position callback listener
416      *
417      * @since 8
418      */
419     virtual void UnsetCapturerPeriodPositionCallback() = 0;
420 
421     /**
422      * @brief set the buffer duration for capturer, minimum buffer duration is 5msec
423      *         maximum is 20msec
424      *
425      * @param bufferDuration  Indicates a buffer duration to be set for capturer
426      * @return Returns {@link SUCCESS} if bufferDuration is successfully set; returns an error code
427      * defined in {@link audio_errors.h} otherwise.
428      * @since 8
429      */
430     virtual int32_t SetBufferDuration(uint64_t bufferDuration) const = 0;
431 
432     /**
433      * @brief Set the application cache path to access the application resources
434      *
435      * @param cachePath Indicates application cache path.
436      * @return none
437      * @since 8
438      */
439     virtual void SetApplicationCachePath(const std::string cachePath) = 0;
440 
441     /**
442      * @brief Obtains the capturer supported formats.
443      *
444      * @return vector with capturer supported formats.
445      * @since 8
446      */
447     static std::vector<AudioSampleFormat> GetSupportedFormats();
448 
449     /**
450      * @brief Obtains the capturer supported channels.
451      *
452      * @return vector with capturer supported channels.
453      * @since 8
454      */
455     static std::vector<AudioChannel> GetSupportedChannels();
456 
457     /**
458      * @brief Obtains the capturer supported encoding types.
459      *
460      * @return vector with capturer supported encoding types.
461      * @since 8
462      */
463     static std::vector<AudioEncodingType> GetSupportedEncodingTypes();
464 
465     /**
466      * @brief Obtains the capturer supported SupportedSamplingRates.
467      *
468      * @return vector with capturer supported SupportedSamplingRates.
469      * @since 8
470      */
471     static std::vector<AudioSamplingRate> GetSupportedSamplingRates();
472 
473     /**
474      * @brief Sets the capture mode. By default the mode is CAPTURE_MODE_NORMAL.
475      * This API is needs to be used only if CAPTURE_MODE_CALLBACK is required.
476      *
477      * * @param captureMode The mode of capture.
478      * @return  Returns {@link SUCCESS} if capture mode is successfully set; returns an error code
479      * defined in {@link audio_errors.h} otherwise.
480      * @since 9
481      */
482     virtual int32_t SetCaptureMode(AudioCaptureMode captureMode) = 0;
483 
484     /**
485      * @brief Obtains the capture mode.
486      *
487      * @return  Returns current capture mode.
488      * @since 9
489      */
490     virtual AudioCaptureMode GetCaptureMode() const = 0;
491 
492     /**
493      * @brief Registers the capturer read callback listener.
494      * This API should only be used if CAPTURE_MODE_CALLBACK is needed.
495      *
496      * @return Returns {@link SUCCESS} if callback registration is successful; returns an error code
497      * defined in {@link audio_errors.h} otherwise.
498      * @since 9
499      */
500     virtual int32_t SetCapturerReadCallback(const std::shared_ptr<AudioCapturerReadCallback> &callback) = 0;
501 
502     /**
503      * @brief Gets the BufferDesc to read the data.
504      * This API should only be used if CAPTURE_MODE_CALLBACK is needed.
505      *
506      * @param bufDesc Indicates the buffer descriptor from which data will be read.
507      * refer BufferQueueState in audio_info.h.
508      * @return Returns {@link SUCCESS} if bufDesc is successfully obtained; returns an error code
509      * defined in {@link audio_errors.h} otherwise.
510      * @since 9
511      */
512     virtual int32_t GetBufferDesc(BufferDesc &bufDesc) const = 0;
513 
514     /**
515      * @brief Enqueues used buffer to the bufferQueue for recording new data.
516      * This API should only be used if CAPTURE_MODE_CALLBACK is needed.
517      *
518      * @return Returns {@link SUCCESS} if bufDesc is successfully enqueued; returns an error code
519      * defined in {@link audio_errors.h} otherwise.
520      * @since 9
521      */
522     virtual int32_t Enqueue(const BufferDesc &bufDesc) const = 0;
523 
524     /**
525      * @brief Clears the bufferQueue.
526      * This API should only be used if CAPTURE_MODE_CALLBACK is needed.
527      *
528      * @return Returns {@link SUCCESS} if successful; returns an error code
529      * defined in {@link audio_errors.h} otherwise.
530      * @since 9
531      */
532     virtual int32_t Clear() const = 0;
533 
534     /**
535      * @brief Obtains the current state of bufferQueue.
536      * This API should only be used if CAPTURE_MODE_CALLBACK is needed.
537      *
538      * @param bufDesc Indicates the bufState reference in which state will be obtained.
539      * refer BufferQueueState in audio_info.h.
540      * @return Returns {@link SUCCESS} if bufState is successfully obtained; returns an error code
541      * defined in {@link audio_errors.h} otherwise.
542      * @since 9
543      */
544     virtual int32_t GetBufQueueState(BufferQueueState &bufState) const = 0;
545 
546     /**
547      * @brief Set audiocapture valid state.
548      *
549      * @param valid Valid or not.
550      * @since 10
551      */
552     virtual void SetValid(bool valid) = 0;
553 
554     /**
555      * @brief Gets the audio frame size that has been read.
556      *
557      * @return Returns the audio frame size that has been read.
558      * @since 10
559      */
560     virtual int64_t GetFramesRead() const = 0;
561 
562     /**
563      * @brief Sets the audio device change callback.
564      *
565      * @return Returns {@link SUCCESS} if callback registration is successful; returns an error code
566      * defined in {@link audio_errors.h} otherwise.
567      * @since 11
568      */
569     virtual int32_t SetAudioCapturerDeviceChangeCallback(
570         const std::shared_ptr<AudioCapturerDeviceChangeCallback> &callback) = 0;
571 
572     /**
573      * @brief Unsets the audio device change callback.
574      *
575      * @return Returns {@link SUCCESS} if callback remove is successful; returns an error code
576      * defined in {@link audio_errors.h} otherwise.
577      * @since 11
578      */
579     virtual int32_t RemoveAudioCapturerDeviceChangeCallback(
580         const std::shared_ptr<AudioCapturerDeviceChangeCallback> &callback) = 0;
581 
582     /**
583      * @brief Sets the audio capturer info change callback.
584      *
585      * @return Returns {@link SUCCESS} if callback registration is successful; returns an error code
586      * defined in {@link audio_errors.h} otherwise.
587      * @since 11
588      */
589     virtual int32_t SetAudioCapturerInfoChangeCallback(
590         const std::shared_ptr<AudioCapturerInfoChangeCallback> &callback) = 0;
591 
592     /**
593      * @brief Removes the audio capturer info change callback.
594      *
595      * @return Returns {@link SUCCESS} if callback registration is successful; returns an error code
596      * defined in {@link audio_errors.h} otherwise.
597      * @since 11
598      */
599     virtual int32_t RemoveAudioCapturerInfoChangeCallback(
600         const std::shared_ptr<AudioCapturerInfoChangeCallback> &callback) = 0;
601 
602     /**
603      * @brief Register the audio capturer event change callback.
604      *
605      * @return Returns {@link SUCCESS} if callback registration is successful; returns an error code
606      * defined in {@link audio_errors.h} otherwise.
607      * @since 11
608      */
609     virtual int32_t RegisterAudioCapturerEventListener() = 0;
610 
611     /**
612      * @brief Unregister the audio capturer event change callback.
613      *
614      * @return Returns {@link SUCCESS} if callback registration is successful; returns an error code
615      * defined in {@link audio_errors.h} otherwise.
616      * @since 11
617      */
618     virtual int32_t UnregisterAudioCapturerEventListener() = 0;
619 
620     /**
621      * @brief Gets current input devices.
622      *
623      * @return Returns current input device info.
624      * @since 11
625      */
626     virtual int32_t GetCurrentInputDevices(DeviceInfo &deviceInfo) const = 0;
627 
628     /**
629      * @brief Gets the current audio capturer change info.
630      *
631      * @return Returns the audio capturer change info.
632      * @since 11
633      */
634     virtual int32_t GetCurrentCapturerChangeInfo(AudioCapturerChangeInfo &changeInfo) const = 0;
635 
636     /**
637      * @brief Obtains microphones this capturer used currently.
638      *
639      * @return Returns Microphone descriptors.
640      * @since 11
641      */
642     virtual std::vector<sptr<MicrophoneDescriptor>> GetCurrentMicrophones() const = 0;
643 
644     /**
645      * @brief Set Capturer Silent State.
646      *
647      * @return Returns {@link SUCCESS} if state setting is successful; returns an error code
648      * defined in {@link audio_errors.h} otherwise.
649      * @since 11
650      */
651     virtual int32_t SetCaptureSilentState(bool state) = 0;
652 
653     virtual uint32_t GetOverflowCount() const = 0;
654 
655     virtual int32_t SetAudioSourceConcurrency(const std::vector<SourceType> &targetSources) = 0;
656 
657     virtual ~AudioCapturer();
658 
659 protected:
660     static AudioStreamType FindStreamTypeBySourceType(SourceType sourceType);
661 
662 private:
663     static void SendCapturerCreateError(const SourceType &sourceType,
664         const int32_t &errorCode);
665 };
666 }  // namespace AudioStandard
667 }  // namespace OHOS
668 #endif  // AUDIO_CAPTURER_H
669