bitratecontrol.h 8.15 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
/*
mediastreamer2 library - modular sound and video processing and streaming

 * Copyright (C) 2011  Belledonne Communications, Grenoble, France

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
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 22 23 24
 */

#ifndef ms2_ratecontrol
#define ms2_ratecontrol

#include "mediastreamer2/msfilter.h"
25
#include <ortp/ortp.h>
26 27 28 29 30 31 32 33 34 35 36 37

#ifdef __cplusplus
extern "C" {
#endif


/**
 * Audio Bitrate controller object
**/

typedef struct _MSAudioBitrateController MSAudioBitrateController;

38
enum _MSRateControlActionType{
39 40 41
	MSRateControlActionDoNothing,
	MSRateControlActionDecreaseBitrate,
	MSRateControlActionDecreasePacketRate,
42
	MSRateControlActionIncreaseQuality,
43
};
44 45 46
typedef enum _MSRateControlActionType MSRateControlActionType;
const char *ms_rate_control_action_type_name(MSRateControlActionType t);

47

48
typedef struct _MSRateControlAction{
49
	MSRateControlActionType type;
50 51 52 53 54 55 56
	int value;
}MSRateControlAction;

typedef struct _MSBitrateDriver MSBitrateDriver;
typedef struct _MSBitrateDriverDesc MSBitrateDriverDesc;

struct _MSBitrateDriverDesc{
57
	int (*execute_action)(MSBitrateDriver *obj, const MSRateControlAction *action);
58 59 60 61
	void (*uninit)(MSBitrateDriver *obj);
};

/*
62
 * The MSBitrateDriver has the responsibility to execute rate control actions.
63 64 65 66
 * This is an abstract interface.
**/
struct _MSBitrateDriver{
	MSBitrateDriverDesc *desc;
67
	int refcnt;
68 69
};

70 71 72
MS2_PUBLIC int ms_bitrate_driver_execute_action(MSBitrateDriver *obj, const MSRateControlAction *action);
MS2_PUBLIC MSBitrateDriver * ms_bitrate_driver_ref(MSBitrateDriver *obj);
MS2_PUBLIC void ms_bitrate_driver_unref(MSBitrateDriver *obj);
73

74 75 76
MS2_PUBLIC MSBitrateDriver *ms_audio_bitrate_driver_new(RtpSession *session, MSFilter *encoder);
MS2_PUBLIC MSBitrateDriver *ms_av_bitrate_driver_new(RtpSession *asession, MSFilter *aenc, RtpSession *vsession, MSFilter *venc);
MS2_PUBLIC MSBitrateDriver *ms_bandwidth_bitrate_driver_new(RtpSession *asession, MSFilter *aenc, RtpSession *vsession, MSFilter *venc);
77

78 79
typedef struct _MSQosAnalyzer MSQosAnalyzer;
typedef struct _MSQosAnalyzerDesc MSQosAnalyzerDesc;
80

81 82 83 84 85 86
struct _MSQosAnalyzerDesc{
	bool_t (*process_rtcp)(MSQosAnalyzer *obj, mblk_t *rtcp);
	void (*suggest_action)(MSQosAnalyzer *obj, MSRateControlAction *action);
	bool_t (*has_improved)(MSQosAnalyzer *obj);
	void (*update)(MSQosAnalyzer *);
	void (*uninit)(MSQosAnalyzer *);
87 88
};

89 90 91 92 93
enum _MSQosAnalyzerAlgorithm {
	MSQosAnalyzerAlgorithmSimple,
	MSQosAnalyzerAlgorithmStateful
};
typedef enum _MSQosAnalyzerAlgorithm MSQosAnalyzerAlgorithm;
Ghislain MARY's avatar
Ghislain MARY committed
94
MS2_PUBLIC const char* ms_qos_analyzer_algorithm_to_string(MSQosAnalyzerAlgorithm alg);
95
MS2_PUBLIC MSQosAnalyzerAlgorithm ms_qos_analyzer_algorithm_from_string(const char* alg);
96

97
/**
98 99
 * A MSQosAnalyzer is responsible to analyze RTCP feedback and suggest
 * actions on bitrate or packet rate accordingly.
100 101
 * This is an abstract interface.
**/
102 103
struct _MSQosAnalyzer{
	MSQosAnalyzerDesc *desc;
104
	OrtpLossRateEstimator *lre;
105
	char *label;
106 107 108 109 110 111 112
	/**
	* Each time the algorithm suggest an action, this callback is called with the userpointer
	* @param userpointer on_action_suggested_user_pointer pointer given
	* @param argc number of arguments on the third argument array
	* @param argv array containing various algorithm dependent information
	**/
	void (*on_action_suggested)(void* userpointer, int argc, const char** argv);
113
	/** User pointer given at #on_action_suggested callback **/
114
	void *on_action_suggested_user_pointer;
115
	int refcnt;
116
	MSQosAnalyzerAlgorithm type;
117 118
};

119

120 121 122 123 124 125 126 127 128
MS2_PUBLIC MSQosAnalyzer * ms_qos_analyzer_ref(MSQosAnalyzer *obj);
MS2_PUBLIC void ms_qos_analyzer_unref(MSQosAnalyzer *obj);
MS2_PUBLIC void ms_qos_analyser_set_label(MSQosAnalyzer *obj, const char *label);
MS2_PUBLIC void ms_qos_analyzer_suggest_action(MSQosAnalyzer *obj, MSRateControlAction *action);
MS2_PUBLIC bool_t ms_qos_analyzer_has_improved(MSQosAnalyzer *obj);
MS2_PUBLIC bool_t ms_qos_analyzer_process_rtcp(MSQosAnalyzer *obj, mblk_t *rtcp);
MS2_PUBLIC void ms_qos_analyzer_update(MSQosAnalyzer *obj);
MS2_PUBLIC const char* ms_qos_analyzer_get_name(MSQosAnalyzer *obj);
MS2_PUBLIC void ms_qos_analyzer_set_on_action_suggested(MSQosAnalyzer *obj, void (*on_action_suggested)(void*,int,const char**),void* u);
129

130
/**
131
 * The simple qos analyzer is an implementation of MSQosAnalyzer that performs analysis for single stream.
132
**/
133
MS2_PUBLIC MSQosAnalyzer * ms_simple_qos_analyzer_new(RtpSession *session);
134

135
MS2_PUBLIC MSQosAnalyzer * ms_stateful_qos_analyzer_new(RtpSession *session);
136
/**
137
 * The audio/video qos analyzer is an implementation of MSQosAnalyzer that performs analysis of two audio and video streams.
138
**/
139
/*MSQosAnalyzer * ms_av_qos_analyzer_new(RtpSession *asession, RtpSession *vsession);*/
140

141 142
/**
 * The MSBitrateController the overall behavior and state machine of the adaptive rate control system.
143
 * It requires a MSQosAnalyzer to obtain analyse of the quality of service, and a MSBitrateDriver
144 145 146 147 148 149
 * to run the actions on media streams, like decreasing or increasing bitrate.
**/
typedef struct _MSBitrateController MSBitrateController;

/**
 * Instanciates MSBitrateController
150
 * @param qosanalyzer a Qos analyzer object
151
 * @param driver a bitrate driver object.
152
 * The newly created bitrate controller owns references to the analyzer and the driver.
153
**/
154
MS2_PUBLIC MSBitrateController *ms_bitrate_controller_new(MSQosAnalyzer *qosanalyzer, MSBitrateDriver *driver);
155

156 157 158 159 160 161 162 163
/**
 * Asks the bitrate controller to process a newly received RTCP packet.
 * @param MSBitrateController the bitrate controller object.
 * @param rtcp an RTCP packet received for the media session(s) being managed by the controller.
 * If the RTCP packet contains useful feedback regarding quality of the media streams received by the far end,
 * then the bitrate controller may take decision and execute actions on the local media streams to adapt the
 * output bitrate.
**/
164
MS2_PUBLIC void ms_bitrate_controller_process_rtcp(MSBitrateController *obj, mblk_t *rtcp);
165

166
MS2_PUBLIC void ms_bitrate_controller_update(MSBitrateController *obj);
167

168
/**
169
 * Return the QoS analyzer associated to the bitrate controller
170
**/
171
MS2_PUBLIC MSQosAnalyzer * ms_bitrate_controller_get_qos_analyzer(MSBitrateController *obj);
172

173 174
/**
 * Destroys the bitrate controller
175
 *
176
 * If no other entity holds references to the underlyings MSQosAnalyzer and MSBitrateDriver object,
177 178
 * then they will be destroyed too.
**/
179
MS2_PUBLIC void ms_bitrate_controller_destroy(MSBitrateController *obj);
180

181 182 183 184 185 186 187 188
/**
 * Convenience function to create a bitrate controller managing a single audio stream.
 * @param session the RtpSession object for the media stream
 * @param encoder the MSFilter object responsible for encoding the audio data.
 * @param flags unused.
 * This function actually calls internally:
 * <br>
 * \code
189
 * ms_bitrate_controller_new(ms_simple_qos_analyzer_new(session),ms_audio_bitrate_driver_new(encoder));
190 191
 * \endcode
**/
192
MS2_PUBLIC MSBitrateController *ms_audio_bitrate_controller_new(RtpSession *session, MSFilter *encoder, unsigned int flags);
193

194 195 196 197 198 199 200 201 202
/**
 * Convenience fonction to create a bitrate controller managing a video and an audio stream.
 * @param vsession the video RtpSession
 * @param venc the video encoder
 * @param asession the audio RtpSession
 * @param aenc the audio encoder
 * This function actually calls internally:
 * <br>
 * \code
203
 * ms_bitrate_controller_new(ms_av_qos_analyzer_new(asession,vsession),ms_av_bitrate_driver_new(aenc,venc));
204 205
 * \endcode
**/
206
MS2_PUBLIC MSBitrateController *ms_av_bitrate_controller_new(RtpSession *asession, MSFilter *aenc, RtpSession *vsession, MSFilter *venc);
207

208
MS2_PUBLIC MSBitrateController *ms_bandwidth_bitrate_controller_new(RtpSession *asession, MSFilter *aenc, RtpSession *vsession, MSFilter *venc);
209 210 211 212 213 214 215
#ifdef __cplusplus
}
#endif

#endif