mediastream.h 49.7 KB
Newer Older
aymeric's avatar
aymeric committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
/*
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
17
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
aymeric's avatar
aymeric committed
18 19 20 21 22 23
*/


#ifndef MEDIASTREAM_H
#define MEDIASTREAM_H

24 25 26
#include <ortp/ortp.h>
#include <ortp/event.h>

27
#include <mediastreamer2/msfactory.h>
Simon Morlat's avatar
Simon Morlat committed
28 29 30 31 32
#include <mediastreamer2/msfilter.h>
#include <mediastreamer2/msticker.h>
#include <mediastreamer2/mssndcard.h>
#include <mediastreamer2/mswebcam.h>
#include <mediastreamer2/msvideo.h>
33 34
#include <mediastreamer2/bitratecontrol.h>
#include <mediastreamer2/qualityindicator.h>
35
#include <mediastreamer2/ice.h>
36
#include <mediastreamer2/zrtp.h>
johan's avatar
johan committed
37
#include <mediastreamer2/dtls_srtp.h>
38
#include <mediastreamer2/ms_srtp.h>
39
#include <mediastreamer2/msequalizer.h>
aymeric's avatar
aymeric committed
40

41 42 43 44
#ifdef __cplusplus
extern "C" {
#endif

45 46 47 48 49 50 51 52 53 54 55 56
/**
 * @addtogroup ring_api
 * @{
**/

struct _RingStream
{
	MSTicker *ticker;
	MSFilter *source;
	MSFilter *gendtmf;
	MSFilter *write_resampler;
	MSFilter *sndwrite;
57 58
	MSFilter *decoder;
	int srcpin;
59 60 61 62
};

typedef struct _RingStream RingStream;

63 64
MS2_PUBLIC RingStream *ring_start(MSFactory *factory, const char * file, int interval, MSSndCard *sndcard);
MS2_PUBLIC RingStream *ring_start_with_cb(MSFactory *factory, const char * file, int interval, MSSndCard *sndcard, MSFilterNotifyFunc func, void * user_data);
65 66 67 68 69
MS2_PUBLIC void ring_stop (RingStream * stream);

/**
 * @}
**/
70 71 72
/**
 * The MediaStream is an object describing a stream (one of AudioStream or VideoStream).
**/
jehan's avatar
jehan committed
73 74 75 76 77
typedef struct _MediaStream MediaStream;

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

80 81
struct _MSMediaStreamSessions{
	RtpSession *rtp_session;
82
	MSSrtpCtx* srtp_context;
83
	MSZrtpContext *zrtp_context;
johan's avatar
johan committed
84
	MSDtlsSrtpContext *dtls_context;
85 86 87
	MSTicker *ticker;
};

Simon Morlat's avatar
Simon Morlat committed
88
#ifndef MS_MEDIA_STREAM_SESSIONS_DEFINED
89
typedef struct _MSMediaStreamSessions MSMediaStreamSessions;
Simon Morlat's avatar
Simon Morlat committed
90 91
#define MS_MEDIA_STREAM_SESSIONS_DEFINED 1
#endif
jehan's avatar
jehan committed
92

93 94 95 96 97
MS2_PUBLIC void ms_media_stream_sessions_uninit(MSMediaStreamSessions *sessions);

typedef enum _MSStreamState{
	MSStreamInitialized,
	MSStreamPreparing,
98 99
	MSStreamStarted,
	MSStreamStopped
100 101
}MSStreamState;

Simon Morlat's avatar
Simon Morlat committed
102

103 104 105 106 107 108
typedef enum MediaStreamDir{
	MediaStreamSendRecv,
	MediaStreamSendOnly,
	MediaStreamRecvOnly
}MediaStreamDir;

109 110 111
/**
 * Base struct for both AudioStream and VideoStream structure.
**/
112
struct _MediaStream {
Simon Morlat's avatar
Simon Morlat committed
113
	MSFormatType type;
114 115
	MSStreamState state;
	MSMediaStreamSessions sessions;
116 117 118 119 120 121 122
	OrtpEvQueue *evq;
	MSFilter *rtprecv;
	MSFilter *rtpsend;
	MSFilter *encoder;
	MSFilter *decoder;
	MSFilter *voidsink;
	MSBitrateController *rc;
123
	MSQualityIndicator *qi;
124
	IceCheckList *ice_check_list;
125 126
	time_t start_time;
	time_t last_iterate_time;
127 128
	uint64_t last_packet_count;
	time_t last_packet_time;
129
	MSQosAnalyzerAlgorithm rc_algorithm;
130
	PayloadType *current_pt;/*doesn't need to be freed*/
131
	bool_t rc_enable;
132
	bool_t is_beginning;
133
	bool_t owns_sessions;
134
	bool_t pad;
135
	int dscp;
jehan's avatar
jehan committed
136
	/**
137
	 * defines encoder target network bit rate, uses #media_stream_set_target_network_bitrate() setter.
jehan's avatar
jehan committed
138 139
	 * */
	int target_bitrate;
140
	media_stream_process_rtcp_callback_t process_rtcp;
141
	OrtpEvDispatcher *evd;
142
	MSFactory *factory;
143 144
};

145
MS2_PUBLIC void media_stream_init(MediaStream *stream, MSFactory *factory, const MSMediaStreamSessions *sessions);
146

jehan's avatar
jehan committed
147 148 149 150 151

/**
 * @addtogroup audio_stream_api
 * @{
**/
152

153 154
MS2_PUBLIC bool_t media_stream_started(MediaStream *stream);

155 156
MS2_PUBLIC int media_stream_join_multicast_group(MediaStream *stream, const char *ip);

johan's avatar
johan committed
157 158
MS2_PUBLIC bool_t media_stream_dtls_supported(void);

159 160 161
/* enable DTLS on the media stream */
MS2_PUBLIC void media_stream_enable_dtls(MediaStream *stream, MSDtlsSrtpParams *params);

162 163 164 165 166 167 168 169
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);

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

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

174 175
MS2_PUBLIC void media_stream_set_ice_check_list(MediaStream *stream, IceCheckList *cl);

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

/**
182
 * @param[in] stream MediaStream object
jehan's avatar
jehan committed
183 184
 * @return true if stream is encrypted
 * */
185 186 187 188 189 190 191 192 193 194 195 196 197 198 199
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.
 */
200
MS2_PUBLIC uint16_t media_stream_get_avpf_rr_interval(const MediaStream *stream);
201

202 203 204 205 206 207
/**
 * 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);
208

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

215 216
MS2_PUBLIC float media_stream_get_average_quality_rating(MediaStream *stream);

217 218 219 220
MS2_PUBLIC float media_stream_get_lq_quality_rating(MediaStream *stream);

MS2_PUBLIC float media_stream_get_average_lq_quality_rating(MediaStream *stream);

221
/**
jehan's avatar
jehan committed
222 223 224 225 226 227 228 229 230 231 232 233
 * <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
234
 * @return target_bitrate in bit per seconds
jehan's avatar
jehan committed
235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251
 * */
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);

252 253 254 255 256 257 258 259 260 261 262 263 264 265
/**
 * 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);

266 267 268 269 270 271
/**
 * 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
272

273
MS2_PUBLIC void media_stream_iterate(MediaStream * stream);
jehan's avatar
jehan committed
274

275 276 277 278 279
/**
 * 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
280
/**
jehan's avatar
jehan committed
281
 * @return current streams state
jehan's avatar
jehan committed
282 283
 * */
MS2_PUBLIC MSStreamState media_stream_get_state(const MediaStream *stream);
284

285 286
MS2_PUBLIC OrtpEvDispatcher* media_stream_get_event_dispatcher(const MediaStream *stream);

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;

jehan's avatar
jehan committed
299

300 301 302 303 304 305 306 307 308 309 310
typedef enum MSResourceType{
	MSResourceInvalid,
	MSResourceDefault,
	MSResourceFile,
	MSResourceRtp,
	MSResourceCamera,
	MSResourceSoundcard
}MSResourceType;

MS2_PUBLIC const char *ms_resource_type_to_string(MSResourceType type);

311
/**
312 313 314 315 316
 * Structure describing the input or the output of a MediaStream.
 * type must be set to one the member of the MSResourceType enum, and the correspoding
 * resource argument must be set: the file name (const char*) for MSResourceFile,
 * the RtpSession for MSResourceRtp, an MSWebCam for MSResourceCamera, an MSSndCard for MSResourceSoundcard.
 * @warning due to implementation, if RTP is to be used for input and output, the same RtpSession must be passed for both sides.
317
 */
318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342
typedef struct _MSMediaResource{
	MSResourceType type;
	union{
		void *resource_arg;
		const char *file;
		RtpSession *session;
		MSWebCam *camera;
		MSSndCard *soundcard;
	};
}MSMediaResource;


MS2_PUBLIC bool_t ms_media_resource_is_consistent(const MSMediaResource *r);
#define ms_media_resource_get_file(r)		(((r)->type == MSResourceFile) ? (r)->file : NULL)
#define ms_media_resource_get_rtp_session(r)	(((r)->type == MSResourceRtp) ? (r)->session : NULL)
#define ms_media_resource_get_camera(r)		(((r)->type == MSResourceCamera) ? (r)->camera : NULL)
#define ms_media_resource_get_soundcard(r)	(((r)->type == MSResourceSoundcard) ? (r)->souncard : NULL)
/**
 * Structure describing the input/output of a MediaStream.
 * Input and output are described as MSMediaResource.
 */
typedef struct _MSMediaStreamIO {
	MSMediaResource input;
	MSMediaResource output;
} MSMediaStreamIO;
343

344 345 346
#define MS_MEDIA_STREAM_IO_INITIALIZER { {0}, {0} }

MS2_PUBLIC bool_t ms_media_stream_io_is_consistent(const MSMediaStreamIO *io);
jehan's avatar
jehan committed
347

aymeric's avatar
aymeric committed
348 349
struct _AudioStream
{
350
	MediaStream ms;
aymeric's avatar
aymeric committed
351 352 353
	MSFilter *soundread;
	MSFilter *soundwrite;
	MSFilter *dtmfgen;
354
	MSFilter *dtmfgen_rtp;
Yann Diorcet's avatar
Yann Diorcet committed
355
	MSFilter *plc;
aymeric's avatar
aymeric committed
356
	MSFilter *ec;/*echo canceler*/
357
	MSFilter *volsend,*volrecv; /*MSVolumes*/
358 359 360
	MSFilter *local_mixer;
	MSFilter *local_player;
	MSFilter *local_player_resampler;
361 362
	MSFilter *read_decoder; /* Used when the input is done via RTP */
	MSFilter *write_encoder; /* Used when the output is done via RTP */
363 364
	MSFilter *read_resampler;
	MSFilter *write_resampler;
365 366
	MSFilter *mic_equalizer;
	MSFilter *spk_equalizer;
367
	MSFilter *dummy;
368 369 370
	MSFilter *recv_tee;
	MSFilter *recorder_mixer;
	MSFilter *recorder;
371
	MSFilter *outbound_mixer;
Simon Morlat's avatar
Simon Morlat committed
372 373 374 375 376 377
	struct {
		MSFilter *resampler;
		MSFilter *encoder;
		MSFilter *recorder;
		MSFilter *video_input;
	}av_recorder;
378 379 380 381 382 383 384 385 386
	struct _AVPlayer{
		MSFilter *player;
		MSFilter *resampler;
		MSFilter *decoder;
		MSFilter *video_output;
		int audiopin;
		int videopin;
		bool_t plumbed;
	}av_player;
387
	RtpSession *rtp_io_session; /**< The RTP session used for RTP input/output. */
388
	MSFilter *vaddtx;
389
	char *recorder_file;
390
	EchoLimiterType el_type; /*use echo limiter: two MSVolume, measured input level controlling local output level*/
391
	EqualizerLocation eq_loc;
392
	uint32_t features;
393 394
	int sample_rate;
	int nchannels;
395
	struct _VideoStream *videostream;/*the stream with which this audiostream is paired*/
396
	MSAudioRoute audio_route;
smorlat's avatar
smorlat committed
397
	bool_t play_dtmfs;
398
	bool_t use_ec;
smorlat's avatar
smorlat committed
399
	bool_t use_gc;
400
	bool_t use_agc;
401
	
402 403
	bool_t mic_eq_active;
	bool_t spk_eq_active;
404
	bool_t use_ng;/*noise gate*/
405
	bool_t is_ec_delay_set;
aymeric's avatar
aymeric committed
406 407
};

408 409 410
/**
 * The AudioStream holds all resources to create and run typical VoIP audiostream.
**/
aymeric's avatar
aymeric committed
411 412 413 414
typedef struct _AudioStream AudioStream;


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

418 419
MS2_PUBLIC AudioStream *audio_stream_start_with_sndcards(MSFactory* factory, 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
420

Simon Morlat's avatar
Simon Morlat committed
421
MS2_PUBLIC int audio_stream_start_with_files (AudioStream * stream, RtpProfile * prof,
422 423 424
						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
425

426 427 428 429 430 431 432 433 434
/**
 * Start an audio stream according to the specified AudioStreamIO.
 *
 * @param[in] stream AudioStream object previously created with audio_stream_new().
 * @param[in] profile RtpProfile object holding the PayloadType that can be used during the audio session.
 * @param[in] rem_rtp_ip The remote IP address where to send the encoded audio to.
 * @param[in] rem_rtp_port The remote port where to send the encoded audio to.
 * @param[in] rem_rtcp_ip The remote IP address for RTCP.
 * @param[in] rem_rtcp_port The remote port for RTCP.
435 436
 * @param[in] payload_type The payload type number used to send the audio stream. A valid PayloadType must be available at this index in the profile.
 * @param[in] io A MSMediaStreamIO describing the local input/output of the audio stream.
437 438
 */
MS2_PUBLIC int audio_stream_start_from_io(AudioStream *stream, RtpProfile *profile, const char *rem_rtp_ip, int rem_rtp_port,
439
	const char *rem_rtcp_ip, int rem_rtcp_port, int payload_type, const MSMediaStreamIO *io);
440

441 442
/**
 * Starts an audio stream from/to local wav files or soundcards.
443
 *
444 445
 * 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.
446 447
 *
 *
448
 * @param stream an AudioStream previously created with audio_stream_new().
449
 * @param profile a RtpProfile containing all PayloadType possible during the audio session.
450 451 452
 * @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.
453
 * @param rem_rtcp_port remote port for RTCP.
454
 * @param payload payload type index to use for the sending stream. This index must point to a valid PayloadType in the RtpProfile.
455 456 457 458 459
 * @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)
460
 * @param use_ec whether echo cancellation is to be performed.
461
 * @return 0 if sucessful, -1 otherwise.
462
**/
463 464
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,
465 466
	MSSndCard *playcard, MSSndCard *captcard, bool_t use_ec);

467

Simon Morlat's avatar
Simon Morlat committed
468 469
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
470

471
static MS2_INLINE void audio_stream_set_rtcp_information(AudioStream *st, const char *cname, const char *tool) {
472 473
	media_stream_set_rtcp_information(&st->ms, cname, tool);
}
aymeric's avatar
aymeric committed
474

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

477 478
/**
 * Creates an AudioStream object listening on a RTP port.
479 480
 * @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
481
 * @param ipv6 TRUE if ipv6 must be used.
482
 * @param factory 
483
 * @return a new AudioStream.
484
**/
485
MS2_PUBLIC AudioStream *audio_stream_new(MSFactory* factory, int loc_rtp_port, int loc_rtcp_port, bool_t ipv6);
486

jehan's avatar
jehan committed
487 488 489 490 491
/**
 * Creates an AudioStream object listening on a RTP port for a dedicated address.
 * @param loc_ip the local ip to listen for RTP packets. Can be ::, O.O.O.O or any ip4/6 addresses
 * @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
492
 * @param factory
jehan's avatar
jehan committed
493 494
 * @return a new AudioStream.
**/
495
MS2_PUBLIC AudioStream *audio_stream_new2(MSFactory* factory, const char* ip, int loc_rtp_port, int loc_rtcp_port);
jehan's avatar
jehan committed
496 497


498 499
/**Creates an AudioStream object from initialized MSMediaStreamSessions.
 * @param sessions the MSMediaStreamSessions
500
 * @param factory the MSFActory from the core object
501
 * @return a new AudioStream
502
**/
503
MS2_PUBLIC AudioStream *audio_stream_new_with_sessions(MSFactory* factory, const MSMediaStreamSessions *sessions);
504

505 506 507 508 509 510 511 512
#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)
513
#define AUDIO_STREAM_FEATURE_LOCAL_PLAYING	(1 << 8)
514
#define AUDIO_STREAM_FEATURE_REMOTE_PLAYING	(1 << 9)
515

Yann Diorcet's avatar
Yann Diorcet committed
516 517 518 519 520 521 522
#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 | \
523
					AUDIO_STREAM_FEATURE_DTMF_ECHO |\
524
					AUDIO_STREAM_FEATURE_MIXED_RECORDING |\
525 526
					AUDIO_STREAM_FEATURE_LOCAL_PLAYING | \
					AUDIO_STREAM_FEATURE_REMOTE_PLAYING \
Yann Diorcet's avatar
Yann Diorcet committed
527 528
					)

529

Yann Diorcet's avatar
Yann Diorcet committed
530 531
MS2_PUBLIC uint32_t audio_stream_get_features(AudioStream *st);
MS2_PUBLIC void audio_stream_set_features(AudioStream *st, uint32_t features);
532

533 534 535
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);
536 537
/**
 * Starts an audio stream from local soundcards.
538
 *
539 540
 * 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.
541
 *
542 543 544 545 546 547 548 549 550 551 552
 * @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
553 554
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
555
/*returns true if we are still receiving some data from remote end in the last timeout seconds*/
Simon Morlat's avatar
Simon Morlat committed
556
MS2_PUBLIC bool_t audio_stream_alive(AudioStream * stream, int timeout);
aymeric's avatar
aymeric committed
557

558 559 560 561
/**
 * 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.
 */
562 563
MS2_PUBLIC void audio_stream_iterate(AudioStream *stream);

jehan's avatar
jehan committed
564 565 566
/**
 * enable echo-limiter dispositve: one MSVolume in input branch controls a MSVolume in the output branch
 * */
Simon Morlat's avatar
Simon Morlat committed
567
MS2_PUBLIC void audio_stream_enable_echo_limiter(AudioStream *stream, EchoLimiterType type);
568

jehan's avatar
jehan committed
569 570 571
/**
 * enable gain control, to be done before start()
 * */
Simon Morlat's avatar
Simon Morlat committed
572
MS2_PUBLIC void audio_stream_enable_gain_control(AudioStream *stream, bool_t val);
smorlat's avatar
smorlat committed
573

jehan's avatar
jehan committed
574 575 576
/**
 * enable automatic gain control, to be done before start()
 * */
Simon Morlat's avatar
Simon Morlat committed
577
MS2_PUBLIC void audio_stream_enable_automatic_gain_control(AudioStream *stream, bool_t val);
578

jehan's avatar
jehan committed
579 580 581
/**
 * to be done before start
 *  */
Simon Morlat's avatar
Simon Morlat committed
582
MS2_PUBLIC void audio_stream_set_echo_canceller_params(AudioStream *st, int tail_len_ms, int delay_ms, int framesize);
583

584 585 586 587 588

/**
 * to be done before start
 *  */
MS2_PUBLIC void audio_stream_enable_echo_canceller(AudioStream *st, bool_t enabled);
jehan's avatar
jehan committed
589 590 591
/**
 * enable adaptive rate control
 * */
592
static MS2_INLINE void audio_stream_enable_adaptive_bitrate_control(AudioStream *stream, bool_t enabled) {
593 594
	media_stream_enable_adaptive_bitrate_control(&stream->ms, enabled);
}
595

jehan's avatar
jehan committed
596 597 598
/**
 *  Enable adaptive jitter compensation
 *  */
599
static MS2_INLINE void audio_stream_enable_adaptive_jittcomp(AudioStream *stream, bool_t enabled) {
600 601
	media_stream_enable_adaptive_jittcomp(&stream->ms, enabled);
}
602

603
/**
604 605 606 607 608 609 610
 * Apply a software gain on the microphone.
 * Be note that this method neither changes the volume gain
 * of the sound card nor the system mixer one. If you intends
 * to control the volume gain at sound card level, you should
 * use audio_stream_set_sound_card_input_gain() instead.
 * 
 * @param stream The stream.
611
 * @param gain_db Gain to apply in dB.
612
 */
613 614
MS2_PUBLIC void audio_stream_set_mic_gain_db(AudioStream *stream, float gain_db);

615 616

/**
617 618
 * Like audio_stream_set_mic_gain_db() excepted that the gain is specified
 * in percentage.
619
 * 
620 621
 * @param stream The stream.
 * @param gain Gain to apply in percetage of the max supported gain.
622
 */
623
MS2_PUBLIC void audio_stream_set_mic_gain(AudioStream *stream, float gain);
624

jehan's avatar
jehan committed
625 626
/**
 *  enable/disable rtp stream
627
 */
Simon Morlat's avatar
Simon Morlat committed
628
MS2_PUBLIC void audio_stream_mute_rtp(AudioStream *stream, bool_t val);
Simon Morlat's avatar
Simon Morlat committed
629

630 631 632 633 634 635 636
/**
 * Apply a gain on received RTP packets.
 * @param stream An AudioStream.
 * @param gain_db Gain to apply in dB.
 */
MS2_PUBLIC void audio_stream_set_spk_gain_db(AudioStream *stream, float gain_db);

637
/**
638
 * Set microphone volume gain.
639
 * If the sound backend supports it, the set volume gain will be synchronized
640 641 642
 * with the host system mixer. If you intended to apply a static software gain,
 * you should use audio_stream_set_mic_gain_db() or audio_stream_set_mic_gain().
 * 
643 644 645
 * @param stream The audio stream.
 * @param gain Percentage of the max supported volume gain. Valid values are in [0.0 : 1.0].
 */
646
MS2_PUBLIC void audio_stream_set_sound_card_input_gain(AudioStream *stream, float gain);
647 648

/**
649
 * Get microphone volume gain.
650 651 652 653
 * @param stream The audio stream.
 * @return double Volume gain in percentage of the max suppored gain.
 * Valid returned values are in [0.0 : 1.0]. A negative value is returned in case of failure.
 */
654
MS2_PUBLIC float audio_stream_get_sound_card_input_gain(const AudioStream *stream);
655 656

/**
657
 * Set speaker volume gain.
658 659 660 661 662
 * If the sound backend supports it, the set volume gain will be synchronized
 * with the host system mixer.
 * @param stream The audio stream.
 * @param gain Percentage of the max supported volume gain. Valid values are in [0.0 : 1.0].
 */
663
MS2_PUBLIC void audio_stream_set_sound_card_output_gain(AudioStream *stream, float volume);
664 665

/**
666
 * Get speaker volume gain.
667 668 669 670
 * @param stream The audio stream.
 * @return Volume gain in percentage of the max suppored gain.
 * Valid returned values are in [0.0 : 1.0]. A negative value is returned in case of failure.
 */
671
MS2_PUBLIC float audio_stream_get_sound_card_output_gain(const AudioStream *stream);
672

jehan's avatar
jehan committed
673 674 675
/**
 * enable noise gate, must be done before start()
 * */
Simon Morlat's avatar
Simon Morlat committed
676
MS2_PUBLIC void audio_stream_enable_noise_gate(AudioStream *stream, bool_t val);
677

jehan's avatar
jehan committed
678
/**
679 680 681 682 683 684
 * Enable a parametric equalizer
 * @param[in] stream An AudioStream
 * @param[in] location Location of the equalizer to enable (speaker or microphone)
 * @param[in] enabled Whether the equalizer must be enabled
 */
MS2_PUBLIC void audio_stream_enable_equalizer(AudioStream *stream, EqualizerLocation location, bool_t enabled);
smorlat's avatar
smorlat committed
685

686 687 688 689 690 691 692
/**
 * Apply a gain on a given frequency band.
 * @param[in] stream An AudioStream
 * @param[in] location Location of the concerned equalizer (speaker or microphone)
 * @param[in] gain Description of the band and the gain to apply.
 */
MS2_PUBLIC void audio_stream_equalizer_set_gain(AudioStream *stream, EqualizerLocation location, const MSEqualizerGain *gain);
smorlat's avatar
smorlat committed
693

jehan's avatar
jehan committed
694 695 696
/**
 *  stop the audio streaming thread and free everything
 *  */
Simon Morlat's avatar
Simon Morlat committed
697
MS2_PUBLIC void audio_stream_stop (AudioStream * stream);
aymeric's avatar
aymeric committed
698

jehan's avatar
jehan committed
699 700 701
/**
 *  send a dtmf
 *  */
Simon Morlat's avatar
Simon Morlat committed
702
MS2_PUBLIC int audio_stream_send_dtmf (AudioStream * stream, char dtmf);
aymeric's avatar
aymeric committed
703

704 705
MS2_PUBLIC MSFilter *audio_stream_get_local_player(AudioStream *stream);

706 707 708 709 710 711
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);

712 713 714 715 716 717
/**
 * 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);

718 719
MS2_PUBLIC void audio_stream_close_remote_play(AudioStream *stream);

Simon Morlat's avatar
Simon Morlat committed
720
MS2_PUBLIC void audio_stream_set_default_card(int cardindex);
aymeric's avatar
aymeric committed
721

Simon Morlat's avatar
Simon Morlat committed
722
/* retrieve RTP statistics*/
723
static MS2_INLINE void audio_stream_get_local_rtp_stats(AudioStream *stream, rtp_stats_t *stats) {
724 725
	media_stream_get_local_rtp_stats(&stream->ms, stats);
}
Simon Morlat's avatar
Simon Morlat committed
726

727
/* returns a realtime indicator of the stream quality between 0 and 5 */
728 729
MS2_PUBLIC float audio_stream_get_quality_rating(AudioStream *stream);

730 731
/* 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
732

733 734 735 736 737 738
/* 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);

739
/* enable ZRTP on the audio stream */
740
MS2_PUBLIC void audio_stream_enable_zrtp(AudioStream *stream, MSZrtpParams *params);
johan's avatar
johan committed
741 742
MS2_PUBLIC void audio_stream_start_zrtp(AudioStream *stream);

jehan's avatar
jehan committed
743 744 745 746
/**
 * 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);
747

748
/* enable SRTP on the audio stream */
749
static MS2_INLINE bool_t audio_stream_enable_srtp(AudioStream* stream, MSCryptoSuite suite, const char* snd_key, const char* rcv_key) {
750 751
	return media_stream_enable_srtp(&stream->ms, suite, snd_key, rcv_key);
}
752

753
static MS2_INLINE int audio_stream_set_dscp(AudioStream *stream, int dscp) {
754 755
	return media_stream_set_dscp(&stream->ms, dscp);
}
Simon Morlat's avatar
Simon Morlat committed
756

757 758 759 760 761 762 763 764 765 766
/**
 * 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
767

768 769 770 771 772 773 774 775 776
/**
 * @}
**/


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

778
typedef void (*VideoStreamRenderCallback)(void *user_pointer, const MSPicture *local_view, const MSPicture *remote_view);
779 780
typedef void (*VideoStreamEventCallback)(void *user_pointer, const MSFilter *f, const unsigned int event_id, const void *args);

781 782 783 784 785 786 787
struct _MediastreamVideoStat
{
    int counter_rcvd_pli; /*Picture Loss Indication counter */
    int counter_rcvd_sli;/* Slice Loss Indication counter */
    int counter_rcvd_rpsi; /*Reference Picture Selection Indication */
    int counter_rcvd_fir; /* Full INTRA-frame Request */
};
788

789
typedef struct _MediastreamVideoStat MediaStreamVideoStat;
790

aymeric's avatar
aymeric committed
791 792
struct _VideoStream
{
793
	MediaStream ms;
794
	MSFilter *void_source;
aymeric's avatar
aymeric committed
795 796
	MSFilter *source;
	MSFilter *pixconv;
797
	MSFilter *sizeconv;
aymeric's avatar
aymeric committed
798 799
	MSFilter *tee;
	MSFilter *output;
800 801
	MSFilter *tee2;
	MSFilter *jpegwriter;
802
	MSFilter *output2;
Simon Morlat's avatar
Simon Morlat committed
803
	MSFilter *tee3;
804
	MSFilter *recorder_output; /*can be an ItcSink to send video to the audiostream's multimedia recorder, or directly a MkvRecorder */
805
	MSFilter *local_jpegwriter;
806
	MSVideoSize sent_vsize;
807
	MSVideoSize preview_vsize;
808 809
	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
810
	int corner; /*for selfview*/
811 812
	VideoStreamRenderCallback rendercb;
	void *render_pointer;
813 814
	VideoStreamEventCallback eventcb;
	void *event_pointer;
815
	char *display_name;
816 817
	void *window_id;
	void *preview_window_id;
818
	MediaStreamDir dir;
819
	MSWebCam *cam;
820
	RtpSession *rtp_io_session; /**< The RTP session used for RTP input/output. */
821
	char *preset;
822
	int device_orientation; /* warning: meaning of this variable depends on the platform (Android, iOS, ...) */
Simon Morlat's avatar
Simon Morlat committed
823
	uint64_t last_reported_decoding_error_time;
824
	uint64_t last_fps_check;
825
	MediaStreamVideoStat ms_video_stat;
826
	bool_t use_preview_window;
827
	bool_t freeze_on_error;
828
	bool_t display_filter_auto_rotate_enabled;
829
	bool_t source_performs_encoding;
830
	
831
	bool_t output_performs_decoding;
832
	bool_t player_active;
833
	bool_t staticimage_webcam_fps_optimization; /* if TRUE, the StaticImage webcam will ignore the fps target in order to save CPU time. Default is TRUE */
834
	
aymeric's avatar
aymeric committed
835 836 837
};

typedef struct _VideoStream VideoStream;
838

839

840
    
841
MS2_PUBLIC VideoStream *video_stream_new(MSFactory* factory, int loc_rtp_port, int loc_rtcp_port, bool_t use_ipv6);
jehan's avatar
jehan committed
842
/**
843
 * Creates a VideoStream object listening on a RTP port for a dedicated address.
jehan's avatar
jehan committed
844 845 846
 * @param loc_ip the local ip to listen for RTP packets. Can be ::, O.O.O.O or any ip4/6 addresses
 * @param [in] loc_rtp_port the local UDP port to listen for RTP packets.
 * @param [in] loc_rtcp_port the local UDP port to listen for RTCP packets
847
 * @return a new VideoStream.
jehan's avatar
jehan committed
848
**/
849
MS2_PUBLIC VideoStream *video_stream_new2(MSFactory* factory, const char* ip, int loc_rtp_port, int loc_rtcp_port);
jehan's avatar
jehan committed
850

851
MS2_PUBLIC VideoStream *video_stream_new_with_sessions(MSFactory* factory, const MSMediaStreamSessions *sessions);
852
MS2_PUBLIC void video_stream_set_direction(VideoStream *vs, MediaStreamDir dir);
853
static MS2_INLINE void video_stream_enable_adaptive_bitrate_control(VideoStream *stream, bool_t enabled) {
854 855
	media_stream_enable_adaptive_bitrate_control(&stream->ms, enabled);
}
856
static MS2_INLINE void video_stream_enable_adaptive_jittcomp(VideoStream *stream, bool_t enabled) {
857 858
	media_stream_enable_adaptive_jittcomp(&stream->ms, enabled);
}
Simon Morlat's avatar
Simon Morlat committed
859 860 861
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);
862 863
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);
864 865 866 867
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, int payload, int jitt_comp, MSWebCam *device);
MS2_PUBLIC int video_stream_start_with_files(VideoStream *stream, RtpProfile *profile, const char *rem_rtp_ip, int rem_rtp_port,
        const char *rem_rtcp_ip, int rem_rtcp_port, int payload_type, const char *play_file, const char *record_file);
868 869 870 871 872 873 874 875 876 877

/**
 * Start a video stream according to the specified VideoStreamIO.
 *
 * @param[in] stream VideoStream object previously created with video_stream_new().
 * @param[in] profile RtpProfile object holding the PayloadType that can be used during the video session.
 * @param[in] rem_rtp_ip The remote IP address where to send the encoded video to.
 * @param[in] rem_rtp_port The remote port where to send the encoded video to.
 * @param[in] rem_rtcp_ip The remote IP address for RTCP.
 * @param[in] rem_rtcp_port The remote port for RTCP.
878
 * @param[in] payload_type The payload type number used to send the video stream. A valid PayloadType must be available at this index in the profile.
879 880 881
 * @param[in] io A VideoStreamIO describing the input/output of the video stream.
 */
MS2_PUBLIC int video_stream_start_from_io(VideoStream *stream, RtpProfile *profile, const char *rem_rtp_ip, int rem_rtp_port,
882
	const char *rem_rtcp_ip, int rem_rtcp_port, int payload_type, const MSMediaStreamIO *io);
883

884 885
MS2_PUBLIC void video_stream_prepare_video(VideoStream *stream);
MS2_PUBLIC void video_stream_unprepare_video(VideoStream *stream);
886 887


Simon Morlat's avatar
Simon Morlat committed
888
MS2_PUBLIC void video_stream_set_relay_session_id(VideoStream *stream, const char *relay_session_id);
889
static MS2_INLINE void video_stream_set_rtcp_information(VideoStream *st, const char *cname, const char *tool) {
890 891
	media_stream_set_rtcp_information(&st->ms, cname, tool);
}
jehan's avatar
jehan committed
892 893 894 895
/*
 * returns current MSWebCam for a given stream
 * */
MS2_PUBLIC const MSWebCam * video_stream_get_camera(const VideoStream *stream);
896 897 898 899 900 901 902 903

/**
 * Returns the current video stream source filter. Be careful, this source will be
 * destroyed if the stream is stopped.
 * @return current stream source
 */
MS2_PUBLIC MSFilter* video_stream_get_source_filter(const VideoStream* stream);

Simon Morlat's avatar
Simon Morlat committed
904
MS2_PUBLIC void video_stream_change_camera(VideoStream *stream, MSWebCam *cam);
905 906 907 908 909

/**
 * @brief This functions changes the source filter for the passed video stream.
 * @details This is quite the same function as \ref video_stream_change_camera, but this one
 * allows you to pass the source filter that is created for the camera and reuse it. This gives you the
910
 * ability to switch rapidly between two streams, whereas re-creating them each time would be
911 912
 * costly (especially with webcams).
 *
913 914
 * @note Since the \ref video_stream_stop() will automatically destroy the source, it is
 *		advised that you use \ref video_stream_stop_keep_source() instead, so that you
915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942
 *		can manually destroy the source filters after the stream is stopped.
 *
 * Example usage:
 *
 *		video_stream_start(stream, profile, [...], noWebcamDevice);
 *		// We manage the sources for the stream ourselves:
 *		MSFilter* noWebCamFilter = video_stream_get_source_filter(stream);
 *		MSFilter* frontCamFilter = ms_web_cam_create_reader(frontCamDevice);
 *
 * 		sleep(1);
 * 		video_stream_change_source_filter(stream, frontCamDevice, frontCamFilter, TRUE); // will keep the previous filter
 * 		sleep(1);
 * 		video_stream_change_source_filter(stream, noWebcamDevice, noWebCamFilter, TRUE); // keep the previous filter
 *
 *		sleep(1)
 *		video_stream_stop_keep_source(stream);
 *		ms_filter_destroy(noWebCamFilter);
 *		ms_filter_destroy(frontCamFilter);
 *
 *
 * @param stream the video stream to modify
 * @param cam the camera that you want to set as the new source
 * @param cam_filter the filter for this camera. It can be obtained with ms_web_cam_create_reader(cam)
 * @return the previous source if keep_previous_source is TRUE, otherwise NULL
 */
MS2_PUBLIC MSFilter* video_stream_change_source_filter(VideoStream *stream, MSWebCam* cam, MSFilter* filter, bool_t keep_previous_source );

/**
Guillaume BIENKOWSKI's avatar
Guillaume BIENKOWSKI committed
943 944
 * @brief This is the same function as \ref video_stream_change_source_filter() called with keep_source=1, but
 *  the new filter will be created from the MSWebcam that is passed as argument.
945
 *
Guillaume BIENKOWSKI's avatar
Guillaume BIENKOWSKI committed
946 947 948
 *  @param stream the video stream
 *  @param cam the MSWebcam from which the new source filter should be created.
 *  @return the previous source filter
949 950 951 952
 */
MS2_PUBLIC MSFilter* video_stream_change_camera_keep_previous_source(VideoStream *stream, MSWebCam *cam);


953 954
/* 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
955
MS2_PUBLIC void video_stream_update_video_params(VideoStream *stream);
aymeric's avatar
aymeric committed
956
/*function to call periodically to handle various events */
Simon Morlat's avatar
Simon Morlat committed
957
MS2_PUBLIC void video_stream_iterate(VideoStream *stream);
958 959

/**
960
 * Asks the video stream to send a Full-Intra Request.
961 962 963 964 965
 * @param[in] stream The videostream object.
 */
MS2_PUBLIC void video_stream_send_fir(VideoStream *stream);

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

Simon Morlat's avatar
Simon Morlat committed
971
MS2_PUBLIC void video_stream_stop(VideoStream * stream);
972

973 974 975 976 977 978 979 980 981
/**
 * Stop the video stream, but does not destroy the source of the video. This function
 * can be use in conjunction with \ref video_stream_change_source_filter() to allow
 * manual management of the source filters for a video stream.
 * @param stream the stream to stop
 * @return returns the source of the video stream, which you should manually destroy when appropriate.
 */
MS2_PUBLIC MSFilter* video_stream_stop_keep_source(VideoStream * stream);

982 983
MS2_PUBLIC bool_t video_stream_started(VideoStream *stream);

984 985 986 987 988 989 990 991
/**
 * Try to set the size of the video that is sent. Since this relies also on the
 * bitrate specified, make sure to set the payload bitrate accordingly with
 * rtp_profile_get_payload and normal_bitrate value otherwise the best
 * possible resolution will be taken instead of the requested one.
 * @param[in] stream The videostream for which to get the sent video size.
 * @param[in] vsize The sent video size wished.
 */
Simon Morlat's avatar
Simon Morlat committed
992
MS2_PUBLIC void video_stream_set_sent_video_size(VideoStream *stream, MSVideoSize vsize);
993 994 995 996 997 998

/**
 * 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.
 */
999
MS2_PUBLIC MSVideoSize video_stream_get_sent_video_size(const VideoStream *stream);
1000 1001 1002 1003 1004 1005

/**
 * 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.
 */
1006
MS2_PUBLIC MSVideoSize video_stream_get_received_video_size(const VideoStream *stream);
1007

1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021
/**
 * 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);

1022 1023 1024
/**
 * Returns the name of the video display filter on the current platform.
**/
1025
MS2_PUBLIC const char *video_stream_get_default_video_renderer(void);
1026

Simon Morlat's avatar
Simon Morlat committed
1027
MS2_PUBLIC void video_stream_enable_self_view(VideoStream *stream, bool_t val);
1028 1029 1030 1031
MS2_PUBLIC void * video_stream_get_native_window_id(VideoStream *stream);
MS2_PUBLIC void video_stream_set_native_window_id(VideoStream *stream, void *id);
MS2_PUBLIC void video_stream_set_native_preview_window_id(VideoStream *stream, void *id);
MS2_PUBLIC void * video_stream_get_native_preview_window_id(VideoStream *stream);
Simon Morlat's avatar
Simon Morlat committed
1032
MS2_PUBLIC void video_stream_use_preview_video_window(VideoStream *stream, bool_t yesno);
1033
MS2_PUBLIC void video_stream_set_device_rotation(VideoStream *stream, int orientation);
1034
MS2_PUBLIC void video_stream_show_video(VideoStream *stream, bool_t show);
1035
MS2_PUBLIC void video_stream_set_freeze_on_error(VideoStream *stream, bool_t yesno);
1036

1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047
/**
 * @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);

1048
/*provided for compatibility, use video_stream_set_direction() instead */
Simon Morlat's avatar
Simon Morlat committed
1049 1050
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,
1051
				RtpProfile *profile, const char *addr, int port, int rtcp_port,
1052
				int used_pt, int  jitt_comp, MSWebCam *device);
Simon Morlat's avatar
Simon Morlat committed
1053 1054
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
1055

1056
/* enable ZRTP on the video stream using information from the audio stream */
johan's avatar
johan committed
1057 1058
MS2_PUBLIC void video_stream_enable_zrtp(VideoStream *vstream, AudioStream *astream);
MS2_PUBLIC void video_stream_start_zrtp(VideoStream *stream);
1059

1060
/* enable SRTP on the video stream */
1061
static MS2_INLINE bool_t video_stream_enable_strp(VideoStream* stream, MSCryptoSuite suite, const char* snd_key, const char* rcv_key) {
1062 1063 1064
	return media_stream_enable_srtp(&stream->ms, suite, snd_key, rcv_key);
}

1065 1066
/* 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);
1067

1068
/* retrieve RTP statistics*/
1069
static MS2_INLINE void video_stream_get_local_rtp_stats(VideoStream *stream, rtp_stats_t *stats) {
1070 1071
	media_stream_get_local_rtp_stats(&stream->ms, stats);
}
1072

1073
static MS2_INLINE int video_stream_set_dscp(VideoStream *stream, int dscp) {
1074 1075
	return media_stream_set_dscp(&stream->ms, dscp);
}
Simon Morlat's avatar
Simon Morlat committed
1076

1077 1078 1079 1080 1081 1082 1083 1084 1085
/**
 * 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);
}

1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099
/**
 * 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);

1100 1101 1102 1103 1104 1105
/**
 * 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
1106

1107 1108 1109 1110 1111 1112 1113
/**
 * 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);

1114 1115 1116 1117 1118 1119 1120
/**
 * 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
1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132
/**
 * 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);

1133 1134 1135 1136 1137 1138 1139
/**
 * Set a video preset to be used for the video stream.
 * @param[in] stream VideoStream object
 * @param[in] preset The name of the video preset to be used.
 */
MS2_PUBLIC void video_stream_use_video_preset(VideoStream *stream, const char *preset);

1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152

/**
 * Open a player to play a video file (mkv) 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 * video_stream_open_remote_play(VideoStream *stream, const char *filename);

MS2_PUBLIC void video_stream_close_remote_play(VideoStream *stream);

/**
 * Open a recorder to record the video coming from remote end into a mkv file.
 * This must be done before the stream is started.
**/
1153
MS2_PUBLIC MSFilter * video_stream_open_remote_record(VideoStream *stream, const char *filename);
1154

1155
MS2_PUBLIC void video_stream_close_remote_record(VideoStream *stream);
1156

1157 1158 1159 1160
/**
 * Small API to display a local preview window.
**/

Simon Morlat's avatar
Simon Morlat committed
1161 1162
typedef VideoStream VideoPreview;

Simon Morlat's avatar
Simon Morlat committed
1163
MS2_PUBLIC VideoPreview * video_preview_new(MSFactory *factory);
1164
#define video_preview_set_size(p,s)			video_stream_set_sent_video_size(p,s)
Simon Morlat's avatar
Simon Morlat committed
1165
#define video_preview_set_display_filter_name(p,dt)	video_stream_set_display_filter_name(p,dt)
1166 1167 1168
#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)
1169
#define video_preview_set_device_rotation(p, r) video_stream_set_device_rotation(p, r)
Simon Morlat's avatar
Simon Morlat committed
1170
MS2_PUBLIC void video_preview_start(VideoPreview *stream, MSWebCam *device);
Simon Morlat's avatar
Simon Morlat committed
1171
MS2_PUBLIC MSVideoSize video_preview_get_current_size(VideoPreview *stream);
Simon Morlat's avatar
Simon Morlat committed
1172
MS2_PUBLIC void video_preview_stop(VideoPreview *stream);
1173 1174 1175
MS2_PUBLIC void video_preview_change_camera(VideoPreview *stream, MSWebCam *cam);
MS2_PUBLIC void video_preview_update_video_params(VideoPreview *stream);

aymeric's avatar
aymeric committed
1176

1177 1178 1179 1180
/**
 * 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,
1181 1182 1183
 * otherwise you should destroy it.
 * @param[in] stream VideoPreview object
 * @return The source filter to be passed to the #video_stream_start_with_source function.
1184 1185 1186
 */
MS2_PUBLIC MSFilter* video_preview_stop_reuse_source(VideoPreview *stream);

1187 1188 1189 1190 1191
/*
 * Returns the web cam descriptor for the mire kind of camera.
**/
MS2_PUBLIC MSWebCamDesc *ms_mire_webcam_desc_get(void);

1192 1193 1194 1195 1196 1197 1198

/**
 * Create an RTP session for duplex communication.
 * @param[in] local_ip The local IP to bind the RTP and RTCP sockets to.
 * @param[in] local_rtp_port The local port to bind the RTP socket to.
 * @param[in] local_rtcp_port The local port to bind the RTCP socket to.
 */
1199
MS2_PUBLIC RtpSession * ms_create_duplex_rtp_session(const char* local_ip, int loc_rtp_port, int loc_rtcp_port, int mtu);
1200

1201
/**
1202
 * Asks the audio playback filter to route to the selected device (currently only used for blackberry)
1203 1204 1205 1206 1207
 * @param[in] stream The AudioStream object
 * @param[in] route The wanted audio output device (earpiece, speaker)
 */
MS2_PUBLIC void audio_stream_set_audio_route(AudioStream *stream, MSAudioRoute route);

1208 1209 1210 1211
/**
 * @}
**/

1212 1213 1214 1215 1216 1217 1218 1219
/**
 * @addtogroup text_stream_api
 * @{
**/

struct _TextStream
{
	MediaStream ms;
1220 1221
	MSFilter *rttsource;
	MSFilter *rttsink;
1222
	int pt_t140;
1223
	int pt_red;
1224 1225 1226 1227 1228 1229 1230 1231 1232
};

typedef struct _TextStream TextStream;

/**
 * Creates a TextStream object listening on a RTP port.
 * @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
 * @param ipv6 TRUE if ipv6 must be used.
1233
 * @param factory 
1234 1235
 * @return a new TextStream.
**/
1236
MS2_PUBLIC TextStream *text_stream_new(MSFactory *factory, int loc_rtp_port, int loc_rtcp_port, bool_t ipv6);
1237 1238 1239 1240

/**
 * Creates a TextStream object from initialized MSMediaStreamSessions.
 * @param sessions the MSMediaStreamSessions
1241
 * @param factory
1242 1243
 * @return a new TextStream
**/
1244
MS2_PUBLIC TextStream *text_stream_new_with_sessions(MSFactory *factory, const MSMediaStreamSessions *sessions);
jehan's avatar
jehan committed
1245

1246 1247 1248 1249 1250
/**
 * Creates a TextStream object listening on a RTP port for a dedicated address.
 * @param loc_ip the local ip to listen for RTP packets. Can be ::, O.O.O.O or any ip4/6 addresses
 * @param [in] loc_rtp_port the local UDP port to listen for RTP packets.
 * @param [in] loc_rtcp_port the local UDP port to listen for RTCP packets
1251
 * @param factory 
1252 1253
 * @return a new TextStream.
**/
1254
MS2_PUBLIC TextStream *text_stream_new2(MSFactory *factory, const char* ip, int loc_rtp_port, int loc_rtcp_port);
aymeric's avatar
aymeric committed
1255

1256 1257 1258 1259 1260 1261 1262 1263 1264 1265
/**
 * Starts a text stream.
 *
 * @param[in] stream TextStream object previously created with text_stream_new().
 * @param[in] profile RtpProfile object holding the PayloadType that can be used during the text session.
 * @param[in] rem_rtp_addr The remote IP address where to send the text to.
 * @param[in] rem_rtp_port The remote port where to send the text to.
 * @param[in] rem_rtcp_addr The remote IP address for RTCP.
 * @param[in] rem_rtcp_port The remote port for RTCP.
 * @param[in] payload_type The payload type number used to send the text stream. A valid PayloadType must be available at this index in the profile.
1266
 * @param[in] factory
1267
 */
1268
MS2_PUBLIC TextStream* text_stream_start(TextStream *stream, RtpProfile *profile, const char *rem_rtp_addr, int rem_rtp_port, const char *rem_rtcp_addr, int rem_rtcp_port,
1269
										 int payload_type);
1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285