blob: a92d508211ed4d03db361223d5c2734d2ddc8fc0 [file] [log] [blame]
henrika883d00f2018-03-16 10:09:49 +01001/*
2 * Copyright (c) 2018 The WebRTC project authors. All Rights Reserved.
3 *
4 * Use of this source code is governed by a BSD-style license
5 * that can be found in the LICENSE file in the root of the source
6 * tree. An additional intellectual property rights grant can be found
7 * in the file PATENTS. All contributing project authors may
8 * be found in the AUTHORS file in the root of the source tree.
9 */
10
11#ifndef MODULES_AUDIO_DEVICE_ANDROID_AAUDIO_PLAYER_H_
12#define MODULES_AUDIO_DEVICE_ANDROID_AAUDIO_PLAYER_H_
13
14#include <aaudio/AAudio.h>
15#include <memory>
16
17#include "modules/audio_device/android/aaudio_wrapper.h"
18#include "modules/audio_device/include/audio_device_defines.h"
19#include "rtc_base/messagehandler.h"
20#include "rtc_base/thread.h"
21#include "rtc_base/thread_annotations.h"
22#include "rtc_base/thread_checker.h"
23
24namespace webrtc {
25
26class AudioDeviceBuffer;
27class FineAudioBuffer;
28class AudioManager;
29
30// Implements low-latency 16-bit mono PCM audio output support for Android
31// using the C based AAudio API.
32//
33// An instance must be created and destroyed on one and the same thread.
34// All public methods must also be called on the same thread. A thread checker
35// will DCHECK if any method is called on an invalid thread. Audio buffers
36// are requested on a dedicated high-priority thread owned by AAudio.
37//
38// The existing design forces the user to call InitPlayout() after StopPlayout()
39// to be able to call StartPlayout() again. This is in line with how the Java-
40// based implementation works.
41//
42// An audio stream can be disconnected, e.g. when an audio device is removed.
43// This implementation will restart the audio stream using the new preferred
44// device if such an event happens.
45//
46// Also supports automatic buffer-size adjustment based on underrun detections
47// where the internal AAudio buffer can be increased when needed. It will
48// reduce the risk of underruns (~glitches) at the expense of an increased
49// latency.
50class AAudioPlayer final : public AAudioObserverInterface,
51 public rtc::MessageHandler {
52 public:
53 explicit AAudioPlayer(AudioManager* audio_manager);
54 ~AAudioPlayer();
55
56 int Init();
57 int Terminate();
58
59 int InitPlayout();
60 bool PlayoutIsInitialized() const;
61
62 int StartPlayout();
63 int StopPlayout();
64 bool Playing() const;
65
66 void AttachAudioBuffer(AudioDeviceBuffer* audioBuffer);
67
68 // Not implemented in AAudio.
69 int SpeakerVolumeIsAvailable(bool& available); // NOLINT
70 int SetSpeakerVolume(uint32_t volume) { return -1; }
71 int SpeakerVolume(uint32_t& volume) const { return -1; } // NOLINT
72 int MaxSpeakerVolume(uint32_t& maxVolume) const { return -1; } // NOLINT
73 int MinSpeakerVolume(uint32_t& minVolume) const { return -1; } // NOLINT
74
75 protected:
76 // AAudioObserverInterface implementation.
77
78 // For an output stream, this function should render and write |num_frames|
79 // of data in the streams current data format to the |audio_data| buffer.
80 // Called on a real-time thread owned by AAudio.
81 aaudio_data_callback_result_t OnDataCallback(void* audio_data,
82 int32_t num_frames) override;
83 // AAudio calls this functions if any error occurs on a callback thread.
84 // Called on a real-time thread owned by AAudio.
85 void OnErrorCallback(aaudio_result_t error) override;
86
87 // rtc::MessageHandler used for restart messages from the error-callback
88 // thread to the main (creating) thread.
89 void OnMessage(rtc::Message* msg) override;
90
91 private:
92 // Closes the existing stream and starts a new stream.
93 void HandleStreamDisconnected();
94
95 // Ensures that methods are called from the same thread as this object is
96 // created on.
97 rtc::ThreadChecker main_thread_checker_;
98
99 // Stores thread ID in first call to AAudioPlayer::OnDataCallback from a
100 // real-time thread owned by AAudio. Detached during construction of this
101 // object.
102 rtc::ThreadChecker thread_checker_aaudio_;
103
104 // The thread on which this object is created on.
105 rtc::Thread* main_thread_;
106
107 // Wraps all AAudio resources. Contains an output stream using the default
108 // output audio device. Can be accessed on both the main thread and the
109 // real-time thread owned by AAudio. See separate AAudio documentation about
110 // thread safety.
111 AAudioWrapper aaudio_;
112
113 // FineAudioBuffer takes an AudioDeviceBuffer which delivers audio data
114 // in chunks of 10ms. It then allows for this data to be pulled in
115 // a finer or coarser granularity. I.e. interacting with this class instead
116 // of directly with the AudioDeviceBuffer one can ask for any number of
117 // audio data samples.
118 // Example: native buffer size can be 192 audio frames at 48kHz sample rate.
119 // WebRTC will provide 480 audio frames per 10ms but AAudio asks for 192
120 // in each callback (once every 4th ms). This class can then ask for 192 and
121 // the FineAudioBuffer will ask WebRTC for new data approximately only every
122 // second callback and also cache non-utilized audio.
123 std::unique_ptr<FineAudioBuffer> fine_audio_buffer_;
124
125 // Counts number of detected underrun events reported by AAudio.
126 int32_t underrun_count_ = 0;
127
128 // True only for the first data callback in each audio session.
129 bool first_data_callback_ = true;
130
131 // Raw pointer handle provided to us in AttachAudioBuffer(). Owned by the
132 // AudioDeviceModuleImpl class and set by AudioDeviceModule::Create().
133 AudioDeviceBuffer* audio_device_buffer_ RTC_GUARDED_BY(main_thread_checker_) =
134 nullptr;
135
136 bool initialized_ RTC_GUARDED_BY(main_thread_checker_) = false;
137 bool playing_ RTC_GUARDED_BY(main_thread_checker_) = false;
138
139 // Estimated latency between writing an audio frame to the output stream and
140 // the time that same frame is played out on the output audio device.
141 double latency_millis_ RTC_GUARDED_BY(thread_checker_aaudio_) = 0;
142};
143
144} // namespace webrtc
145
146#endif // MODULES_AUDIO_DEVICE_ANDROID_AAUDIO_PLAYER_H_