src/third_party/libjingle/source/talk/media/base/mediaengine.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_BASE_MEDIAENGINE_H_
  29 #define TALK_MEDIA_BASE_MEDIAENGINE_H_
  30
  31 #ifdef OSX
  32 #include <CoreAudio/CoreAudio.h>
  33 #endif
  34
  35 #include <limits.h>
  36
  37 #include <string>
  38 #include <vector>
  39
  40 #include "talk/media/base/codec.h"
  41 #include "talk/media/base/mediachannel.h"
  42 #include "talk/media/base/mediacommon.h"
  43 #include "talk/media/base/videocapturer.h"
  44 #include "talk/media/base/videocommon.h"
  45 #include "talk/media/base/videoprocessor.h"
  46 #include "talk/media/base/voiceprocessor.h"
  47 #include "talk/media/devices/devicemanager.h"
  48 #include "webrtc/base/fileutils.h"
  49 #include "webrtc/base/sigslotrepeater.h"
  50
  51 #if defined(GOOGLE_CHROME_BUILD) || defined(CHROMIUM_BUILD)
  52 #define DISABLE_MEDIA_ENGINE_FACTORY
  53 #endif
  54
  55 namespace cricket {
  56
  57 class VideoCapturer;
  58
  59 // MediaEngineInterface is an abstraction of a media engine which can be
  60 // subclassed to support different media componentry backends.
  61 // It supports voice and video operations in the same class to facilitate
  62 // proper synchronization between both media types.
  63 class MediaEngineInterface {
  64  public:
  65   // Default value to be used for SetAudioDelayOffset().
  66   static const int kDefaultAudioDelayOffset;
  67
  68   virtual ~MediaEngineInterface() {}
  69
  70   // Initialization
  71   // Starts the engine.
  72   virtual bool Init(rtc::Thread* worker_thread) = 0;
  73   // Shuts down the engine.
  74   virtual void Terminate() = 0;
  75   // Returns what the engine is capable of, as a set of Capabilities, above.
  76   virtual int GetCapabilities() = 0;
  77
  78   // MediaChannel creation
  79   // Creates a voice media channel. Returns NULL on failure.
  80   virtual VoiceMediaChannel *CreateChannel() = 0;
  81   // Creates a video media channel, paired with the specified voice channel.
  82   // Returns NULL on failure.
  83   virtual VideoMediaChannel* CreateVideoChannel(
  84       const VideoOptions& options,
  85       VoiceMediaChannel* voice_media_channel) = 0;
  86
  87   // Creates a soundclip object for playing sounds on. Returns NULL on failure.
  88   virtual SoundclipMedia *CreateSoundclip() = 0;
  89
  90   // Configuration
  91   // Gets global audio options.
  92   virtual AudioOptions GetAudioOptions() const = 0;
  93   // Sets global audio options. "options" are from AudioOptions, above.
  94   virtual bool SetAudioOptions(const AudioOptions& options) = 0;
  95   // Sets the value used by the echo canceller to offset delay values obtained
  96   // from the OS.
  97   virtual bool SetAudioDelayOffset(int offset) = 0;
  98   // Sets the default (maximum) codec/resolution and encoder option to capture
  99   // and encode video.
 100   virtual bool SetDefaultVideoEncoderConfig(const VideoEncoderConfig& config)
 101       = 0;
 102
 103   // Device selection
 104   // TODO(tschmelcher): Add method for selecting the soundclip device.
 105   virtual bool SetSoundDevices(const Device* in_device,
 106                                const Device* out_device) = 0;
 107
 108   // Device configuration
 109   // Gets the current speaker volume, as a value between 0 and 255.
 110   virtual bool GetOutputVolume(int* level) = 0;
 111   // Sets the current speaker volume, as a value between 0 and 255.
 112   virtual bool SetOutputVolume(int level) = 0;
 113
 114   // Local monitoring
 115   // Gets the current microphone level, as a value between 0 and 10.
 116   virtual int GetInputLevel() = 0;
 117   // Starts or stops the local microphone. Useful if local mic info is needed
 118   // prior to a call being connected; the mic will be started automatically
 119   // when a VoiceMediaChannel starts sending.
 120   virtual bool SetLocalMonitor(bool enable) = 0;
 121   // Installs a callback for raw frames from the local camera.
 122
 123   virtual const std::vector<AudioCodec>& audio_codecs() = 0;
 124   virtual const std::vector<RtpHeaderExtension>&
 125       audio_rtp_header_extensions() = 0;
 126   virtual const std::vector<VideoCodec>& video_codecs() = 0;
 127   virtual const std::vector<RtpHeaderExtension>&
 128       video_rtp_header_extensions() = 0;
 129
 130   // Logging control
 131   virtual void SetVoiceLogging(int min_sev, const char* filter) = 0;
 132   virtual void SetVideoLogging(int min_sev, const char* filter) = 0;
 133
 134   // Starts AEC dump using existing file.
 135   virtual bool StartAecDump(rtc::PlatformFile file) = 0;
 136
 137   // Voice processors for effects.
 138   virtual bool RegisterVoiceProcessor(uint32 ssrc,
 139                                       VoiceProcessor* video_processor,
 140                                       MediaProcessorDirection direction) = 0;
 141   virtual bool UnregisterVoiceProcessor(uint32 ssrc,
 142                                         VoiceProcessor* video_processor,
 143                                         MediaProcessorDirection direction) = 0;
 144
 145   virtual VideoFormat GetStartCaptureFormat() const = 0;
 146
 147   virtual sigslot::repeater2<VideoCapturer*, CaptureState>&
 148       SignalVideoCaptureStateChange() = 0;
 149 };
 150
 151
 152 #if !defined(DISABLE_MEDIA_ENGINE_FACTORY)
 153 class MediaEngineFactory {
 154  public:
 155   typedef cricket::MediaEngineInterface* (*MediaEngineCreateFunction)();
 156   // Creates a media engine, using either the compiled system default or the
 157   // creation function specified in SetCreateFunction, if specified.
 158   static MediaEngineInterface* Create();
 159   // Sets the function used when calling Create. If unset, the compiled system
 160   // default will be used. Returns the old create function, or NULL if one
 161   // wasn't set. Likewise, NULL can be used as the |function| parameter to
 162   // reset to the default behavior.
 163   static MediaEngineCreateFunction SetCreateFunction(
 164       MediaEngineCreateFunction function);
 165  private:
 166   static MediaEngineCreateFunction create_function_;
 167 };
 168 #endif
 169
 170 // CompositeMediaEngine constructs a MediaEngine from separate
 171 // voice and video engine classes.
 172 template<class VOICE, class VIDEO>
 173 class CompositeMediaEngine : public MediaEngineInterface {
 174  public:
 175   CompositeMediaEngine() {}
 176   virtual ~CompositeMediaEngine() {}
 177   virtual bool Init(rtc::Thread* worker_thread) {
 178     if (!voice_.Init(worker_thread))
 179       return false;
 180     if (!video_.Init(worker_thread)) {
 181       voice_.Terminate();
 182       return false;
 183     }
 184     SignalVideoCaptureStateChange().repeat(video_.SignalCaptureStateChange);
 185     return true;
 186   }
 187   virtual void Terminate() {
 188     video_.Terminate();
 189     voice_.Terminate();
 190   }
 191
 192   virtual int GetCapabilities() {
 193     return (voice_.GetCapabilities() | video_.GetCapabilities());
 194   }
 195   virtual VoiceMediaChannel *CreateChannel() {
 196     return voice_.CreateChannel();
 197   }
 198   virtual VideoMediaChannel* CreateVideoChannel(const VideoOptions& options,
 199                                                 VoiceMediaChannel* channel) {
 200     return video_.CreateChannel(options, channel);
 201   }
 202   virtual SoundclipMedia *CreateSoundclip() {
 203     return voice_.CreateSoundclip();
 204   }
 205
 206   virtual AudioOptions GetAudioOptions() const {
 207     return voice_.GetOptions();
 208   }
 209   virtual bool SetAudioOptions(const AudioOptions& options) {
 210     return voice_.SetOptions(options);
 211   }
 212   virtual bool SetAudioDelayOffset(int offset) {
 213     return voice_.SetDelayOffset(offset);
 214   }
 215   virtual bool SetDefaultVideoEncoderConfig(const VideoEncoderConfig& config) {
 216     return video_.SetDefaultEncoderConfig(config);
 217   }
 218
 219   virtual bool SetSoundDevices(const Device* in_device,
 220                                const Device* out_device) {
 221     return voice_.SetDevices(in_device, out_device);
 222   }
 223
 224   virtual bool GetOutputVolume(int* level) {
 225     return voice_.GetOutputVolume(level);
 226   }
 227   virtual bool SetOutputVolume(int level) {
 228     return voice_.SetOutputVolume(level);
 229   }
 230
 231   virtual int GetInputLevel() {
 232     return voice_.GetInputLevel();
 233   }
 234   virtual bool SetLocalMonitor(bool enable) {
 235     return voice_.SetLocalMonitor(enable);
 236   }
 237   virtual const std::vector<AudioCodec>& audio_codecs() {
 238     return voice_.codecs();
 239   }
 240   virtual const std::vector<RtpHeaderExtension>& audio_rtp_header_extensions() {
 241     return voice_.rtp_header_extensions();
 242   }
 243   virtual const std::vector<VideoCodec>& video_codecs() {
 244     return video_.codecs();
 245   }
 246   virtual const std::vector<RtpHeaderExtension>& video_rtp_header_extensions() {
 247     return video_.rtp_header_extensions();
 248   }
 249
 250   virtual void SetVoiceLogging(int min_sev, const char* filter) {
 251     voice_.SetLogging(min_sev, filter);
 252   }
 253   virtual void SetVideoLogging(int min_sev, const char* filter) {
 254     video_.SetLogging(min_sev, filter);
 255   }
 256
 257   virtual bool StartAecDump(rtc::PlatformFile file) {
 258     return voice_.StartAecDump(file);
 259   }
 260
 261   virtual bool RegisterVoiceProcessor(uint32 ssrc,
 262                                       VoiceProcessor* processor,
 263                                       MediaProcessorDirection direction) {
 264     return voice_.RegisterProcessor(ssrc, processor, direction);
 265   }
 266   virtual bool UnregisterVoiceProcessor(uint32 ssrc,
 267                                         VoiceProcessor* processor,
 268                                         MediaProcessorDirection direction) {
 269     return voice_.UnregisterProcessor(ssrc, processor, direction);
 270   }
 271   virtual VideoFormat GetStartCaptureFormat() const {
 272     return video_.GetStartCaptureFormat();
 273   }
 274   virtual sigslot::repeater2<VideoCapturer*, CaptureState>&
 275       SignalVideoCaptureStateChange() {
 276     return signal_state_change_;
 277   }
 278
 279  protected:
 280   VOICE voice_;
 281   VIDEO video_;
 282   sigslot::repeater2<VideoCapturer*, CaptureState> signal_state_change_;
 283 };
 284
 285 // NullVoiceEngine can be used with CompositeMediaEngine in the case where only
 286 // a video engine is desired.
 287 class NullVoiceEngine {
 288  public:
 289   bool Init(rtc::Thread* worker_thread) { return true; }
 290   void Terminate() {}
 291   int GetCapabilities() { return 0; }
 292   // If you need this to return an actual channel, use FakeMediaEngine instead.
 293   VoiceMediaChannel* CreateChannel() {
 294     return NULL;
 295   }
 296   SoundclipMedia* CreateSoundclip() {
 297     return NULL;
 298   }
 299   bool SetDelayOffset(int offset) { return true; }
 300   AudioOptions GetOptions() const { return AudioOptions(); }
 301   bool SetOptions(const AudioOptions& options) { return true; }
 302   bool SetDevices(const Device* in_device, const Device* out_device) {
 303     return true;
 304   }
 305   bool GetOutputVolume(int* level) {
 306     *level = 0;
 307     return true;
 308   }
 309   bool SetOutputVolume(int level) { return true; }
 310   int GetInputLevel() { return 0; }
 311   bool SetLocalMonitor(bool enable) { return true; }
 312   const std::vector<AudioCodec>& codecs() { return codecs_; }
 313   const std::vector<RtpHeaderExtension>& rtp_header_extensions() {
 314     return rtp_header_extensions_;
 315   }
 316   void SetLogging(int min_sev, const char* filter) {}
 317   bool StartAecDump(rtc::PlatformFile file) { return false; }
 318   bool RegisterProcessor(uint32 ssrc,
 319                          VoiceProcessor* voice_processor,
 320                          MediaProcessorDirection direction) { return true; }
 321   bool UnregisterProcessor(uint32 ssrc,
 322                            VoiceProcessor* voice_processor,
 323                            MediaProcessorDirection direction) { return true; }
 324
 325  private:
 326   std::vector<AudioCodec> codecs_;
 327   std::vector<RtpHeaderExtension> rtp_header_extensions_;
 328 };
 329
 330 // NullVideoEngine can be used with CompositeMediaEngine in the case where only
 331 // a voice engine is desired.
 332 class NullVideoEngine {
 333  public:
 334   bool Init(rtc::Thread* worker_thread) { return true; }
 335   void Terminate() {}
 336   int GetCapabilities() { return 0; }
 337   // If you need this to return an actual channel, use FakeMediaEngine instead.
 338   VideoMediaChannel* CreateChannel(
 339       VoiceMediaChannel* voice_media_channel) {
 340     return NULL;
 341   }
 342   bool SetOptions(const VideoOptions& options) { return true; }
 343   bool SetDefaultEncoderConfig(const VideoEncoderConfig& config) {
 344     return true;
 345   }
 346   const std::vector<VideoCodec>& codecs() { return codecs_; }
 347   const std::vector<RtpHeaderExtension>& rtp_header_extensions() {
 348     return rtp_header_extensions_;
 349   }
 350   void SetLogging(int min_sev, const char* filter) {}
 351   VideoFormat GetStartCaptureFormat() const { return VideoFormat(); }
 352
 353   sigslot::signal2<VideoCapturer*, CaptureState> SignalCaptureStateChange;
 354  private:
 355   std::vector<VideoCodec> codecs_;
 356   std::vector<RtpHeaderExtension> rtp_header_extensions_;
 357 };
 358
 359 typedef CompositeMediaEngine<NullVoiceEngine, NullVideoEngine> NullMediaEngine;
 360
 361 enum DataChannelType {
 362   DCT_NONE = 0,
 363   DCT_RTP = 1,
 364   DCT_SCTP = 2
 365 };
 366
 367 class DataEngineInterface {
 368  public:
 369   virtual ~DataEngineInterface() {}
 370   virtual DataMediaChannel* CreateChannel(DataChannelType type) = 0;
 371   virtual const std::vector<DataCodec>& data_codecs() = 0;
 372 };
 373
 374 }  // namespace cricket
 375
 376 #endif  // TALK_MEDIA_BASE_MEDIAENGINE_H_