1 /* 2 mediastreamer2 library - modular sound and video processing and streaming 3 4 * Copyright (C) 2011 Belledonne Communications, Grenoble, France 5 6 This program is free software; you can redistribute it and/or 7 modify it under the terms of the GNU General Public License 8 as published by the Free Software Foundation; either version 2 9 of the License, or (at your option) any later version. 10 11 This program is distributed in the hope that it will be useful, 12 but WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 GNU General Public License for more details. 15 16 You should have received a copy of the GNU General Public License 17 along with this program; if not, write to the Free Software 18 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 19 */ 20 21 #ifndef ms2_ratecontrol 22 #define ms2_ratecontrol 23 24 #include "mediastreamer2/msfilter.h" 25 #include <ortp/ortp.h> 26 27 #ifdef __cplusplus 28 extern "C" { 29 #endif 30 31 struct _MediaStream; 32 33 typedef struct _MSBandwidthControllerStats{ 34 float estimated_download_bandwidth; /*in bits/seconds*/ 35 float controlled_stream_bandwidth; 36 bool_t in_congestion; 37 }MSBandwidthControllerStats; 38 39 struct _MSBandwidthController{ 40 bctbx_list_t *streams; /*list of MediaStream objects*/ 41 struct _MediaStream *controlled_stream; /*the most bandwidth consuming stream, which is the one flow controlled*/ 42 MSBandwidthControllerStats stats; 43 bool_t congestion_detected; 44 float remote_video_bandwidth_available_estimated; 45 }; 46 /** 47 * The MSBandwidthController is a object managing several streams (audio, video) and monitoring congestion of inbound streams. 48 * If a congestion is detected, it will send RTCP TMMBR packet to the remote sender in order to stop the congestion and adapt 49 * the incoming bitrate of received streams to the available bandwidth. 50 * It superseeds the MSBitrateController, MSQosAnalyzer, MSBitrateDriver objects, which were using different but less robust techniques 51 * to detect congestion and adapt bandwidth usage. 52 **/ 53 typedef struct _MSBandwidthController MSBandwidthController; 54 55 56 MS2_PUBLIC MSBandwidthController *ms_bandwidth_controller_new(void); 57 58 MS2_PUBLIC void ms_bandwidth_controller_add_stream(MSBandwidthController *obj, struct _MediaStream *stream); 59 60 MS2_PUBLIC void ms_bandwidth_controller_remove_stream(MSBandwidthController *obj, struct _MediaStream *stream); 61 62 MS2_PUBLIC const MSBandwidthControllerStats * ms_bandwidth_controller_get_stats(MSBandwidthController *obj); 63 64 MS2_PUBLIC void ms_bandwidth_controller_destroy(MSBandwidthController *obj); 65 66 67 /** 68 * Audio Bitrate controller object. 69 * @deprecated 70 **/ 71 typedef struct _MSAudioBitrateController MSAudioBitrateController; 72 73 enum _MSRateControlActionType{ 74 MSRateControlActionDoNothing, 75 MSRateControlActionDecreaseBitrate, 76 MSRateControlActionDecreasePacketRate, 77 MSRateControlActionIncreaseQuality, 78 }; 79 typedef enum _MSRateControlActionType MSRateControlActionType; 80 const char *ms_rate_control_action_type_name(MSRateControlActionType t); 81 82 83 typedef struct _MSRateControlAction{ 84 MSRateControlActionType type; 85 int value; 86 }MSRateControlAction; 87 88 typedef struct _MSBitrateDriver MSBitrateDriver; 89 typedef struct _MSBitrateDriverDesc MSBitrateDriverDesc; 90 91 struct _MSBitrateDriverDesc{ 92 int (*execute_action)(MSBitrateDriver *obj, const MSRateControlAction *action); 93 void (*uninit)(MSBitrateDriver *obj); 94 }; 95 96 /** 97 * The MSBitrateDriver has the responsibility to execute rate control actions. 98 * This is an abstract interface. 99 * @deprecated 100 **/ 101 struct _MSBitrateDriver{ 102 MSBitrateDriverDesc *desc; 103 int refcnt; 104 }; 105 106 MS2_PUBLIC int ms_bitrate_driver_execute_action(MSBitrateDriver *obj, const MSRateControlAction *action); 107 MS2_PUBLIC MSBitrateDriver * ms_bitrate_driver_ref(MSBitrateDriver *obj); 108 MS2_PUBLIC void ms_bitrate_driver_unref(MSBitrateDriver *obj); 109 110 MS2_PUBLIC MSBitrateDriver *ms_audio_bitrate_driver_new(RtpSession *session, MSFilter *encoder); 111 MS2_PUBLIC MSBitrateDriver *ms_av_bitrate_driver_new(RtpSession *asession, MSFilter *aenc, RtpSession *vsession, MSFilter *venc); 112 MS2_PUBLIC MSBitrateDriver *ms_bandwidth_bitrate_driver_new(RtpSession *asession, MSFilter *aenc, RtpSession *vsession, MSFilter *venc); 113 114 typedef struct _MSQosAnalyzer MSQosAnalyzer; 115 typedef struct _MSQosAnalyzerDesc MSQosAnalyzerDesc; 116 117 struct _MSQosAnalyzerDesc{ 118 bool_t (*process_rtcp)(MSQosAnalyzer *obj, mblk_t *rtcp); 119 void (*suggest_action)(MSQosAnalyzer *obj, MSRateControlAction *action); 120 bool_t (*has_improved)(MSQosAnalyzer *obj); 121 void (*update)(MSQosAnalyzer *); 122 void (*uninit)(MSQosAnalyzer *); 123 }; 124 125 enum _MSQosAnalyzerAlgorithm { 126 MSQosAnalyzerAlgorithmSimple, 127 MSQosAnalyzerAlgorithmStateful 128 }; 129 typedef enum _MSQosAnalyzerAlgorithm MSQosAnalyzerAlgorithm; 130 MS2_PUBLIC const char* ms_qos_analyzer_algorithm_to_string(MSQosAnalyzerAlgorithm alg); 131 MS2_PUBLIC MSQosAnalyzerAlgorithm ms_qos_analyzer_algorithm_from_string(const char* alg); 132 133 /** 134 * A MSQosAnalyzer is responsible to analyze RTCP feedback and suggest 135 * actions on bitrate or packet rate accordingly. 136 * This is an abstract interface. 137 * @deprecated 138 **/ 139 struct _MSQosAnalyzer{ 140 MSQosAnalyzerDesc *desc; 141 OrtpLossRateEstimator *lre; 142 char *label; 143 /** 144 * Each time the algorithm suggest an action, this callback is called with the userpointer 145 * @param userpointer on_action_suggested_user_pointer pointer given 146 * @param argc number of arguments on the third argument array 147 * @param argv array containing various algorithm dependent information 148 **/ 149 void (*on_action_suggested)(void* userpointer, int argc, const char** argv); 150 /** User pointer given at #on_action_suggested callback **/ 151 void *on_action_suggested_user_pointer; 152 int refcnt; 153 MSQosAnalyzerAlgorithm type; 154 }; 155 156 157 MS2_PUBLIC MSQosAnalyzer * ms_qos_analyzer_ref(MSQosAnalyzer *obj); 158 MS2_PUBLIC void ms_qos_analyzer_unref(MSQosAnalyzer *obj); 159 MS2_PUBLIC void ms_qos_analyser_set_label(MSQosAnalyzer *obj, const char *label); 160 MS2_PUBLIC void ms_qos_analyzer_suggest_action(MSQosAnalyzer *obj, MSRateControlAction *action); 161 MS2_PUBLIC bool_t ms_qos_analyzer_has_improved(MSQosAnalyzer *obj); 162 MS2_PUBLIC bool_t ms_qos_analyzer_process_rtcp(MSQosAnalyzer *obj, mblk_t *rtcp); 163 MS2_PUBLIC void ms_qos_analyzer_update(MSQosAnalyzer *obj); 164 MS2_PUBLIC const char* ms_qos_analyzer_get_name(MSQosAnalyzer *obj); 165 MS2_PUBLIC void ms_qos_analyzer_set_on_action_suggested(MSQosAnalyzer *obj, void (*on_action_suggested)(void*,int,const char**),void* u); 166 167 /** 168 * The simple qos analyzer is an implementation of MSQosAnalyzer that performs analysis for single stream. 169 **/ 170 MS2_PUBLIC MSQosAnalyzer * ms_simple_qos_analyzer_new(RtpSession *session); 171 172 MS2_PUBLIC MSQosAnalyzer * ms_stateful_qos_analyzer_new(RtpSession *session); 173 /** 174 * The audio/video qos analyzer is an implementation of MSQosAnalyzer that performs analysis of two audio and video streams. 175 **/ 176 /*MSQosAnalyzer * ms_av_qos_analyzer_new(RtpSession *asession, RtpSession *vsession);*/ 177 178 /** 179 * The MSBitrateController the overall behavior and state machine of the adaptive rate control system. 180 * It requires a MSQosAnalyzer to obtain analyse of the quality of service, and a MSBitrateDriver 181 * to run the actions on media streams, like decreasing or increasing bitrate. 182 **/ 183 typedef struct _MSBitrateController MSBitrateController; 184 185 /** 186 * Instanciates MSBitrateController 187 * @param qosanalyzer a Qos analyzer object 188 * @param driver a bitrate driver object. 189 * The newly created bitrate controller owns references to the analyzer and the driver. 190 **/ 191 MS2_PUBLIC MSBitrateController *ms_bitrate_controller_new(MSQosAnalyzer *qosanalyzer, MSBitrateDriver *driver); 192 193 /** 194 * Asks the bitrate controller to process a newly received RTCP packet. 195 * @param MSBitrateController the bitrate controller object. 196 * @param rtcp an RTCP packet received for the media session(s) being managed by the controller. 197 * If the RTCP packet contains useful feedback regarding quality of the media streams received by the far end, 198 * then the bitrate controller may take decision and execute actions on the local media streams to adapt the 199 * output bitrate. 200 **/ 201 MS2_PUBLIC void ms_bitrate_controller_process_rtcp(MSBitrateController *obj, mblk_t *rtcp); 202 203 MS2_PUBLIC void ms_bitrate_controller_update(MSBitrateController *obj); 204 205 /** 206 * Return the QoS analyzer associated to the bitrate controller 207 **/ 208 MS2_PUBLIC MSQosAnalyzer * ms_bitrate_controller_get_qos_analyzer(MSBitrateController *obj); 209 210 /** 211 * Destroys the bitrate controller 212 * 213 * If no other entity holds references to the underlyings MSQosAnalyzer and MSBitrateDriver object, 214 * then they will be destroyed too. 215 **/ 216 MS2_PUBLIC void ms_bitrate_controller_destroy(MSBitrateController *obj); 217 218 /** 219 * Convenience function to create a bitrate controller managing a single audio stream. 220 * @param session the RtpSession object for the media stream 221 * @param encoder the MSFilter object responsible for encoding the audio data. 222 * @param flags unused. 223 * This function actually calls internally: 224 * <br> 225 * \code 226 * ms_bitrate_controller_new(ms_simple_qos_analyzer_new(session),ms_audio_bitrate_driver_new(encoder)); 227 * \endcode 228 **/ 229 MS2_PUBLIC MSBitrateController *ms_audio_bitrate_controller_new(RtpSession *session, MSFilter *encoder, unsigned int flags); 230 231 /** 232 * Convenience fonction to create a bitrate controller managing a video and an audio stream. 233 * @param vsession the video RtpSession 234 * @param venc the video encoder 235 * @param asession the audio RtpSession 236 * @param aenc the audio encoder 237 * This function actually calls internally: 238 * <br> 239 * \code 240 * ms_bitrate_controller_new(ms_av_qos_analyzer_new(asession,vsession),ms_av_bitrate_driver_new(aenc,venc)); 241 * \endcode 242 **/ 243 MS2_PUBLIC MSBitrateController *ms_av_bitrate_controller_new(RtpSession *asession, MSFilter *aenc, RtpSession *vsession, MSFilter *venc); 244 245 MS2_PUBLIC MSBitrateController *ms_bandwidth_bitrate_controller_new(RtpSession *asession, MSFilter *aenc, RtpSession *vsession, MSFilter *venc); 246 #ifdef __cplusplus 247 } 248 #endif 249 250 #endif 251 252 253