1 /* 2 * Copyright (c) 2013 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 WEBRTC_MODULES_AUDIO_DEVICE_ANDROID_OPENSLES_OUTPUT_H_ 12 #define WEBRTC_MODULES_AUDIO_DEVICE_ANDROID_OPENSLES_OUTPUT_H_ 13 14 #include <SLES/OpenSLES.h> 15 #include <SLES/OpenSLES_Android.h> 16 #include <SLES/OpenSLES_AndroidConfiguration.h> 17 18 #include "webrtc/modules/audio_device/android/audio_manager_jni.h" 19 #include "webrtc/modules/audio_device/android/low_latency_event.h" 20 #include "webrtc/modules/audio_device/android/audio_common.h" 21 #include "webrtc/modules/audio_device/include/audio_device_defines.h" 22 #include "webrtc/modules/audio_device/include/audio_device.h" 23 #include "webrtc/system_wrappers/interface/scoped_ptr.h" 24 25 namespace webrtc { 26 27 class AudioDeviceBuffer; 28 class CriticalSectionWrapper; 29 class FineAudioBuffer; 30 class SingleRwFifo; 31 class ThreadWrapper; 32 33 // OpenSL implementation that facilitate playing PCM data to an android device. 34 // This class is Thread-compatible. I.e. Given an instance of this class, calls 35 // to non-const methods require exclusive access to the object. 36 class OpenSlesOutput : public PlayoutDelayProvider { 37 public: 38 explicit OpenSlesOutput(const int32_t id); 39 virtual ~OpenSlesOutput(); 40 41 static int32_t SetAndroidAudioDeviceObjects(void* javaVM, 42 void* env, 43 void* context); 44 static void ClearAndroidAudioDeviceObjects(); 45 46 // Main initializaton and termination 47 int32_t Init(); 48 int32_t Terminate(); 49 bool Initialized() const { return initialized_; } 50 51 // Device enumeration 52 int16_t PlayoutDevices() { return 1; } 53 54 int32_t PlayoutDeviceName(uint16_t index, 55 char name[kAdmMaxDeviceNameSize], 56 char guid[kAdmMaxGuidSize]); 57 58 // Device selection 59 int32_t SetPlayoutDevice(uint16_t index); 60 int32_t SetPlayoutDevice( 61 AudioDeviceModule::WindowsDeviceType device) { return 0; } 62 63 // No-op 64 int32_t SetPlayoutSampleRate(uint32_t sample_rate_hz) { return 0; } 65 66 // Audio transport initialization 67 int32_t PlayoutIsAvailable(bool& available); // NOLINT 68 int32_t InitPlayout(); 69 bool PlayoutIsInitialized() const { return play_initialized_; } 70 71 // Audio transport control 72 int32_t StartPlayout(); 73 int32_t StopPlayout(); 74 bool Playing() const { return playing_; } 75 76 // Audio mixer initialization 77 int32_t InitSpeaker(); 78 bool SpeakerIsInitialized() const { return speaker_initialized_; } 79 80 // Speaker volume controls 81 int32_t SpeakerVolumeIsAvailable(bool& available); // NOLINT 82 int32_t SetSpeakerVolume(uint32_t volume); 83 int32_t SpeakerVolume(uint32_t& volume) const { return 0; } // NOLINT 84 int32_t MaxSpeakerVolume(uint32_t& maxVolume) const; // NOLINT 85 int32_t MinSpeakerVolume(uint32_t& minVolume) const; // NOLINT 86 int32_t SpeakerVolumeStepSize(uint16_t& stepSize) const; // NOLINT 87 88 // Speaker mute control 89 int32_t SpeakerMuteIsAvailable(bool& available); // NOLINT 90 int32_t SetSpeakerMute(bool enable) { return -1; } 91 int32_t SpeakerMute(bool& enabled) const { return -1; } // NOLINT 92 93 94 // Stereo support 95 int32_t StereoPlayoutIsAvailable(bool& available); // NOLINT 96 int32_t SetStereoPlayout(bool enable); 97 int32_t StereoPlayout(bool& enabled) const; // NOLINT 98 99 // Delay information and control 100 int32_t SetPlayoutBuffer(const AudioDeviceModule::BufferType type, 101 uint16_t sizeMS) { return -1; } 102 int32_t PlayoutBuffer(AudioDeviceModule::BufferType& type, // NOLINT 103 uint16_t& sizeMS) const; 104 int32_t PlayoutDelay(uint16_t& delayMS) const; // NOLINT 105 106 107 // Error and warning information 108 bool PlayoutWarning() const { return false; } 109 bool PlayoutError() const { return false; } 110 void ClearPlayoutWarning() {} 111 void ClearPlayoutError() {} 112 113 // Attach audio buffer 114 void AttachAudioBuffer(AudioDeviceBuffer* audioBuffer); 115 116 // Speaker audio routing 117 int32_t SetLoudspeakerStatus(bool enable); 118 int32_t GetLoudspeakerStatus(bool& enable) const; // NOLINT 119 120 protected: 121 virtual int PlayoutDelayMs(); 122 123 private: 124 enum { 125 kNumInterfaces = 3, 126 // TODO(xians): Reduce the numbers of buffers to improve the latency. 127 // Currently 30ms worth of buffers are needed due to audio 128 // pipeline processing jitter. Note: kNumOpenSlBuffers must 129 // not be changed. 130 // According to the opensles documentation in the ndk: 131 // The lower output latency path is used only if the application requests a 132 // buffer count of 2 or more. Use minimum number of buffers to keep delay 133 // as low as possible. 134 kNumOpenSlBuffers = 2, 135 // NetEq delivers frames on a 10ms basis. This means that every 10ms there 136 // will be a time consuming task. Keeping 10ms worth of buffers will ensure 137 // that there is 10ms to perform the time consuming task without running 138 // into underflow. 139 // In addition to the 10ms that needs to be stored for NetEq processing 140 // there will be jitter in audio pipe line due to the acquisition of locks. 141 // Note: The buffers in the OpenSL queue do not count towards the 10ms of 142 // frames needed since OpenSL needs to have them ready for playout. 143 kNum10MsToBuffer = 6, 144 }; 145 146 bool InitSampleRate(); 147 bool SetLowLatency(); 148 void UpdatePlayoutDelay(); 149 // It might be possible to dynamically add or remove buffers based on how 150 // close to depletion the fifo is. Few buffers means low delay. Too few 151 // buffers will cause underrun. Dynamically changing the number of buffer 152 // will greatly increase code complexity. 153 void CalculateNumFifoBuffersNeeded(); 154 void AllocateBuffers(); 155 int TotalBuffersUsed() const; 156 bool EnqueueAllBuffers(); 157 // This function also configures the audio player, e.g. sample rate to use 158 // etc, so it should be called when starting playout. 159 bool CreateAudioPlayer(); 160 void DestroyAudioPlayer(); 161 162 // When underrun happens there won't be a new frame ready for playout that 163 // can be retrieved yet. Since the OpenSL thread must return ASAP there will 164 // be one less queue available to OpenSL. This function handles this case 165 // gracefully by restarting the audio, pushing silent frames to OpenSL for 166 // playout. This will sound like a click. Underruns are also logged to 167 // make it possible to identify these types of audio artifacts. 168 // This function returns true if there has been underrun. Further processing 169 // of audio data should be avoided until this function returns false again. 170 // The function needs to be protected by |crit_sect_|. 171 bool HandleUnderrun(int event_id, int event_msg); 172 173 static void PlayerSimpleBufferQueueCallback( 174 SLAndroidSimpleBufferQueueItf queueItf, 175 void* pContext); 176 // This function must not take any locks or do any heavy work. It is a 177 // requirement for the OpenSL implementation to work as intended. The reason 178 // for this is that taking locks exposes the OpenSL thread to the risk of 179 // priority inversion. 180 void PlayerSimpleBufferQueueCallbackHandler( 181 SLAndroidSimpleBufferQueueItf queueItf); 182 183 bool StartCbThreads(); 184 void StopCbThreads(); 185 static bool CbThread(void* context); 186 // This function must be protected against data race with threads calling this 187 // class' public functions. It is a requirement for this class to be 188 // Thread-compatible. 189 bool CbThreadImpl(); 190 191 // Java API handle 192 AudioManagerJni audio_manager_; 193 194 int id_; 195 bool initialized_; 196 bool speaker_initialized_; 197 bool play_initialized_; 198 199 // Members that are read/write accessed concurrently by the process thread and 200 // threads calling public functions of this class. 201 scoped_ptr<ThreadWrapper> play_thread_; // Processing thread 202 scoped_ptr<CriticalSectionWrapper> crit_sect_; 203 // This member controls the starting and stopping of playing audio to the 204 // the device. 205 bool playing_; 206 207 // Only one thread, T1, may push and only one thread, T2, may pull. T1 may or 208 // may not be the same thread as T2. T1 is the process thread and T2 is the 209 // OpenSL thread. 210 scoped_ptr<SingleRwFifo> fifo_; 211 int num_fifo_buffers_needed_; 212 LowLatencyEvent event_; 213 int number_underruns_; 214 215 // OpenSL handles 216 SLObjectItf sles_engine_; 217 SLEngineItf sles_engine_itf_; 218 SLObjectItf sles_player_; 219 SLPlayItf sles_player_itf_; 220 SLAndroidSimpleBufferQueueItf sles_player_sbq_itf_; 221 SLObjectItf sles_output_mixer_; 222 223 // Audio buffers 224 AudioDeviceBuffer* audio_buffer_; 225 scoped_ptr<FineAudioBuffer> fine_buffer_; 226 scoped_ptr<scoped_ptr<int8_t[]>[]> play_buf_; 227 // Index in |rec_buf_| pointing to the audio buffer that will be ready the 228 // next time PlayerSimpleBufferQueueCallbackHandler is invoked. 229 // Ready means buffer is ready to be played out to device. 230 int active_queue_; 231 232 // Audio settings 233 uint32_t speaker_sampling_rate_; 234 int buffer_size_samples_; 235 int buffer_size_bytes_; 236 237 // Audio status 238 uint16_t playout_delay_; 239 }; 240 241 } // namespace webrtc 242 243 #endif // WEBRTC_MODULES_AUDIO_DEVICE_ANDROID_OPENSLES_OUTPUT_H_ 244