mediastream.h 32.2 KB
Newer Older
aymeric's avatar
aymeric committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
/*
mediastreamer2 library - modular sound and video processing and streaming
Copyright (C) 2006  Simon MORLAT (simon.morlat@linphone.org)

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
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
*/


#ifndef MEDIASTREAM_H
#define MEDIASTREAM_H

24 25
#include <ortp/ortp.h>
#include <ortp/event.h>
jehan's avatar
jehan committed
26 27
/* defined in srtp.h*/
typedef struct srtp_ctx_t *MSSrtpCtx;
28

Simon Morlat's avatar
Simon Morlat committed
29 30 31 32 33
#include <mediastreamer2/msfilter.h>
#include <mediastreamer2/msticker.h>
#include <mediastreamer2/mssndcard.h>
#include <mediastreamer2/mswebcam.h>
#include <mediastreamer2/msvideo.h>
34 35
#include <mediastreamer2/bitratecontrol.h>
#include <mediastreamer2/qualityindicator.h>
36
#include <mediastreamer2/ice.h>
37
#include <mediastreamer2/zrtp.h>
aymeric's avatar
aymeric committed
38

Ghislain MARY's avatar
Ghislain MARY committed
39

Simon Morlat's avatar
Simon Morlat committed
40 41 42
#define PAYLOAD_TYPE_FLAG_CAN_RECV	PAYLOAD_TYPE_USER_FLAG_1
#define PAYLOAD_TYPE_FLAG_CAN_SEND	PAYLOAD_TYPE_USER_FLAG_2

Ghislain MARY's avatar
Ghislain MARY committed
43 44 45 46 47

#ifdef __cplusplus
extern "C" {
#endif

48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70
/**
 * @addtogroup ring_api
 * @{
**/

struct _RingStream
{
	MSTicker *ticker;
	MSFilter *source;
	MSFilter *gendtmf;
	MSFilter *write_resampler;
	MSFilter *sndwrite;
};

typedef struct _RingStream RingStream;

MS2_PUBLIC RingStream *ring_start (const char * file, int interval, MSSndCard *sndcard);
MS2_PUBLIC RingStream *ring_start_with_cb(const char * file, int interval, MSSndCard *sndcard, MSFilterNotifyFunc func, void * user_data);
MS2_PUBLIC void ring_stop (RingStream * stream);

/**
 * @}
**/
jehan's avatar
jehan committed
71 72 73
/*
 * Crypto suite used configure encrypted stream*/
typedef enum _MSCryptoSuite{
Simon Morlat's avatar
Simon Morlat committed
74 75
	MS_CRYPTO_SUITE_INVALID=0,
	MS_AES_128_SHA1_80,
jehan's avatar
jehan committed
76 77 78 79 80 81
	MS_AES_128_SHA1_32,
	MS_AES_128_NO_AUTH,
	MS_NO_CIPHER_SHA1_80,
	MS_AES_256_SHA1_80,
	MS_AES_256_SHA1_32
} MSCryptoSuite;
82

Simon Morlat's avatar
Simon Morlat committed
83 84 85 86 87 88 89 90
typedef struct _MSCryptoSuiteNameParams{
	const char *name;
	const char *params;
}MSCryptoSuiteNameParams;

MS2_PUBLIC MSCryptoSuite ms_crypto_suite_build_from_name_params(const MSCryptoSuiteNameParams *nameparams);
MS2_PUBLIC int ms_crypto_suite_to_name_params(MSCryptoSuite cs, MSCryptoSuiteNameParams *nameparams);

91 92 93
/**
 * The MediaStream is an object describing a stream (one of AudioStream or VideoStream).
**/
jehan's avatar
jehan committed
94 95 96 97 98
typedef struct _MediaStream MediaStream;

/*
 * internal cb to process rtcp stream
 * */
99
typedef void (*media_stream_process_rtcp_callback_t)(MediaStream *stream, mblk_t *m);
jehan's avatar
jehan committed
100

101 102
struct _MSMediaStreamSessions{
	RtpSession *rtp_session;
jehan's avatar
jehan committed
103
	MSSrtpCtx srtp_session;
104
	MSZrtpContext *zrtp_context;
105
	MSTicker *ticker;
jehan's avatar
jehan committed
106
	bool_t is_secured;
107 108 109
};

typedef struct _MSMediaStreamSessions MSMediaStreamSessions;
jehan's avatar
jehan committed
110

111 112 113 114 115
MS2_PUBLIC void ms_media_stream_sessions_uninit(MSMediaStreamSessions *sessions);

typedef enum _MSStreamState{
	MSStreamInitialized,
	MSStreamPreparing,
116 117
	MSStreamStarted,
	MSStreamStopped
118 119
}MSStreamState;

Simon Morlat's avatar
Simon Morlat committed
120 121 122
#define AudioStreamType MSAudio
#define VideoStreamType MSVideo

123 124 125
/**
 * Base struct for both AudioStream and VideoStream structure.
**/
Ghislain MARY's avatar
Ghislain MARY committed
126
struct _MediaStream {
Simon Morlat's avatar
Simon Morlat committed
127
	MSFormatType type;
128 129
	MSStreamState state;
	MSMediaStreamSessions sessions;
Ghislain MARY's avatar
Ghislain MARY committed
130 131 132 133 134 135 136
	OrtpEvQueue *evq;
	MSFilter *rtprecv;
	MSFilter *rtpsend;
	MSFilter *encoder;
	MSFilter *decoder;
	MSFilter *voidsink;
	MSBitrateController *rc;
137
	MSQualityIndicator *qi;
Ghislain MARY's avatar
Ghislain MARY committed
138
	IceCheckList *ice_check_list;
139 140
	time_t start_time;
	time_t last_iterate_time;
141 142
	uint64_t last_packet_count;
	time_t last_packet_time;
143 144
	bool_t rc_enable;
	MSQosAnalyzerAlgorithm rc_algorithm;
145
	bool_t is_beginning;
146
	bool_t owns_sessions;
147
	bool_t pad;
jehan's avatar
jehan committed
148
	/**
149
	 * defines encoder target network bit rate, uses #media_stream_set_target_network_bitrate() setter.
jehan's avatar
jehan committed
150 151
	 * */
	int target_bitrate;
152
	media_stream_process_rtcp_callback_t process_rtcp;
Ghislain MARY's avatar
Ghislain MARY committed
153 154
};

jehan's avatar
jehan committed
155 156 157 158 159

/**
 * @addtogroup audio_stream_api
 * @{
**/
Ghislain MARY's avatar
Ghislain MARY committed
160

161 162
MS2_PUBLIC bool_t media_stream_srtp_supported(void);

163 164 165 166 167 168 169 170
MS2_PUBLIC void media_stream_set_rtcp_information(MediaStream *stream, const char *cname, const char *tool);

MS2_PUBLIC void media_stream_get_local_rtp_stats(MediaStream *stream, rtp_stats_t *stats);

MS2_PUBLIC int media_stream_set_dscp(MediaStream *stream, int dscp);

MS2_PUBLIC void media_stream_enable_adaptive_bitrate_control(MediaStream *stream, bool_t enabled);

171 172
MS2_PUBLIC void media_stream_set_adaptive_bitrate_algorithm(MediaStream *stream, MSQosAnalyzerAlgorithm algorithm);

173 174
MS2_PUBLIC void media_stream_enable_adaptive_jittcomp(MediaStream *stream, bool_t enabled);

175 176 177
/*
 * deprecated, use media_stream_set_srtp_recv_key and media_stream_set_srtp_send_key.
**/
jehan's avatar
jehan committed
178 179
MS2_PUBLIC bool_t media_stream_enable_srtp(MediaStream* stream, MSCryptoSuite suite, const char* snd_key, const char* rcv_key);

180
MS2_PUBLIC int media_stream_set_srtp_recv_key(MediaStream *stream, MSCryptoSuite suite, const char* key, bool_t keyisb64);
181

182
MS2_PUBLIC int media_stream_set_srtp_send_key(MediaStream *stream, MSCryptoSuite suite, const char* key, bool_t keyisb64);
jehan's avatar
jehan committed
183
/**
184
 * @param[in] stream MediaStream object
jehan's avatar
jehan committed
185 186
 * @return true if stream is encrypted
 * */
187 188 189 190 191 192 193 194 195 196 197 198 199 200 201
MS2_PUBLIC bool_t media_stream_secured(const MediaStream *stream);
#define media_stream_is_secured media_stream_secured

/**
 * Tells whether AVPF is enabled or not.
 * @param[in] stream #MediaStream object.
 * @return True if AVPF is enabled, false otherwise.
 */
MS2_PUBLIC bool_t media_stream_avpf_enabled(const MediaStream *stream);

/**
 * Gets the AVPF Regular RTCP report interval.
 * @param[in] stream #MediaStream object.
 * @return The AVPF Regular RTCP report interval in seconds.
 */
202
MS2_PUBLIC uint16_t media_stream_get_avpf_rr_interval(const MediaStream *stream);
203

204 205 206 207 208 209
/**
 * Gets the RTP session of the media stream.
 * @param[in] stream #MediaStream object.
 * @return The RTP session of the media stream.
 */
MS2_PUBLIC RtpSession * media_stream_get_rtp_session(const MediaStream *stream);
210

211
MS2_PUBLIC const MSQualityIndicator *media_stream_get_quality_indicator(MediaStream *stream);
jehan's avatar
jehan committed
212 213 214
/* *
 * returns a realtime indicator of the stream quality between 0 and 5
 * */
215
MS2_PUBLIC float media_stream_get_quality_rating(MediaStream *stream);
216

217 218
MS2_PUBLIC float media_stream_get_average_quality_rating(MediaStream *stream);

219 220 221 222
MS2_PUBLIC float media_stream_get_lq_quality_rating(MediaStream *stream);

MS2_PUBLIC float media_stream_get_average_lq_quality_rating(MediaStream *stream);

223
/**
jehan's avatar
jehan committed
224 225 226 227 228 229 230 231 232 233 234 235
 * <br>For multirate codecs like OPUS, encoder output target bitrate must be set.
 * <br>Encoder will compute output codec bitrate from this value.
 * <br> default value is the value corresponding the rtp PayloadType
 * @param stream stream to apply parameter on
 * @param target_bitrate in bit per seconds
 * @return 0 if succeed
 * */
MS2_PUBLIC int media_stream_set_target_network_bitrate(MediaStream *stream,int target_bitrate);

/**
 * get the stream target bitrate.
 * @param stream stream to apply parameter on
236
 * @return target_bitrate in bit per seconds
jehan's avatar
jehan committed
237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253
 * */
MS2_PUBLIC int media_stream_get_target_network_bitrate(const MediaStream *stream);

/**
 * get current stream  upload bitrate. Value is updated every seconds
 * @param stream
 * @return bitrate in bit per seconds
 * */
MS2_PUBLIC float media_stream_get_up_bw(const MediaStream *stream);

/**
 * get current stream download bitrate. Value is updated every seconds
 * @param stream
 * @return bitrate in bit per seconds
 * */
MS2_PUBLIC float media_stream_get_down_bw(const MediaStream *stream);

254 255 256 257 258 259 260 261 262 263 264 265 266 267
/**
 * get current stream rtcp upload bitrate. Value is updated every seconds
 * @param stream
 * @return bitrate in bit per seconds
 * */
MS2_PUBLIC float media_stream_get_rtcp_up_bw(const MediaStream *stream);

/**
 * get current stream rtcp download bitrate. Value is updated every seconds
 * @param stream
 * @return bitrate in bit per seconds
 * */
MS2_PUBLIC float media_stream_get_rtcp_down_bw(const MediaStream *stream);

268 269 270 271 272 273
/**
 * Returns the sessions that were used in the media stream (RTP, SRTP, ZRTP...) so that they can be re-used.
 * As a result of calling this function, the media stream no longer owns the sessions and thus will not free them.
**/
MS2_PUBLIC void media_stream_reclaim_sessions(MediaStream *stream, MSMediaStreamSessions *sessions);

jehan's avatar
jehan committed
274

275
MS2_PUBLIC void media_stream_iterate(MediaStream * stream);
jehan's avatar
jehan committed
276

277 278 279 280 281
/**
 * Returns TRUE if stream was still actively receiving packets (RTP or RTCP) in the last period specified in timeout_seconds.
**/
MS2_PUBLIC bool_t media_stream_alive(MediaStream *stream, int timeout_seconds);

jehan's avatar
jehan committed
282 283 284 285
/**
 * @returns curret streams tate
 * */
MS2_PUBLIC MSStreamState media_stream_get_state(const MediaStream *stream);
286

287 288 289
typedef enum EchoLimiterType{
	ELInactive,
	ELControlMic,
290
	ELControlFull
291 292
} EchoLimiterType;

293 294 295 296 297 298

typedef enum EqualizerLocation {
	MSEqualizerHP = 0,
	MSEqualizerMic
} EqualizerLocation;

aymeric's avatar
aymeric committed
299 300
struct _AudioStream
{
Ghislain MARY's avatar
Ghislain MARY committed
301
	MediaStream ms;
aymeric's avatar
aymeric committed
302 303 304
	MSFilter *soundread;
	MSFilter *soundwrite;
	MSFilter *dtmfgen;
305
	MSFilter *dtmfgen_rtp;
Yann Diorcet's avatar
Yann Diorcet committed
306
	MSFilter *plc;
aymeric's avatar
aymeric committed
307
	MSFilter *ec;/*echo canceler*/
308
	MSFilter *volsend,*volrecv; /*MSVolumes*/
309 310 311
	MSFilter *local_mixer;
	MSFilter *local_player;
	MSFilter *local_player_resampler;
312 313
	MSFilter *read_resampler;
	MSFilter *write_resampler;
smorlat's avatar
smorlat committed
314
	MSFilter *equalizer;
Simon Morlat's avatar
Simon Morlat committed
315
	MSFilter *dummy;
316 317 318
	MSFilter *recv_tee;
	MSFilter *recorder_mixer;
	MSFilter *recorder;
319
	MSFilter *outbound_mixer;
Simon Morlat's avatar
Simon Morlat committed
320 321 322 323 324 325
	struct {
		MSFilter *resampler;
		MSFilter *encoder;
		MSFilter *recorder;
		MSFilter *video_input;
	}av_recorder;
326 327 328 329 330 331 332 333 334
	struct _AVPlayer{
		MSFilter *player;
		MSFilter *resampler;
		MSFilter *decoder;
		MSFilter *video_output;
		int audiopin;
		int videopin;
		bool_t plumbed;
	}av_player;
335
	char *recorder_file;
336
	EchoLimiterType el_type; /*use echo limiter: two MSVolume, measured input level controlling local output level*/
337
	EqualizerLocation eq_loc;
Ghislain MARY's avatar
Ghislain MARY committed
338
	uint32_t features;
339
	struct _VideoStream *videostream;/*the stream with which this audiostream is paired*/
smorlat's avatar
smorlat committed
340
	bool_t play_dtmfs;
smorlat's avatar
smorlat committed
341
	bool_t use_gc;
342
	bool_t use_agc;
smorlat's avatar
smorlat committed
343
	bool_t eq_active;
344
	bool_t use_ng;/*noise gate*/
345
	bool_t is_ec_delay_set;
aymeric's avatar
aymeric committed
346 347
};

348 349 350
/**
 * The AudioStream holds all resources to create and run typical VoIP audiostream.
**/
aymeric's avatar
aymeric committed
351 352 353 354
typedef struct _AudioStream AudioStream;


/* start a thread that does sampling->encoding->rtp_sending|rtp_receiving->decoding->playing */
Simon Morlat's avatar
Simon Morlat committed
355
MS2_PUBLIC AudioStream *audio_stream_start (RtpProfile * prof, int locport, const char *remip,
aymeric's avatar
aymeric committed
356 357
				 int remport, int payload_type, int jitt_comp, bool_t echo_cancel);

Simon Morlat's avatar
Simon Morlat committed
358
MS2_PUBLIC AudioStream *audio_stream_start_with_sndcards(RtpProfile * prof, int locport, const char *remip4, int remport, int payload_type, int jitt_comp, MSSndCard *playcard, MSSndCard *captcard, bool_t echocancel);
aymeric's avatar
aymeric committed
359

360

Simon Morlat's avatar
Simon Morlat committed
361
MS2_PUBLIC int audio_stream_start_with_files (AudioStream * stream, RtpProfile * prof,
362 363 364
						const char *remip, int remport, int rem_rtcp_port,
						int pt, int jitt_comp,
						const char * infile,  const char * outfile);
aymeric's avatar
aymeric committed
365

366 367
/**
 * Starts an audio stream from/to local wav files or soundcards.
368
 *
369 370
 * This method starts the processing of the audio stream, that is playing from wav file or soundcard, voice processing, encoding,
 * sending through RTP, receiving from RTP, decoding, voice processing and wav file recording or soundcard playback.
371 372
 *
 *
373
 * @param stream an AudioStream previously created with audio_stream_new().
374
 * @param profile a RtpProfile containing all PayloadType possible during the audio session.
375 376 377
 * @param rem_rtp_ip remote IP address where to send the encoded audio.
 * @param rem_rtp_port remote IP port where to send the encoded audio.
 * @param rem_rtcp_ip remote IP address for RTCP.
378
 * @param rem_rtcp_port remote port for RTCP.
379
 * @param payload payload type index to use for the sending stream. This index must point to a valid PayloadType in the RtpProfile.
380 381 382 383 384
 * @param jitt_comp Nominal jitter buffer size in milliseconds.
 * @param infile path to wav file to play out (can be NULL)
 * @param outfile path to wav file to record into (can be NULL)
 * @param playcard The soundcard to be used for playback (can be NULL)
 * @param captcard The soundcard to be used for catpure. (can be NULL)
385
 * @param use_ec whether echo cancellation is to be performed.
386 387
 * @returns 0 if sucessful, -1 otherwise.
**/
388 389
MS2_PUBLIC int audio_stream_start_full(AudioStream *stream, RtpProfile *profile, const char *rem_rtp_ip,int rem_rtp_port,
	const char *rem_rtcp_ip, int rem_rtcp_port, int payload,int jitt_comp, const char *infile, const char *outfile,
390 391
	MSSndCard *playcard, MSSndCard *captcard, bool_t use_ec);

392

Simon Morlat's avatar
Simon Morlat committed
393 394
MS2_PUBLIC void audio_stream_play(AudioStream *st, const char *name);
MS2_PUBLIC void audio_stream_record(AudioStream *st, const char *name);
aymeric's avatar
aymeric committed
395

396
static MS2_INLINE void audio_stream_set_rtcp_information(AudioStream *st, const char *cname, const char *tool) {
Ghislain MARY's avatar
Ghislain MARY committed
397 398
	media_stream_set_rtcp_information(&st->ms, cname, tool);
}
aymeric's avatar
aymeric committed
399

Simon Morlat's avatar
Simon Morlat committed
400
MS2_PUBLIC void audio_stream_play_received_dtmfs(AudioStream *st, bool_t yesno);
smorlat's avatar
smorlat committed
401

402 403
/**
 * Creates an AudioStream object listening on a RTP port.
404 405
 * @param loc_rtp_port the local UDP port to listen for RTP packets.
 * @param loc_rtcp_port the local UDP port to listen for RTCP packets
406 407 408
 * @param ipv6 TRUE if ipv6 must be used.
 * @returns a new AudioStream.
**/
409
MS2_PUBLIC AudioStream *audio_stream_new(int loc_rtp_port, int loc_rtcp_port, bool_t ipv6);
Simon Morlat's avatar
Simon Morlat committed
410

411 412
/**Creates an AudioStream object from initialized MSMediaStreamSessions.
 * @param sessions the MSMediaStreamSessions
413 414 415 416
 * @returns a new AudioStream
**/
MS2_PUBLIC AudioStream *audio_stream_new_with_sessions(const MSMediaStreamSessions *sessions);

417 418 419 420 421 422 423 424
#define AUDIO_STREAM_FEATURE_PLC 		(1 << 0)
#define AUDIO_STREAM_FEATURE_EC 		(1 << 1)
#define AUDIO_STREAM_FEATURE_EQUALIZER		(1 << 2)
#define AUDIO_STREAM_FEATURE_VOL_SND 		(1 << 3)
#define AUDIO_STREAM_FEATURE_VOL_RCV 		(1 << 4)
#define AUDIO_STREAM_FEATURE_DTMF		(1 << 5)
#define AUDIO_STREAM_FEATURE_DTMF_ECHO		(1 << 6)
#define AUDIO_STREAM_FEATURE_MIXED_RECORDING	(1 << 7)
425
#define AUDIO_STREAM_FEATURE_LOCAL_PLAYING	(1 << 8)
426
#define AUDIO_STREAM_FEATURE_REMOTE_PLAYING	(1 << 9)
427

Yann Diorcet's avatar
Yann Diorcet committed
428 429 430 431 432 433 434
#define AUDIO_STREAM_FEATURE_ALL	(\
					AUDIO_STREAM_FEATURE_PLC | \
					AUDIO_STREAM_FEATURE_EC | \
					AUDIO_STREAM_FEATURE_EQUALIZER | \
					AUDIO_STREAM_FEATURE_VOL_SND | \
					AUDIO_STREAM_FEATURE_VOL_RCV | \
					AUDIO_STREAM_FEATURE_DTMF | \
435
					AUDIO_STREAM_FEATURE_DTMF_ECHO |\
436
					AUDIO_STREAM_FEATURE_MIXED_RECORDING |\
437 438
					AUDIO_STREAM_FEATURE_LOCAL_PLAYING | \
					AUDIO_STREAM_FEATURE_REMOTE_PLAYING \
Yann Diorcet's avatar
Yann Diorcet committed
439 440
					)

441

Yann Diorcet's avatar
Yann Diorcet committed
442 443
MS2_PUBLIC uint32_t audio_stream_get_features(AudioStream *st);
MS2_PUBLIC void audio_stream_set_features(AudioStream *st, uint32_t features);
444

Simon Morlat's avatar
Simon Morlat committed
445 446 447
MS2_PUBLIC void audio_stream_prepare_sound(AudioStream *st, MSSndCard *playcard, MSSndCard *captcard);
MS2_PUBLIC void audio_stream_unprepare_sound(AudioStream *st);
MS2_PUBLIC bool_t audio_stream_started(AudioStream *stream);
448 449
/**
 * Starts an audio stream from local soundcards.
450
 *
451 452
 * This method starts the processing of the audio stream, that is capture from soundcard, voice processing, encoding,
 * sending through RTP, receiving from RTP, decoding, voice processing and soundcard playback.
453
 *
454 455 456 457 458 459 460 461 462 463 464
 * @param stream an AudioStream previously created with audio_stream_new().
 * @param prof a RtpProfile containing all PayloadType possible during the audio session.
 * @param remip remote IP address where to send the encoded audio.
 * @param remport remote IP port where to send the encoded audio
 * @param rem_rtcp_port remote port for RTCP.
 * @param payload_type payload type index to use for the sending stream. This index must point to a valid PayloadType in the RtpProfile.
 * @param jitt_comp Nominal jitter buffer size in milliseconds.
 * @param playcard The soundcard to be used for playback
 * @param captcard The soundcard to be used for catpure.
 * @param echo_cancel whether echo cancellation is to be performed.
**/
Simon Morlat's avatar
Simon Morlat committed
465 466
MS2_PUBLIC int audio_stream_start_now(AudioStream * stream, RtpProfile * prof,  const char *remip, int remport, int rem_rtcp_port, int payload_type, int jitt_comp,MSSndCard *playcard, MSSndCard *captcard, bool_t echo_cancel);
MS2_PUBLIC void audio_stream_set_relay_session_id(AudioStream *stream, const char *relay_session_id);
aymeric's avatar
aymeric committed
467
/*returns true if we are still receiving some data from remote end in the last timeout seconds*/
Simon Morlat's avatar
Simon Morlat committed
468
MS2_PUBLIC bool_t audio_stream_alive(AudioStream * stream, int timeout);
aymeric's avatar
aymeric committed
469

470 471 472 473
/**
 * Executes background low priority tasks related to audio processing (RTP statistics analysis).
 * It should be called periodically, for example with an interval of 100 ms or so.
 */
474 475
MS2_PUBLIC void audio_stream_iterate(AudioStream *stream);

jehan's avatar
jehan committed
476 477 478
/**
 * enable echo-limiter dispositve: one MSVolume in input branch controls a MSVolume in the output branch
 * */
Simon Morlat's avatar
Simon Morlat committed
479
MS2_PUBLIC void audio_stream_enable_echo_limiter(AudioStream *stream, EchoLimiterType type);
480

jehan's avatar
jehan committed
481 482 483
/**
 * enable gain control, to be done before start()
 * */
Simon Morlat's avatar
Simon Morlat committed
484
MS2_PUBLIC void audio_stream_enable_gain_control(AudioStream *stream, bool_t val);
smorlat's avatar
smorlat committed
485

jehan's avatar
jehan committed
486 487 488
/**
 * enable automatic gain control, to be done before start()
 * */
Simon Morlat's avatar
Simon Morlat committed
489
MS2_PUBLIC void audio_stream_enable_automatic_gain_control(AudioStream *stream, bool_t val);
490

jehan's avatar
jehan committed
491 492 493
/**
 * to be done before start
 *  */
Simon Morlat's avatar
Simon Morlat committed
494
MS2_PUBLIC void audio_stream_set_echo_canceller_params(AudioStream *st, int tail_len_ms, int delay_ms, int framesize);
495

jehan's avatar
jehan committed
496 497 498
/**
 * enable adaptive rate control
 * */
499
static MS2_INLINE void audio_stream_enable_adaptive_bitrate_control(AudioStream *stream, bool_t enabled) {
Ghislain MARY's avatar
Ghislain MARY committed
500 501
	media_stream_enable_adaptive_bitrate_control(&stream->ms, enabled);
}
502

jehan's avatar
jehan committed
503 504 505
/**
 *  Enable adaptive jitter compensation
 *  */
506
static MS2_INLINE void audio_stream_enable_adaptive_jittcomp(AudioStream *stream, bool_t enabled) {
Ghislain MARY's avatar
Ghislain MARY committed
507 508
	media_stream_enable_adaptive_jittcomp(&stream->ms, enabled);
}
509

Simon Morlat's avatar
Simon Morlat committed
510
MS2_PUBLIC void audio_stream_set_mic_gain(AudioStream *stream, float gain);
smorlat's avatar
smorlat committed
511

jehan's avatar
jehan committed
512 513 514
/**
 *  enable/disable rtp stream
 *  */
Simon Morlat's avatar
Simon Morlat committed
515
MS2_PUBLIC void audio_stream_mute_rtp(AudioStream *stream, bool_t val);
Simon Morlat's avatar
Simon Morlat committed
516

jehan's avatar
jehan committed
517 518 519
/**
 * enable noise gate, must be done before start()
 * */
Simon Morlat's avatar
Simon Morlat committed
520
MS2_PUBLIC void audio_stream_enable_noise_gate(AudioStream *stream, bool_t val);
521

jehan's avatar
jehan committed
522 523 524
/**
 * enable parametric equalizer in the stream that goes to the speaker
 * */
Simon Morlat's avatar
Simon Morlat committed
525
MS2_PUBLIC void audio_stream_enable_equalizer(AudioStream *stream, bool_t enabled);
smorlat's avatar
smorlat committed
526

Simon Morlat's avatar
Simon Morlat committed
527
MS2_PUBLIC void audio_stream_equalizer_set_gain(AudioStream *stream, int frequency, float gain, int freq_width);
smorlat's avatar
smorlat committed
528

jehan's avatar
jehan committed
529 530 531
/**
 *  stop the audio streaming thread and free everything
 *  */
Simon Morlat's avatar
Simon Morlat committed
532
MS2_PUBLIC void audio_stream_stop (AudioStream * stream);
aymeric's avatar
aymeric committed
533

jehan's avatar
jehan committed
534 535 536
/**
 *  send a dtmf
 *  */
Simon Morlat's avatar
Simon Morlat committed
537
MS2_PUBLIC int audio_stream_send_dtmf (AudioStream * stream, char dtmf);
aymeric's avatar
aymeric committed
538

539 540
MS2_PUBLIC MSFilter *audio_stream_get_local_player(AudioStream *stream);

541 542 543 544 545 546
MS2_PUBLIC int audio_stream_mixed_record_open(AudioStream *st, const char*filename);

MS2_PUBLIC int audio_stream_mixed_record_start(AudioStream *st);

MS2_PUBLIC int audio_stream_mixed_record_stop(AudioStream *st);

547 548 549 550 551 552
/**
 * Open a player to play an audio/video file to remote end.
 * The player is returned as a MSFilter so that application can make usual player controls on it using the MSPlayerInterface.
**/
MS2_PUBLIC MSFilter * audio_stream_open_remote_play(AudioStream *stream, const char *filename);

553 554
MS2_PUBLIC void audio_stream_close_remote_play(AudioStream *stream);

Simon Morlat's avatar
Simon Morlat committed
555
MS2_PUBLIC void audio_stream_set_default_card(int cardindex);
aymeric's avatar
aymeric committed
556

Simon Morlat's avatar
Simon Morlat committed
557
/* retrieve RTP statistics*/
558
static MS2_INLINE void audio_stream_get_local_rtp_stats(AudioStream *stream, rtp_stats_t *stats) {
Ghislain MARY's avatar
Ghislain MARY committed
559 560
	media_stream_get_local_rtp_stats(&stream->ms, stats);
}
Simon Morlat's avatar
Simon Morlat committed
561

562
/* returns a realtime indicator of the stream quality between 0 and 5 */
563 564
MS2_PUBLIC float audio_stream_get_quality_rating(AudioStream *stream);

565 566
/* returns the quality rating as an average since the start of the streaming session.*/
MS2_PUBLIC float audio_stream_get_average_quality_rating(AudioStream *stream);
aymeric's avatar
aymeric committed
567

568 569 570 571 572 573
/* returns a realtime indicator of the listening quality of the stream between 0 and 5 */
MS2_PUBLIC float audio_stream_get_lq_quality_rating(AudioStream *stream);

/* returns the listening quality rating as an average since the start of the streaming session.*/
MS2_PUBLIC float audio_stream_get_average_lq_quality_rating(AudioStream *stream);

Guillaume Beraudo's avatar
Guillaume Beraudo committed
574
/* enable ZRTP on the audio stream */
575
MS2_PUBLIC void audio_stream_enable_zrtp(AudioStream *stream, MSZrtpParams *params);
jehan's avatar
jehan committed
576 577 578 579
/**
 * return TRUE if zrtp is enabled, it does not mean that stream is encrypted, but only that zrtp is configured to know encryption status, uses #
 * */
bool_t  audio_stream_zrtp_enabled(const AudioStream *stream);
Guillaume Beraudo's avatar
Guillaume Beraudo committed
580

581
/* enable SRTP on the audio stream */
582
static MS2_INLINE bool_t audio_stream_enable_srtp(AudioStream* stream, MSCryptoSuite suite, const char* snd_key, const char* rcv_key) {
Ghislain MARY's avatar
Ghislain MARY committed
583 584
	return media_stream_enable_srtp(&stream->ms, suite, snd_key, rcv_key);
}
Guillaume Beraudo's avatar
Guillaume Beraudo committed
585

586
static MS2_INLINE int audio_stream_set_dscp(AudioStream *stream, int dscp) {
Ghislain MARY's avatar
Ghislain MARY committed
587 588
	return media_stream_set_dscp(&stream->ms, dscp);
}
Simon Morlat's avatar
Simon Morlat committed
589

590 591 592 593 594 595 596 597 598 599
/**
 * Gets the RTP session of an audio stream.
 * @param[in] stream #MediaStream object.
 * @return The RTP session of the audio stream.
 */
static MS2_INLINE RtpSession * audio_stream_get_rtp_session(const AudioStream *stream) {
	return media_stream_get_rtp_session(&stream->ms);
}


Simon Morlat's avatar
Simon Morlat committed
600

601 602 603 604 605 606 607 608 609
/**
 * @}
**/


/**
 * @addtogroup video_stream_api
 * @{
**/
aymeric's avatar
aymeric committed
610

611
typedef void (*VideoStreamRenderCallback)(void *user_pointer, const MSPicture *local_view, const MSPicture *remote_view);
612 613 614
typedef void (*VideoStreamEventCallback)(void *user_pointer, const MSFilter *f, const unsigned int event_id, const void *args);


615 616 617 618 619 620
typedef enum _VideoStreamDir{
	VideoStreamSendRecv,
	VideoStreamSendOnly,
	VideoStreamRecvOnly
}VideoStreamDir;

aymeric's avatar
aymeric committed
621 622
struct _VideoStream
{
Ghislain MARY's avatar
Ghislain MARY committed
623
	MediaStream ms;
aymeric's avatar
aymeric committed
624 625
	MSFilter *source;
	MSFilter *pixconv;
626
	MSFilter *sizeconv;
aymeric's avatar
aymeric committed
627 628
	MSFilter *tee;
	MSFilter *output;
629 630
	MSFilter *tee2;
	MSFilter *jpegwriter;
631
	MSFilter *output2;
Simon Morlat's avatar
Simon Morlat committed
632 633
	MSFilter *tee3;
	MSFilter *itcsink;
634
	MSFilter *local_jpegwriter;
smorlat's avatar
smorlat committed
635
	MSVideoSize sent_vsize;
636
	MSVideoSize preview_vsize;
637 638
	float fps; /*the target fps explicitely set by application, overrides internally selected fps*/
	float configured_fps; /*the fps that was configured to the encoder. It might be different from the one really obtained from camera.*/
smorlat's avatar
smorlat committed
639
	int corner; /*for selfview*/
640 641
	VideoStreamRenderCallback rendercb;
	void *render_pointer;
642 643
	VideoStreamEventCallback eventcb;
	void *event_pointer;
644
	char *display_name;
645 646
	unsigned long window_id;
	unsigned long preview_window_id;
647
	VideoStreamDir dir;
648
	MSWebCam *cam;
649
	int device_orientation; /* warning: meaning of this variable depends on the platform (Android, iOS, ...) */
Simon Morlat's avatar
Simon Morlat committed
650
	uint64_t last_reported_decoding_error_time;
651
	uint64_t last_fps_check;
Ghislain MARY's avatar
Ghislain MARY committed
652
	bool_t use_preview_window;
653
	bool_t freeze_on_error;
Ghislain MARY's avatar
Ghislain MARY committed
654
	bool_t display_filter_auto_rotate_enabled;
655 656
	bool_t source_performs_encoding;
	bool_t output_performs_decoding;
657
	bool_t player_active;
658

aymeric's avatar
aymeric committed
659 660 661
};

typedef struct _VideoStream VideoStream;
smorlat's avatar
smorlat committed
662

663

664
MS2_PUBLIC VideoStream *video_stream_new(int loc_rtp_port, int loc_rtcp_port, bool_t use_ipv6);
665
MS2_PUBLIC VideoStream *video_stream_new_with_sessions(const MSMediaStreamSessions *sessions);
Simon Morlat's avatar
Simon Morlat committed
666
MS2_PUBLIC void video_stream_set_direction(VideoStream *vs, VideoStreamDir dir);
667
static MS2_INLINE void video_stream_enable_adaptive_bitrate_control(VideoStream *stream, bool_t enabled) {
Ghislain MARY's avatar
Ghislain MARY committed
668 669
	media_stream_enable_adaptive_bitrate_control(&stream->ms, enabled);
}
670
static MS2_INLINE void video_stream_enable_adaptive_jittcomp(VideoStream *stream, bool_t enabled) {
Ghislain MARY's avatar
Ghislain MARY committed
671 672
	media_stream_enable_adaptive_jittcomp(&stream->ms, enabled);
}
Simon Morlat's avatar
Simon Morlat committed
673 674 675
MS2_PUBLIC void video_stream_set_render_callback(VideoStream *s, VideoStreamRenderCallback cb, void *user_pointer);
MS2_PUBLIC void video_stream_set_event_callback(VideoStream *s, VideoStreamEventCallback cb, void *user_pointer);
MS2_PUBLIC void video_stream_set_display_filter_name(VideoStream *s, const char *fname);
676 677
MS2_PUBLIC int video_stream_start_with_source(VideoStream *stream, RtpProfile *profile, const char *rem_rtp_ip, int rem_rtp_port,
		const char *rem_rtcp_ip, int rem_rtcp_port, int payload, int jitt_comp, MSWebCam* cam, MSFilter* source);
678
MS2_PUBLIC int video_stream_start(VideoStream * stream, RtpProfile *profile, const char *rem_rtp_ip, int rem_rtp_port, const char *rem_rtcp_ip, int rem_rtcp_port,
aymeric's avatar
aymeric committed
679
		int payload, int jitt_comp, MSWebCam *device);
680 681
MS2_PUBLIC void video_stream_prepare_video(VideoStream *stream);
MS2_PUBLIC void video_stream_unprepare_video(VideoStream *stream);
682 683


Simon Morlat's avatar
Simon Morlat committed
684
MS2_PUBLIC void video_stream_set_relay_session_id(VideoStream *stream, const char *relay_session_id);
685
static MS2_INLINE void video_stream_set_rtcp_information(VideoStream *st, const char *cname, const char *tool) {
Ghislain MARY's avatar
Ghislain MARY committed
686 687
	media_stream_set_rtcp_information(&st->ms, cname, tool);
}
Simon Morlat's avatar
Simon Morlat committed
688
MS2_PUBLIC void video_stream_change_camera(VideoStream *stream, MSWebCam *cam);
689 690
/* Calling video_stream_set_sent_video_size() or changing the bitrate value in the used PayloadType during a stream is running does nothing.
The following function allows to take into account new parameters by redrawing the sending graph*/
Simon Morlat's avatar
Simon Morlat committed
691
MS2_PUBLIC void video_stream_update_video_params(VideoStream *stream);
aymeric's avatar
aymeric committed
692
/*function to call periodically to handle various events */
Simon Morlat's avatar
Simon Morlat committed
693
MS2_PUBLIC void video_stream_iterate(VideoStream *stream);
694 695 696 697 698 699 700 701 702 703 704

/**
 * Ask the video stream to send a Full-Intra Request.
 * @param[in] stream The videostream object.
 */
MS2_PUBLIC void video_stream_send_fir(VideoStream *stream);

/**
 * Ask the video stream to generate a Video Fast Update (generally after receiving a Full-Intra Request.
 * @param[in] stream The videostream object.
 */
Simon Morlat's avatar
Simon Morlat committed
705
MS2_PUBLIC void video_stream_send_vfu(VideoStream *stream);
706

Simon Morlat's avatar
Simon Morlat committed
707 708
MS2_PUBLIC void video_stream_stop(VideoStream * stream);
MS2_PUBLIC void video_stream_set_sent_video_size(VideoStream *stream, MSVideoSize vsize);
709 710 711 712 713 714

/**
 * Gets the size of the video that is sent.
 * @param[in] stream The videostream for which to get the sent video size.
 * @return The sent video size or MS_VIDEO_SIZE_UNKNOWN if not available.
 */
Ghislain MARY's avatar
Ghislain MARY committed
715
MS2_PUBLIC MSVideoSize video_stream_get_sent_video_size(const VideoStream *stream);
716 717 718 719 720 721

/**
 * Gets the size of the video that is received.
 * @param[in] stream The videostream for which to get the received video size.
 * @return The received video size or MS_VIDEO_SIZE_UNKNOWN if not available.
 */
Ghislain MARY's avatar
Ghislain MARY committed
722
MS2_PUBLIC MSVideoSize video_stream_get_received_video_size(const VideoStream *stream);
723

724 725 726 727 728 729 730 731 732 733 734 735 736 737
/**
 * Gets the framerate of the video that is sent.
 * @param[in] stream The videostream.
 * @return The actual framerate, 0 if not available..
 */
MS2_PUBLIC float video_stream_get_sent_framerate(const VideoStream *stream);

/**
 * Gets the framerate of the video that is received.
 * @param[in] stream The videostream.
 * @return The received framerate or 0 if not available.
 */
MS2_PUBLIC float video_stream_get_received_framerate(const VideoStream *stream);

Simon Morlat's avatar
Simon Morlat committed
738 739 740 741 742
/**
 * Returns the name of the video display filter on the current platform.
**/
const char *video_stream_get_default_video_renderer(void);

Simon Morlat's avatar
Simon Morlat committed
743 744 745 746 747 748
MS2_PUBLIC void video_stream_enable_self_view(VideoStream *stream, bool_t val);
MS2_PUBLIC unsigned long video_stream_get_native_window_id(VideoStream *stream);
MS2_PUBLIC void video_stream_set_native_window_id(VideoStream *stream, unsigned long id);
MS2_PUBLIC void video_stream_set_native_preview_window_id(VideoStream *stream, unsigned long id);
MS2_PUBLIC unsigned long video_stream_get_native_preview_window_id(VideoStream *stream);
MS2_PUBLIC void video_stream_use_preview_video_window(VideoStream *stream, bool_t yesno);
749
MS2_PUBLIC void video_stream_set_device_rotation(VideoStream *stream, int orientation);
750
MS2_PUBLIC void video_stream_show_video(VideoStream *stream, bool_t show);
751
MS2_PUBLIC void video_stream_set_freeze_on_error(VideoStream *stream, bool_t yesno);
752

753 754 755 756 757 758 759 760 761 762 763
/**
 * @brief Gets the camera sensor rotation.
 *
 * This is needed on some mobile platforms to get the number of degrees the camera sensor
 * is rotated relative to the screen.
 *
 * @param stream The video stream related to the operation
 * @return The camera sensor rotation in degrees (0 to 360) or -1 if it could not be retrieved
 */
MS2_PUBLIC int video_stream_get_camera_sensor_rotation(VideoStream *stream);

764
/*provided for compatibility, use video_stream_set_direction() instead */
Simon Morlat's avatar
Simon Morlat committed
765 766
MS2_PUBLIC int video_stream_recv_only_start(VideoStream *videostream, RtpProfile *profile, const char *addr, int port, int used_pt, int jitt_comp);
MS2_PUBLIC int video_stream_send_only_start(VideoStream *videostream,
767
				RtpProfile *profile, const char *addr, int port, int rtcp_port,
768
				int used_pt, int  jitt_comp, MSWebCam *device);
Simon Morlat's avatar
Simon Morlat committed
769 770
MS2_PUBLIC void video_stream_recv_only_stop(VideoStream *vs);
MS2_PUBLIC void video_stream_send_only_stop(VideoStream *vs);
aymeric's avatar
aymeric committed
771

Guillaume Beraudo's avatar
Guillaume Beraudo committed
772
/* enable ZRTP on the video stream using information from the audio stream */
773
MS2_PUBLIC void video_stream_enable_zrtp(VideoStream *vstream, AudioStream *astream, MSZrtpParams *param);
774

775
/* enable SRTP on the video stream */
776
static MS2_INLINE bool_t video_stream_enable_strp(VideoStream* stream, MSCryptoSuite suite, const char* snd_key, const char* rcv_key) {
Ghislain MARY's avatar
Ghislain MARY committed
777 778 779
	return media_stream_enable_srtp(&stream->ms, suite, snd_key, rcv_key);
}

780 781
/* if enabled, the display filter will internaly rotate the video, according to the device orientation */
MS2_PUBLIC void video_stream_enable_display_filter_auto_rotate(VideoStream* stream, bool_t enable);
782

783
/* retrieve RTP statistics*/
784
static MS2_INLINE void video_stream_get_local_rtp_stats(VideoStream *stream, rtp_stats_t *stats) {
Ghislain MARY's avatar
Ghislain MARY committed
785 786
	media_stream_get_local_rtp_stats(&stream->ms, stats);
}
787

788
static MS2_INLINE int video_stream_set_dscp(VideoStream *stream, int dscp) {
Ghislain MARY's avatar
Ghislain MARY committed
789 790
	return media_stream_set_dscp(&stream->ms, dscp);
}
Simon Morlat's avatar
Simon Morlat committed
791

792 793 794 795 796 797 798 799 800
/**
 * Gets the RTP session of a video stream.
 * @param[in] stream #MediaStream object.
 * @return The RTP session of the video stream.
 */
static MS2_INLINE RtpSession * video_stream_get_rtp_session(const VideoStream *stream) {
	return media_stream_get_rtp_session(&stream->ms);
}

801 802 803 804 805 806 807 808 809 810 811 812 813 814
/**
 * Ask the video stream whether a decoding error should be reported (eg. to send a VFU request).
 * @param[in] stream The VideoStream object.
 * @param[in] ms The minimum interval in milliseconds between to decoding error report.
 * @return TRUE if the decoding error should be reported, FALSE otherwise.
 */
MS2_PUBLIC bool_t video_stream_is_decoding_error_to_be_reported(VideoStream *stream, uint32_t ms);

/**
 * Tell the video stream that a decoding error has been reported.
 * @param[in] stream The VideoStream object.
 */
MS2_PUBLIC void video_stream_decoding_error_reported(VideoStream *stream);

815 816 817 818 819 820
/**
 * Tell the video stream that a decoding error has been recovered so that new decoding can be reported sooner.
 * @param[in] stream The VideoStream object.
 */
MS2_PUBLIC void video_stream_decoding_error_recovered(VideoStream *stream);

Simon Morlat's avatar
Simon Morlat committed
821

822 823 824 825 826 827 828
/**
 * Force a resolution for the preview.
 * @param[in] stream The VideoStream object.
 * @param[in] vsize video resolution.
**/
MS2_PUBLIC void video_stream_set_preview_size(VideoStream *stream, MSVideoSize vsize);

829 830 831 832 833 834 835
/**
 * Force a resolution for the preview.
 * @param[in] stream The VideoStream object.
 * @param[in] fps the frame rate in frame/seconds. A value of zero means "use encoder default value".
**/
MS2_PUBLIC void video_stream_set_fps(VideoStream *stream, float fps);

Simon Morlat's avatar
Simon Morlat committed
836 837 838 839 840 841 842 843 844 845 846 847
/**
 * Link the audio stream with an existing video stream.
 * This is necessary to enable recording of audio & video into a multimedia file.
 */
MS2_PUBLIC void audio_stream_link_video(AudioStream *stream, VideoStream *video);

/**
 * Unlink the audio stream from the video stream.
 * This must be done if the video stream is about to be stopped.
**/
MS2_PUBLIC void audio_stream_unlink_video(AudioStream *stream, VideoStream *video);

848 849 850 851
/**
 * Small API to display a local preview window.
**/

Simon Morlat's avatar
Simon Morlat committed
852 853
typedef VideoStream VideoPreview;

854
MS2_PUBLIC VideoPreview * video_preview_new(void);
855
#define video_preview_set_size(p,s)			video_stream_set_sent_video_size(p,s)
Simon Morlat's avatar
Simon Morlat committed
856
#define video_preview_set_display_filter_name(p,dt)	video_stream_set_display_filter_name(p,dt)
857 858 859
#define video_preview_set_native_window_id(p,id)	video_stream_set_native_preview_window_id(p,id)
#define video_preview_get_native_window_id(p)		video_stream_get_native_preview_window_id(p)
#define video_preview_set_fps(p,fps)			video_stream_set_fps((VideoStream*)p,fps)
860
#define video_preview_set_device_rotation(p, r) video_stream_set_device_rotation(p, r)
Simon Morlat's avatar
Simon Morlat committed
861 862
MS2_PUBLIC void video_preview_start(VideoPreview *stream, MSWebCam *device);
MS2_PUBLIC void video_preview_stop(VideoPreview *stream);
aymeric's avatar
aymeric committed
863

864 865 866 867 868 869 870 871
/**
 * Stops the video preview graph but keep the source filter for reuse.
 * This is useful when transitioning from a preview-only to a duplex video.
 * The filter needs to be passed to the #video_stream_start_with_source function,
 * otherwise you should detroy it.
 */
MS2_PUBLIC MSFilter* video_preview_stop_reuse_source(VideoPreview *stream);

872 873 874 875
/**
 * @}
**/

Simon Morlat's avatar
Simon Morlat committed
876
MS2_PUBLIC bool_t ms_is_ipv6(const char *address);
aymeric's avatar
aymeric committed
877

Guillaume Beraudo's avatar
Guillaume Beraudo committed
878

aymeric's avatar
aymeric committed
879 880 881 882 883
#ifdef __cplusplus
}
#endif

#endif