src/third_party/libjingle/source/talk/media/webrtc/webrtcvoiceengine.h

   1 /*
   2  * libjingle
   3  * Copyright 2004 Google Inc.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions are met:
   7  *
   8  *  1. Redistributions of source code must retain the above copyright notice,
   9  *     this list of conditions and the following disclaimer.
  10  *  2. Redistributions in binary form must reproduce the above copyright notice,
  11  *     this list of conditions and the following disclaimer in the documentation
  12  *     and/or other materials provided with the distribution.
  13  *  3. The name of the author may not be used to endorse or promote products
  14  *     derived from this software without specific prior written permission.
  15  *
  16  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
  17  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  18  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
  19  * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  20  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  21  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  22  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  23  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  24  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  25  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26  */
  27
  28 #ifndef TALK_MEDIA_WEBRTCVOICEENGINE_H_
  29 #define TALK_MEDIA_WEBRTCVOICEENGINE_H_
  30
  31 #include <map>
  32 #include <set>
  33 #include <string>
  34 #include <vector>
  35
  36 #include "talk/media/base/rtputils.h"
  37 #include "talk/media/webrtc/webrtccommon.h"
  38 #include "talk/media/webrtc/webrtcexport.h"
  39 #include "talk/media/webrtc/webrtcvoe.h"
  40 #include "talk/session/media/channel.h"
  41 #include "webrtc/base/buffer.h"
  42 #include "webrtc/base/byteorder.h"
  43 #include "webrtc/base/logging.h"
  44 #include "webrtc/base/scoped_ptr.h"
  45 #include "webrtc/base/stream.h"
  46 #include "webrtc/common.h"
  47
  48 #if !defined(LIBPEERCONNECTION_LIB) && \
  49     !defined(LIBPEERCONNECTION_IMPLEMENTATION)
  50 // If you hit this, then you've tried to include this header from outside
  51 // the shared library.  An instance of this class must only be created from
  52 // within the library that actually implements it.  Otherwise use the
  53 // WebRtcMediaEngine to construct an instance.
  54 #error "Bogus include."
  55 #endif
  56
  57 namespace webrtc {
  58 class VideoEngine;
  59 }
  60
  61 namespace cricket {
  62
  63 // WebRtcSoundclipStream is an adapter object that allows a memory stream to be
  64 // passed into WebRtc, and support looping.
  65 class WebRtcSoundclipStream : public webrtc::InStream {
  66  public:
  67   WebRtcSoundclipStream(const char* buf, size_t len)
  68       : mem_(buf, len), loop_(true) {
  69   }
  70   void set_loop(bool loop) { loop_ = loop; }
  71
  72   virtual int Read(void* buf, int len) OVERRIDE;
  73   virtual int Rewind() OVERRIDE;
  74
  75  private:
  76   rtc::MemoryStream mem_;
  77   bool loop_;
  78 };
  79
  80 // WebRtcMonitorStream is used to monitor a stream coming from WebRtc.
  81 // For now we just dump the data.
  82 class WebRtcMonitorStream : public webrtc::OutStream {
  83   virtual bool Write(const void *buf, int len) OVERRIDE {
  84     return true;
  85   }
  86 };
  87
  88 class AudioDeviceModule;
  89 class AudioRenderer;
  90 class VoETraceWrapper;
  91 class VoEWrapper;
  92 class VoiceProcessor;
  93 class WebRtcSoundclipMedia;
  94 class WebRtcVoiceMediaChannel;
  95
  96 // WebRtcVoiceEngine is a class to be used with CompositeMediaEngine.
  97 // It uses the WebRtc VoiceEngine library for audio handling.
  98 class WebRtcVoiceEngine
  99     : public webrtc::VoiceEngineObserver,
 100       public webrtc::TraceCallback,
 101       public webrtc::VoEMediaProcess  {
 102  public:
 103   WebRtcVoiceEngine();
 104   // Dependency injection for testing.
 105   WebRtcVoiceEngine(VoEWrapper* voe_wrapper,
 106                     VoEWrapper* voe_wrapper_sc,
 107                     VoETraceWrapper* tracing);
 108   ~WebRtcVoiceEngine();
 109   bool Init(rtc::Thread* worker_thread);
 110   void Terminate();
 111
 112   int GetCapabilities();
 113   VoiceMediaChannel* CreateChannel();
 114
 115   SoundclipMedia* CreateSoundclip();
 116
 117   AudioOptions GetOptions() const { return options_; }
 118   bool SetOptions(const AudioOptions& options);
 119   // Overrides, when set, take precedence over the options on a
 120   // per-option basis.  For example, if AGC is set in options and AEC
 121   // is set in overrides, AGC and AEC will be both be set.  Overrides
 122   // can also turn off options.  For example, if AGC is set to "on" in
 123   // options and AGC is set to "off" in overrides, the result is that
 124   // AGC will be off until different overrides are applied or until
 125   // the overrides are cleared.  Only one set of overrides is present
 126   // at a time (they do not "stack").  And when the overrides are
 127   // cleared, the media engine's state reverts back to the options set
 128   // via SetOptions.  This allows us to have both "persistent options"
 129   // (the normal options) and "temporary options" (overrides).
 130   bool SetOptionOverrides(const AudioOptions& options);
 131   bool ClearOptionOverrides();
 132   bool SetDelayOffset(int offset);
 133   bool SetDevices(const Device* in_device, const Device* out_device);
 134   bool GetOutputVolume(int* level);
 135   bool SetOutputVolume(int level);
 136   int GetInputLevel();
 137   bool SetLocalMonitor(bool enable);
 138
 139   const std::vector<AudioCodec>& codecs();
 140   bool FindCodec(const AudioCodec& codec);
 141   bool FindWebRtcCodec(const AudioCodec& codec, webrtc::CodecInst* gcodec);
 142
 143   const std::vector<RtpHeaderExtension>& rtp_header_extensions() const;
 144
 145   void SetLogging(int min_sev, const char* filter);
 146
 147   bool RegisterProcessor(uint32 ssrc,
 148                          VoiceProcessor* voice_processor,
 149                          MediaProcessorDirection direction);
 150   bool UnregisterProcessor(uint32 ssrc,
 151                            VoiceProcessor* voice_processor,
 152                            MediaProcessorDirection direction);
 153
 154   // Method from webrtc::VoEMediaProcess
 155   virtual void Process(int channel,
 156                        webrtc::ProcessingTypes type,
 157                        int16_t audio10ms[],
 158                        int length,
 159                        int sampling_freq,
 160                        bool is_stereo) OVERRIDE;
 161
 162   // For tracking WebRtc channels. Needed because we have to pause them
 163   // all when switching devices.
 164   // May only be called by WebRtcVoiceMediaChannel.
 165   void RegisterChannel(WebRtcVoiceMediaChannel *channel);
 166   void UnregisterChannel(WebRtcVoiceMediaChannel *channel);
 167
 168   // May only be called by WebRtcSoundclipMedia.
 169   void RegisterSoundclip(WebRtcSoundclipMedia *channel);
 170   void UnregisterSoundclip(WebRtcSoundclipMedia *channel);
 171
 172   // Called by WebRtcVoiceMediaChannel to set a gain offset from
 173   // the default AGC target level.
 174   bool AdjustAgcLevel(int delta);
 175
 176   VoEWrapper* voe() { return voe_wrapper_.get(); }
 177   VoEWrapper* voe_sc() { return voe_wrapper_sc_.get(); }
 178   int GetLastEngineError();
 179
 180   // Set the external ADMs. This can only be called before Init.
 181   bool SetAudioDeviceModule(webrtc::AudioDeviceModule* adm,
 182                             webrtc::AudioDeviceModule* adm_sc);
 183
 184   // Starts AEC dump using existing file.
 185   bool StartAecDump(rtc::PlatformFile file);
 186
 187   // Check whether the supplied trace should be ignored.
 188   bool ShouldIgnoreTrace(const std::string& trace);
 189
 190   // Create a VoiceEngine Channel.
 191   int CreateMediaVoiceChannel();
 192   int CreateSoundclipVoiceChannel();
 193
 194  private:
 195   typedef std::vector<WebRtcSoundclipMedia *> SoundclipList;
 196   typedef std::vector<WebRtcVoiceMediaChannel *> ChannelList;
 197   typedef sigslot::
 198       signal3<uint32, MediaProcessorDirection, AudioFrame*> FrameSignal;
 199
 200   void Construct();
 201   void ConstructCodecs();
 202   bool GetVoeCodec(int index, webrtc::CodecInst& codec);
 203   bool InitInternal();
 204   bool EnsureSoundclipEngineInit();
 205   void SetTraceFilter(int filter);
 206   void SetTraceOptions(const std::string& options);
 207   // Applies either options or overrides.  Every option that is "set"
 208   // will be applied.  Every option not "set" will be ignored.  This
 209   // allows us to selectively turn on and off different options easily
 210   // at any time.
 211   bool ApplyOptions(const AudioOptions& options);
 212
 213   // webrtc::TraceCallback:
 214   virtual void Print(webrtc::TraceLevel level,
 215                      const char* trace,
 216                      int length) OVERRIDE;
 217
 218   // webrtc::VoiceEngineObserver:
 219   virtual void CallbackOnError(int channel, int errCode) OVERRIDE;
 220
 221   // Given the device type, name, and id, find device id. Return true and
 222   // set the output parameter rtc_id if successful.
 223   bool FindWebRtcAudioDeviceId(
 224       bool is_input, const std::string& dev_name, int dev_id, int* rtc_id);
 225   bool FindChannelAndSsrc(int channel_num,
 226                           WebRtcVoiceMediaChannel** channel,
 227                           uint32* ssrc) const;
 228   bool FindChannelNumFromSsrc(uint32 ssrc,
 229                               MediaProcessorDirection direction,
 230                               int* channel_num);
 231   bool ChangeLocalMonitor(bool enable);
 232   bool PauseLocalMonitor();
 233   bool ResumeLocalMonitor();
 234
 235   bool UnregisterProcessorChannel(MediaProcessorDirection channel_direction,
 236                                   uint32 ssrc,
 237                                   VoiceProcessor* voice_processor,
 238                                   MediaProcessorDirection processor_direction);
 239
 240   void StartAecDump(const std::string& filename);
 241   void StopAecDump();
 242   int CreateVoiceChannel(VoEWrapper* voe);
 243
 244   // When a voice processor registers with the engine, it is connected
 245   // to either the Rx or Tx signals, based on the direction parameter.
 246   // SignalXXMediaFrame will be invoked for every audio packet.
 247   FrameSignal SignalRxMediaFrame;
 248   FrameSignal SignalTxMediaFrame;
 249
 250   static const int kDefaultLogSeverity = rtc::LS_WARNING;
 251
 252   // The primary instance of WebRtc VoiceEngine.
 253   rtc::scoped_ptr<VoEWrapper> voe_wrapper_;
 254   // A secondary instance, for playing out soundclips (on the 'ring' device).
 255   rtc::scoped_ptr<VoEWrapper> voe_wrapper_sc_;
 256   bool voe_wrapper_sc_initialized_;
 257   rtc::scoped_ptr<VoETraceWrapper> tracing_;
 258   // The external audio device manager
 259   webrtc::AudioDeviceModule* adm_;
 260   webrtc::AudioDeviceModule* adm_sc_;
 261   int log_filter_;
 262   std::string log_options_;
 263   bool is_dumping_aec_;
 264   std::vector<AudioCodec> codecs_;
 265   std::vector<RtpHeaderExtension> rtp_header_extensions_;
 266   bool desired_local_monitor_enable_;
 267   rtc::scoped_ptr<WebRtcMonitorStream> monitor_;
 268   SoundclipList soundclips_;
 269   ChannelList channels_;
 270   // channels_ can be read from WebRtc callback thread. We need a lock on that
 271   // callback as well as the RegisterChannel/UnregisterChannel.
 272   rtc::CriticalSection channels_cs_;
 273   webrtc::AgcConfig default_agc_config_;
 274
 275   webrtc::Config voe_config_;
 276
 277   bool initialized_;
 278   // See SetOptions and SetOptionOverrides for a description of the
 279   // difference between options and overrides.
 280   // options_ are the base options, which combined with the
 281   // option_overrides_, create the current options being used.
 282   // options_ is stored so that when option_overrides_ is cleared, we
 283   // can restore the options_ without the option_overrides.
 284   AudioOptions options_;
 285   AudioOptions option_overrides_;
 286
 287   // When the media processor registers with the engine, the ssrc is cached
 288   // here so that a look up need not be made when the callback is invoked.
 289   // This is necessary because the lookup results in mux_channels_cs lock being
 290   // held and if a remote participant leaves the hangout at the same time
 291   // we hit a deadlock.
 292   uint32 tx_processor_ssrc_;
 293   uint32 rx_processor_ssrc_;
 294
 295   rtc::CriticalSection signal_media_critical_;
 296
 297   // Cache received experimental_aec and experimental_ns values, and apply them
 298   // in case they are missing in the audio options. We need to do this because
 299   // SetExtraOptions() will revert to defaults for options which are not
 300   // provided.
 301   Settable<bool> experimental_aec_;
 302   Settable<bool> experimental_ns_;
 303 };
 304
 305 // WebRtcMediaChannel is a class that implements the common WebRtc channel
 306 // functionality.
 307 template <class T, class E>
 308 class WebRtcMediaChannel : public T, public webrtc::Transport {
 309  public:
 310   WebRtcMediaChannel(E *engine, int channel)
 311       : engine_(engine), voe_channel_(channel) {}
 312   E *engine() { return engine_; }
 313   int voe_channel() const { return voe_channel_; }
 314   bool valid() const { return voe_channel_ != -1; }
 315
 316  protected:
 317   // implements Transport interface
 318   virtual int SendPacket(int channel, const void *data, int len) OVERRIDE {
 319     rtc::Buffer packet(data, len, kMaxRtpPacketLen);
 320     if (!T::SendPacket(&packet)) {
 321       return -1;
 322     }
 323     return len;
 324   }
 325
 326   virtual int SendRTCPPacket(int channel, const void *data, int len) OVERRIDE {
 327     rtc::Buffer packet(data, len, kMaxRtpPacketLen);
 328     return T::SendRtcp(&packet) ? len : -1;
 329   }
 330
 331  private:
 332   E *engine_;
 333   int voe_channel_;
 334 };
 335
 336 // WebRtcVoiceMediaChannel is an implementation of VoiceMediaChannel that uses
 337 // WebRtc Voice Engine.
 338 class WebRtcVoiceMediaChannel
 339     : public WebRtcMediaChannel<VoiceMediaChannel, WebRtcVoiceEngine> {
 340  public:
 341   explicit WebRtcVoiceMediaChannel(WebRtcVoiceEngine *engine);
 342   virtual ~WebRtcVoiceMediaChannel();
 343   virtual bool SetOptions(const AudioOptions& options);
 344   virtual bool GetOptions(AudioOptions* options) const {
 345     *options = options_;
 346     return true;
 347   }
 348   virtual bool SetRecvCodecs(const std::vector<AudioCodec> &codecs);
 349   virtual bool SetSendCodecs(const std::vector<AudioCodec> &codecs);
 350   virtual bool SetRecvRtpHeaderExtensions(
 351       const std::vector<RtpHeaderExtension>& extensions);
 352   virtual bool SetSendRtpHeaderExtensions(
 353       const std::vector<RtpHeaderExtension>& extensions);
 354   virtual bool SetPlayout(bool playout);
 355   bool PausePlayout();
 356   bool ResumePlayout();
 357   virtual bool SetSend(SendFlags send);
 358   bool PauseSend();
 359   bool ResumeSend();
 360   virtual bool AddSendStream(const StreamParams& sp);
 361   virtual bool RemoveSendStream(uint32 ssrc);
 362   virtual bool AddRecvStream(const StreamParams& sp);
 363   virtual bool RemoveRecvStream(uint32 ssrc);
 364   virtual bool SetRemoteRenderer(uint32 ssrc, AudioRenderer* renderer);
 365   virtual bool SetLocalRenderer(uint32 ssrc, AudioRenderer* renderer);
 366   virtual bool GetActiveStreams(AudioInfo::StreamList* actives);
 367   virtual int GetOutputLevel();
 368   virtual int GetTimeSinceLastTyping();
 369   virtual void SetTypingDetectionParameters(int time_window,
 370       int cost_per_typing, int reporting_threshold, int penalty_decay,
 371       int type_event_delay);
 372   virtual bool SetOutputScaling(uint32 ssrc, double left, double right);
 373   virtual bool GetOutputScaling(uint32 ssrc, double* left, double* right);
 374
 375   virtual bool SetRingbackTone(const char *buf, int len);
 376   virtual bool PlayRingbackTone(uint32 ssrc, bool play, bool loop);
 377   virtual bool CanInsertDtmf();
 378   virtual bool InsertDtmf(uint32 ssrc, int event, int duration, int flags);
 379
 380   virtual void OnPacketReceived(rtc::Buffer* packet,
 381                                 const rtc::PacketTime& packet_time);
 382   virtual void OnRtcpReceived(rtc::Buffer* packet,
 383                               const rtc::PacketTime& packet_time);
 384   virtual void OnReadyToSend(bool ready) {}
 385   virtual bool MuteStream(uint32 ssrc, bool on);
 386   virtual bool SetMaxSendBandwidth(int bps);
 387   virtual bool GetStats(VoiceMediaInfo* info);
 388   // Gets last reported error from WebRtc voice engine.  This should be only
 389   // called in response a failure.
 390   virtual void GetLastMediaError(uint32* ssrc,
 391                                  VoiceMediaChannel::Error* error);
 392   bool FindSsrc(int channel_num, uint32* ssrc);
 393   void OnError(uint32 ssrc, int error);
 394
 395   bool sending() const { return send_ != SEND_NOTHING; }
 396   int GetReceiveChannelNum(uint32 ssrc);
 397   int GetSendChannelNum(uint32 ssrc);
 398
 399   bool SetupSharedBandwidthEstimation(webrtc::VideoEngine* vie,
 400                                       int vie_channel);
 401  protected:
 402   int GetLastEngineError() { return engine()->GetLastEngineError(); }
 403   int GetOutputLevel(int channel);
 404   bool GetRedSendCodec(const AudioCodec& red_codec,
 405                        const std::vector<AudioCodec>& all_codecs,
 406                        webrtc::CodecInst* send_codec);
 407   bool EnableRtcp(int channel);
 408   bool ResetRecvCodecs(int channel);
 409   bool SetPlayout(int channel, bool playout);
 410   static uint32 ParseSsrc(const void* data, size_t len, bool rtcp);
 411   static Error WebRtcErrorToChannelError(int err_code);
 412
 413  private:
 414   class WebRtcVoiceChannelRenderer;
 415   // Map of ssrc to WebRtcVoiceChannelRenderer object.  A new object of
 416   // WebRtcVoiceChannelRenderer will be created for every new stream and
 417   // will be destroyed when the stream goes away.
 418   typedef std::map<uint32, WebRtcVoiceChannelRenderer*> ChannelMap;
 419   typedef int (webrtc::VoERTP_RTCP::* ExtensionSetterFunction)(int, bool,
 420       unsigned char);
 421
 422   void SetNack(int channel, bool nack_enabled);
 423   void SetNack(const ChannelMap& channels, bool nack_enabled);
 424   bool SetSendCodec(const webrtc::CodecInst& send_codec);
 425   bool SetSendCodec(int channel, const webrtc::CodecInst& send_codec);
 426   bool ChangePlayout(bool playout);
 427   bool ChangeSend(SendFlags send);
 428   bool ChangeSend(int channel, SendFlags send);
 429   void ConfigureSendChannel(int channel);
 430   bool ConfigureRecvChannel(int channel);
 431   bool DeleteChannel(int channel);
 432   bool InConferenceMode() const {
 433     return options_.conference_mode.GetWithDefaultIfUnset(false);
 434   }
 435   bool IsDefaultChannel(int channel_id) const {
 436     return channel_id == voe_channel();
 437   }
 438   bool SetSendCodecs(int channel, const std::vector<AudioCodec>& codecs);
 439   bool SetSendBitrateInternal(int bps);
 440
 441   bool SetHeaderExtension(ExtensionSetterFunction setter, int channel_id,
 442                           const RtpHeaderExtension* extension);
 443   bool SetupSharedBweOnChannel(int voe_channel);
 444
 445   bool SetChannelRecvRtpHeaderExtensions(
 446     int channel_id,
 447     const std::vector<RtpHeaderExtension>& extensions);
 448   bool SetChannelSendRtpHeaderExtensions(
 449     int channel_id,
 450     const std::vector<RtpHeaderExtension>& extensions);
 451
 452   rtc::scoped_ptr<WebRtcSoundclipStream> ringback_tone_;
 453   std::set<int> ringback_channels_;  // channels playing ringback
 454   std::vector<AudioCodec> recv_codecs_;
 455   std::vector<AudioCodec> send_codecs_;
 456   rtc::scoped_ptr<webrtc::CodecInst> send_codec_;
 457   bool send_bitrate_setting_;
 458   int send_bitrate_bps_;
 459   AudioOptions options_;
 460   bool dtmf_allowed_;
 461   bool desired_playout_;
 462   bool nack_enabled_;
 463   bool playout_;
 464   bool typing_noise_detected_;
 465   SendFlags desired_send_;
 466   SendFlags send_;
 467   // shared_bwe_vie_ and shared_bwe_vie_channel_ together identifies a WebRTC
 468   // VideoEngine channel that this voice channel should forward incoming packets
 469   // to for Bandwidth Estimation purposes.
 470   webrtc::VideoEngine* shared_bwe_vie_;
 471   int shared_bwe_vie_channel_;
 472
 473   // send_channels_ contains the channels which are being used for sending.
 474   // When the default channel (voe_channel) is used for sending, it is
 475   // contained in send_channels_, otherwise not.
 476   ChannelMap send_channels_;
 477   std::vector<RtpHeaderExtension> send_extensions_;
 478   uint32 default_receive_ssrc_;
 479   // Note the default channel (voe_channel()) can reside in both
 480   // receive_channels_ and send_channels_ in non-conference mode and in that
 481   // case it will only be there if a non-zero default_receive_ssrc_ is set.
 482   ChannelMap receive_channels_;  // for multiple sources
 483   // receive_channels_ can be read from WebRtc callback thread.  Access from
 484   // the WebRtc thread must be synchronized with edits on the worker thread.
 485   // Reads on the worker thread are ok.
 486   //
 487   std::vector<RtpHeaderExtension> receive_extensions_;
 488   // Do not lock this on the VoE media processor thread; potential for deadlock
 489   // exists.
 490   mutable rtc::CriticalSection receive_channels_cs_;
 491 };
 492
 493 }  // namespace cricket
 494
 495 #endif  // TALK_MEDIA_WEBRTCVOICEENGINE_H_