1 /* 2 * Copyright (c) 2012 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 // This sub-API supports the following functionalities: 12 // 13 // - Creating and deleting VideoEngine instances. 14 // - Creating and deleting channels. 15 // - Connect a video channel with a corresponding voice channel for audio/video 16 // synchronization. 17 // - Start and stop sending and receiving. 18 19 #ifndef WEBRTC_VIDEO_ENGINE_INCLUDE_VIE_BASE_H_ 20 #define WEBRTC_VIDEO_ENGINE_INCLUDE_VIE_BASE_H_ 21 22 #include "webrtc/common_types.h" 23 24 #if defined(ANDROID) && !defined(WEBRTC_CHROMIUM_BUILD) 25 #include <jni.h> 26 #endif 27 28 namespace webrtc { 29 30 class Config; 31 class VoiceEngine; 32 33 // CpuOveruseObserver is called when a system overuse is detected and 34 // VideoEngine cannot keep up the encoding frequency. 35 class CpuOveruseObserver { 36 public: 37 // Called as soon as an overuse is detected. 38 virtual void OveruseDetected() = 0; 39 // Called periodically when the system is not overused any longer. 40 virtual void NormalUsage() = 0; 41 42 protected: 43 virtual ~CpuOveruseObserver() {} 44 }; 45 46 // Limits on standard deviation for under/overuse. 47 #ifdef WEBRTC_ANDROID 48 const float kOveruseStdDevMs = 32.0f; 49 const float kNormalUseStdDevMs = 27.0f; 50 #elif WEBRTC_LINUX 51 const float kOveruseStdDevMs = 20.0f; 52 const float kNormalUseStdDevMs = 14.0f; 53 #elif WEBRTC_MAC 54 const float kOveruseStdDevMs = 27.0f; 55 const float kNormalUseStdDevMs = 21.0f; 56 #elif WEBRTC_WIN 57 const float kOveruseStdDevMs = 20.0f; 58 const float kNormalUseStdDevMs = 14.0f; 59 #else 60 const float kOveruseStdDevMs = 30.0f; 61 const float kNormalUseStdDevMs = 20.0f; 62 #endif 63 64 struct CpuOveruseOptions { 65 CpuOveruseOptions() 66 : enable_capture_jitter_method(true), 67 low_capture_jitter_threshold_ms(kNormalUseStdDevMs), 68 high_capture_jitter_threshold_ms(kOveruseStdDevMs), 69 enable_encode_usage_method(false), 70 low_encode_usage_threshold_percent(60), 71 high_encode_usage_threshold_percent(90), 72 low_encode_time_rsd_threshold(-1), 73 high_encode_time_rsd_threshold(-1), 74 frame_timeout_interval_ms(1500), 75 min_frame_samples(120), 76 min_process_count(3), 77 high_threshold_consecutive_count(2) {} 78 79 // Method based on inter-arrival jitter of captured frames. 80 bool enable_capture_jitter_method; 81 float low_capture_jitter_threshold_ms; // Threshold for triggering underuse. 82 float high_capture_jitter_threshold_ms; // Threshold for triggering overuse. 83 // Method based on encode time of frames. 84 bool enable_encode_usage_method; 85 int low_encode_usage_threshold_percent; // Threshold for triggering underuse. 86 int high_encode_usage_threshold_percent; // Threshold for triggering overuse. 87 int low_encode_time_rsd_threshold; // Additional threshold for triggering 88 // underuse (used in addition to 89 // threshold above if configured). 90 int high_encode_time_rsd_threshold; // Additional threshold for triggering 91 // overuse (used in addition to 92 // threshold above if configured). 93 // General settings. 94 int frame_timeout_interval_ms; // The maximum allowed interval between two 95 // frames before resetting estimations. 96 int min_frame_samples; // The minimum number of frames required. 97 int min_process_count; // The number of initial process times required before 98 // triggering an overuse/underuse. 99 int high_threshold_consecutive_count; // The number of consecutive checks 100 // above the high threshold before 101 // triggering an overuse. 102 103 bool Equals(const CpuOveruseOptions& o) const { 104 return enable_capture_jitter_method == o.enable_capture_jitter_method && 105 low_capture_jitter_threshold_ms == o.low_capture_jitter_threshold_ms && 106 high_capture_jitter_threshold_ms == 107 o.high_capture_jitter_threshold_ms && 108 enable_encode_usage_method == o.enable_encode_usage_method && 109 low_encode_usage_threshold_percent == 110 o.low_encode_usage_threshold_percent && 111 high_encode_usage_threshold_percent == 112 o.high_encode_usage_threshold_percent && 113 low_encode_time_rsd_threshold == o.low_encode_time_rsd_threshold && 114 high_encode_time_rsd_threshold == o.high_encode_time_rsd_threshold && 115 frame_timeout_interval_ms == o.frame_timeout_interval_ms && 116 min_frame_samples == o.min_frame_samples && 117 min_process_count == o.min_process_count && 118 high_threshold_consecutive_count == o.high_threshold_consecutive_count; 119 } 120 }; 121 122 struct CpuOveruseMetrics { 123 CpuOveruseMetrics() 124 : capture_jitter_ms(-1), 125 avg_encode_time_ms(-1), 126 encode_usage_percent(-1), 127 encode_rsd(-1), 128 capture_queue_delay_ms_per_s(-1) {} 129 130 int capture_jitter_ms; // The current estimated jitter in ms based on 131 // incoming captured frames. 132 int avg_encode_time_ms; // The average encode time in ms. 133 int encode_usage_percent; // The average encode time divided by the average 134 // time difference between incoming captured frames. 135 int encode_rsd; // The relative std dev of encode time of frames. 136 int capture_queue_delay_ms_per_s; // The current time delay between an 137 // incoming captured frame until the frame 138 // is being processed. The delay is 139 // expressed in ms delay per second. 140 }; 141 142 class WEBRTC_DLLEXPORT VideoEngine { 143 public: 144 // Creates a VideoEngine object, which can then be used to acquire subAPIs. 145 static VideoEngine* Create(); 146 static VideoEngine* Create(const Config& config); 147 148 // Deletes a VideoEngine instance. 149 static bool Delete(VideoEngine*& video_engine); 150 151 // Specifies the amount and type of trace information, which will be created 152 // by the VideoEngine. 153 static int SetTraceFilter(const unsigned int filter); 154 155 // Sets the name of the trace file and enables nonencrypted trace messages. 156 static int SetTraceFile(const char* file_nameUTF8, 157 const bool add_file_counter = false); 158 159 // Installs the TraceCallback implementation to ensure that the VideoEngine 160 // user receives callbacks for generated trace messages. 161 static int SetTraceCallback(TraceCallback* callback); 162 163 #if defined(ANDROID) && !defined(WEBRTC_CHROMIUM_BUILD) 164 // Android specific. 165 static int SetAndroidObjects(JavaVM* java_vm, jobject context); 166 #endif 167 168 protected: 169 VideoEngine() {} 170 virtual ~VideoEngine() {} 171 }; 172 173 class WEBRTC_DLLEXPORT ViEBase { 174 public: 175 // Factory for the ViEBase subAPI and increases an internal reference 176 // counter if successful. Returns NULL if the API is not supported or if 177 // construction fails. 178 static ViEBase* GetInterface(VideoEngine* video_engine); 179 180 // Releases the ViEBase sub-API and decreases an internal reference counter. 181 // Returns the new reference count. This value should be zero 182 // for all sub-API:s before the VideoEngine object can be safely deleted. 183 virtual int Release() = 0; 184 185 // Initiates all common parts of the VideoEngine. 186 virtual int Init() = 0; 187 188 // Connects a VideoEngine instance to a VoiceEngine instance for audio video 189 // synchronization. 190 virtual int SetVoiceEngine(VoiceEngine* voice_engine) = 0; 191 192 // Creates a new channel. 193 virtual int CreateChannel(int& video_channel) = 0; 194 195 // Creates a new channel grouped together with |original_channel|. The channel 196 // can both send and receive video. It is assumed the channel is sending 197 // and/or receiving video to the same end-point. 198 // Note: |CreateReceiveChannel| will give better performance and network 199 // properties for receive only channels. 200 virtual int CreateChannel(int& video_channel, 201 int original_channel) = 0; 202 203 // Creates a new channel grouped together with |original_channel|. The channel 204 // can only receive video and it is assumed the remote end-point is the same 205 // as for |original_channel|. 206 virtual int CreateReceiveChannel(int& video_channel, 207 int original_channel) = 0; 208 209 // Deletes an existing channel and releases the utilized resources. 210 virtual int DeleteChannel(const int video_channel) = 0; 211 212 // Registers an observer to be called when an overuse is detected, see 213 // 'CpuOveruseObserver' for details. 214 // NOTE: This is still very experimental functionality. 215 virtual int RegisterCpuOveruseObserver(int channel, 216 CpuOveruseObserver* observer) = 0; 217 218 // Sets options for cpu overuse detector. 219 // TODO(asapersson): Remove default implementation. 220 virtual int SetCpuOveruseOptions(int channel, 221 const CpuOveruseOptions& options) { 222 return -1; 223 } 224 225 // Gets cpu overuse measures. 226 // TODO(asapersson): Remove default implementation. 227 virtual int GetCpuOveruseMetrics(int channel, 228 CpuOveruseMetrics* metrics) { 229 return -1; 230 } 231 // TODO(asapersson): Remove this function when libjingle has been updated. 232 virtual int CpuOveruseMeasures(int channel, 233 int* capture_jitter_ms, 234 int* avg_encode_time_ms, 235 int* encode_usage_percent, 236 int* capture_queue_delay_ms_per_s) { 237 return -1; 238 } 239 240 // Specifies the VoiceEngine and VideoEngine channel pair to use for 241 // audio/video synchronization. 242 virtual int ConnectAudioChannel(const int video_channel, 243 const int audio_channel) = 0; 244 245 // Disconnects a previously paired VideoEngine and VoiceEngine channel pair. 246 virtual int DisconnectAudioChannel(const int video_channel) = 0; 247 248 // Starts sending packets to an already specified IP address and port number 249 // for a specified channel. 250 virtual int StartSend(const int video_channel) = 0; 251 252 // Stops packets from being sent for a specified channel. 253 virtual int StopSend(const int video_channel) = 0; 254 255 // Prepares VideoEngine for receiving packets on the specified channel. 256 virtual int StartReceive(const int video_channel) = 0; 257 258 // Stops receiving incoming RTP and RTCP packets on the specified channel. 259 virtual int StopReceive(const int video_channel) = 0; 260 261 // Retrieves the version information for VideoEngine and its components. 262 virtual int GetVersion(char version[1024]) = 0; 263 264 // Returns the last VideoEngine error code. 265 virtual int LastError() = 0; 266 267 protected: 268 ViEBase() {} 269 virtual ~ViEBase() {} 270 }; 271 272 } // namespace webrtc 273 274 #endif // #define WEBRTC_VIDEO_ENGINE_MAIN_INTERFACE_VIE_BASE_H_ 275
