Tristan Matthews | 0a329cc | 2013-07-17 13:20:14 -0400 | [diff] [blame] | 1 | /* $Id$ */ |
| 2 | /* |
| 3 | * Copyright (C) 2011 Teluu Inc. (http://www.teluu.com) |
| 4 | * |
| 5 | * This program is free software; you can redistribute it and/or modify |
| 6 | * it under the terms of the GNU General Public License as published by |
| 7 | * the Free Software Foundation; either version 2 of the License, or |
| 8 | * (at your option) any later version. |
| 9 | * |
| 10 | * This program is distributed in the hope that it will be useful, |
| 11 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 12 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 13 | * GNU General Public License for more details. |
| 14 | * |
| 15 | * You should have received a copy of the GNU General Public License |
| 16 | * along with this program; if not, write to the Free Software |
| 17 | * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
| 18 | */ |
| 19 | #ifndef __PJMEDIA_VID_STREAM_H__ |
| 20 | #define __PJMEDIA_VID_STREAM_H__ |
| 21 | |
| 22 | |
| 23 | /** |
| 24 | * @file vid_stream.h |
| 25 | * @brief Video Stream. |
| 26 | */ |
| 27 | |
| 28 | #include <pjmedia/endpoint.h> |
| 29 | #include <pjmedia/jbuf.h> |
| 30 | #include <pjmedia/port.h> |
| 31 | #include <pjmedia/rtcp.h> |
| 32 | #include <pjmedia/transport.h> |
| 33 | #include <pjmedia/vid_codec.h> |
| 34 | #include <pj/sock.h> |
| 35 | |
| 36 | PJ_BEGIN_DECL |
| 37 | |
| 38 | |
| 39 | /** |
| 40 | * @defgroup PJMED_VID_STRM Video streams |
| 41 | * @ingroup PJMEDIA_PORT |
| 42 | * @brief Video communication via the network |
| 43 | * @{ |
| 44 | * |
| 45 | * A video stream is a bidirectional video communication between two |
| 46 | * endpoints. It corresponds to a video media description ("m=video" line) |
| 47 | * in SDP session descriptor. |
| 48 | * |
| 49 | * A video stream consists of two unidirectional channels: |
| 50 | * - encoding channel, which transmits unidirectional video to remote, and |
| 51 | * - decoding channel, which receives unidirectional media from remote. |
| 52 | * |
| 53 | * A video stream exports two media port interface (see @ref PJMEDIA_PORT), |
| 54 | * one for each direction, and application normally uses this interface to |
| 55 | * interconnect the stream to other PJMEDIA components, e.g: the video |
| 56 | * capture port supplies frames to the encoding port and video renderer |
| 57 | * consumes frames from the decoding port. |
| 58 | * |
| 59 | * A video stream internally manages the following objects: |
| 60 | * - an instance of video codec (see @ref PJMEDIA_VID_CODEC), |
| 61 | * - an @ref PJMED_JBUF, |
| 62 | * - two instances of RTP sessions (#pjmedia_rtp_session, one for each |
| 63 | * direction), |
| 64 | * - one instance of RTCP session (#pjmedia_rtcp_session), |
| 65 | * - and a reference to video transport to send and receive packets |
| 66 | * to/from the network (see @ref PJMEDIA_TRANSPORT). |
| 67 | * |
| 68 | * Video streams are created by calling #pjmedia_vid_stream_create(), |
| 69 | * specifying #pjmedia_stream_info structure in the parameter. Application |
| 70 | * can construct the #pjmedia_vid_stream_info structure manually, or use |
| 71 | * #pjmedia_vid_stream_info_from_sdp() function to construct the |
| 72 | * #pjmedia_vid stream_info from local and remote SDP session descriptors. |
| 73 | */ |
| 74 | |
| 75 | |
| 76 | /** |
| 77 | * Enumeration of video stream sending rate control. |
| 78 | */ |
| 79 | typedef enum pjmedia_vid_stream_rc_method |
| 80 | { |
| 81 | /** |
| 82 | * No sending rate control. All outgoing RTP packets will be transmitted |
| 83 | * immediately right after encoding process is done. |
| 84 | */ |
| 85 | PJMEDIA_VID_STREAM_RC_NONE = 0, |
| 86 | |
| 87 | /** |
| 88 | * Simple blocking. Each outgoing RTP packet transmission may be delayed |
| 89 | * to avoid peak bandwidth that is much higher than specified. The thread |
| 90 | * invoking the video stream put_frame(), e.g: video capture device thread, |
| 91 | * will be blocked whenever transmission delay takes place. |
| 92 | */ |
| 93 | PJMEDIA_VID_STREAM_RC_SIMPLE_BLOCKING = 1 |
| 94 | |
| 95 | } pjmedia_vid_stream_rc_method; |
| 96 | |
| 97 | |
| 98 | /** |
| 99 | * Structure of configuration settings for video stream sending rate control. |
| 100 | */ |
| 101 | typedef struct pjmedia_vid_stream_rc_config |
| 102 | { |
| 103 | /** |
| 104 | * Rate control method. |
| 105 | * |
| 106 | * Default: PJMEDIA_VID_STREAM_RC_SIMPLE_BLOCKING. |
| 107 | */ |
| 108 | pjmedia_vid_stream_rc_method method; |
| 109 | |
| 110 | /** |
| 111 | * Upstream/outgoing bandwidth. If this is set to zero, the video stream |
| 112 | * will use codec maximum bitrate setting. |
| 113 | * |
| 114 | * Default: 0 (follow codec maximum bitrate). |
| 115 | */ |
| 116 | unsigned bandwidth; |
| 117 | |
| 118 | } pjmedia_vid_stream_rc_config; |
| 119 | |
| 120 | |
| 121 | /** |
| 122 | * This structure describes video stream information. Each video stream |
| 123 | * corresponds to one "m=" line in SDP session descriptor, and it has |
| 124 | * its own RTP/RTCP socket pair. |
| 125 | */ |
| 126 | typedef struct pjmedia_vid_stream_info |
| 127 | { |
| 128 | pjmedia_type type; /**< Media type (audio, video) */ |
| 129 | pjmedia_tp_proto proto; /**< Transport protocol (RTP/AVP, etc.) */ |
| 130 | pjmedia_dir dir; /**< Media direction. */ |
| 131 | pj_sockaddr rem_addr; /**< Remote RTP address */ |
| 132 | pj_sockaddr rem_rtcp; /**< Optional remote RTCP address. If |
| 133 | sin_family is zero, the RTP address |
| 134 | will be calculated from RTP. */ |
| 135 | unsigned tx_pt; /**< Outgoing codec paylaod type. */ |
| 136 | unsigned rx_pt; /**< Incoming codec paylaod type. */ |
| 137 | pj_uint32_t ssrc; /**< RTP SSRC. */ |
| 138 | pj_uint32_t rtp_ts; /**< Initial RTP timestamp. */ |
| 139 | pj_uint16_t rtp_seq; /**< Initial RTP sequence number. */ |
| 140 | pj_uint8_t rtp_seq_ts_set; |
| 141 | /**< Bitmask flags if initial RTP sequence |
| 142 | and/or timestamp for sender are set. |
| 143 | bit 0/LSB : sequence flag |
| 144 | bit 1 : timestamp flag */ |
| 145 | int jb_init; /**< Jitter buffer init delay in msec. |
| 146 | (-1 for default). */ |
| 147 | int jb_min_pre; /**< Jitter buffer minimum prefetch |
| 148 | delay in msec (-1 for default). */ |
| 149 | int jb_max_pre; /**< Jitter buffer maximum prefetch |
| 150 | delay in msec (-1 for default). */ |
| 151 | int jb_max; /**< Jitter buffer max delay in msec. */ |
| 152 | |
| 153 | #if defined(PJMEDIA_STREAM_ENABLE_KA) && PJMEDIA_STREAM_ENABLE_KA!=0 |
| 154 | pj_bool_t use_ka; /**< Stream keep-alive and NAT hole punch |
| 155 | (see #PJMEDIA_STREAM_ENABLE_KA) |
| 156 | is enabled? */ |
| 157 | #endif |
| 158 | |
| 159 | pjmedia_vid_codec_info codec_info; /**< Incoming codec format info. */ |
| 160 | pjmedia_vid_codec_param *codec_param; /**< Optional codec param. */ |
| 161 | |
| 162 | pj_bool_t rtcp_sdes_bye_disabled; |
| 163 | /**< Disable automatic sending of RTCP |
| 164 | SDES and BYE. */ |
| 165 | |
| 166 | pjmedia_vid_stream_rc_config rc_cfg; |
| 167 | /**< Stream send rate control settings. */ |
| 168 | } pjmedia_vid_stream_info; |
| 169 | |
| 170 | |
| 171 | /** |
| 172 | * This function will initialize the video stream info based on information |
| 173 | * in both SDP session descriptors for the specified stream index. |
| 174 | * The remaining information will be taken from default codec parameters. |
| 175 | * If socket info array is specified, the socket will be copied to the |
| 176 | * session info as well. |
| 177 | * |
| 178 | * @param si Stream info structure to be initialized. |
| 179 | * @param pool Pool to allocate memory. |
| 180 | * @param endpt PJMEDIA endpoint instance. |
| 181 | * @param local Local SDP session descriptor. |
| 182 | * @param remote Remote SDP session descriptor. |
| 183 | * @param stream_idx Media stream index in the session descriptor. |
| 184 | * |
| 185 | * @return PJ_SUCCESS if stream info is successfully initialized. |
| 186 | */ |
| 187 | PJ_DECL(pj_status_t) |
| 188 | pjmedia_vid_stream_info_from_sdp(pjmedia_vid_stream_info *si, |
| 189 | pj_pool_t *pool, |
| 190 | pjmedia_endpt *endpt, |
| 191 | const pjmedia_sdp_session *local, |
| 192 | const pjmedia_sdp_session *remote, |
| 193 | unsigned stream_idx); |
| 194 | |
| 195 | |
| 196 | /** |
| 197 | * Initialize the video stream rate control with default settings. |
| 198 | * |
| 199 | * @param cfg Video stream rate control structure to be initialized. |
| 200 | */ |
| 201 | PJ_DECL(void) |
| 202 | pjmedia_vid_stream_rc_config_default(pjmedia_vid_stream_rc_config *cfg); |
| 203 | |
| 204 | |
| 205 | /* |
| 206 | * Opaque declaration for video stream. |
| 207 | */ |
| 208 | typedef struct pjmedia_vid_stream pjmedia_vid_stream; |
| 209 | |
| 210 | |
| 211 | /** |
| 212 | * Create a video stream based on the specified parameter. After the video |
| 213 | * stream has been created, application normally would want to get the media |
| 214 | * port interface of the stream, by calling pjmedia_vid_stream_get_port(). |
| 215 | * The media port interface exports put_frame() and get_frame() function, |
| 216 | * used to transmit and receive media frames from the stream. |
| 217 | * |
| 218 | * Without application calling put_frame() and get_frame(), there will be |
| 219 | * no media frames transmitted or received by the stream. |
| 220 | * |
| 221 | * @param endpt Media endpoint. |
| 222 | * @param pool Optional pool to allocate memory for the stream. If |
| 223 | * this is not specified, one will be created internally. |
| 224 | * A large number of memory may be needed because jitter |
| 225 | * buffer needs to preallocate some storage. |
| 226 | * @param info Stream information to create the stream. Upon return, |
| 227 | * this info will be updated with the information from |
| 228 | * the instantiated codec. Note that if the "pool" |
| 229 | * argument is NULL, some fields in this "info" parameter |
| 230 | * will be allocated from the internal pool of the |
| 231 | * stream, which means that they will only remain valid |
| 232 | * as long as the stream is not destroyed. |
| 233 | * @param tp Media transport instance used to transmit and receive |
| 234 | * RTP/RTCP packets to/from the underlying network. |
| 235 | * @param user_data Arbitrary user data (for future callback feature). |
| 236 | * @param p_stream Pointer to receive the video stream. |
| 237 | * |
| 238 | * @return PJ_SUCCESS on success. |
| 239 | */ |
| 240 | PJ_DECL(pj_status_t) pjmedia_vid_stream_create( |
| 241 | pjmedia_endpt *endpt, |
| 242 | pj_pool_t *pool, |
| 243 | pjmedia_vid_stream_info *info, |
| 244 | pjmedia_transport *tp, |
| 245 | void *user_data, |
| 246 | pjmedia_vid_stream **p_stream); |
| 247 | |
| 248 | /** |
| 249 | * Destroy the video stream. |
| 250 | * |
| 251 | * @param stream The video stream. |
| 252 | * |
| 253 | * @return PJ_SUCCESS on success. |
| 254 | */ |
| 255 | PJ_DECL(pj_status_t) pjmedia_vid_stream_destroy(pjmedia_vid_stream *stream); |
| 256 | |
| 257 | |
| 258 | /** |
| 259 | * Get the media port interface of the stream. The media port interface |
| 260 | * declares put_frame() and get_frame() function, which is the only |
| 261 | * way for application to transmit and receive media frames from the |
| 262 | * stream. As bidirectional video streaming may have different video |
| 263 | * formats in the encoding and decoding direction, there are two media |
| 264 | * ports exported by the video stream, one for each direction. |
| 265 | * |
| 266 | * @param stream The video stream. |
| 267 | * @param dir The video direction. |
| 268 | * @param p_port Pointer to receive the port interface. |
| 269 | * |
| 270 | * @return PJ_SUCCESS on success. |
| 271 | */ |
| 272 | PJ_DECL(pj_status_t) pjmedia_vid_stream_get_port( |
| 273 | pjmedia_vid_stream *stream, |
| 274 | pjmedia_dir dir, |
| 275 | pjmedia_port **p_port); |
| 276 | |
| 277 | |
| 278 | /** |
| 279 | * Get the media transport object associated with this stream. |
| 280 | * |
| 281 | * @param st The video stream. |
| 282 | * |
| 283 | * @return The transport object being used by the stream. |
| 284 | */ |
| 285 | PJ_DECL(pjmedia_transport*) pjmedia_vid_stream_get_transport( |
| 286 | pjmedia_vid_stream *st); |
| 287 | |
| 288 | |
| 289 | /** |
| 290 | * Get the stream statistics. See also #pjmedia_stream_get_stat_jbuf() |
| 291 | * |
| 292 | * @param stream The video stream. |
| 293 | * @param stat Media stream statistics. |
| 294 | * |
| 295 | * @return PJ_SUCCESS on success. |
| 296 | */ |
| 297 | PJ_DECL(pj_status_t) pjmedia_vid_stream_get_stat( |
| 298 | const pjmedia_vid_stream *stream, |
| 299 | pjmedia_rtcp_stat *stat); |
| 300 | |
| 301 | /** |
| 302 | * Reset the video stream statistics. |
| 303 | * |
| 304 | * @param stream The video stream. |
| 305 | * |
| 306 | * @return PJ_SUCCESS on success. |
| 307 | */ |
| 308 | PJ_DECL(pj_status_t) pjmedia_vid_stream_reset_stat(pjmedia_vid_stream *stream); |
| 309 | |
| 310 | |
| 311 | /** |
| 312 | * Get current jitter buffer state. See also #pjmedia_stream_get_stat() |
| 313 | * |
| 314 | * @param stream The video stream. |
| 315 | * @param state Jitter buffer state. |
| 316 | * |
| 317 | * @return PJ_SUCCESS on success. |
| 318 | */ |
| 319 | PJ_DECL(pj_status_t) pjmedia_vid_stream_get_stat_jbuf( |
| 320 | const pjmedia_vid_stream *stream, |
| 321 | pjmedia_jb_state *state); |
| 322 | |
| 323 | |
| 324 | /** |
| 325 | * Get the stream info. |
| 326 | * |
| 327 | * @param stream The video stream. |
| 328 | * @param info Video stream info. |
| 329 | * |
| 330 | * @return PJ_SUCCESS on success. |
| 331 | */ |
| 332 | PJ_DECL(pj_status_t) pjmedia_vid_stream_get_info( |
| 333 | const pjmedia_vid_stream *stream, |
| 334 | pjmedia_vid_stream_info *info); |
| 335 | |
| 336 | |
| 337 | /** |
| 338 | * Start the video stream. This will start the appropriate channels |
| 339 | * in the video stream, depending on the video direction that was set |
| 340 | * when the stream was created. |
| 341 | * |
| 342 | * @param stream The video stream. |
| 343 | * |
| 344 | * @return PJ_SUCCESS on success. |
| 345 | */ |
| 346 | PJ_DECL(pj_status_t) pjmedia_vid_stream_start(pjmedia_vid_stream *stream); |
| 347 | |
| 348 | |
| 349 | /** |
| 350 | * Query if the stream is started on the specified direction. |
| 351 | * |
| 352 | * @param stream The video stream. |
| 353 | * @param dir The direction to be checked. |
| 354 | * |
| 355 | * @return PJ_TRUE if stream is started. |
| 356 | */ |
| 357 | PJ_DECL(pj_bool_t) pjmedia_vid_stream_is_running(pjmedia_vid_stream *stream, |
| 358 | pjmedia_dir dir); |
| 359 | |
| 360 | /** |
| 361 | * Pause stream channels. |
| 362 | * |
| 363 | * @param stream The video stream. |
| 364 | * @param dir Which channel direction to pause. |
| 365 | * |
| 366 | * @return PJ_SUCCESS on success. |
| 367 | */ |
| 368 | PJ_DECL(pj_status_t) pjmedia_vid_stream_pause(pjmedia_vid_stream *stream, |
| 369 | pjmedia_dir dir); |
| 370 | |
| 371 | /** |
| 372 | * Resume stream channels. |
| 373 | * |
| 374 | * @param stream The video stream. |
| 375 | * @param dir Which channel direction to resume. |
| 376 | * |
| 377 | * @return PJ_SUCCESS on success; |
| 378 | */ |
| 379 | PJ_DECL(pj_status_t) pjmedia_vid_stream_resume(pjmedia_vid_stream *stream, |
| 380 | pjmedia_dir dir); |
| 381 | |
| 382 | |
| 383 | /** |
| 384 | * Force stream to send video keyframe on the next transmission. |
| 385 | * |
| 386 | * @param stream The video stream. |
| 387 | * |
| 388 | * @return PJ_SUCCESS on success; |
| 389 | */ |
| 390 | PJ_DECL(pj_status_t) pjmedia_vid_stream_send_keyframe( |
| 391 | pjmedia_vid_stream *stream); |
| 392 | |
| 393 | |
| 394 | /** |
| 395 | * Send RTCP SDES for the media stream. |
| 396 | * |
| 397 | * @param stream The media stream. |
| 398 | * |
| 399 | * @return PJ_SUCCESS on success. |
| 400 | */ |
| 401 | PJ_DECL(pj_status_t) pjmedia_vid_stream_send_rtcp_sdes( |
| 402 | pjmedia_vid_stream *stream); |
| 403 | |
| 404 | |
| 405 | /** |
| 406 | * Send RTCP BYE for the media stream. |
| 407 | * |
| 408 | * @param stream The media stream. |
| 409 | * |
| 410 | * @return PJ_SUCCESS on success. |
| 411 | */ |
| 412 | PJ_DECL(pj_status_t) pjmedia_vid_stream_send_rtcp_bye( |
| 413 | pjmedia_vid_stream *stream); |
| 414 | |
| 415 | |
| 416 | /** |
| 417 | * @} |
| 418 | */ |
| 419 | |
| 420 | PJ_END_DECL |
| 421 | |
| 422 | |
| 423 | #endif /* __PJMEDIA_VID_STREAM_H__ */ |