content/media/webrtc/MediaEngine.h

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   3  * You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 #ifndef MEDIAENGINE_H_
   6 #define MEDIAENGINE_H_
   7
   8 #include "nsIDOMFile.h"
   9 #include "DOMMediaStream.h"
  10 #include "MediaStreamGraph.h"
  11
  12 namespace mozilla {
  13
  14 /**
  15  * Abstract interface for managing audio and video devices. Each platform
  16  * must implement a concrete class that will map these classes and methods
  17  * to the appropriate backend. For example, on Desktop platforms, these will
  18  * correspond to equivalent webrtc (GIPS) calls, and on B2G they will map to
  19  * a Gonk interface.
  20  */
  21 class MediaEngineVideoSource;
  22 class MediaEngineAudioSource;
  23 struct MediaEnginePrefs;
  24
  25 enum MediaEngineState {
  26   kAllocated,
  27   kStarted,
  28   kStopped,
  29   kReleased
  30 };
  31
  32 // We only support 1 audio and 1 video track for now.
  33 enum {
  34   kVideoTrack = 1,
  35   kAudioTrack = 2
  36 };
  37
  38 class MediaEngine
  39 {
  40 public:
  41   virtual ~MediaEngine() {}
  42
  43   static const int DEFAULT_VIDEO_FPS = 30;
  44   static const int DEFAULT_VIDEO_MIN_FPS = 10;
  45   static const int DEFAULT_VIDEO_WIDTH = 640;
  46   static const int DEFAULT_VIDEO_HEIGHT = 480;
  47   static const int DEFAULT_AUDIO_TIMER_MS = 10;
  48   static const bool DEFAULT_LOAD_ADAPT = false;
  49
  50   /* Populate an array of video sources in the nsTArray. Also include devices
  51    * that are currently unavailable. */
  52   virtual void EnumerateVideoDevices(nsTArray<nsRefPtr<MediaEngineVideoSource> >*) = 0;
  53
  54   /* Populate an array of audio sources in the nsTArray. Also include devices
  55    * that are currently unavailable. */
  56   virtual void EnumerateAudioDevices(nsTArray<nsRefPtr<MediaEngineAudioSource> >*) = 0;
  57 };
  58
  59 /**
  60  * Common abstract base class for audio and video sources.
  61  */
  62 class MediaEngineSource : public nsISupports
  63 {
  64 public:
  65   virtual ~MediaEngineSource() {}
  66
  67   /* Populate the human readable name of this device in the nsAString */
  68   virtual void GetName(nsAString&) = 0;
  69
  70   /* Populate the UUID of this device in the nsAString */
  71   virtual void GetUUID(nsAString&) = 0;
  72
  73   /* This call reserves but does not start the device. */
  74   virtual nsresult Allocate(const MediaEnginePrefs &aPrefs) = 0;
  75
  76   /* Release the device back to the system. */
  77   virtual nsresult Deallocate() = 0;
  78
  79   /* Start the device and add the track to the provided SourceMediaStream, with
  80    * the provided TrackID. You may start appending data to the track
  81    * immediately after. */
  82   virtual nsresult Start(SourceMediaStream*, TrackID) = 0;
  83
  84   /* Take a snapshot from this source. In the case of video this is a single
  85    * image, and for audio, it is a snippet lasting aDuration milliseconds. The
  86    * duration argument is ignored for a MediaEngineVideoSource.
  87    */
  88   virtual nsresult Snapshot(uint32_t aDuration, nsIDOMFile** aFile) = 0;
  89
  90   /* Called when the stream wants more data */
  91   virtual void NotifyPull(MediaStreamGraph* aGraph,
  92                           SourceMediaStream *aSource,
  93                           TrackID aId,
  94                           StreamTime aDesiredTime,
  95                           TrackTicks &aLastEndTime) = 0;
  96
  97   /* Stop the device and release the corresponding MediaStream */
  98   virtual nsresult Stop(SourceMediaStream *aSource, TrackID aID) = 0;
  99
 100   /* Change device configuration.  */
 101   virtual nsresult Config(bool aEchoOn, uint32_t aEcho,
 102                           bool aAgcOn, uint32_t aAGC,
 103                           bool aNoiseOn, uint32_t aNoise) = 0;
 104
 105   /* Returns true if a source represents a fake capture device and
 106    * false otherwise
 107    */
 108   virtual bool IsFake() = 0;
 109
 110   /* Return false if device is currently allocated or started */
 111   bool IsAvailable() {
 112     if (mState == kAllocated || mState == kStarted) {
 113       return false;
 114     } else {
 115       return true;
 116     }
 117   }
 118
 119   /* It is an error to call Start() before an Allocate(), and Stop() before
 120    * a Start(). Only Allocate() may be called after a Deallocate(). */
 121
 122 protected:
 123   MediaEngineState mState;
 124 };
 125
 126 /**
 127  * Video source and friends.
 128  */
 129 struct MediaEnginePrefs {
 130   int32_t mWidth;
 131   int32_t mHeight;
 132   int32_t mFPS;
 133   int32_t mMinFPS;
 134   bool mLoadAdapt;
 135 };
 136
 137 class MediaEngineVideoSource : public MediaEngineSource
 138 {
 139 public:
 140   virtual ~MediaEngineVideoSource() {}
 141 };
 142
 143 /**
 144  * Audio source and friends.
 145  */
 146 class MediaEngineAudioSource : public MediaEngineSource
 147 {
 148 public:
 149   virtual ~MediaEngineAudioSource() {}
 150 };
 151
 152 }
 153
 154 #endif /* MEDIAENGINE_H_ */