src/third_party/webrtc/modules/audio_device/android/opensles_output.h

   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_